TipcMonServerConnSetWatch

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

Return Values

TRUE if the RTserver connections watch status was successfully set, FALSE otherwise.

Diagnostics

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

Description

TipcMonServerConnSetWatch sets whether this RTclient is watching RTserver connections of the RTservers that match the value of the Monitor_Scope option. TipcMonServerConnSetWatch saves the watch status and sends a MON_SERVER_CONN_SET_WATCH message to RTserver. The watch status controls whether the RTclient receives a MON_SERVER_CONN_STATUS message each time a connection between RTservers is created or destroyed. The watch status is saved internally so the RTclient can automatically resume watching all appropriate categories if RTclient has to reconnect to RTserver.

Each MON_SERVER_CONN_STATUS message contains eight fields (all the array fields have the same number of elements):

a STR_ARRAY field containing the names of the first RTservers on the connections

a STR_ARRAY field containing the names of the second RTservers on the connections

a STR_ARRAY field containing the logical connection names of the connections

an INT4_ARRAY field containing the weights of the connections (always one)

a STR field containing the name of the first RTserver on the created connection (or "" if not applicable)

a STR field containing the name of the second RTserver on the created connection (or "" if not applicable)

a STR field containing the name of the first RTserver on the destroyed connection (or "" if not applicable)

a STR field containing the name of the second RTserver on the destroyed connection (or "" if not applicable)

In addition to sending a MON_SERVER_CONN_STATUS message each time an RTserver connection is created or destroyed, RTserver also sends an initial MON_SERVER_CONN_STATUS message when the watch status is set to TRUE, so that the RTclient does not have to wait for the next RTserver connection change to receive the first MON_SERVER_CONN_STATUS message.

To determine if this RTclient is watching RTserver connections, use TipcMonServerConnGetWatch. To poll once for RTserver connections, use TipcMonServerConnPoll.

For an example of how MON_SERVER_CONN_STATUS messages can be used, see the RTmon GDI Watch Server Connections window.

Caution

TipcMonServerConnSetWatch sends a MON_SERVER_CONN_SET_WATCH message to RTserver, but does not explicitly flush the message. See TipcSrvGetAutoFlushSize for more information on message buffering.

See Also

Examples

This example uses TipcMonServerConnSetWatch to start watching RTserver connections and creates a callback to process the incoming MON_SERVER_CONN_STATUS messages:

/* =============================================================== */ 
/*..process_mon_server_conn_status -- process a MON_SERVER_CONN_STATUS message */ 
void T_ENTRY process_mon_server_conn_status(conn, data, arg) 
T_IPC_CONN conn; 
T_IPC_CONN_PROCESS_CB_DATA data; 
T_CB_ARG arg; 
{ 
  T_STR *server1_names; 
  T_INT4 num_fields; 
  T_STR *server2_names; 
  T_STR *conn_names; 
  T_INT4 *weights; 
  T_STR created_server1; 
  T_STR created_server2; 
  T_STR destroyed_server1; 
  T_STR destroyed_server2; 
  T_INT4 counter; 
 
  /* must set current field first */ 
  if (!TipcMsgSetCurrent(data->msg, 0)) { 
    return; /* error */ 
  }  
 
  /* get the fields from the message */ 
    /* the array fields contain the same number of elements */ 
  if (!TipcMsgNextStrArray(data->msg, &server1_names,  
                           &num_fields) 
      || !TipcMsgNextStrArray(data->msg, &server2_names, 
                              &num_fields) 
      || !TipcMsgNextStrArray(data->msg, &conn_names, 
                              &num_fields) 
      || !TipcMsgNextInt4Array(data->msg, &weights, 
                               &num_fields) 
      || !TipcMsgNextStr(data->msg, &created_server1) 
      || !TipcMsgNextStr(data->msg, &created_server2) 
      || !TipcMsgNextStr(data->msg, &destroyed_server1) 
      || !TipcMsgNextStr(data->msg, &destroyed_server2)) { 
    return; /* error */ 
  }  
 
  TutOut("Got SERVER_CONN status.\n"); 
  for (counter = 0; counter < num_fields; counter++) { 
    TutOut("server1_names[%d] = %s\n", counter, 
           server1_names[counter]); 
    TutOut("server2_names[%d] = %s\n", counter, 
           server2_names[counter]); 
    TutOut("conn_names[%d] = %s\n", counter, 
           conn_names[counter]); 
    TutOut("weights[%d] = %d\n", counter, 
           weights[counter]); 
  } 
  TutOut("created RTserver 1 = %s\n", created_server1); 
  TutOut("created RTserver 2 = %s\n", created_server2); 
  TutOut("destroyed RTserver 1 = %s\n", destroyed_server1); 
  TutOut("destroyed RTserver 2 = %s\n", destroyed_server2); 
} /* process_mon_server_conn_status */ 
 
/* =========================================================== */ 
/*...code from calling function is below */ 
 
T_IPC_MT mt; 
 
if (!TipcMonServerConnSetWatch(TRUE)) { 
  return; /* error */ 
}  
 
mt = TipcMtLookupByNum(T_MT_MON_SERVER_CONN_STATUS); 
if (mt == NULL) { 
  return; /* error */ 
} 
 
if (TipcSrvProcessCbCreate(mt, process_mon_server_conn_status, 
NULL) 
    == NULL) { 
  return; /* error */ 
} 
/* At this point TipcSrvMainLoop can be used to read and process messages. */