TipcGetGmdDir

Name

TipcGetGmdDir — get name of directory where files are written for guaranteed message delivery

Synopsis

T_STR TipcGetGmdDir() 

Arguments

None

Return Values

String containing directory name if successful, NULL otherwise.

Diagnostics

If TipcGetGmdDir fails, it returns NULL and sets the global SmartSockets error number to one of:

Description

TipcGetGmdDir returns the name of the directory where guaranteed message delivery (GMD) files are kept. These messages are saved in files so that they can be resent after a program crashes and is restarted. The name of this directory is built from the value of the option Ipc_Gmd_Directory plus gmd plus the value of the option Unique_Subject. The generated components of the directory name are shrunk to 8 characters if they are too long for the native filesystem. (Windows Version 3.1 only allows 8-character file base names, and OpenVMS only allows 39-character file base names.)

For example, a server process with the unique subject server_us communicating with a client process with the unique subject client_us using the logical connection name tcp:workstation1:2042 would use the full pathname:

/tmp/rtworks/gmd/server_us/tcp_workstation1_2042_client_us.hsn 

dka300:[ssuser.gmd.server_us]tcp_workstation1_2042_client_us.hsn 

c:\temp\rtworks\gmd\server_us\tcp_workstation1_2042_client_us.hsn 

For best performance, this directory should be on a local file system.

Each process needs a unique directory where it can store its GMD files, and thus the value of the option Unique_Subject is used to build the name of this directory. Using files allows a program to be restarted and continue sending and receiving messages from exactly where it left off previously. The default value for the Unique_Subject option has the integer process identifier (PID) in it. Because the PID changes on UNIX and Windows systems when a program is rerun, to use GMD files the option Unique_Subject must be set to value other than the default _Node_Pid. If Unique_Subject is not explicitly set by the user, then file-based GMD cannot be used. See the page for TipcSrvConnGmdFileCreate for more information on GMD areas.

Caution

The string returned by TipcGetGmdDir points into an internal data structure and should not be modified.

The most common cause of TipcGetGmdDir failing is not setting the option Unique_Subject to a value other than the default _Node_Pid. Each process that uses file-based GMD must properly configure Unique_Subject.

TipcGetGmdDir uses mkdir as needed to create the directory structure if it does not already exist. If any directories are created, their protection is set to be writable by all users. If world-writable directories are a security risk for a site, create the necessary directories ahead of time with the desired permissions. Read and write access to this directory is required for all authorized users. GMD files are created with the same permission as the directory they are stored in; this allows for easier security configuration.

See Also

TipcSrvConnGmdFileCreate; see the TIBCO SmartSockets Utilities for information on TutGetSocketDir.

Examples

This example uses TipcGetGmdDir to check if this process is configured properly for file-based GMD:

if (TipcGetGmdDir() != NULL) { 
  TutOut("This process is configured properly for file-based 
GMD.\n"); 
} 
else { 
  if (TutErrNumGet() == T_ERR_VAL_REQUIRED) { 
    TutOut("Unique_Subject must be set to a non-default value.\n"); 
  } 
  else if (TutErrNumGet() == T_ERR_C) { 
    TutOut("Creation of GMD dirs failed.\n"); 
    TutPerror("TipcGetGmdDir"); 
  } 
  else { 
    return;  /* error */ 
  } 
}