TipcSrvMonClientNamesSetWatch

watch_status — new watch status (TRUE to start watching, FALSE to stop watching)

Return Values

TRUE if the RTclient names watch status was successfully set, FALSE otherwise.

Diagnostics

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

Description

TipcSrvMonClientNamesSetWatch sets whether this RTclient is watching the RTclient names in the current project that match the value of the Monitor_Scope option. TipcSrvMonClientNamesSetWatch saves the watch status and sends a MON_CLIENT_NAMES_SET_WATCH message to RTserver. The watch status controls whether the RTclient receives a MON_CLIENT_NAMES_STATUS message each time an RTclient is created or destroyed. An RTclient is considered created when it connects to RTserver. An RTclient is considered destroyed when it disconnects from RTserver. The watch status is saved internally so the RTclient can automatically resume watching all appropriate categories if RTclient has to reconnect to RTserver.

The Srv_Client_Names_Min_Msgs option, described in the TIBCO SmartSockets User’s Guide, controls the number of fields returned in the MON_CLIENT_NAMES_STATUS message. If Srv_Client_Names_Min_Msgs is set to FALSE, each MON_CLIENT_NAMES_STATUS message contains the following fields:

a STR_ARRAY field containing the current RTclient names

a STR_ARRAY field containing RTclient info strings of the form "ident: user@node" (such as "Primary_RTclient: ssuser@workstation1")

a STR_ARRAY field containing the name of the RTserver each RTclient is connected to

a STR field containing the name of the created RTclient (or "" if not applicable)

a STR field containing the name of the destroyed RTclient (or "" if not applicable)

a STR field containing the reason for the client's disconnection (or "" if not applicable). This field is returned if the RTserver version is 6.8 or later. The possible disconnect reasons known at the time this document was written are:

disconnect - The client cleanly disconnected.

failure detected - A failure was detected while trying to communicate with the client (in most instances this means a keepalive failed due to network failure or a non-responsive client).

max_buffer exceeded - The client was disconnected by the server because its write buffer exceeded the size allowed by the "client_max_buffer" option.

socket closed - The client unexpectedly closed the socket (an EOF was detected). This would typically occur when a client terminates without first disconnecting (e.g. was CTRL-C'd).

nak failure - The client was disconnected by the group manager due to unrecoverable loss / NAK failure (disconnect_client_on_nak_failure was set to TRUE).

disconnected by group - The client was disconnected by the group connection server (RTgms). This message is used only when the specific reason for the disconnect is not known or is unavailable (which should only happen with a 6.8+ RTserver and a pre-6.8 RTgms).

group connection lost - The connection to the client's group server (RTgms) was lost, either due to network failure or because the RTgms is no longer running, or because the RTserver disconnected the RTgms.

server connection lost - The connection to the client's server was lost, either due to network failure or because the server is no longer running.

server out of memory - The server dropped the connection because it ran out of memory while trying to read from or write to the connection.

gms out of memory - The gms dropped the connection because it ran out of memory while trying to read from or write to the connection.

unknown - The connection was closed for an unknown (or unhandled) reason.

In addition to sending a MON_CLIENT_NAMES_STATUS message each time an RTclient is created or destroyed, RTserver also sends an initial MON_CLIENT_NAMES_STATUS message when the watch status is set to TRUE, so that the RTclient does not have to wait for the next RTclient name change to receive the first MON_CLIENT_NAMES_STATUS message. User’s can limit the size of subsequent MON_CLIENT_NAMES_STATUS messages to only the name of the RTclient created or destroyed and the reason for the destroy by setting the RTserver option Srv_Client_Names_Min_Msgs to TRUE.

To determine if this RTclient is watching RTclient names, use TipcSrvMonClientNamesGetWatch. To poll once for the RTclient names, use TipcSrvMonClientNamesPoll.

Caution

TipcSrvMonClientNamesSetWatch sends a MON_CLIENT_NAMES_SET_WATCH message to RTserver, but does not explicitly flush the message. See TipcSrvConnGetAutoFlushSize for more information on message buffering.

See Also

Examples

This example uses TipcSrvMonClientNamesSetWatch to start watching RTclient names and creates a callback to process the incoming MON_CLIENT_NAMES_STATUS messages:

/* =============================================================== */ 
/*..process_mon_client_names_status -- process a MON_CLIENT_NAMES_STATUS message */ 
void T_ENTRY process_mon_client_names_status(conn, data, arg) 
T_IPC_CONN conn; 
T_IPC_CONN_PROCESS_CB_DATA data; 
T_CB_ARG arg; 
{ 
  T_STR *client_names; 
  T_INT4 num_client_names; 
  T_STR *info_strs; 
  T_STR *server_names; 
  T_STR created_client; 
  T_STR destroyed_client; 
  T_STR reason; 
  T_INT4 counter; 
 
  /* must set current field first */ 
  if (!TipcMsgSetCurrent(data->msg, 0)) { 
    return;  /* error */ 
  }  
 
  /* get the fields from the message */ 
 
  /* client_names, info_strs, and server_names contains the same  
  number of elements */ 
 
  if (!TipcMsgNextStrArray(data->msg, &client_names,  
                           &num_client_names) 
      || !TipcMsgNextStrArray(data->msg, &info_strs, 
                              &num_client_names) 
      || !TipcMsgNextStrArray(data->msg, &server_names, 
                              &num_client_names) 
      || !TipcMsgNextStr(data->msg, &created_client) 
      || !TipcMsgNextStr(data->msg, &destroyed_client)) { 
    return;  /* error */ 
  }  
 
  TutOut("Got CLIENT_NAMES status.\n"); 
  for (counter = 0; counter < num_client_names; counter++) { 
    TutOut("client_names[%d] = %s\n", counter, 
            client_names[counter]); 
    TutOut("info_strs[%d] = %s\n", counter, info_strs[counter]); 
    TutOut("server_names[%d] = %s\n", counter, 
            server_names[counter]); 
  } 
  TutOut("created RTclient = %s\n", created_client); 
  TutOut("destroyed RTclient = %s\n", destroyed_client); 
  if (TipcMsgNextStr(data->msg, &reason)) { 
     TutOut("reason for disconnect = %s\n", reason); 
   } 
} /* process_mon_client_names_status */ 
 
/* =========================================================== */ 
/*...code from calling function is below */ 
 
T_IPC_MT mt; 
 
if (!TipcSrvMonClientNamesSetWatch(srv, TRUE)) { 
  return;  /* error */ 
} 
 
mt = TipcMtLookupByNum(T_MT_MON_CLIENT_NAMES_STATUS); 
if (mt == NULL) { 
  return;  /* error */ 
} 
 
if (TipcSrvConnProcessCbCreate(srv, mt, 
process_mon_client_names_status, NULL) 
    == NULL) { 
  return;  /* error */ 
} 
 
/* At this point TipcSrvConnMainLoop can be used to read and process messages. */