TipcMonClientSubjectPoll

Name

TipcMonClientSubjectPoll — poll once for RTclient subject information

The previous function, TipcMonClientSubjectExPoll, supersedes this function for all new development. Use this older function only when operating with clients prior to release 6.7. This poll can truncate the statistics data that it returns.

Synopsis

T_BOOL TipcMonClientSubjectPoll(client_name, subject_name) 
T_STR client_name; 
T_STR subject_name; 

Arguments

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

subject_name — name of subject to poll for information (use T_IPC_MON_ALL to indicate a poll of all subjects in the polled RTclient)

Return Values

TRUE if the poll for RTclient subject information was successfully initiated, FALSE otherwise.

Diagnostics

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

Description

TipcMonClientSubjectPoll polls for RTclient subject information by sending a MON_CLIENT_SUBJECT_POLL_CALL message to 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. The polled RTclient responds by sending back a MON_CLIENT_SUBJECT_POLL_RESULT message. The response may or may not come back quickly, depending on what the polled RTclient is doing. If subject_name is T_IPC_MON_ALL, and the option monitor_level is set to all, then all subjects ever used in the polled RTclient are polled. The polling RTclient can use functions such as TipcSrvMsgSearchType or TipcSrvMainLoop to get the response.

Each MON_CLIENT_SUBJECT_POLL_RESULT message contains one fixed field followed by one or more groups of five fields. The fixed field is a STR field containing the name of the RTclient. The group of five fields is:

There are multiple responses only if client_name is a wildcard or T_IPC_MON_ALL.

To poll once for global message traffic information, use TipcMonClientMsgTrafficPoll. To poll once for message traffic information by message type, use TipcMonClientMsgTypePoll.

For an example of how MON_CLIENT_SUBJECT_POLL_RESULT messages can be used, see the RTmon GDI Client Subject Message Traffic window.

Caution

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

There is no response message if the RTclient named client_name or the subject named subject_name does not exist; the poll is silently dropped.

RTclient subject information can only be polled, not watched.

There is no way to poll for RTserver subject information.

See Also

TipcMonClientMsgTrafficPoll, TipcSrvMsgWrite

Examples

This example uses TipcMonClientSubjectPoll to poll for all subject information in all RTclients (including this one), creates a callback to process the incoming MON_CLIENT_SUBJECT_POLL_RESULT messages, and then waits up to 10 seconds for the poll results:

/* =============================================================== */ 
/*..process_mon_client_subject_poll_result -- process a 
MON_CLIENT_SUBJECT_POLL_RESULT message */ 
void T_ENTRY process_mon_client_subject_poll_result(conn, data, 
arg) 
T_IPC_CONN conn; 
T_IPC_CONN_PROCESS_CB_DATA data; 
T_CB_ARG arg; 
{ 
  T_STR client_name; 
  T_STR subject_name; 
  T_INT4 total_msg_send; 
  T_INT4 total_msg_recv; 
  T_INT4 total_byte_send; 
  T_INT4 total_byte_recv; 
   
  /* must set current field first */ 
  if (!TipcMsgSetCurrent(data->msg, 0)) { 
    return; /* error */ 
  } 
 
  /* get first fixed field */ 
  if (!TipcMsgNextStr(data->msg, &client_name)) { 
    return; /* error */ 
  } 
  TutOut("Got CLIENT_SUBJECT poll result.\n"); 
  TutOut("RTclient name = %s\n", client_name); 
 
  /* loop through all groups */ 
  while (TipcMsgRead(data->msg,  
                     T_IPC_FT_STR, &subject_name, 
                     T_IPC_FT_INT4, &total_msg_send, 
                     T_IPC_FT_INT4, &total_msg_recv, 
                     T_IPC_FT_INT4, &total_byte_send, 
                     T_IPC_FT_INT4, &total_byte_recv, 
                     NULL)) { 
    TutOut("subject name = %s\n", subject_name); 
    TutOut("total msg send = %d\n", total_msg_send); 
    TutOut("total msg recv = %d\n", total_msg_recv); 
    TutOut("total byte send = %d\n", total_byte_send); 
    TutOut("total byte recv = %d\n", total_byte_recv); 
  } 
 
  /* make sure we reached the end of the message */ 
  if (TutErrNumGet() != T_ERR_MSG_EOM) { 
    return; /* error */ 
  } 
} /* process_mon_client_subject_poll_result */ 
 
/* =========================================================== */ 
/*...code from calling function is below */ 
 
T_IPC_MT mt; 
 
/* send the poll request out to RTserver */ 
if (!TipcMonClientSubjectPoll("/...", T_IPC_MON_ALL)) { 
  return; /* error */ 
}  
mt = TipcMtLookupByNum(T_MT_MON_CLIENT_SUBJECT_POLL_RESULT); 
if (mt == NULL) { 
  return; /* error */ 
} 
if (TipcSrvProcessCbCreate(mt, 
                      process_mon_client_subject_poll_result, 
                      NULL) == NULL) { 
  return; /* error */ 
} 
/* read and process all poll results (as well as any other incoming 
messages) that arrive within the next 10 seconds */ 
if (!TipcSrvMainLoop(10.0)) { 
  return; /* error */ 
}