TipcMonSubjectNamesSetWatch

Name

TipcMonSubjectNamesSetWatch — start or stop watching subject names

Synopsis

T_BOOL TipcMonSubjectNamesSetWatch(watch_status) 
T_BOOL watch_status; 

Arguments

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

Return Values

TRUE if the subject names watch status was successfully set, FALSE otherwise.

Diagnostics

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

Description

TipcMonSubjectNamesSetWatch sets whether this RTclient is watching the subject names in the current project that match the value of the Monitor_Scope option. TipcMonSubjectNamesSetWatch saves the watch status and sends a MON_SUBJECT_NAMES_SET_WATCH message to RTserver. The watch status controls whether the RTclient receives a MON_SUBJECT_NAMES_STATUS message each time a subject is created or destroyed. A subject is considered created when the first RTclient starts subscribing to that subject. A subject is considered destroyed when the last RTclient stops subscribing to that subject. 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_SUBJECT_NAMES_STATUS message contains three fields:

In addition to sending a MON_SUBJECT_NAMES_STATUS message each time a subject is created or destroyed, RTserver also sends an initial MON_SUBJECT_NAMES_STATUS message when the watch status is set to TRUE, so that the RTclient does not have to wait for the next subject name change to receive the first MON_SUBJECT_NAMES_STATUS message.

To determine if this RTclient is watching subject names, use TipcMonSubjectNamesGetWatch. To poll once for subject names, use TipcMonSubjectNamesPoll.

Caution

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

See Also

TipcMonSubjectNamesGetWatch, TipcMonSubjectNamesPoll

Examples

This example uses TipcMonSubjectNamesSetWatch to start watching subject names and creates a callback to process the incoming MON_SUBJECT_NAMES_STATUS messages:

/* =============================================================== */ 
/*..process_mon_subject_names_status -- process a MON_SUBJECT_NAMES_STATUS message 
*/ 
void T_ENTRY process_mon_subject_names_status(conn, data, arg) 
T_IPC_CONN conn; 
T_IPC_CONN_PROCESS_CB_DATA data; 
T_CB_ARG arg; 
{ 
  T_STR *subject_names; 
  T_INT4 num_subject_names; 
  T_STR created_subject; 
  T_STR destroyed_subject; 
  T_INT4 counter; 
 
  /* must set current field first */ 
  if (!TipcMsgSetCurrent(data->msg, 0)) { 
    return; /* error */ 
  }  
 
  /* get the fields from the message */ 
  if (!TipcMsgNextStrArray(data->msg, &subject_names,  
                           &num_subject_names) 
      || !TipcMsgNextStr(data->msg, &created_subject) 
      || !TipcMsgNextStr(data->msg, &destroyed_subject)) { 
    return; /* error */ 
  }  
 
  TutOut("Got SUBJECT_NAMES status.\n"); 
  for (counter = 0; counter < num_subject_names; counter++) { 
    TutOut("subject_names[%d] = %s\n", counter, 
    subject_names[counter]); 
  } 
  TutOut("created subject = %s\n", created_subject); 
  TutOut("destroyed subject = %s\n", destroyed_subject); 
} /* process_mon_subject_names_status */ 
 
/* =========================================================== */ 
/*...code from calling function is below */ 
 
T_IPC_MT mt; 
if (!TipcMonSubjectNamesSetWatch(TRUE)) { 
  return; /* error */ 
}  
mt = TipcMtLookupByNum(T_MT_MON_SUBJECT_NAMES_STATUS); 
if (mt == NULL) { 
  return; /* error */ 
} 
 
if (TipcSrvProcessCbCreate(mt, process_mon_subject_names_status, 
NULL) 
    == NULL) { 
  return; /* error */ 
} 
/* At this point TipcSrvMainLoop can be used to read and process messages. */