ImqItem

Figure 14. ImqItem class

This abstract class represents an item, perhaps one of several, within a message. Items are concatenated together in a message buffer. Each specialization is associated with a particular data structure that begins with a structure id.

Polymorphic methods in this abstract class allow items to be copied to and from messages. The ImqMessage class readItem and writeItem methods provide another style of invoking these polymorphic methods, a style that is more natural for application programs.

This class relates to the MQI calls listed in Table 15.

Other relevant classes

ImqCache (see ImqCache)

ImqError (see ImqError)

ImqMessage (see ImqMessage)

Object attributes

structure id

A string of four characters at the beginning of the data structure. This attribute is read-only. This attribute is recommended for derived classes. It is not included automatically.

Constructors

ImqItem( );

The default constructor.

ImqItem( const ImqItem & item );

The copy constructor.

Class methods (public)

static ImqBoolean structureIdIs( const char * structure-id-to-test, const ImqMessage & msg );

Returns TRUE if the structure id of the next ImqItem in the incoming msg is the same as structure-id-to-test. The next item is identified as that part of the message buffer currently addressed by the ImqCache data pointer. This method relies on the structure id and therefore is not guaranteed to work for all ImqItem derived classes.

Object methods (public)

void operator = ( const ImqItem & item );

Instance data is copied from item, replacing the existing instance data.

virtual ImqBoolean copyOut( ImqMessage & msg ) = 0 ;

Writes this object as the next item in an outgoing message buffer, appending it to any existing items. If the write operation is successful, the ImqCache data length is increased. This method returns TRUE if successful.

Override this method to work with a specific subclass.

virtual ImqBoolean pasteIn( ImqMessage & msg ) = 0 ;

Reads this object destructively³ from the incoming message buffer.

The (sub)class of this object must be consistent with the structure id found next in the message buffer of the msg object.

The encoding of the msg object should be MQENC_NATIVE. It is recommended that messages be retrieved with the ImqMessage encoding set to MQENC_NATIVE, and with the ImqGetMessageOptions options including MQGMO_CONVERT.

If the read operation is successful, the ImqCache data length is reduced. This method returns TRUE if successful.

Override this method to work with a specific subclass.

Reason codes

MQRC_ENCODING_ERROR

MQRC_STRUC_ID_ERROR

MQRC_INCONSISTENT_FORMAT

MQRC_INSUFFICIENT_BUFFER

MQRC_INSUFFICIENT_DATA

³

The read is destructive in that the ImqCache data pointer is moved on. However, the buffer content remains the same, so data can be re-read by resetting the ImqCache data pointer.