TipcMtCreate

Name

TipcMtCreate — create a new message type

Synopsis

T_IPC_MT TipcMtCreate(name, num, grammar) 
T_STR name; 
T_INT4 num; 
T_STR grammar; 

Arguments

name — name of new message type (not case-sensitive)

num — number of new message type

grammar — description for reading and writing message files

Return Values

New message type if successful, NULL otherwise.

Diagnostics

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

Description

TipcMtCreate creates a new message type. A message type is a template for a specific kind of message. Once the message type is created, any number of messages of that type can be created.

The message type name should be a legal identifier. The message type number num is a signed four-byte integer. Message type numbers less than 1 are reserved for SmartSockets standard message types. The standard SmartSockets message types use similar names and numbers. (For example, the message type with name "numeric_data" has a C #define defined number T_MT_NUMERIC_DATA.) See the TIBCO SmartSockets User’s Guide for a list of all standard message types.

The message type grammar identifies the layout of fields in messages that use this message type. The grammar consists of a list of field types. See the TIBCO SmartSockets User’s Guide for more information on message type grammars.

The new message type is created with an unset priority property, a delivery mode property of T_IPC_DELIVERY_BEST_EFFORT, an unset delivery timeout property, a load balancing mode property of T_IPC_LB_NONE, a header string encode property of FALSE, and a user-defined property of 0. These properties can be set with the functions TipcMtSetPriority, TipcMtSetDeliveryMode, TipcMtSetDeliveryTimeout, TipcMtSetLbMode, TipcMtSetHeaderStrEncode, and TipcMtSetUserProp, respectively.

TipcMtCreate makes a copy of name and grammar.

Caution

User-defined message types must be created in all processes that will use the message types. Because there is no central SmartSockets message type repository, the recommended approach is to write an initialization function that calls TipcMtCreate as needed, link that function into all user-defined programs, and then call the function during program initialization.

See Also

TipcMtDestroy, TipcMtLookup, TipcMtLookupByNum

Examples

This example creates a message type named XYZ_COORD which uses three integer coordinates, creates an XYZ_COORD message, appends fields, and writes the message to a message file:

#define USER_MT_XYZ_COORD 2000 
 
T_IPC_MT mt; 
T_IPC_MSG msg; 
T_IPC_MSG_FILE msg_file; 
 
/* create the message type */ 
mt = TipcMtCreate("xyz_coord", USER_MT_XYZ_COORD, "int4 int4 
int4"); 
if (mt == NULL) { 
  return;  /* error */ 
}  
 
/* create a message and append fields */ 
msg = TipcMsgCreate(mt); 
if (msg == NULL) { 
  return;  /* error */ 
}  
 
if (!TipcMsgAppendInt4(msg, 5)) { 
  return;  /* error */ 
}  
if (!TipcMsgAppendInt4(msg, 2)) { 
  return;  /* error */ 
}  
if (!TipcMsgAppendInt4(msg, 9)) { 
  return;  /* error */ 
}  
 
/* create a message file */ 
msg_file = TipcMsgFileCreate("test.msg", 
T_IPC_MSG_FILE_CREATE_WRITE); 
if (msg_file == NULL) { 
  return;  /* error */ 
}  
 
if (!TipcMsgFileWrite(msg_file, msg)) { 
  return;  /* error */ 
}  
 
if (!TipcMsgDestroy(msg)) { 
  return;  /* error */ 
}  
 
if (!TipcMsgFileDestroy(msg_file)) { 
  return;  /* error */ 
} 

This is printed to the message file test.msg:

xyz_coord _null 5 2 9 

If the grammar in the call to TipcMtCreate was changed from "int4 int4 int4" to "verbose" in the above code, this is printed to the message file:

xyz_coord _null { 
  int4 5 
  int4 2 
  int4 9 
}