Biosym/MSI IPC C Application Program Interface

C Functions for IPC:

BiosymIpc_SetChannel - Specify new pair of FILE pointers for BiosymIpc functions.
BiosymIpc_Init - Initialize IPC package.
BiosymIpc_Shutdown - Close file handles associated with IPC connection.
BiosymIpc_GetError - Return pointer to local error message buffer.
BiosymIpc_GetLocalVersion - Return pointer to version of BiosymIpc used in Discover program.
BiosymIpc_GetRemoteVersion - Return pointer to version of BiosymIpc used in remote program.
BiosymIpc_Read - Read data entry from inputFile filehandle.
BiosymIpc_Write - Write data entry to outputFile filehandle.
BiosymIpc_Print - Print contents of BiosymIpcData structure.
BiosymIpc_VarWrite - Package variable-length string to be sent via IPC.
BiosymIpc_WriteRawBtcl2 - Send all strings from variable-length list to IPC output channel.
BiosymIpc_WriteRawBtcl - Send all strings from variable-length list to IPC output channel.

Background

This is the C language interface to the Biosym/MSI interprocess communication facilities implemented by the Discover program. A FORTRAN interface is also available. See Discover BTCL Interface for an overview of the Discover program's use of the IPC facilities.

Biosym/MSI IPC allows long, double, and character data to be exchanged. All data exchanges are done via IPC Frames which consist of a header describing the data which follow.

To use these routines you need to compile the file ipc.c (C) and link the resulting object (ipc.o) with your program. Note that ipc.c also the file ipc.h.

Parallel Note: On shared-memory parallel machines, use of these functions must be single-threaded and locked to one node, due to static data structures.

C Functions for IPC

BiosymIpc_Init

Function:

Initialize the IPC package. Provide input and output file names. If these are not specified (given as NULL), use the values in the environmental variables BiosymIpcIn and BiosymIpcOut.

The order in which the files are opened is important, since the Discover process that opens these named pipes at the other end does so in this order.

int BiosymIpc_Init(char *inputFilename, char *outputFilename)

BiosymIpc_Shutdown

Function:

Close the file handles associated with the Discover IPC connection.

void BiosymIpc_Shutdown(void)

BiosymIpc_Read

Function:

Read a data entry from the inputFile filehandle. This function blocks until data is available (i.e., until the Discover program needs work from the client). If end-of-file is detected (i.e., Discover has exited or shut down the connection), the endOfFile variable is set to 1 and a 0 is returned. This signals that the client should then shut itself down.

Upon entry, "data" must be non-NULL and point to a BiosymIpcData structure; "endOfFile" must be non-NULL and point to an integer.

Upon successful return, the "data" union member of the BiosymIpcData structure points to allocated memory containing the data received. It is the caller's responsibility to free this storage when it is no longer needed.

int BiosymIpc_Read(BiosymIpcData *data, int *endOfFile)

BiosymIpc_Write

Function:

Write a data entry to the outputFile filehandle. The last data block of a session should flush by setting the flush flag to 1. Flushing the data is necessary to ensure that the Discover program receives it.

int BiosymIpc_Write(BiosymIpcData *data, int flush)

BiosymIpc_Print

Function:

ASCII print the contents of a BiosymIpcData structure. This is intended primarily for debugging purposes.

int BiosymIpc_Print(BiosymIpcData *data, FILE *fp)

BiosymIpc_VarWrite

Function:

Package a variable-length list of strings to be sent via IPC.

int BiosymIpc_VarWrite(char *message, int flush, char *p, ...)

message:  string to place in IPC frame message header field
flush:    if non-zero, flush after done
p:        one or more strings to send

Return value:

0 on success, non-zero on failure.

BiosymIpc_WriteRawBtcl2

Function:

Send all strings from a variable-length list to the IPC output channel. Newlines are optionally placed after each string; a final flush is optionally performed. An IPC frame is not constructed.

int BiosymIpc_WriteRawBtcl2(int noNewLine, int flush, char *p, ...)

noNewLine:  if non-zero, do not append newlines to strings
flush:      if non-zero, flush after done
p:          one or more strings to send

Return value:

0 on success, non-zero on failure.

BiosymIpc_WriteRawBtcl

Function:

Send all strings from a variable-length list to the IPC output channel. Newlines are placed after each string; a final flush is performed. An IPC frame is not constructed.

int BiosymIpc_WriteRawBtcl(...)

Return value:

0 on success, non-zero on failure.

BiosymIpc_SetChannel

Function:

Specify a new pair of FILE pointers for the BiosymIpc functions. The previous input and output FILE pointers are returned through the addresses provided.

Note: to open more than one channel, the procedure is as follows:

{
  FILE *fpIN = NULL;
  FILE *fpOUT = NULL;

  BiosymIpc_SetChannel(&fpIN, &fpOUT);
  BiosymIpc_Init("newInputFile", "newOutputFile");

}

That is, the IPC channel pointers must be set to NULL, NULL before initializing a new channel.

void BiosymIpc_SetChannel(FILE **in, FILE **out)

BiosymIpc_GetError

Function:

Return a pointer to the local error message buffer.

char *BiosymIpc_GetError(void)

BiosymIpc_GetLocalVersion

Function:

Return a pointer to the version of BiosymIpc being used in the program.

char *BiosymIpc_GetLocalVersion(void)

BiosymIpc_GetRemoteVersion

Function:

Return a pointer to the version of BiosymIpc being used in the remote program.

char *BiosymIpc_GetRemoteVersion(void)

Main access page

Advanced-Use access.

IPC Main Page