TipcMonClientBufferSetWatch

Name

TipcMonClientBufferSetWatch — start or stop watching RTclient message-related buffer information

Synopsis

T_BOOL TipcMonClientBufferSetWatch(client_name, watch_status) 
T_STR client_name; 
T_BOOL watch_status; 

Arguments

client_name — name of RTclient to set watch status for (wildcard names allowed, or use T_IPC_MON_ALL to indicate a watch of all RTclients matching the value of Monitor_Scope)

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

Return Values

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

Diagnostics

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

Description

TipcMonClientBufferSetWatch sets whether this RTclient is watching message-related buffer information in the client_name RTclient. The client_name argument can be the unique subject name of a single RTclient, a wildcarded subject name to match many RTclients, or T_IPC_MON_ALL to watch all RTclients in the project that match the value of the Monitor_Scope option. TipcMonClientBufferSetWatch saves the watch status and sends a MON_CLIENT_BUFFER_SET_WATCH message to the client_name RTclient. The watch status controls whether the RTclient receives a MON_CLIENT_BUFFER_STATUS message each time the message queue for the connection to RTserver changes in the watched RTclient. 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_CLIENT_BUFFER_STATUS message contains five fields:

In addition to sending a MON_CLIENT_BUFFER_STATUS message each time the message queue changes, the watched RTclient also sends an initial MON_CLIENT_BUFFER_STATUS message when the watch status is set to TRUE, so that the RTclient does not have to wait for the next message queue change to receive the first MON_CLIENT_BUFFER_STATUS message.

To determine if this RTclient is watching RTclient buffer information, use TipcMonClientBufferGetWatch. To poll once for RTclient buffer information, use TipcMonClientBufferPoll.

For an example of how MON_CLIENT_BUFFER_STATUS messages can be used, see the RTmon GDI Watch Client Buffer window.

Caution

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

There is no initial status message if the RTclient named client_name does not exist.

Buffer changes caused by MON_CLIENT_BUFFER_STATUS, MON_CLIENT_MSG_RECV_STATUS, and MON_CLIENT_MSG_SEND_STATUS message types cannot be watched and are silently ignored by the internal monitoring callbacks that generate outgoing MON_CLIENT_BUFFER_STATUS messages. The callbacks ignore buffer changes due to these message types to prevent infinite loops.

See Also

TipcMonClientBufferGetWatch, TipcMonClientBufferPoll

Examples

This example uses TipcMonClientBufferSetWatch to start watching buffer information in the primary RTclient and creates a callback to process the incoming MON_CLIENT_BUFFER_STATUS messages:

/* =============================================================== */ 
/*..process_mon_client_buffer_status -- process a MON_CLIENT_BUFFER_STATUS message */ 
 
void T_ENTRY process_mon_client_buffer_status(conn, data, arg) 
T_IPC_CONN conn; 
T_IPC_CONN_PROCESS_CB_DATA data; 
T_CB_ARG arg; 
{ 
  T_STR client_name; 
  T_INT4 msg_queue_count; 
  T_INT4 msg_queue_byte_count; 
  T_INT4 read_buffer_count; 
  T_INT4 write_buffer_count; 
 
  /* must set current field first */ 
  if (!TipcMsgSetCurrent(data->msg, 0)) { 
    return;  /* error */ 
  }  
 
  /* get the fields from the message */ 
  if (!TipcMsgRead(data->msg,  
                   T_IPC_FT_STR, &client_name, 
                   T_IPC_FT_INT4, &msg_queue_count, 
                   T_IPC_FT_INT4, &msg_queue_byte_count, 
                   T_IPC_FT_INT4, &read_buffer_count, 
                   T_IPC_FT_INT4, &write_buffer_count, 
                   NULL)) { 
    return;  /* error */ 
  }  
 
  TutOut("Got CLIENT_BUFFER status.\n"); 
  TutOut("RTclient name = %s\n", client_name); 
  TutOut("msg queue count = %d\n", msg_queue_count); 
  TutOut("msg queue byte count = %d\n", msg_queue_byte_count); 
  TutOut("read buffer count = %d\n", read_buffer_count); 
  TutOut("write buffer count = %d\n", write_buffer_count); 
} /* process_mon_client_buffer_status */ 
 
/* =========================================================== */ 
/*...code from calling function is below */ 
 
T_IPC_MT mt; 
 
if (!TipcMonClientBufferSetWatch("primary", TRUE)) { 
  return;  /* error */ 
}  
 
mt = TipcMtLookupByNum(T_MT_MON_CLIENT_BUFFER_STATUS); 
if (mt == NULL) { 
  return;  /* error */ 
} 
 
if (TipcSrvProcessCbCreate(mt, process_mon_client_buffer_status, 
NULL) 
    == NULL) { 
  return;  /* error */ 
} 
 
/* At this point TipcSrvMainLoop can be used to read and process messages. */