RTclient GMD Considerations

Configuring RTclient for GMD

The configuration of GMD for the RTclient is similar to the configuration for peer-to-peer connections. The same options apply:

The settings for these options have the same effect for GMD with RTclients as for GMD with peer-to-peer connections. For an RTclient, you can specify the values for the options in the RTclient’s startup command file or by calling the API function TutCommandParseStr, or by calling one of the TutOptionSetType API functions.

For more information, see Configuring GMD.

In addition to these options, you can also specify the option Server_Disconnect_Mode for the RTclient. The Server_Disconnect_Mode option specifies the action RTserver should take when RTclient disconnects from RTserver. The possible values are:

Setting Server_Disconnect_Mode to warm is useful when RTclient must run continuously and not lose any messages even if it crashes or accidentally terminates. In this mode, RTserver remembers the subjects being subscribed to by the disconnecting RTclient and buffers guaranteed messages. When an RTclient with the same value for the option Unique_Subject reconnects to RTserver, RTserver resends the guaranteed messages to RTclient. The option Client_Reconnect_Timeout in RTserver controls the maximum amount of time (in seconds) RTclient has to reconnect. If RTclient does not reconnect to RTserver within Client_Reconnect_Timeout seconds, then RTserver clears the guaranteed messages that have not been acknowledged by this RTclient and sends a GMD_NACK message back to the sender of these messages.

Setting Server_Disconnect_Mode to gmd_failure is useful for short-lived operation. In this mode, RTserver clears the guaranteed messages that have not been acknowledged by this RTclient and sends a GMD_NACK message back to the sender of these messages.

Setting Server_Disconnect_Mode to gmd_success is useful for short-lived operation or when RTclient wants to exit cleanly without causing GMD failure in the publishing process. In this mode, RTserver clears the guaranteed messages that have not been acknowledged by this RTclient and sends a GMD_ACK message back to the sender of these messages.

DISCONNECT Message Type

When RTclient creates a full connection to RTserver by calling TipcSrvCreate(T_IPC_SRV_CONN_FULL), the value of the RTclient option Server_Disconnect_Mode is sent to RTserver in a CONNECT_CALL message. Server_Disconnect_Mode specifies the action RTserver should take when RTclient disconnects from RTserver. To allow RTclient to change Server_Disconnect_Mode before disconnecting, the function TipcSrvDestroy tries to send the value of Server_Disconnect_Mode to RTserver in a DISCONNECT message. This allows an RTclient to easily change Server_Disconnect_Mode before disconnecting (otherwise RTclient would have to disconnect, change the option, reconnect, and then disconnect again).

The DISCONNECT message is not sent if TipcSrvDestroy is being called as the result of a nonrecoverable error on the connection to RTserver. When a nonrecoverable error occurs, no more messages can be sent or received.

Server_Disconnect_Mode and the DISCONNECT message type are somewhat related to warm connections in RTclient, but they control how RTserver handles GMD for a disconnecting RTclient. This provides more robustness for GMD in RTserver, as RTserver does not care if RTclient crashes or exits cleanly; all disconnects are treated the same.

GMD Area

The internal full pathnames used for the RTclient file-based GMD area are simpler than they are for peer-to-peer connections, because the connection to RTserver has a fixed purpose. See the reference page for TipcSrvGmdFileCreate in the TIBCO SmartSockets Application Programming Interface reference for full details on RTclient GMD area pathnames.

RTclient GMD area holds one highest sequence number for each sending RTclient it has received a message (sent with GMD) from. This enables each receiving RTclient to differentiate the sequence numbers from all sending RTclients. The sending RTclients are identified by the value of their Unique_Subject option.

With peer-to-peer connections, messages must be resent with GMD by calling the function TipcConnGmdResend; RTclient does this resending automatically. Both TipcSrvCreate and TipcSrvDestroy(T_IPC_SRV_CONN_WARM) call TipcSrvGmdResend to resend messages from the GMD area. With a warm connection to RTserver, this is needed to prime the warm connection with old GMD messages so as to preserve the proper outgoing message order. It should almost never be necessary to call TipcSrvGmdResend explicitly; it is provided for completeness only.

This automatic resending helps RTclients, especially SmartSockets Modules such as RTie, to use GMD more easily without requiring any extra coding. The only disadvantage of the automatic use of TipcSrvGmdResend is that if TipcSrvGmdFileDelete is used, it must be called before calling TipcSrvCreate.

The TipcSrvCreate function does not create the file-based GMD area directories until they are needed. This helps to prevent large numbers of unused directories from being created for large publish-subscribe projects.

File-based GMD and Connections to Multiple RTservers

For normal global connections, you must set the Unique_Subject option to a value other than the default to use file-based GMD. For multiple connections that connect to multiple RTservers from a single RTclient, you must also set a unique subject for each connection, but not using the Unique_Subject option. Instead, you set a connection’s unique subject using named options or by specifying the unique subject as an argument when you create the connection. Connections are allowed to share the same unique subject only if their projects are different or if they connect to different RTserver clouds.

When you specify file-based GMD, a sub-directory is created in which the messages are written, to be stored in case they need to be resent due to a failure. By default, this sub-directory is named after the RTclient’s unique subject. If you have connections that share the same unique subject, you must specify different GMD sub-directories for each of them, or else they both attempt to use the same GMD sub-directory and cause file conflicts.

To specify a GMD sub-directory for a connection, set the named option Server_Gmd_Dir_Name for the connection or call the TipcSrvConnSetGmdDirName function.