Polling

Polling for information allows you to receive a one-time snapshot of information. Polling can be done at regular time intervals by issuing poll requests repeatedly. All polling of a project goes through RTserver. Typically, a request for particular information is sent to RTserver, then RTserver retrieves the information from its internal tables, from other RTservers, or from RTclients and sends it back to the requesting program.

The type of information polled about projects, RTservers, RTclients, and subjects, is shown in the table. The table lists the entity from where the information is available (RTclient, RTserver, subject), a brief description of the information available, whether the information can be watched as well as polled, and the final column shows the TipcMon* API call that initiates the polling and then the monitoring message type returned. The prefix T_MT_ is omitted from the message type for the sake of brevity.


Entity	Information Available	Watch?	API Function and Message Type Returned (T_MT_ omitted)
Project	Names	Yes	TipcMonProjectNamesPoll MON_PROJECT_NAMES_POLL_RESULT
RTclient	Read and write message buffers	Yes	TipcMonClientBufferPoll MON_CLIENT_BUFFER_POLL_RESULT
RTclient	Callback summary	No	TipcMonClientCbPoll MON_CLIENT_CB_POLL_RESULT
RTclient	CPU percentage used	No	TipcMonClientCpuPoll MON_CLIENT_CPU_POLL_RESULT
RTclient	Extension data	No	TipcMonClientExtPoll MON_CLIENT_EXT_POLL_RESULT
RTclient	General (process)	No	TipcMonClientGeneralPoll MON_CLIENT_GENERAL_POLL_RESULT
RTclient	General information	No	TipcMonClientInfoPoll MON_CLIENT_INFO_POLL_RESULT
RTclient	Message traffic	No	TipcMonClientMsgTrafficPoll MON_CLIENT_MSG_TRAFFIC_POLL_RESULT
RTclient	Message types	No	TipcMonClientMsgTypeExPoll MON_CLIENT_MSG_TYPE_EX_POLL_RESULT
RTclient	Names	Yes	TipcMonClientNamesPoll MON_CLIENT_NAMES_POLL_RESULT
RTclient	Options	No	TipcMonClientOptionPoll MON_CLIENT_OPTION_POLL_RESULT
RTclient	Summary of messages sent or received from a subject	No	TipcMonClientSubjectExPoll MON_CLIENT_SUBJECT_EX_POLL_RESULT
RTclient	Subjects subscribing to	Yes	TipcMonClientSubscribePoll MON_CLIENT_SUBSCRIBE_POLL_RESULT
RTclient	Wall time, CPU time used	Yes	TipcMonClientTimePoll MON_CLIENT_TIME_POLL_RESULT
RTclient	Version	No	TipcMonClientVersionPoll MON_CLIENT_VERSION_POLL_RESULT
RTserver	Number of RTclients in a project	No	TipcMonClientNamesNumPoll MON_CLIENT_NAMES_NUM_POLL_RESULT
RTserver	Number of subjects a client subscribes to	No	TipcMonClientSubscribeNumPoll MON_CLIENT_SUBSCRIBE_NUM_POLL_RESULT
RTserver	Read and write message buffers	No	TipcMonServerBufferPoll MON_SERVER_BUFFER_POLL_RESULT
RTserver	Connections	Yes	TipcMonServerConnPoll MON_SERVER_CONN_POLL_RESULT
RTserver	CPU percentage used	No	TipcMonServerCpuPoll MON_SERVER_CPU_POLL_RESULT
RTserver	General (process)	No	TipcMonServerGeneralPoll MON_SERVER_GENERAL_POLL_RESULT
RTserver	Message traffic	No	TipcMonServerMsgTrafficExPoll MON_SERVER_MSG_TRAFFIC_EX_POLL_RESULT
RTserver	Names	Yes	TipcMonServerNamesPoll MON_SERVER_NAMES_POLL_RESULT
RTserver	Options	No	TipcMonServerOptionPoll MON_SERVER_OPTION_POLL_RESULT
RTserver	Routes	No	TipcMonServerRoutePoll MON_SERVER_ROUTE_POLL_RESULT
RTserver	Start time and elapsed time	No	TipcMonServerStartTimePoll MON_SERVER_START_TIME_POLL_RESULT
RTserver	Wall time, CPU time used	No	TipcMonServerTimePoll MON_SERVER_TIME_POLL_RESULT
RTserver	Version	No	TipcMonServerVersionPoll MON_SERVER_VERSION_POLL_RESULT
subject	Names	Yes	TipcMonSubjectNamesPoll MON_SUBJECT_NAMES_POLL_RESULT
subject	Clients subscribing to	Yes	TipcMonSubjectSubscribePoll MON_SUBJECT_SUBSCRIBE_POLL_RESULT

Some information that can be polled can also be watched. See Watching for more details on watching information.

To initiate a polling request in your program, call an API function, TipcMonTypePoll, where Type is the kind of information you wish to request. For example, a call to TipcMonSubjectSubscribePoll initiates a poll for information about which RTclients are subscribing to a specified subject, and a call to TipcMonClientTimePoll initiates a poll for time information about an RTclient.

Calling a TipcMonTypePoll function causes a message of type MON_TYPE_POLL_CALL to be sent to RTserver, where TYPE is the kind of information being requested. This TYPE is very similar to the Type used in the name of the API function as shown in these examples:

RTserver may already hold the information requested, RTserver may need to ask other RTservers for the information, or RTserver may need to forward the message to one or more RTclients to retrieve the information. If RTserver holds the information, the response should come back quickly. For example, you can poll for the names of all projects that RTserver knows about.

If the RTclient has the information, the response may or may not come back quickly depending on how busy the RTclient is. For example, you can poll for information about an RTclient’s message buffers. If RTserver must gather the requested information from an RTclient, the RTclient must read and process messages through calls to TipcSrvMainLoop, TipcSrvMsgNext, TipcMsgSearch, or TipcMsgSearchType in order for the poll request to be returned.

RTserver returns requested information in a MON_TYPE_POLL_RESULT message, where TYPE matches the TYPE in the MON_TYPE_POLL_CALL that initiated the request. The message types are in pairs of MON_TYPE_POLL_CALL and MON_TYPE_POLL_RESULT as shown in these examples:

A complete listing and description of these message types are described in Polling Message Types. The message grammars for all monitoring message types are described in Monitoring Message Types.

Processing Poll Results

When the results of a poll are returned in a MON_TYPE_POLL_RESULT message, the message is processed in one of these two ways:

Typically, after performing a one-time poll for information, the program blocks and waits for the result before continuing. For example, you can poll to find out if any RTclients are subscribing to a subject prior to sending a message. When polling often, or watching for information, using callbacks is usually the preferred method, as it is unclear when the monitoring results may be returned to the program. The sections that follow present examples of how to process poll results using both methods.

Using the TipcMsgSearchType Function

This example shows how to issue a poll request and then use TipcMsgSearchType to block and search for the results (for up to 10 seconds):

T_IPC_MT mt; 
T_IPC_MSG msg; 
T_STR *project_names; 
T_INT4 num_project_names; 
/* send the poll request out to RTserver */ 
if (!TipcMonProjectNamesPoll()) { 
  /* error */ 
}  
 
mt = TipcMtLookupByNum(T_MT_MON_PROJECT_NAMES_POLL_RESULT); 
if (mt == NULL) { 
  /* error */ 
}  
 
/* wait up to 10 seconds for the poll result */ 
msg = TipcSrvMsgSearchType(10.0, mt); 
if (msg == NULL) { 
  /* error */ 
}  
 
/* access the fields of the returned message */ 
if (!TipcMsgSetCurrent(msg, 0)) { 
  /* error */ 
} 
 
if (!TipcMsgNextStrArray(msg, &project_names, &num_project_names)) 
{ 
  /* error */ 
} 
 
/* do whatever here with the poll results */ 
 
/* clean up */ 
if (!TipcMsgDestroy(msg)) { 
  /* error */ 
}

Using Callbacks

This example shows how to use an RTclient message process callback (created with TipcSrvProcessCbCreate) to process the message containing the poll result:

/*..process_project_names_poll - callback to process  
                            MON_PROJECT_NAMES_POLL_RESULT */ 
static void T_ENTRY process_project_names_poll( 
                      T_IPC_CONN conn, 
                      T_IPC_CONN_PROCESS_CB_DATA data, 
                      T_CB_ARG arg) 
{ 
  T_STR *project_names; 
  T_INT4 num_project_names; 
 
  /* access the fields of the returned message */ 
  if (!TipcMsgSetCurrent(data->msg, 0)) { 
    /* error */ 
  } 
 
  if (!TipcMsgNextStrArray(data->msg, &project_names,  
                           &num_project_names)) { 
    /* error */ 
  } 
 
  /* do whatever here with poll results */ 
} /* process_project_names_poll */ 
 
/* =============================================================== */ 
/* ... later, in main program */ 
 
T_IPC_MT mt; 
 
/* create callback to process MON_PROJECT_NAMES poll results */ 
mt = TipcMtLookupByNum(T_MT_MON_PROJECT_NAMES_POLL_RESULT); 
if (mt == NULL) { 
  /* error */ 
} 
 
if (TipcSrvProcessCbCreate(mt, process_project_names_poll, NULL) 
    == NULL){ 
  /* error */ 
} 
 
/* send the poll request out to RTserver */ 
if (!TipcMonProjectNamesPoll()) { 
  /* error */ 
} 
 
/* TipcSrvMainLoop may be called here */

Polling Message Types

This section contains a complete listing of each polling message type. For each message pair (MON_TYPE_POLL_CALL and MON_TYPE_POLL_RESULT), a description of the type of information, the API function, and where the information is collected from is shown. Information gathered from RTserver should come back quickly, while information gathered from RTclient may or may not.

The T_MT_ prefix is omitted from the name of each message type for the sake of brevity.

MON_CLIENT_BUFFER_POLL_*

The MON_CLIENT_BUFFER_POLL_CALL message type is used to request message-related buffer information about one or more RTclients in a project. The polled RTclients respond by sending back MON_CLIENT_BUFFER_POLL_RESULT messages.

MON_CLIENT_CB_POLL_*

The MON_CLIENT_CB_POLL_CALL message type is used to request callback information about one or more RTclients in a project. The polled RTclients respond by sending back a MON_CLIENT_CB_POLL_RESULT message.

MON_CLIENT_CPU_POLL_*

The MON_CLIENT_CPU_POLL_CALL message type is used to request CPU usage information about one or more RTclients in a project. The polled RTclients respond by sending back MON_CLIENT_CPU_POLL_RESULT messages.

MON_CLIENT_EXT_POLL_*

The MON_CLIENT_EXT_POLL_CALL message type is used to request RTclient extension data. Extension data is information created by an RTclient. You must use the TipcMonExt* APIs to define and update the fields of an RTclient’s MON_CLIENT_EXT_POLL_RESULT message for extension data. The polled RTclients respond by sending back MON_CLIENT_EXT_POLL_RESULT messages.

MON_CLIENT_GENERAL_POLL_*

The MON_CLIENT_GENERAL_POLL_CALL message type is used to request general information about one or more RTclients in a project. The polled RTclients respond by sending back a MON_CLIENT_GENERAL_POLL_RESULT message.

MON_CLIENT_INFO_POLL_*

The MON_CLIENT_INFO_POLL_CALL message type is used to request general information, including CPU usage, about one or more RTclients in a project. The polled RTclients respond by sending back MON_CLIENT_INFO_POLL_RESULT messages.

MON_CLIENT_MSG_TRAFFIC_POLL_*

The MON_CLIENT_MSG_TRAFFIC_POLL_CALL message type is used to request message traffic information about one or more RTclients in a project. The polled RTclients respond by sending back a MON_CLIENT_MSG_TRAFFIC_POLL_RESULT message.

MON_CLIENT_MSG_TYPE_EX_POLL_*

The MON_CLIENT_MSG_TYPE_EX_POLL_CALL message type is used to request message type information about one or more RTclients in a project. The polled RTclients respond by sending back a MON_CLIENT_MSG_TYPE_POLL_EX_RESULT message.

MON_CLIENT_NAMES_NUM_POLL_*

The MON_CLIENT_NAMES_NUM_POLL_CALL message type is used to request the number of RTclients in an RTserver cloud. The polled RTclients respond by sending back MON_CLIENT_NAMES_NUM_POLL_RESULT messages.

MON_CLIENT_NAMES_POLL_*

The MON_CLIENT_NAMES_POLL_CALL message type is used to request the running RTclient names in the current project. RTserver responds by sending back a MON_CLIENT_NAMES_POLL_RESULT message.

MON_CLIENT_OPTION_POLL_*

The MON_CLIENT_OPTION_POLL_CALL message type is used to request option information about one or more RTclients in a project. The polled RTclients respond by sending back a MON_CLIENT_OPTION_POLL_RESULT message.

MON_CLIENT_SUBJECT_EX_POLL_*

The MON_CLIENT_SUBJECT_EX_POLL_CALL message type is used to request subject information about one or more RTclients in a project. The polled RTclients respond by sending back a MON_CLIENT_SUBJECT_EX_POLL_RESULT message.

MON_CLIENT_SUBSCRIBE_NUM_POLL_*

The MON_CLIENT_SUBSCRIBE_NUM_POLL_CALL message type is used to request the number of subjects subscribed to by one or more RTclients in a project. The polled RTclients respond by sending back MON_CLIENT_SUBSCRIBE_NUM_POLL_RESULT messages.

MON_CLIENT_SUBSCRIBE_POLL_*

The MON_CLIENT_SUBSCRIBE_POLL_CALL message type is used to request the current subjects to which one or more RTclients in a project are subscribing. RTserver responds by sending back a MON_CLIENT_SUBSCRIBE_POLL_RESULT message for each RTclient specified.

MON_CLIENT_TIME_POLL_*

The MON_CLIENT_TIME_POLL_CALL message type is used to request time information about one or more RTclients in a project. The polled RTclients respond by sending back MON_CLIENT_TIME_POLL_RESULT messages.

MON_CLIENT_VERSION_POLL_*

The MON_CLIENT_VERSION_POLL_CALL message type is used to request client version of one or more RTclients in a project. The polled RTclients respond by sending back MON_CLIENT_VERSION_POLL_RESULT messages.

MON_PROJECT_NAMES_POLL_*

The MON_PROJECT_NAMES_POLL_CALL message type is used to request the current project names from RTserver. RTserver responds by sending back a MON_PROJECT_NAMES_POLL_RESULT message.

MON_SERVER_BUFFER_POLL_*

The MON_SERVER_BUFFER_POLL_CALL message type is used to request message-related buffer information about one or more RTservers in an RTserver group. The polled RTservers respond by sending back a MON_SERVER_BUFFER_POLL_RESULT message.

MON_SERVER_CONN_POLL_*

The MON_SERVER_CONN_POLL_CALL message type is used to request connection information about one or more RTservers in an RTserver group. The polled RTservers respond by sending back a MON_SERVER_CONN_POLL_RESULT message.

MON_SERVER_CPU_POLL_*

The MON_SERVER_CPU_POLL_CALL message type is used to request CPU usage information about one or more RTservers in a project. The polled RTclients respond by sending back MON_SERVER_CPU_POLL_RESULT messages.

MON_SERVER_GENERAL_POLL_*

The MON_SERVER_GENERAL_POLL_CALL message type is used to request general process information about one or more RTservers in an RTserver group. The polled RTservers respond by sending back a MON_SERVER_GENERAL_POLL_RESULT message.

MON_SERVER_MSG_TRAFFIC_EX_POLL_*

The MON_SERVER_MSG_TRAFFIC_EX_POLL_CALL message type is used to request message traffic information about one or more RTservers in an RTserver group. The polled RTservers respond by sending back a MON_SERVER_MSG_TRAFFIC_EX_POLL_RESULT message.

MON_SERVER_NAMES_POLL_*

The MON_SERVER_NAMES_POLL_CALL message type is used to request the running RTserver names. RTserver responds by sending back a MON_SERVER_NAMES_POLL_RESULT message.

MON_SERVER_OPTION_POLL_*

The MON_SERVER_OPTION_POLL_CALL message type is used to request option information about one or more RTservers in an RTserver group. The polled RTservers respond by sending back a MON_SERVER_OPTION_POLL_RESULT message.

MON_SERVER_ROUTE_POLL_*

The MON_SERVER_ROUTE_POLL_CALL message type is used to request route information about one or more RTservers in an RTserver group. The polled RTservers respond by sending back a MON_SERVER_ROUTE_POLL_RESULT message.

MON_SERVER_START_TIME_POLL_*

The MON_SERVER_START_TIME_POLL_CALL message type is used to request start time and elapsed time information about one or more RTservers in an RTserver group. The polled RTservers respond by sending back MON_SERVER_START_TIME_POLL_RESULT messages.

MON_SERVER_TIME_POLL_*

The MON_SERVER_TIME_POLL_CALL message type is used to request time information (wall time and CPU timed used) about one or more RTservers in an RTserver group. The polled RTservers respond by sending back a MON_SERVER_TIME_POLL_RESULT message.

MON_SERVER_VERSION_POLL_*

The MON_SERVER_VERSION_POLL_CALL message type is used to request server version of one or more RTservers in a project. The polled RTservers respond by sending back MON_SERVER_VERSION_POLL_RESULT messages.

MON_SUBJECT_NAMES_POLL_*

The MON_SUBJECT_NAMES_POLL_CALL message type is used to request the current subject names in the current project. RTserver responds by sending back a MON_SUBJECT_NAMES_POLL_RESULT message.

MON_SUBJECT_SUBSCRIBE_POLL_*

The MON_SUBJECT_SUBSCRIBE_POLL_CALL message type is used to request the current RTclients that are subscribing to a specified subject or all subjects. RTserver responds by sending back a MON_SUBJECT_SUBSCRIBE_POLL_RESULT message for each subject.

Polling Example

The following is a complete C source example of a program that continues to poll for message traffic information at a regular interval, where the interval (in seconds) is one of the command line arguments passed in to the program.

	This poll supersedes the MON_CLIENT_MSG_TYPE_POLL_* poll for new development. See TipcMonClientMsgTypePoll in the TIBCO SmartSockets Application Programming Interface guide for more information. The MON_CLIENT_MSG_TYPE_POLL_* is retained for compatibility with clients prior to release 6.7.

	This poll supersedes the MON_CLIENT_SUBJECT_POLL_* poll for new development. See TipcMonClientSubjectPoll in the TIBCO SmartSockets Application Programming Interface guide for more information. The MON_CLIENT_SUBJECT_POLL_* is retained for compatibility with clients prior to release 6.7.

	This poll supersedes the MON_SERVER_MSG_TRAFFIC_POLL_* poll for new development. See TipcMonServerMsgTrafficPoll in the TIBCO SmartSockets Application Programming Interface guide for more information. The MON_SERVER_MSG_TRAFFIC_POLL_* is retained for compatibility with servers prior to release 6.7.

$RTHOME/examples/smrtsock/manual

RTHOME:[EXAMPLES.SMRTSOCK.MANUAL]

%RTHOME%\examples\smrtsock\manual

The online source files have additional #ifdefs to provide C++ support. These #ifdefs are not shown to simplify the example.

/* 
  
------------------------------------------------------------------ 
  polltraf.c 
 
  USAGE 
    polltraf <project> <unique_subject> <poll_interval> 
 
  This program gathers message traffic information on the RTclient 
  specified in the command line arg <unique_subject> in 
  project <project>. The info is polled for on a 
  regular interval as specified in <poll_interval>. You can gather 
  message traffic info on all clients in a project by 
  specifying "/..." for <unique_subject>. <poll_interval> is 
  always specified in seconds (as an integer). 
 
    Sample usage: 
      polltraf tank my_ie 10 
      polltraf tank /... 30 
  
------------------------------------------------------------------ 
*/ 
 
#include <rtworks/ipc.h> 
 
/* 
================================================================ 
*/ 
/*..cb_default - default callback */ 
static void T_ENTRY cb_default 
( 
 T_IPC_CONN conn, 
 T_IPC_CONN_DEFAULT_CB_DATA data, 
 T_CB_ARG arg 
) 
{ 
  if (!TipcMsgPrintError(data->msg)) { 
    TutOut("Could not print message: error <%s>.\n", 
           TutErrStrGet()); 
  } 
} /* cb_default */ 
 
/* =============================================================== 
*/ 
/*..process_traffic_poll - callback to process a 
                           MON_CLIENT_MSG_TRAFFIC_POLL_RESULT message 
*/ 
static void T_ENTRY process_traffic_poll 
( 
 T_IPC_CONN conn, 
 T_IPC_CONN_PROCESS_CB_DATA data, 
 T_CB_ARG arg 
) 
{ 
  T_IPC_MSG msg = data->msg; 
  T_STR client_name; 
  T_INT4 total_msg_recv_4; 
  T_INT4 total_msg_send_4; 
  T_INT4 total_byte_recv_4; 
  T_INT4 total_byte_send_4; 
  T_INT8 total_msg_recv_8; 
  T_INT8 total_msg_send_8; 
  T_INT8 total_byte_recv_8; 
  T_INT8 total_byte_send_8; 
 
  /* Set current field */ 
  if (!TipcMsgSetCurrent(msg, 0)) { 
    TutOut("Could not set current field of message: error <%s>.\n", 
           TutErrStrGet()); 
    return; 
  } 
 
  /* Get the fields from the message */ 
  if (!TipcMsgRead(data->msg, T_IPC_FT_STR,  &client_name, 
                              T_IPC_FT_INT4, &total_msg_recv_4, 
                              T_IPC_FT_INT4, &total_msg_send_4, 
                              T_IPC_FT_INT4, &total_byte_recv_4, 
                              T_IPC_FT_INT4, &total_byte_send_4, 
                              NULL)) { 
    TutOut("Unable to access message traffic message: error 
<%s>.\n", 
           TutErrStrGet()); 
    return; 
  } 
 
  TutOut("Summary of message traffic for RTclient <%s>\n", 
client_name); 
  if (TipcMsgRead(data->msg, T_IPC_FT_INT8, &total_msg_recv_8, 
                             T_IPC_FT_INT8, &total_msg_send_8, 
                             T_IPC_FT_INT8, &total_byte_recv_8, 
                             T_IPC_FT_INT8, &total_byte_send_8, 
                             NULL)) { 
    /* Print out the new information received */ 
    TutOut("   (Received 64-bit data)\n"); 
    TutOut("   Total messages received = " T_INT8_SPEC "\n", 
           total_msg_recv_8); 
    TutOut("   Total messages sent     = " T_INT8_SPEC "\n", 
           total_msg_send_8); 
    TutOut("   Total bytes received    = " T_INT8_SPEC "\n", 
           total_byte_recv_8); 
    TutOut("   Total bytes sent        = " T_INT8_SPEC "\n", 
           total_byte_recv_8); 
  } 
  else { 
    /* Print out the new information received */ 
    TutOut("   (Received 32-bit data)\n"); 
    TutOut("   Total messages received = " T_INT4_SPEC "\n", 
           total_msg_recv_4); 
    TutOut("   Total messages sent     = " T_INT4_SPEC "\n", 
           total_msg_send_4); 
    TutOut("   Total bytes received    = " T_INT4_SPEC "\n", 
           total_byte_recv_4); 
    TutOut("   Total bytes sent        = " T_INT4_SPEC "\n", 
           total_byte_recv_4); 
  } 
  
TutOut("======================================================\n")
; 
 
} /* process_traffic_poll */ 
 
/* =============================================================== 
*/ 
int main 
( 
 int argc, 
 char **argv 
) 
{ 
  T_STR project_name; 
  T_STR unique_subject; 
  T_REAL8 poll_interval; 
  T_IPC_MT mt; 
  T_OPTION option; 
 
  /* Check the command line arguments */ 
  if (argc != 4) { 
    TutOut("Usage: polltraf <project> <unique_subject> "); 
    TutOut("<poll_interval>\n"); 
    TutExit(T_EXIT_FAILURE); 
  } 
 
  /* Save pointers to command line arguments */ 
  project_name = argv[1]; 
  unique_subject = argv[2]; 
  poll_interval = atof(argv[3]); 
 
  /* Check that the polling interval is greater than zero */ 
  if (poll_interval <= 0.0) { 
    TutOut("Poll_Interval must be greater than zero.\n"); 
    TutExit(T_EXIT_FAILURE); 
  } 
 
  TutOut("Polling RTclient <%s> in project <%s> ", 
   unique_subject, project_name); 
  TutOut("every <%g> seconds...\n", poll_interval); 
 
  /* Set the project name */ 
  option = TutOptionLookup("project"); 
  if (option == NULL) { 
    TutOut("Could not look up option <project>: error <%s>.\n", 
           TutErrStrGet()); 
    TutExit(T_EXIT_FAILURE); 
  } 
 
  if (!TutOptionSetEnum(option, project_name)) { 
    TutOut("Could not set option <project>: error <%s>.\n", 
           TutErrStrGet()); 
    TutExit(T_EXIT_FAILURE); 
  } 
 
  /* Connect to RTserver */ 
  if (!TipcSrvCreate(T_IPC_SRV_CONN_FULL)) { 
    TutOut("Could not connect to RTserver: error <%s>.\n", 
           TutErrStrGet()); 
    TutExit(T_EXIT_FAILURE); 
  } 
 
  /* Create callback to process CLIENT_MSG_TRAFFIC poll results */ 
  mt = TipcMtLookupByNum(T_MT_MON_CLIENT_MSG_TRAFFIC_POLL_RESULT); 
  if (mt == NULL) { 
    TutOut("Could not look up message type "); 
    TutOut("MON_CLIENT_MSG_TRAFFIC_POLL_RESULT: error <%s>.\n", 
           TutErrStrGet()); 
    TutExit(T_EXIT_FAILURE); 
  } 
 
  if (TipcSrvProcessCbCreate(mt, process_traffic_poll, NULL) == 
NULL){ 
    TutOut("Could not set up callback to process "); 
    TutOut("MON_CLIENT_MSG_POLL_RESULT: error <%s>.\n", 
           TutErrStrGet()); 
    TutExit(T_EXIT_FAILURE); 
  } 
 
  /* Create default callback to receive unwanted message types */ 
  if (TipcSrvDefaultCbCreate(cb_default, NULL) == NULL) { 
    TutOut("Could not create default callback: error <%s>.\n", 
           TutErrStrGet()); 
  } 
 
  /* Read and process poll results every "poll_interval" seconds */ 
  while (1) { 
    TutOut("==> Polling RTclient <%s> for message traffic 
info...\n", 
           unique_subject); 
 
    /* Initiate poll for message traffic info about an RTclient */ 
    if (!TipcMonClientMsgTrafficPoll(unique_subject)) { 
      TutOut("Unable to poll for message traffic for RTclient 
<%s>.\n", 
             unique_subject); 
      TutOut(" error <%s>.\n", TutErrStrGet()); 
    } 
 
    /* Process the poll results which arrive */ 
    if (!TipcSrvMainLoop(poll_interval)) { 
      TutOut("TipcSrvMainLoop failed: error <%s>.\n", 
             TutErrStrGet()); 
    } 
  } 
 
  /* This line should not be reached. */ 
  return T_EXIT_FAILURE; 
} /* main */

This program retrieves both input and output information about the RTclients’ message traffic. The poll for traffic information is initiated by the call to TipcMonClientMsgTrafficPoll. Note that the argument to this function is unique_subject. This argument is passed in as a command line argument and must be either:

In this program, the poll is sent to the specified RTclient or many RTclients at a regular interval, which is controlled by the call to TipcSrvMainLoop. The poll_interval timeout causes TipcSrvMainLoop to read and process all incoming messages for that many seconds before giving up control.

The call to TipcMonClientMsgTrafficPoll results in one or a series (one for each RTclient polled) of MON_CLIENT_MSG_TRAFFIC_POLL_RESULT messages being returned to the program from RTserver. An RTclient message process callback, process_traffic_poll, is created to process messages of that type.

The callback function process_traffic_poll accesses the fields of the poll result message and prints the requested information. If no RTclient exists that matches the unique_subject passed to TipcMonClientMsgTrafficPoll, no results are printed.

Compiling, Linking, and Running

To compile, link, and run the polltraf program, first you must either copy the program to your own directory or have write permission to the directory:

$RTHOME/examples/smrtsock/manual

RTHOME:[EXAMPLES.SMRTSOCK.MANUAL]

%RTHOME%\examples\smrtsock\manual

Step 1

Note that this program is part of the ss_tutorial project and subscribes to the lesson5 subject.

$RTHOME/examples/smrtsock/tutorial/lesson5

RTHOME:[EXAMPLES.SMRTSOCK.TUTORIAL.LESSON5]

%RTHOME%\examples\smrtsock\tutorial\lesson5

Step 2

$ rtlink polltraf.c -o polltraf.x 
$ rtlink receive.c -o receive.x

$ cc polltraf.c 
$ rtlink /exec=polltraf.exe polltraf.obj 
$ cc receive.c 
$ rtlink /exec=receive.exe receive.obj

$ nmake /f pollw32m.mak 
$ nmake /f recw32m.mak

To run the programs, start the receive process in one terminal emulator window and then the polltraf process in another terminal emulator window.

Step 3

Step 4

$ polltraf.x ss_tutorial /... 10

$ polltraf :== $sys$disk:[]polltraf.exe 
$ polltraf ss_tutorial /... 10

$ polltraf.exe ss_tutorial /... 10

The name /... indicates that all RTclients should be polled. Here is an example of the output displayed:

Polling RTclient </...> in project <ss_tutorial> every <10> 
seconds... 
Connecting to project <ss_tutorial> on <_node> RTserver. 
Using local protocol. 
Message from RTserver: Connection established. 
Start subscribing to subject </_grissom_1037>. 
==> Polling RTclient </...> for message traffic info... 
Summary of message traffic for RTclient </_grissom_1028> 
   Total messages received = 19 
   Total messages sent     = 19 
   Total bytes received    = 792 
   Total bytes sent        = 792 
====================================================== 
Summary of message traffic for RTclient </_grissom_1037> 
   Total messages received = 1 
   Total messages sent     = 2 
   Total bytes received    = 64 
   Total bytes sent        = 64 
====================================================== 
==> Polling RTclient </...> for message traffic info... 
Summary of message traffic for RTclient </_grissom_1028> 
   Total messages received = 20 
   Total messages sent     = 20 
   Total bytes received    = 904 
   Total bytes sent        = 904 
====================================================== 
Summary of message traffic for RTclient </_grissom_1037> 
   Total messages received = 3 
   Total messages sent     = 4 
   Total bytes received    = 240 
   Total bytes sent        = 240 
======================================================

Notice than when a poll takes place, two results are reported. One is for the receive program, the second is for the polltraf program. When /... is used to specify all RTclients, polltraf even receives information about itself (which initiated the poll).