Message File Logging

A message file is a file, in either text format or binary format, containing one or more messages. Through the use of options, RTclient can easily log (that is, write into text message files) the messages that have been sent to or received from RTserver. With this message file logging, the message types are grouped into three standard categories. Any message type can also be added to or removed from these categories with the API functions TipcSrvLogAddMt and TipcSrvLogRemoveMt (see Changing Logging Categories). This section describes the features of message file logging.

Message File Logging Categories

Message types are divided into three categories for the purpose of being logged into message file:

All standard message types are described in detail in the section Standard Message Types.

The standard message types in each message file logging category are:

Data Messages

Data messages are the most common category of message sent between RTclients. This message file shows several sample data messages (note that alias names are identifiers):

time /_time 42 
numeric_data /system/thermal { 
  voltage 33.4534 
  switch_pos 0 
} 
boolean_data /elec_pwr relay_aligned true 
string_data /system { 
  i80_message "Carry tire chains" 
  i50_message "Road closed" 
} 
enum_data /system/console battery_status normal 
control /system "setopt frame_interval 1.0" 
end_of_frame /_time 

Internal Messages

All the remaining standard message types are included in the internal category. Internal messages include (but are not limited to) these groups of message types:

You do not usually explicitly create and send internal messages, but logging these types of messages can be useful for debugging purposes. This message file shows several sample internal messages:

subject_set_subscribe /_server thermal true true 
server_stop_call /_server 2 
gmd_ack /_server 345613 
server_stop_result /_client "RTserver stopping"  
mon_subject_subscribe_status /_client "/_workstation1_2269" { 
"/_workstation1_2269" } "" "" 

Logging Messages

RTclient starts and stops logging messages in the logging categories by setting these options:

RTserver can also log incoming and outgoing messages to message files. See Message File Logging for more information on logging messages in an RTserver.

Starting Message Logging

Message logging is started by setting one of the above options (either with the function TutOptionSetStr or the setopt command) to the name of a file. For example:

setopt log_in_data incoming.msg 

The above example causes the RTclient to start logging all incoming data messages into the incoming.msg file. If the file does not exist, it is created. If the file exists from a previous session, it is overwritten with new information.

Multiple categories can be logged into the same file. For example, RTclient could log both incoming data messages and outgoing status messages into the same message file by setting these options:

setopt log_in_data messages.msg 
setopt log_out_status messages.msg 

The first line either creates the file or overwrites an existing file and begins logging incoming data messages. The second line begins logging outgoing status messages to the same file.

Stopping Message Logging

Message logging is stopped by setting one of the above options to UNKNOWN, either with the function TutOptionSetUnknown or the unsetopt command. For example:

unsetopt log_in_data 

The above example causes the RTclient to stop logging all incoming data messages. If multiple categories are being logged to the same file, the file is not closed until logging is stopped for all the relevant categories.

Changing Logging Categories

Any message type can be added to or removed from a message file logging category, including both standard message types and user-defined message types. All the standard messages types are automatically added to exactly one category. Message types can be added to multiple categories and they can also be removed from all categories.

The function TipcSrvLogAddMt is used to add a message type to a logging category. This creates a user-defined message type and adds it to the data category:

#define XYZ_COORD_DATA 1001 
 
mt = TipcMtCreate("xyz_coord_data, XYZ_COORD_DATA, "int4 int4 
int4"); 
if (mt == NULL) { 
  /* error */ 
} 
if (!TipcSrvLogAddMt(T_IPC_SRV_LOG_DATA, mt)) { 
  /* error */ 
} 

The function TipcSrvLogRemoveMt is used to remove a message type from a logging category. This looks up the TIME message type and removes it from the data category:

mt = TipcMtLookupByNum(T_MT_TIME); 
if (mt == NULL) { 
  /* error */ 
} 
if (!TipcSrvLogRemoveMt(T_IPC_SRV_LOG_DATA, mt)) { 
  /* error */ 
} 

Both TipcSrvLogAddMt and TipcSrvLogRemoveMt can only be used before RTclient has created any connection to RTserver.