Configuring GMD

If you want to use the default configuration for GMD, there is little configuration required. File-based GMD, rather than memory-only GMD, is the recommended way to use GMD because of its ability to recover from process failures. The main configuration required for file-based GMD is to set the option Unique_Subject to a value other than the default, to a unique and consistent name that no other process on the node is using.

To configure GMD, you set the GMD-related options using the setopt command. Many of these options are not required unless you want to use a value other than the default setting. The GMD options for peer-to-peer connections are the same as the GMD options for RTclients. For more detailed information about the options, see Chapter 8, Options Reference.

Here are the options you can set to change your GMD configuration:

Notes on File-Based GMD

Reverting to Memory-Based GMD

When Unique_Subject is set, and Ipc_Gmd_Type is default, SmartSockets attempts file-based GMD. If file-based GMD cannot be carried out, SmartSockets reverts to memory-based GMD for the message. Generally, when SmartSockets reverts from file-based to memory-based GMD, it is because the file-based GMD area could not be written to, for example, due to a permissions problem.

If file-based GMD cannot be used, a warning is issued and the process switches to memory-only GMD. For example:

WARNING: Could not create GMD file(s) with base name 
<tcp__node_5252_conngmdc> 
for connection <server:tcp:_node:5252:1>. 
The option Unique_Subject must be set to a value other than the 
default (_himalia.talarian.com_10783). 
WARNING: Switching to memory-only GMD. 

To check if a process is properly configured for file-based GMD, use the function TipcGetGmdDir. For example:

if (TipcGetGmdDir() == NULL) { 
  /* process is not configured properly */ 
} 

TipcGetGmdDir attempts to create the needed directories if they do not exist.

Deleting Files From an Old GMD Area

When a process creates a connection, the process may not want to use the file-based GMD information from a previous connection with the same GMD configuration. Some applications, for example, may want to have the concept of a complete restart where all old GMD information is purged. The function TipcConnGmdFileDelete can be used to delete the old GMD files. For example:

if (!TipcConnGmdFileDelete(conn)) { 
  /* error */ 
} 

When a process using GMD creates a client connection with TipcConnCreateClient or accepts a connection from a client with TipcConnAccept, it typically does one of two things:

Creating a GMD Area

Before any messages can be sent or received with GMD, a GMD area must be created with the function TipcConnGmdFileCreate. For example:

if (!TipcConnGmdFileCreate(conn)) { 
  /* error */ 
} 

If the GMD area files already exist on disk, TipcConnGmdFileCreate reads in the contents of the old GMD area. The functions TipcConnRead and TipcConnMsgSend automatically call TipcConnGmdFileCreate to create a GMD area for a connection that needs one. For example, the server example program conngmds.c does not explicitly call TipcConnGmdFileCreate, but instead lets TipcConnMainLoop, which eventually calls TipcConnRead, take care of it. For most applications, both ways are equivalent.

Specifying Ipc_Gmd_Directory

File-based GMD places all files it creates under the directory specified in the option Ipc_Gmd_Directory, which defaults to these locations:

/tmp/rtworks 

sys$scratch 

%TEMP%\rtworks 

The directory specified in Ipc_Gmd_Directory should be on a local file system for best performance. File-based GMD also uses Unique_Subject to generate pathnames for the GMD area. See the reference page for TipcConnGmdFileCreate in the TIBCO SmartSockets Application Programming Interface reference for full details on GMD area pathnames.

Limiting GMD Resources

The resources used by GMD can be constrained by storage used, by elapsed time, or by both.

GMD Area Maximum Size

A connection GMD area uses disk files or memory to store the information needed for GMD. A GMD area has a maximum size (in bytes) that can be used to limit the amount of disk space or memory that a GMD area can use. The default connection GMD area maximum size is 0, which means that no maximum size limit checking is performed. Use the TipcConnGetGmdMaxSize function to get the GMD area maximum size. For example:

if (!TipcConnGetGmdMaxSize(conn, &gmd_max_size)) { 
  /* error */ 
} 

The function TipcConnSetGmdMaxSize is used to set the GMD area maximum size. For example:

/* limit GMD area to one megabyte */ 
if (!TipcConnSetGmdMaxSize(conn, 1000000)) { 
  /* error */ 
} 

If the connection GMD area maximum size is exceeded, then no further messages can be sent with GMD until some unacknowledged, previously-sent messages are acknowledged. This is one of the few synchronous notifications of a GMD-related failure, compared to the asynchronous GMD_FAILURE messages.

Delivery Timeout

The connection delivery timeout property can be used to limit the amount of time that GMD has to deliver each message. This can be useful for real-time applications that need to be notified if a certain action does not take place within a certain period of time. If a different timeout is required for an individual message, the message’s delivery timeout property can instead be set directly.