Advanced Uses of Messages

What we covered so far are the most common ways of working with messages. There are many other ways, and some of these advanced uses include:

Checking the Type of the Current Field

The function TipcMsgNextType can be used to look at the type of the current field without advancing the current field. This is useful when the type of the current field can vary.

For example, if the current field is either a STR or REAL8 field, this code is used to access the field:

T_IPC_FT ft; 
T_STR str; 
T_REAL8 real8; 
 
if (!TipcMsgNextType(msg, &ft)) { 
  /* error */ 
} 
switch (ft) { 
case T_IPC_FT_STR: 
  if (!TipcMsgNextStr(msg, &str)) { 
    /* error */ 
  } 
  break; 
case T_IPC_FT_REAL8: 
  if (!TipcMsgNextReal8(msg, &real8)) { 
    /* error */ 
  } 
  break; 
default: 
   /* error */ 
} 

Cloning a Message

Before destroying a message, you may want to make a copy of the message to use for other purposes. The clone is an identical copy of the original message, but does not share the memory of the original message. A message is cloned using the TipcMsgClone function. For example:

clone_msg = TipcMsgClone(msg); 
if (clone_msg == NULL) { 
  /* error */ 
} 

Array Fields

Arrays can also be fields in a message. Array fields are appended to a message with the functions TipcMsgAppendTypeArray, where Type is the type of the array. These append functions also require the number of elements in the array as a parameter. For example:

T_REAL8 real8_array[10]; /* can hold up to 10 values */ 
 
real8_array[0] = 3.0; 
real8_array[1] = 4.0; 
real8_array[2] = 55.75; 
if (!TipcMsgAppendReal8Array(msg, real8_array, 3)) { 
  /* error */ 
}

Empty arrays, where the number of array elements is zero, are allowed.

When using array fields with TipcMsgWrite, both the array and the number of elements must be supplied. For example, the above array field could be appended as follows:

if (!TipcMsgWrite(msg,  
                  T_IPC_FT_REAL8_ARRAY, real8_array, 3, NULL)) { 
  /* error */ 
} 

Array fields are accessed from a message with the functions TipcMsgNextTypeArray, where Type is the type of the array. These append functions also require a parameter where they store the number of elements in the array. For example:

T_REAL8 *real8_array; 
T_INT4 array_size; 
 
if (!TipcMsgNextReal8Array(msg, &real8_array, &array_size)) { 
  /* error */ 
} 

When using array fields with TipcMsgRead, storage for both the array and the number of elements must be supplied. For example, the above array field could be accessed as follows:

if (!TipcMsgRead(msg,  
                 T_IPC_FT_REAL8_ARRAY, &real8_array, &array_size, 
                 NULL)) { 
  /* error */ 
} 

Constructing a Message Within a Message

Messages can also be fields in a message. This is useful for batching several messages into one large transaction or when using a message as a container for another message, such as the GMD_FAILURE message type. Messages are appended as fields with the function TipcMsgAppendMsg. When a message is appended as a field to another message, a complete copy of the field message is made. For example:

if (!TipcMsgAppendMsg(msg, field_msg)) { 
  /* error */ 
} 
if (!TipcMsgDestroy(field_msg)) { 
  /* error */ 
} 

Once TipcMsgAppendMsg returns, changing (or even destroying) the message used as a field does not affect the other message. Message fields are accessed from a message with the function TipcMsgNextMsg. For example:

T_IPC_MSG field_msg; 
if (!TipcMsgNextMsg(msg, &field_msg)) { 
  /* error */ 
} 

Pointer Fields

Normally, when a field is appended to a message the field data is copied into the message. For large fields, such as a 10-megabyte binary image, this memory copy can decrease performance measurably. To avoid this, all array-oriented fields, including string, message, and binary fields, can be appended to a message as a pointer field. A pointer field does not make a copy of the data. Instead, the supplied pointer is entered directly into the new message field’s internal data structure. When using pointer fields, the field data must not be deallocated or changed while the message field is still valid.

Pointer fields are appended to a message with the functions TipcMsgAppendTypePtr, where Type is the field type. These pointer field construction functions are available:

The TipcMsgAppendTypePtr functions have one extra parameter in addition to the parameters for the TipcMsgAppendType functions. This extra parameter, an optional T_IPC_MSG_FIELD message field, is filled in if non-null. For example:

T_REAL8 real8_array[10]; /* can hold up to 10 values */ 
T_IPC_MSG_FIELD msg_field; 
 
real8_array[0] = 3.0; 
real8_array[1] = 4.0; 
real8_array[2] = 55.75; 
if (!TipcMsgAppendReal8ArrayPtr(msg, real8_array, 3, &msg_field)) 
{  
                                                               /* can be NULL */ 
  /* error */ 
} 

Another advantage of pointer fields is that they can be easily resized with the function TipcMsgFieldSetSize after the field is created. This allows message fields to be efficiently and easily resized. For example:

/* add an array element and resize the pointer field size */ 
real8_array[3] = 318.9; 
if (!TipcMsgFieldSetSize(msg_field, 4)) { 
    /* error */ 
} 

Once a pointer field is appended to a message and the message is sent through a connection, the pointer field data is copied into the connection just like a non-pointer field. Pointer fields can also be added by name. Pointer fields are added by name to a message with the functions TipcMsgAddNamedTypePtr, where Type is the field type. These pointer field construction functions are available:

Unknown Field Values

In some cases, it is necessary to designate a field value “unknown” or “invalid”. This may be used in cases where data is missing, say in a sequence of time series data. For some data types, like T_STR, this can be accomplished using an invalid value as a marker (such as NULL). However, some data types, such as numeric values, do not allow any invalid values, even for use as a marker. For these cases, there are a few special message field functions:

These functions allow any field to be marked uniquely as holding an unknown value. Fields with unknown values still have a type, so TipcMsgAppendUnknown takes a field type parameter:

TipcMsgAppendUnknown(msg, T_IPC_FT_INT4); 

If the type of the unknown field is significant, it can be accessed with TipcMsgNextType, like any other field. Using a normal TipcMsgNext* function to access a field with an unknown value will fail. If TipcMsgNextInt4 were used on the above field, it would return FALSE, and no value would be returned. Instead, TipcMsgNextUnknown can be used to access unknown fields, or the field pointer could simply be set to skip the field, using TipcMsgSetCurrent. To determine if the current field value is unknown, use TipcMsgGetCurrentFieldKnown.

High Performance Guidelines

There are two simple recommended strategies to use when sending large amounts of data with messages: