Message Files

A message file is a file (in either text format or binary format) containing one or more messages. It provides a means to capture real or simulated data and is typically used as a testing and debugging tool by any process in a SmartSockets application. A message file serves these purposes:

A message file typically has a .msg file extension (although SmartSockets does not enforce this extension).

Text Message Files

Messages are printed in a text message file in the following format:

message_type destination data 

The sender, priority, delivery mode, reference count, sequence number, and user-defined property of a message are not included. To be written to a message file, the message data must be written according to the message type grammar (see Grammar for more information on message type grammars). Groups of fields must be delimited by curly braces ({}), unless the group is not repeated, in which case the curly braces can be omitted. Array fields, binary fields, and messages whose type has a grammar of verbose must also be delimited by curly braces ({}). Comments (delimited by /* */, (* *), or // and end-of-line) are allowed anywhere in the file. If you are creating a text message file manually, with a text editor, an easy way to check how to format the file is to use TipcMsgFileWrite in a small program to see how it formats a similar message.

This is an example of a text message file holding four messages:

numeric_data thermal { 
 voltage 33.4534 
 switch_pos 0 
} 
numeric_data eps temperature 200.4 // note: no curly braces needed  
/* sent to the operator’s display */ 
info _hci "Satellite has entered science mode." 
string_data thermal relay1 "off" 

Binary Message Files

A binary message file has both advantages and disadvantages when compared to text message files. The advantages include:

Binary message files, however, are not easily editable with a text editor.

Using Message Files

Message files are created with the function TipcMsgFileCreate and can be created for reading (an existing file is opened), for writing in text format, for writing in binary format, or for appending. TipcMsgFileCreate automatically detects the proper format (text or binary) when used for reading and appending. For example:

msg_file = TipcMsgFileCreate("output.msg", 
T_IPC_MSG_FILE_CREATE_WRITE); 
if (msg_file == NULL) { 
  /* error */ 
} 

Messages are written to a message file using the TipcMsgFileWrite function. For example:

if (!TipcMsgFileWrite(msg_file, msg)) { 
  /* error */ 
} 

Any process can read messages from the message file using the TipcMsgFileRead function. The message file must be created for reading. For example:

msg_file = TipcMsgFileCreate("input.msg", 
T_IPC_MSG_FILE_CREATE_READ); 
if (msg_file == NULL) { 
  /* error */ 
} 
if (!TipcMsgFileRead(msg_file, &msg)) { 
  /* error */ 
}

Because T_IPC_MSG_FILE_CREATE_READ was used in this example, the actual file must already exist. The structure needed for the message file is created in an existing file. If no file exists, you get a null pointer error message.

Messages can also be logged into a message file from an RTclient process. See Message File Logging Categories for more information.

When a process finishes with a message file, the message file can be destroyed to free up the memory it uses. For example:

if (!TipcMsgFileDestroy(msg_file)) { 
  /* error */ 
} 

TipcMsgFileDestroy does not remove the file on disk, only the in-memory record of the file.

Advanced Use of Message Files

It is possible to serialize messages into a binary buffer, and retrieve them from the buffer. Here is a sample program that illustrates this technique:

#include <rtworks/ipc.h> 
 
char *filename = "file"; 
 
void SerializeMsgToDisk(T_IPC_MSG msg) 
{ 
  T_BUF buf; 
  T_PTR data; 
  T_INT4 size; 
  FILE *fp; 
 
  buf = TutBufCreate(128); 
  TipcBufMsgAppend(buf, msg); 
  TutBufGetSize(buf, &size); 
 
  data = TutBufNextAligned(buf, size, 1); 
  if (data == NULL) { 
    /* error */ 
  } 
 
  fp = fopen(filename, "w"); 
  if (fp == NULL) { 
    /* error */ 
  } 
 
  fwrite(data, sizeof(T_UCHAR), size, fp); 
  fclose(fp); 
  TutBufDestroy(buf); 
} 
 
T_IPC_MSG ReadFromDisk(void) 
{ 
  T_BUF buf; 
  T_PTR data; 
  T_INT4 size; 
  T_BOOL status; 
  FILE *fp; 
  T_IPC_MSG msg; 
 
  status = TutFileGetSize(filename, &size); 
  if (status == FALSE) { 
    /* error */ 
  } 
 
  fp = fopen(filename, "r"); 
  if (fp == NULL) { 
    /* error */ 
  } 
 
  T_MALLOC(data, size, T_PTR); 
  fread(data, sizeof(T_UINT1), size, fp); 
 
  /* create static buffer, set max size */ 
  buf = TutBufCreateStatic(data, size); 
 
  /* set write pointer size */ 
  status = TutBufSetSize(buf, size); 
 
  msg = TipcBufMsgNext(buf); 
  if (msg == NULL) { 
    /* error */ 
  } 
 
  TutBufDestroy(buf); 
  T_FREE(data); 
 
  return msg; 
} 
 
int main(int argc, char *argv[]) 
{ 
  T_IPC_MSG msg_in, msg_out; 
 
  msg_in = TipcMsgCreate(TipcMtLookupByNum(T_MT_INFO)); 
  TipcMsgAppendStr(msg_in, "hello world"); 
 
  SerializeMsgToDisk(msg_in); 
  TipcMsgDestroy(msg_in); 
 
  msg_out = ReadFromDisk(); 
  TipcMsgPrint(msg_out, TutOut); 
  TipcMsgDestroy(msg_out); 
}