What’s in a Message?

A message is composed of several parts, or properties. The most important property is the message data. Figure 6 shows an example of the message that you constructed and sent in the previous lesson (Lesson 2). This message was a standard TIBCO SmartSockets message type, INFO, and was sent to the lesson2 subject. The data part of the message consisted of a single string field containing the string "Hello World!".

All parts of a message can be accessed directly with the TIBCO SmartSockets API. Almost all parts of a message can be specified using the API. Functions for working with messages always start with TipcMsg. Messages can be created using TipcMsgCreate, destroyed using TipcMsgDestroy, and copied using TipcMsgClone.

There are TIBCO SmartSockets functions to get (access) and set (write) each part of the message. A message is composed of these properties (TIBCO SmartSockets API functions for setting and getting the message property are enclosed in parentheses):


Type	The kind of message being manipulated (TipcMsgSetType, TipcMsgGetType).
Sender	The name of the originator of a message (TipcMsgSetSender, TipcMsgGetSender). TIBCO SmartSockets automatically fills this in for you when using an RTserver to deliver the message.
Destination	The name of the subject where a message is going (TipcMsgSetDest, TipcMsgGetDest).
Priority	The level of importance of a message (TipcMsgSetPriority, TipcMsgGetPriority).
Delivery Mode	is the level of guarantee when a message is sent through a connection (TipcMsgSetDeliveryMode, TipcMsgGetDeliveryMode).
Delivery Timeout	is the number of seconds specifying how long to wait for acknowledgment of delivery of a message sent through a connection (TipcMsgSetDeliveryTimeout, TipcMsgGetDeliveryTimeout).
Load Balancing Mode	is the method of delivery for publish-subscribe operations, which allows a message to be delivered to one or to all subscribing RTclients (TipcMsgSetLbMode, TipcMsgGetLbMode).
Header String Encode	controls whether or not header strings are converted to four-byte integers when a message is sent through a connection (TipcMsgSetHeaderStrEncode, TipcMsgGetHeaderStrEncode).
Reference Count	is the number of independent references to a message (TipcMsgGetRefCount, TipcMsgIncrRefCount).
Sequence Number	uniquely identifies a message for guaranteed message delivery (TipcMsgGetSeqNum). TIBCO SmartSockets assigns this number and it cannot be manually set.
User-defined Property	is a user-defined value that can be used for any purpose (TipcMsgSetUserProp, TipcMsgGetUserProp). This field is not used internally by TIBCO SmartSockets.
Read Only	controls whether or not a message can be modified (TipcMsgGetReadOnly). TIBCO SmartSockets automatically sets this property and it cannot be manually set.
Data	is the instructions or value part of a message (TipcMsgAppend, TipcMsgNext).

There are a large number of TIBCO SmartSockets functions to build the data part of a message (TipcMsgAppend*) and access the data part of a message (TipcMsgNext*). See the TIBCO SmartSockets Application Programming Interface reference for a complete description of these functions.

Figure 7 shows an example of a more complex message. It is a TIBCO SmartSockets standard NUMERIC_DATA message, and the data part of this message is a series of variable name-value pairs (voltage = 33.4534, switch_pos = 0). You construct a NUMERIC_DATA message, similar to this one, later in this lesson.

Automatic Data Translation

One of the key features of TIBCO SmartSockets is that it has structured messages. There is no need for you to figure out how to encode your messages. TIBCO SmartSockets takes care of that for you and provides a robust API that allows you complete access to any part of the structure of a message. Because the messages are structured, TIBCO SmartSockets knows how to automatically convert different data types when delivering the message across a heterogeneous network. This includes ASCII-EBCDIC, big endian and little endian, floating point numbers, and more. This is all done transparently for you using a receiver-makes-right approach in which the final receiver of the message does the translation. This is most efficient because data translation is only done once.

Many other messaging products do not have the concept of a structured message type. They simply move a block of memory across the network. There is no API to help build and access the different fields of the message, and there is no automatic conversion of data. They leave these tasks up to you, increasing the amount of time it takes to build your application.