TipcSrvDestroy

Name

TipcSrvDestroy — destroy the connection to RTserver

Synopsis

T_BOOL TipcSrvDestroy(destroy_status) 
T_IPC_SRV_CONN_STATUS destroy_status; 

Arguments

destroy_status — whether to keep a warm connection to RTserver (use T_IPC_SRV_CONN_WARM) or fully destroy the connection to RTserver (use T_IPC_SRV_CONN_NONE)

Return Values

TRUE if the connection to RTserver was successfully destroyed, FALSE otherwise.

Diagnostics

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

Description

TipcSrvDestroy destroys the connection to RTserver. There are two ways to destroy the connection to RTserver. A full destroy removes all of RTclient’s RTserver-related information. Once this has occurred, RTclient can continue as if it had never been connected at all to RTserver. The other mode of TipcSrvDestroy is a warm destroy. A warm destroy keeps as much RTserver-related information as possible. Once this has occurred, RTclient can easily reconnect to RTserver in the future and pick up where it left off. After a warm destroy, RTclient can even partially operate as if it still had a connection to RTserver. Messages can be sent, and they are buffered until a full connection to RTserver is created again. See TipcSrvCreate on automatic creation of connections and warm connections to RTserver.

If RTclient has a full connection to RTserver when TipcSrvDestroy is called and the connection error callbacks aren’t being called (which implies the connection is unusable), then TipcSrvDestroy first tries to send a DISCONNECT message to RTserver. This DISCONNECT message has one field, an integer based on the value of the option Server_Disconnect_Mode. The DISCONNECT message is not necessary for RTserver to detect that RTclient has destroyed its connection to RTserver, but the DISCONNECT message does provide a more graceful disconnect and also allows RTclient to change Server_Disconnect_Mode dynamically before calling TipcSrvDestroy.

TipcSrvDestroy does not destroy any message types, options, server create callbacks, or server destroy callbacks. These entities only need to be created once, not every time TipcSrvCreate is called.

Destroy Status T_IPC_SRV_CONN_WARM

If destroy_status is T_IPC_SRV_CONN_WARM, then TipcSrvDestroy first closes the socket in the connection to RTserver. (As soon as the socket is closed, RTserver destroys its own connection to RTclient.) TipcSrvDestroy then removes all buffered incoming messages from the connection read buffer and all buffered outgoing messages from the connection write buffer. All messages in the connection message queue are left in place, however. TipcSrvDestroy next calls TipcSrvGmdResend to resend any messages for GMD; this primes the warm connection with GMD messages so that sequence number order is preserved. The server destroy callbacks are then called.

Destroy Status T_IPC_SRV_NONE

If destroy_status is T_IPC_SRV_NONE, then TipcSrvDestroy removes all local subject information, destroys all internal callbacks (for options like Server_Read_Timeout and Log_In_Data), destroys the connection, and finally calls the server destroy callbacks.

RTclient Options

The RTclient options (Project, Server_Names, and so on) are only accessed when the RTclient creates a connection to RTserver (see below for special handling for Project, Unique_Subject, and Default_Subject_Prefix). If one of these options is changed, it has no effect until the next time the RTclient creates a connection to RTserver. One possible way of doing this is to destroy the connection to RTserver (but keep it warm) and then create a new connection to RTserver using the warm information. This code can be used to change an option like Project and have it take effect immediately:

/* destroy existing connection to RTserver, but keep it warm */ 
if (!TipcSrvDestroy(T_IPC_SRV_CONN_WARM)) { 
  return;  /* error */ 
} 
 
/* change project */ 
TutCommandParseStr("setopt project new_project"); 
 
/* create a new connection to RTserver from warm info */ 
if (!TipcSrvCreate(T_IPC_SRV_CONN_FULL)) { 
  return;  /* error */ 
} 

The Project option is set as read-only while RTclient has a full connection to RTserver. This prevents confusion from resulting if this option is changed after the full connection is created.

Because the Unique_Subject and Default_Subject_Prefix options may be used each time RTclient publishes a message, these options are set as read-only while RTclient has a warm or full connection to RTserver. This prevents misconfiguration during normal publish-subscribe operation. For a change in Unique_Subject or Default_Subject_Prefix to take effect, the connection to RTserver must be fully destroyed (no warm connection can be left) and recreated.

Caution

An RTclient using the TCP/IP protocol to connect to RTserver may lose outgoing messages if the process terminates without calling TipcSrvDestroy. TCP/IP’s SO_LINGER option, which preserves data, is ignored when closing a socket that has non-blocking I/O enabled. While data loss rarely occurs on UNIX and OpenVMS, it can happen very frequently on Windows. TipcSrvDestroy sets the block mode of the connection to TRUE before closing the connection’s socket, which forces the operating system to deliver all flushed outgoing messages.

Messages that have been sent to RTserver but not flushed may be lost after a call to TipcSrvDestroy.

Use TipcSrvDestroy(T_IPC_SRV_CONN_NONE) with caution from a connection callback such as a connection process callback. Because TipcSrvDestroy(T_IPC_SRV_CONN_NONE) completely destroys the connection, the program crashes if control from the callback is returned to a function such as TipcSrvMainLoop.

See Also

TipcSrvCreate, TipcSrvGetConnStatus

Examples

This example creates a connection to RTserver, sends a message, and then fully destroys the connection to RTserver with TipcSrvDestroy:

T_IPC_MT mt; 
 
/* Create a connection to RTserver. */ 
if (!TipcSrvCreate(T_IPC_SRV_CONN_FULL)) { 
  return;  /* error */ 
}  
 
mt = TipcMtLookupByNum(T_MT_NUMERIC_DATA); 
if (mt == NULL) { 
  return;  /* error */ 
}  
 
/* Send a message and make sure it gets flushed out. */ 
if (!TipcSrvMsgWrite("/system/admin", mt, TRUE, 
                     T_IPC_FT_STR, "speed_limit", 
                     T_IPC_FT_REAL8, 65.0, 
                     NULL)) { 
  return;  /* error */ 
}  
 
if (!TipcSrvFlush()) { 
  return;  /* error */ 
}  
 
/* Fully destroy the connection to RTserver. */ 
if (!TipcSrvDestroy(T_IPC_SRV_CONN_NONE)) { 
  return;  /* error */ 
}