4. Data Function Filters, Interprocess Communication - DataIPC

The interprocess communication module, DataIPC, utilizes a client/server approach to data functions. The server component resides in the application that will utilize the data in the datasets, such as nodal coordinates, element connectivity, etc. The client component resides where the file resides, either on the same platform, or on a different computer networked to the server. Client/server platforms need not be homogeneous. For example, the server may be a Linux computer and the client a Windows computer.

Although the same DataIPC module is used for both the server and the client, the applications contain significant differences between them. On the server side the DataIPC module is treated like any other DataFun interface: a file is opened, datasets are read, and the file is closed. On the client side a DataFun object is set into the DataIPC object and DataIPC is put in a listening mode to process requests from the server. Once the server is done with the interprocess communication it tells the client to terminate the listening mode.

The DataIPC module can use either the VSocket module for interprocess communication or a user-defined communication mechanism. If a user-defined mechanism is employed, callback functions for sending and receiving data must be implemented. In this case, it is the user's responsibility to ensure that byte swapping between different platforms is properly accounted for.

The DataIPC module contains the following functions.

Begin and end an instance of an object, generic object functions

*vdm_DataIPCBegin      - create an instance of a DataIPC object
vdm_DataIPCEnd         - destroy an instance of a DataIPC object
vdm_DataIPCError       - return DataIPC object error flag

Initialization functions

vdm_DataIPCDef         - specify client/server and connection type
vdm_DataIPCInq         - inquire for client/server and connection type

User interface functions

vdm_DataIPCSetSwap     - set user interface swap toggle

Server functions

vdm_DataIPCDataFun     - fill a DataFun object
vdm_DataIPCStartServer - initiate server's listening mode

Client functions

vdm_DataIPCStopServer  - terminate server's listening mode
vdm_DataIPCSetObject   - set a DataFun object for processing
vdm_DataIPCGetObject   - get DataFun object used for processing
vdm_DataIPCSetFunction - set monitoring, read, and write functions
vdm_DataIPCGetInteger  - retrieve integer parameters from client
vdm_DataIPCGetString   - retrieve string parameters from client
vdm_DataIPCAbort       - abort client
vdm_DataIPCUser        - communicate user data to server

Instance a DataIPC object using vdm_DataIPCBegin. Once a DataIPC object is instanced, specify whether it will be used as a client or a server and the type of connection with vdm_DataIPCDef. All inter-process communication setup is done externally. Two functions must be set with vdm_DataIPCSetFunction which is a reading and writing function. These depend on the inter-process communication selected by the user. The read function - specified with DATAIPC_FUN_READ - is used internally for receiving data. The write function - specified with DATAIPC_FUN_WRITE - is used for receiving data. Client and server applications need not use the same user-defined read and write functions. Use vdm_DataIPCSetSwap to flag DataIPC to swap bytes between dissimilar machines.

On the client side use vdm_DataIPCDataFun to fill a DataFun object. Once a connection to the client is established, use the DataFun object to retrieve information from the client using vdm_DataFunOpen, vdm_DataFunReadDataset, etc. The client application can interact directly with the server using function vdm_DataIPCUser. If this function is called its parameters are passed to the server via a call-back mechanism whose function pointer is set with vdm_DataIPCSetFunction. If the client is no longer required, terminate the connection with the server with vdm_DataIPCStopServer.

On the server side use vdm_DataIPCSetObject to set a DataFun object. This DataFun object must be filled with the format that will be required of the server when it issues vdm_DataFunOpen. Start the server's communication with a particular client with vdm_DataIPCStartServer. This function call can only be terminated in two ways: either by issuing vdm_DataIPCAbort via a monitor function, or by having the client call vdm_DataIPCStopServer.

Table of Contents

4.1 Function Descriptions

The currently available DataIPC functions are described in detail in this section.

Table of Contents , DataIPC

NAME

*vdm_DataIPCBegin - create an instance of a DataIPC object

C SPECIFICATION

vdm_DAtaIPC *vdm_DataIPCBegin ()

ARGUMENTS

None

FUNCTION RETURN VALUE

The function returns a pointer to the newly created DataIPC object. If the object creation fails, NULL is returned.

DESCRIPTION

Create an instance of an DataIPC object. Memory is allocated for the object private data and the pointer to the data is returned. The default basic coordinate system is the global Cartesian coordinate system.

Destroy an instance of a DataIPC object using

     void vdm_DataIPCEnd (vdm_DataIPC *dataipc)

Return the current value of a DataIPC object error flag using

     Vint vdm_DataIPCError (vdm_DataIPC *dataipc)

Table of Contents , DataIPC

NAME

vdm_DataIPCDef - define client or server and connection type

C SPECIFICATION

void vdm_DataIPCDef (vdm_DataIPC *dataipc,
                     Vint type)

INPUT ARGUMENTS

dataipc      Pointer to DataIPC object.
type         Connection type
             =DATAIPC_SERVER      Server type
             =DATAIPC_CLIENT      Client type

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_ENUM is generated if an improper type is specified.

DESCRIPTION

Define whether the DataIPC object will be used in server or client mode.

Inquire of defined type as output arguments using

     void vdm_DataIPCInq (vdm_DataIPC *dataipc,
                          Vint *type)

Table of Contents , DataIPC

NAME

vdm_DataIPCSetSwap - Set swap flag for user connection callback

C SPECIFICATION

void vdm_DataIPCSetSwap (vdm_DataIPC *dataipc,
                         Vint swap)

INPUT ARGUMENTS

dataipc      Pointer to DataIPC object.
swap         Swap toggle
             =SYS_ON
             =SYS_OFF

OUTPUT ARGUMENTS

None

ERRORS

None

DESCRIPTION

If swapping is specified then it occurs after each call to the DATAIPC_FUN_READ function. Defaults to SYS_OFF.

Table of Contents , DataIPC

NAME

vdm_DataIPCDataFun - Server function to fill a DataFun object

C SPECIFICATION

void vdm_DataIPCDataFun (vdm_DataIPC *dataipc,
                         vdm_DataFun *datafun)

INPUT ARGUMENTS

dataipc      Pointer to DataIPC object.
datafun      Pointer to DataFun object to be filled with data functions

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_OPERATION is generated if mode is DATAIPC_CLIENT.

DESCRIPTION

Fill a DataFun object with interface data functions.

Table of Contents , DataIPC

NAME

vdm_DataIPCStopServer - Client function to stop server's communication mode

C SPECIFICATION

void vdm_DataIPCStopServer (vdm_DataIPC *dataipc)

INPUT ARGUMENTS

dataipc      Pointer to DataIPC object.

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_OPERATION is generated if mode is DATAIPC_SERVER.

DESCRIPTION

Sends a signal to server process to stop the communication with the specific client. This interrupts the call to vdm_DataIPCStartServer initiated on the server side.

Table of Contents , DataIPC

NAME

vdm_DataIPCSetObject - Client function to store an object

C SPECIFICATION

void vdm_DataIPCSetObject (vdm_DataIPC *dataipc,
                           Vint type,
                           Vobject *obj)

INPUT ARGUMENTS

dataipc      Pointer to DataIPC object.
type         Object type
             =VDM_DATAFUN
obj          Object to be stored

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_OPERATION is generated if mode is DATAIPC_SERVER. VIS_ERROR_ENUM is generated if type is invalid.

DESCRIPTION

If type is set to VDM_DATAFUN then a DataFun object is stored. This object will be used by the client to process all requests generated by the server.

     void vis_DataIPCGetObject (vdm_DataIPC *dataipc,
                                Vint type,
                                Vobject **obj)

Table of Contents , DataIPC

NAME

vdm_DataIPCStartServer - Server function to start communication with client

C SPECIFICATION

void vdm_DataIPCStartServer (vdm_DataIPC *dataipc)

INPUT ARGUMENTS

dataipc      Pointer to DataIPC object.

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_OPERATION is generated if mode is DATAIPC_CLIENT, or if vdm_DataIPCSetObject has not been called to set the VDM_DATAFUN object, or if one of DATAIPC_FUN_READ or DATAIPC_FUN_WRITE has not been set with vdm_DataIPCSetFunction.

DESCRIPTION

Starts the server's listening mode. This is an infinite loop that can be terminated from the client with the command vdm_DataIPCStopServer, or from the server with vdm_DataIPCAbort called from within a monitoring function. During this communication mode the server receives commands from the client, and processes them by sending the client the requested data.

Table of Contents , DataIPC

NAME

vdm_DataIPCSetFunction - set a function pointer

C SPECIFICATION

void vdm_DataIPCSetFunction (vdm_DataIPC *dataipc,
                             Vint functype,
                             Vfunc *function,
                             Vobject *object)

INPUT ARGUMENTS

dataipc    Pointer to DataIPC object.
functype   The function type identifier
           =DATAIPC_FUN_MONITOR      Monitoring function
           =DATAIPC_FUN_READ         Reading function
           =DATAIPC_FUN_WRITE        Writing function
           =DATAIPC_FUN_USER         Function to interact with client
function   Pointer to the function to be called
object     Pointer to a user object to be passed to the monitoring function

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_ENUM is generated if an improper functype is specified.

DESCRIPTION

Set a pointer to a function. By default, all function pointers are NULL.

The DATAIPC_FUN_MONITOR prototype is

   void function (vdm_DataIPC *dataipc, Vobject *object)

A callback is not invoked if it is NULL. The methods vdm_DataIPCAbort, vdm_DataIPCGetInteger, and vdm_DataIPCGetString can be called from within the monitoring function if necessary. The first aborts the client's listening mode, while the second and third functions provides information on its status.

The DATAIPC_FUN_READ prototype is

   void function (Vobject *obj, Vint size, Vchar *buffer)

The first argument object is the user's object. The second argument size is the number of bytes being sent. The third argument buffer is the binary data being received. If vdm_DataIPCSetSwap is called indicating that swapping is to take place, then DataIPC will perform the swapping after the data is received. DataIPC will not swap character strings.

The DATAIPC_FUN_WRITE prototype is

   void function (Vobject *object, Vint size, Vchar *buffer)

The first argument object is the user's object. The second argument size is the number of bytes being sent. The third argument buffer is the binary data being sent.

The DATAIPC_FUN_USER prototype is

   void function (vdm_DataIPC *dataipc, vdm_DataFun *datafun,
                  Vint nchars, Vchar chars[], Vint nints, Vint ints[],
                  Vint nfloats, Vfloat floats[], Vint ndoubles,
                  Vdouble doubles[])

This function uses no user object. The first argument is the server's DataIPC object. The second is the DataFun object set on the server. The remaining arguments come directly from the client through function vdm_DataIPCUser. These arguments can be updated by the user and are sent back to the client once the function terminates.

Table of Contents , DataIPC

NAME

vdm_DataIPCGetInteger - retrieve integer status information

C SPECIFICATION

void vdm_DataIPCGetInteger (vdm_DataIPC *dataipc,
                            Vint type,
                            Vint iparam[])

INPUT ARGUMENTS

dataipc      Pointer to DataIPC object.
type         Type of parameter to be queried
             =DATAIPC_DATAFUN  The DataFun callback being executed
             =DATAIPC_STATE    Toggle for call before or after execution
             =DATAIPC_FILETYPE Enumerated format currently in use

OUTPUT ARGUMENTS

iparam       Values(s) retrieved

ERRORS

VIS_ERROR_OPERATION is generated if mode is DATAIPC_SERVER. VIS_ERROR_ENUM is generated if type is invalid.

DESCRIPTION

If DATAIPC_DATAFUN is requested then iparam is one of DATAFUN_OPEN, DATAFUN_SETMODE, DATAFUN_SETCONVENTION, DATAFUN_SETSTATUS, DATAFUN_SETIDS, DATAFUN_GETNUMENTITIES, DATAFUN_GETLIBRARY, DATAFUN_READDATASET, DATAFUN_READDATASETCOLS, DATAFUN_CLOSE, or DATAFUN_APPEND. If DATAIPC_STATE is requested, then iparam is one of DATAIPC_BEFORE or DATAIPC_AFTER, indicating that the monitoring function is being called either before or after the DataFun called specified by DATAIPC_DATAFUN. If DATAIPC_FILETYPE is requested, then iparam returns the last argument of vdm_DataFunOpen.

Table of Contents , DataIPC

NAME

vdm_DataIPCGetString - retrieve character string status information

C SPECIFICATION

void vdm_DataIPCGetString (vdm_DataIPC *dataipc,
                           Vint type,
                           Vchar cparam[])

INPUT ARGUMENTS

dataipc      Pointer to DataIPC object.
type         Type of parameter to be queried
             =DATAIPC_FILENAME The file name

OUTPUT ARGUMENTS

cparam       Values retrieved

ERRORS

VIS_ERROR_OPERATION is generated if mode is DATAIPC_SERVER. VIS_ERROR_ENUM is generated if type is invalid.

DESCRIPTION

If DATAIPC_FILENAME is requested, then cparam is the third argument to vdm_DataFunOpen.

Table of Contents , DataIPC

NAME

vdm_DataIPCAbort - abort the client's listening mode

C SPECIFICATION

void vdm_DataIPCAbort (vdm_DataIPC *dataipc)

INPUT ARGUMENTS

dataipc      Pointer to DataIPC object.

OUTPUT ARGUMENTS

None

ERRORS

None

DESCRIPTION

Aborts the client's listening mode. If the client is aborted in this mode, then all subsequent calls by the server to retrieve data from the client will generate VIS_ERROR_OPERATION. This error is only cleared if the client issues vdm_DataIPCError, vdm_DataIPCDef, or vdm_DataIPCStartServer.

Table of Contents , DataIPC

NAME

vdm_DataIPCUser - communicate user data to server

C SPECIFICATION

void vdm_DataIPCUser (vdm_DataIPC *dataipc,
                      Vint nchars,
                      Vchar chars[],
                      Vint nints,
                      Vint ints[],
                      Vint nfloats[],
                      Vfloat floats[],
                      Vint ndoubles,
                      Vdouble doubles[])

INPUT ARGUMENTS

dataipc      Pointer to DataIPC object.
nchars       Number of entries in character array chars
chars        String array
nints        Number of entries in integer array ints
ints         Integer array
nfloats      Number of entries in float array floats
floats       Float array
ndouble      Number of entries in double array doubles
doubles      Double array

OUTPUT ARGUMENTS

None

ERRORS

None

DESCRIPTION

Passes the arguments nchars, chars, nints, ints, nfloats, floats, ndoubles, and doubles directly to a call-back function on the server.

On the server side the call-back function is set with vdm_DataIPCSetFunction with function type set to DATAIPC_FUN_USER. The call-back function's arguments are described in vdm_DataIPCSetFunction.