Biosym/MSI IPC Fortran Application Program Interface

FORTRAN functions for IPC:

BiosymIpc_ReadHeaderf - Read IPC frame header.
BiosymIpc_ReadString128f - Read IPC string frame into array of char*128 variables.
BiosymIpc_WriteIntegerf - Write IPC frame of integers.
BiosymIpc_WriteReal8f - Write IPC frame of real*8 values.
BiosymIpc_WriteStringf - Write IPC frame of arbitrary-length strings.
BiosymIpc_WriteString128f - Write series of char*128 variables in strings of specified lengths.
BiosymIpc_WriteBtcl128f - Write series of char*128 variables as BTCL commands.
BiosymIpc_WriteRawBtcl128f - Write array of char*128 variables containing BTCL commands.
BiosymIpc_GetErrorf - Return last BiosymIpc error message.
BiosymIpc_GetLocalVersionf - Return version string for BiosymIpc code used in Discover program.
BiosymIpc_GetRemoteVersionf - Return version string for BiosymIpc code used by remote program.
BiosymIpc_Int2Charf - Convert string from zero-terminated integer array into character variable.
BiosymIpc_Char2Intf - Convert character variable into zero-terminated integer array.
BiosymIpc_Initf - Initialize an IPC connection.
BiosymIpc_ReadIntegerf - Read an IPC integer frame into an array of integers.
BiosymIpc_ReadReal8f - Read an IPC 8-byte real frame into an array of 8-byte reals.
BiosymIpc_ReadStringf - Read an IPC string frame into an array of integers representing the strings.

Background

This is the FORTRAN interface to the Biosym/MSI interprocess communication facilities implemented by the Discover program. A C Language 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 INTEGER, REAL*8, and CHARACTER data to be exchanged. All data exchanges are done via IPC Frames, which consist of a header describing the data which follow.

The routines to write data out (usually to Discover) consist of single function calls. The arguments to the functions describe the data to be sent.

The routines to read data consist of two calls. The first call is always ``BiosymIpc_ReadHeaderf'', which returns information about the data that will follow. The program uses this information to make the appropriate follow-up call that puts the transfered data into a local array.

The few remaining calls perform tasks such as initializing the connection, closing the connection, and determining version information.

Many read and write functions contain numItem and numElement arguments. These arguments are merely descriptive of how the data is organized. For example, coordinates are a common thing to exchange. The Discover program will send coordinates as collections of (x,y,z) with numElement == 3 and numItems == the number of points to be transferred.

To use these routines you need to compile the file ipcf.f (FORTRAN) and the file ipc.c (C). Both resulting objects (ipcf.o and ipc.o) must be linked with your program. Note that ipc.c requires the file ipc.h, and ipcf.f requires the file ipcf.inc.

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.

Subroutines

BiosymIpc_Initf

      SUBROUTINE BiosymIpc_Initf()

Initialize an IPC connection. There is no input or output to the routine. The environmental variables BiosymIpcIn and BiosymIpcOut are set up by the Discover program before the client program is executed; these are used to establish the connection.

BiosymIpc_ReadHeaderf

      SUBROUTINE BiosymIpc_ReadHeaderf(type,
     &     numItem,
     &     numElement,
     &     numByte,
     &     message,
     &     messageMax,
     &     messageLen,
     &     endOfFile,
     &     status)

Read an IPC frame header.

Input:

INTEGER messageMax: maximum characters to transfer from message in IPC frame to message character variable

Output:

INTEGER type: data type, 1 = integer
2 = real*8
3 = string
INTEGER numItem: number of items in data block
INTEGER numElement: number of elements per item
INTEGER numByte: total bytes in data block
CHARACTER*(*) message: message from IPC frame
INTEGER messageLen: actual character length of message, but not greater than messageMax
INTEGER endOfFile: 1 if end of file occurred
INTEGER status: 1 is OK, 0 is error

BiosymIpc_ReadString128f

      SUBROUTINE BiosymIpc_ReadString128f(string,
     &     iString,
     &     iiString,
     &     status)

Read an IPC string frame into an array of character*128 variables.

Input:

INTEGER iString(*): Work space to hold input characters. Must be dimensioned to hold all input characters including NULs at the end of each string.
INTEGER iiString(*): Work space to hold string offsets into iString. Must be dimensioned to the largest number of strings that will be read.

Output:

CHARACTER*128 string(*): An array of strings each of which is no longer than 128 characters.
INTEGER iiString(*): Contains the length of each string.
INTEGER status: 1 is OK, 0 is error.

BiosymIpc_WriteIntegerf

      SUBROUTINE BiosymIpc_WriteIntegerf(data,
     &     numItem,
     &     numElement,
     &     message,
     &     messageLen,
     &     flush,
     &     status)

Write an IPC frame of integers.

Input:

INTEGER data(*): Array containing integers to be sent.
INTEGER numItem: The number of logical groups of integers in data.
INTEGER numElement: The number of integers in each logical group in data.
CHARACTER*(*) message: A message to place in the outgoing IPC frame header.
INTEGER messageLen: Number of valid characters in message.
INTEGER flush: 1 means flush the output pipe;
0 means do not flush the output.

Output:

INTEGER status: 1 is OK, 0 is error.

BiosymIpc_WriteReal8f

      SUBROUTINE BiosymIpc_WriteReal8f(data,
     &     numItem,
     &     numElement,
     &     message,
     &     messageLen,
     &     flush,
     &     status)

Write an IPC frame of real*8 values.

Input:

REAL*8 data(*): Array containing integers to be sent.
INTEGER numItem: The number of logical groups of integers in data.
INTEGER numElement: The number of integers in each logical group in data.
CHARACTER*(*) message: A message to place in the outgoing IPC frame header.
INTEGER messageLen: Number of valid characters in message.
INTEGER flush: 1 means flush the output pipe;
0 means do not flush the output.

Output:

INTEGER status: 1 is OK, 0 is error.

BiosymIpc_WriteStringf

      SUBROUTINE BiosymIpc_WriteStringf(data,
     &     numItem,
     &     numElement,
     &     message,
     &     messageLen,
     &     flush,
     &     status)

Write an IPC frame of arbitrary-length strings.

Input:

INTEGER data(*): Array of integers containing the characters of the strings packed together with each string 0 terminated.
INTEGER numItem: The number of logical groups of integers in data.
INTEGER numElement: The number of integers in each logical group in data.
CHARACTER*(*) message: A message to place in the outgoing IPC frame header.
INTEGER messageLen: Number of valid characters in message.
INTEGER flush: 1 means flush the output pipe;
0 means do not flush the output.

Output:

INTEGER status: 1 is OK, 0 is error.

BiosymIpc_WriteString128f

      SUBROUTINE BiosymIpc_WriteString128f(string,
     &     lenString,
     &     iString,
     &     numItem,
     &     numElement,
     &     message,
     &     messageLen,
     &     flush,
     &     status)

Write a series of char*128 variables in strings with lengths given in the corresponding lenString.

Input:

CHARACTER*128 string: Array of character*128 values to be written in an IPC frame.
INTEGER lenString(*): Number of characters to use from each corresponding entry in string.
INTEGER iString(*): Buffer (must have space for at least the total number of characters (sum of lenString) plus nString.
INTEGER numItem: Number of groupings.
INTEGER numElement: Number of elements per item.
numItem * numElement is the total number of strings.
CHARACTER*(*) message: Message tag for output IPC header.
INTEGER messageLen: Number of characters in message.
INTEGER flush: Non-zero means flush output stream.
INTEGER status: 1 = no error, 0 = error.

BiosymIpc_WriteBtcl128f

      SUBROUTINE BiosymIpc_WriteBtcl128f(command,
     &     nCommand,
     &     noNewline,
     &     iString,
     &     flush,
     &     status)

Write a series of char*128 variables in command. The strings will be interpreted by Discover as a series of BTCL commands to be executed. Discover concatenates all the strings into a single string and evaluates this.

Discover must be waiting in an evaluation loop, collecting IPC frames, and evaluating the contents. See the Discover IPC documentation for how to do this in a Discover script.

Input:

CHARACTER*128 command(*): Array of character*128 values to be written in an IPC frame.
INTEGER nCommand: Number of command strings in command.
INTEGER noNewline: Normally each string is given a newline so that it corresponds to one BTCL command; if noNewline is non-zero, newline characters are not appended to the strings. This allows commands longer than 128 characters to be built up.
INTEGER iString(*): Buffer (must be dimensioned at least 130*nCommand = nCommand*128 + 2*nCommand to accommodate all string data plus possible newlines for each command and a mandatory 0 terminator).
INTEGER flush: Non-zero means flush output stream.
INTEGER status: 1 = no error, 0 = error.

BiosymIpc_WriteRawBtcl128f

      SUBROUTINE BiosymIpc_WriteRawBtcl128f(command,
     &     nCommand,
     &     noNewline,
     &     iString,
     &     flush,
     &     status)

Write an array of character*128 variables which should contain BTCL code. The write is done without an IPC frame header. Discover must be waiting in an evaluation loop, collecting lines, and evaluating them as they form complete commands. See the Discover IPC documentation for how to do this in a Discover script.

The strings are concatenated into one large string for writing as indicated by the noNewline flag.

Input:

CHARACTER*128 command(*): Array of character*128 values.
INTEGER nCommand: Number of strings in command.
INTEGER noNewline: If 1, do not place newlines between strings: just concatenate and output one big string;
if 0, place newline characters between each string and after the last string and output the concatenated string.
INTEGER iString(*): Buffer (must be dimensioned at least 130*nCommand = nCommand*128 + 2*nCommand to accommodate all string data plus possible newlines for each command and a mandatory 0 terminator).
INTEGER flush: Non-zero means flush output stream.
INTEGER status: 1 = no error, 0 = error.

BiosymIpc_GetErrorf

      SUBROUTINE BiosymIpc_GetErrorf(err, maxChar)

Return the last BiosymIpc error message.

Input:

INTEGER maxChar: The maximum number of characters that can be transfered back into the ``err'' variable.

Output:

CHARACTER*(*) err: Contains the error string.

BiosymIpc_GetLocalVersionf

      SUBROUTINE BiosymIpc_GetLocalVersionf(ver, maxChar)

Return the version string for the BiosymIpc code being used in this program.

Input:

INTEGER maxChar: The maximum number of characters that can be transfered back into the "ver" variable.

Output:

CHARACTER*(*) ver: Contains the version string.

BiosymIpc_GetRemoteVersionf

      SUBROUTINE BiosymIpc_GetRemoteVersionf(ver, maxChar)

Return the version string for the BiosymIpc code being used by the remote program.

Input:

INTEGER maxChar: The maximum number of characters that can be transfered back into the ``ver'' variable.

Output:

CHARACTER*(*) ver: Contains the version string.

BiosymIpc_Int2Charf

      SUBROUTINE BiosymIpc_Int2Charf(c, ia, n, l)

Utility to convert a string from a zero-terminated array of integers into a character variable.

Input:

INTEGER ia(*): Zero-terminated integer array of characters.
INTEGER n: Largest number of integers/chars to transfer.

Output:

CHARACTER*(*) c: Filled to n characters and space padded.
INTEGER l: Filled with the actual number of non-zero characters or n if the limit is reached first.

BiosymIpc_Char2Intf

      SUBROUTINE BiosymIpc_Char2Intf(ia, c, n)

Utility to convert a character variable into a zero-terminated array of integers.

Input:

CHARACTER *(*) c: A character variable.
INTEGER n: The largest number of chars to transfer into ia.

Output:

INTEGER ia(*): Filled to n integers. ia(n) is always 0.

BiosymIpc_ReadIntegerf

      SUBROUTINE BiosymIpc_ReadIntegerf(data,
     &     status)

Read an IPC integer frame into an array of integers.

Output:

INTEGER data(*): Incoming integers.
INTEGER status: 1 is OK, 0 is error.

BiosymIpc_ReadReal8f

      SUBROUTINE BiosymIpc_ReadReal8f(data,
     &     status)

Read an IPC 8-byte real frame into an array of 8-byte reals.

Output:

REAL*8 data(*): Incoming real*8 values.
INTEGER status: 1 is OK, 0 is error.

BiosymIpc_ReadStringf

      SUBROUTINE BiosymIpc_ReadStringf(data,
     &     status)

Read an IPC string frame into an array of integers representing the strings. Use BiosymIpc_Int2Charf to convert to Fortran character variables.

Output:

INTEGER data: An array where all the incoming characters are stored as integers. Each individual string is separated by a 0 integer.
INTEGER index: An array of Fortran indices indicating the starting positions of each string in data.
INTEGER retNString: The number of strings read in from the IPC frame.
INTEGER status: 1 is OK, 0 is error.

Main access page

Advanced-Use access.

IPC Main Page