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().

4.1. Function Descriptions

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

vdm_DataIPC *vdm_DataIPCBegin(void)

create an instance of a DataIPC object

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)

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

void vdm_DataIPCEnd(vdm_DataIPC *p)

destroy an instance of a DataIPC object

See vdm_DataIPCBegin()

Vint vdm_DataIPCError(vdm_DataIPC *p)

return the current value of a DataIPC object error flag

See vdm_DataIPCBegin()

void vdm_DataIPCDef(vdm_DataIPC *p, Vint type)

define client or server and connection type

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)

Errors: VIS_ERROR_ENUM is generated if an improper type is specified.

Parameters:

p – Pointer to DataIPC object.

type – Connection type

x=DATAIPC_SERVER      Server type
 =DATAIPC_CLIENT      Client type

void vdm_DataIPCInq(vdm_DataIPC *p, Vint *type)

inquire of defined type as output arguments

See vdm_DataIPCDef()

void vdm_DataIPCSetSwap(vdm_DataIPC *p, Vint swap)

Set swap flag for user connection callback.

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

Parameters:

p – Pointer to DataIPC object.
swap – Swap toggle
```
x=SYS_ON
 =SYS_OFF
```

void vdm_DataIPCSetObject(vdm_DataIPC *p, Vint type, Vobject *obj)

Client function to store an object.

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)

Errors

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

Parameters:

p – Pointer to DataIPC object.
type – Object type
```
x=VDM_DATAFUN
```
obj – Object to be stored

void vdm_DataIPCGetObject(vdm_DataIPC *p, Vint type, Vobject **obj)

client function to store an object

See vdm_DataIPCSetObject()

void vdm_DataIPCGetInteger(vdm_DataIPC *p, Vint type, Vint *iparam)

retrieve integer status information

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().

Errors

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

Parameters:

p – Pointer to DataIPC object.

type – Type of parameter to be queried

x=DATAIPC_DATAFUN  The DataFun callback being executed
 =DATAIPC_STATE    Toggle for call before or after execution
 =DATAIPC_FILETYPE Enumerated format currently in use

iparam – [out] Values(s) retrieved

void vdm_DataIPCGetString(vdm_DataIPC *p, Vint type, Vchar *cparam)

retrieve character string status information

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

Errors

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

Parameters:

p – Pointer to DataIPC object.
type – Type of parameter to be queried
```
x=DATAIPC_FILENAME The file name
```
cparam – [out] Values retrieved

void vdm_DataIPCStartServer(vdm_DataIPC *p)

Server function to start communication with client.

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 withvdm_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.

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().

Parameters:: p – Pointer to DataIPC object.

void vdm_DataIPCStopServer(vdm_DataIPC *p)

Client function to stop server’s communication mode.

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.

Errors: VIS_ERROR_OPERATION is generated if mode is DATAIPC_SERVER.

Parameters:: p – Pointer to DataIPC object.

void vdm_DataIPCDataFun(vdm_DataIPC *p, vdm_DataFun *datafun)

Server function to fill a DataFun object.

Fill a DataFun object with interface data functions.

Errors: VIS_ERROR_OPERATION is generated if mode is DATAIPC_CLIENT.

Parameters:

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

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

set a function pointer

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.

Errors: VIS_ERROR_ENUM is generated if an improper functype is specified.

Parameters:

p – Pointer to DataIPC object.

functype – The function type identifier

x=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

void vdm_DataIPCAbort(vdm_DataIPC *p)

abort the client’s listening mode

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().

Parameters:: p – Pointer to DataIPC object.

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

communicate user data to server

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().

Parameters:

p – 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
ndoubles – Number of entries in double array doubles
doubles – Double array

4. Data Function Filters, Interprocess Communication - DataIPC

4.1. Function Descriptions

4. Data Function Filters, Interprocess Communication - DataIPC 