TipcSrvMonClientTimeSetWatch

Name

TipcSrvMonClientTimeSetWatch — start or stop watching RTclient time information

Synopsis

T_BOOL TipcSrvMonClientTimeSetWatch(srv, client_name, watch_status) 
T_IPC_SRV srv; 
T_STR client_name; 
T_BOOL watch_status; 

Arguments

srv — connection handle to RTserver

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 time information watch status was successfully set, FALSE otherwise.

Diagnostics

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

Description

TipcSrvMonClientTimeSetWatch sets whether this RTclient is watching time 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 poll all RTclients in the project that match the value of the Monitor_Scope option. TipcSrvMonClientTimeSetWatch saves the watch status and sends a MON_CLIENT_TIME_SET_WATCH message to the client_name RTclient. The watch status controls whether the RTclient receives a MON_CLIENT_TIME_STATUS message each time the current time 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_TIME_STATUS message contains seven fields:

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

To determine if this RTclient is watching RTclient time information, use TipcSrvMonClientTimeGetWatch. To poll once for RTclient time information, use TipcSrvMonClientTimePoll.

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

Caution

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

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

See Also

TipcSrvMonClientTimeGetWatch, TipcSrvMonClientTimePoll

Examples

This example uses TipcSrvMonClientTimeSetWatch to start watching time information in the primary RTclient and creates a callback to process the incoming MON_CLIENT_TIME_STATUS messages:

/* ===============================================================*/ 
/*..process_mon_client_time_status -- process a MON_CLIENT_TIME_STATUS message */ 
void T_ENTRY process_mon_client_time_status(conn, data, arg) 
T_IPC_CONN conn; 
T_IPC_CONN_PROCESS_CB_DATA data; 
T_CB_ARG arg; 
{ 
  T_STR client_name; 
  T_REAL8 current_time; 
  T_STR current_time_str; 
  T_REAL8 wall_time; 
  T_STR wall_time_str; 
  T_REAL8 cpu_time; 
  T_INT4 frame_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_REAL8, &current_time, 
                   T_IPC_FT_STR, &current_time_str, 
                   T_IPC_FT_REAL8, &wall_time, 
                   T_IPC_FT_STR, &wall_time_str, 
                   T_IPC_FT_REAL8, &cpu_time, 
                   T_IPC_FT_INT4, &frame_count, 
                   NULL)) { 
    return;  /* error */ 
  }  
 
  TutOut("Got CLIENT_TIME status.\n"); 
  TutOut("RTclient name = %s\n", client_name); 
  TutOut("current time = %f\n", current_time); 
  TutOut("current time str = %s\n", current_time_str); 
  TutOut("wall time = %f\n", wall_time); 
  TutOut("wall time str = %s\n", wall_time_str); 
  TutOut("CPU time = %f\n", cpu_time); 
  TutOut("frame count = %d\n", frame_count); 
} /* process_mon_client_time_status */ 
 
/* =========================================================== */ 
/*...code from calling function is below */ 
 
T_IPC_MT mt; 
 
if (!TipcSrvMonClientTimeSetWatch(srv, "primary", TRUE)) { 
  return;  /* error */ 
}  
 
mt = TipcMtLookupByNum(T_MT_MON_CLIENT_TIME_STATUS); 
if (mt == NULL) { 
  return;  /* error */ 
} 
 
if (TipcSrvConnProcessCbCreate(srv, mt, 
process_mon_client_time_status, 
                               NULL) 
    == NULL) { 
  return;  /* error */ 
} 
 
/* At this point TipcSrvConnMainLoop can be used to read and process messages. */