TipcMonClientMsgRecvSetWatch

TipcMonClientMsgRecvSetWatch — start or stop watching RTclient received messages

Synopsis

T_BOOL TipcMonClientMsgRecvSetWatch(client_name, msg_type_name, 
watch_status) 
T_STR client_name; 
T_STR msg_type_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)

msg_type_name — name of message type to set watch status for (use T_IPC_MON_ALL to indicate a watch of all message types)

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

Return Values

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

Diagnostics

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

Description

TipcMonClientMsgRecvSetWatch sets whether this RTclient is watching received messages 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. TipcMonClientMsgRecvSetWatch saves the watch status and sends a MON_CLIENT_MSG_RECV_SET_WATCH message to the client_name RTclient. The watch status controls whether the RTclient receives a MON_CLIENT_MSG_RECV_STATUS message each time a received message is inserted or deleted from the message queue for the connection to RTserver 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. If msg_type_name is T_IPC_MON_ALL, then all message types in the watched RTclient are watched.

a STR field containing the name of the RTclient

a MSG field containing the received message

an INT4 field containing whether the message was just inserted into or deleted from the connection’s message queue (really of type T_BOOL); a value of TRUE means the message was inserted, a value of FALSE means the message was deleted

an INT4 field containing the position in the queue where the received message was just inserted or deleted (a value of 0 means the front of the queue)

a BINARY field containing a unique 8-byte identifier for the received message; this field is useful for processes that need to accurately track the entire contents of the connection’s message queue, such as the RTmon GDI

a BINARY field containing an array of unique 8-byte identifiers for all messages in the connection’s message queue; this field is useful for processes that need to accurately track the entire contents of the connection’s message queue, such as the RTmon GDI

In addition to sending a MON_CLIENT_MSG_RECV_STATUS message each time there is a message queue change, the watched RTclient also sends an initial MON_CLIENT_MSG_RECV_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_MSG_RECV_STATUS message.

To see if this RTclient is watching RTclient received messages, use TipcMonClientMsgRecvGetWatch.

For an example of how MON_CLIENT_MSG_RECV_STATUS messages can be used, see the RTmon GDI Watch Messages Received window.

Caution

TipcMonClientMsgRecvSetWatch sends a MON_CLIENT_MSG_RECV_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 or the message type named msg_type_name does not exist.

The 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_MSG_RECV_STATUS messages. The callbacks ignore these message types to prevent infinite loops.

See Also

Examples

This uses TipcMonClientMsgRecvSetWatch to start watching all received messages in the primary RTclient and creates a callback to process the incoming MON_CLIENT_MSG_RECV_STATUS messages:

/* =============================================================== */ 
/*..process_mon_client_msg_recv_status -- process a MON_CLIENT_MSG_RECV_STATUS 
message */ 
void T_ENTRY process_mon_client_msg_recv_status(conn, data, arg) 
T_IPC_CONN conn; 
T_IPC_CONN_PROCESS_CB_DATA data; 
T_CB_ARG arg; 
{ 
  T_STR client_name; 
  T_IPC_MSG recv_msg; 
  T_INT4 insert_flag; 
  T_INT4 queue_pos; 
  T_PTR msg_id; 
  T_INT4 msg_id_size; 
  T_PTR queue_msg_id_array; 
  T_INT4 queue_msg_id_array_size; 
   
  /* 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_MSG, &recv_msg, 
                   T_IPC_FT_INT4, &insert_flag, 
                   T_IPC_FT_INT4, &queue_pos, 
                   T_IPC_FT_BINARY, &msg_id, &msg_id_size, 
                   T_IPC_FT_BINARY, &queue_msg_id_array, 
                     &queue_msg_id_array_size, 
                   NULL)) { 
    return;  /* error */ 
  }  
 
  TutOut("Got CLIENT_MSG_RECV status.\n"); 
  TutOut("RTclient name = %s\n", client_name); 
  TutOut("recv msg\n"); 
  if (!TipcMsgPrint(recv_msg, TutOut)) { 
    return;  /* error */ 
  } 
  TutOut("insert flag = %s\n", insert_flag ? "TRUE" : "FALSE"); 
  TutOut("queue pos = %d\n", queue_pos); 
  /* At this point, msg_id and queue_msg_id_array could be used */ 
  /* to accurately track any changes to the message queue (as */ 
  /* RTmon GDI does). */ 
} /* process_mon_client_msg_recv_status */ 
/* =========================================================== */ 
/*...code from calling function is below */ 
 
T_IPC_MT mt; 
 
if (!TipcMonClientMsgRecvSetWatch("primary", T_IPC_MON_ALL, 
                                  TRUE)) { 
  return;  /* error */ 
}  
 
mt = TipcMtLookupByNum(T_MT_MON_CLIENT_MSG_RECV_STATUS); 
if (mt == NULL) { 
  return;  /* error */ 
} 
 
if (TipcSrvProcessCbCreate(mt, process_mon_client_msg_recv_status, 
                           NULL) == NULL) { 
  return;  /* error */ 
} 
 
/* At this point TipcSrvMainLoop can be used to read and process messages. */