ImqMessage

Figure 15. ImqMessage class

This class encapsulates an MQMD data structure (see Table 16), and also handles the construction and reconstruction of message data.

Other relevant classes

ImqCache (see ImqCache)

ImqItem (see ImqItem)

ImqMessageTracker (see ImqMessageTracker)

ImqString (see ImqString)

Object attributes

application id data

Identity information associated with a message. The initial value is a null string.

application origin data

Origin information associated with a message. The initial value is a null string.

backout count

The number of times a message has been tentatively retrieved and subsequently backed out. The initial value is zero. This attribute is read-only.

character set

Coded Character Set Id. The initial value is MQCCSI_Q_MGR. The following additional values are possible:

MQCCSI_INHERIT

MQCCSI_EMBEDDED

You can also use a Coded Character Set Id of your choice. For information about this, see the code page conversion tables in the WebSphere MQ Application Programming Reference book.

encoding

The machine encoding of the message data. The initial value is MQENC_NATIVE.

expiry

A time-dependent quantity that controls how long WebSphere MQ retains an unretrieved message before discarding it. The initial value is MQEI_UNLIMITED.

format

The name of the format (template) that describes the layout of data in the buffer. Names longer than eight characters are truncated to eight characters. Names are always padded with blanks to eight characters. The initial value is MQFMT_NONE. The following additional values are possible:

MQFMT_ADMIN

MQFMT_CICS

MQFMT_COMMAND_1

MQFMT_COMMAND_2

MQFMT_DEAD_LETTER_HEADER

MQFMT_DIST_HEADER

MQFMT_EVENT

MQFMT_IMS

MQFMT_IMS_VAR_STRING

MQFMT_MD_EXTENSION

MQFMT_PCF

MQFMT_REF_MSG_HEADER

MQFMT_RF_HEADER

MQFMT_STRING

MQFMT_TRIGGER

MQFMT_WORK_INFO_HEADER

MQFMT_XMIT_Q_HEADER

You can also use an application-specific string of your choice. For more information about this, see the Format field of the message descriptor (MQMD) in the WebSphere MQ Application Programming Reference book.

message flags

Segmentation control information. The initial value is MQMF_SEGMENTATION_INHIBITED. The following additional values are possible:

MQMF_SEGMENTATION_ALLOWED

MQMF_MSG_IN_GROUP

MQMF_LAST_MSG_IN_GROUP

MQMF_SEGMENT

MQMF_LAST_SEGMENT

MQMF_NONE

This attribute is not supported on z/OS.

message type

The broad categorization of a message. The initial value is MQMT_DATAGRAM. The following additional values are possible:

MQMT_SYSTEM_FIRST

MQMT_SYSTEM_LAST

MQMT_DATAGRAM

MQMT_REQUEST

MQMT_REPLY

MQMT_REPORT

MQMT_APPL_FIRST

MQMT_APPL_LAST

You can also use an application-specific value of your choice. For more information about this, see the MsgType field of the message descriptor (MQMD) in the WebSphere MQ Application Programming Reference book.

offset

Offset information. The initial value is zero. This attribute is not supported on z/OS.

original length

The original length of a segmented message. The initial value is MQOL_UNDEFINED. This attribute is not supported on z/OS.

persistence

Indicates that the message is important and must at all times be backed up using persistent storage. This option implies a performance penalty. The initial value is MQPER_PERSISTENCE_AS_Q_DEF. The following additional values are possible:

MQPER_PERSISTENT

MQPER_NOT_PERSISTENT

priority

The relative priority for transmission and delivery. Messages of the same priority are usually delivered in the same sequence as they were supplied (although there are several criteria that must be satisfied to guarantee this). The initial value is MQPRI_PRIORITY_AS_Q_DEF.

put application name

The name of the application that put a message. The initial value is a null string.

put application type

The type of application that put a message. The initial value is MQAT_NO_CONTEXT. The following additional values are possible:

MQAT_AIX

MQAT_CICS

MQAT_CICS_BRIDGE

MQAT_DOS

MQAT_IMS

MQAT_IMS_BRIDGE

MQAT_MVS

MQAT_NOTES_AGENT

MQAT_OS2

MQAT_OS390

MQAT_OS400

MQAT_QMGR

MQAT_UNIX

MQAT_WINDOWS

MQAT_WINDOWS_NT

MQAT_XCF

MQAT_DEFAULT

MQAT_UNKNOWN

MQAT_USER_FIRST

MQAT_USER_LAST

You can also use an application-specific string of your choice. For more information about this, see the PutApplType field of the message descriptor (MQMD) in the WebSphere MQ Application Programming Reference book.

put date

The date on which a message was put. The initial value is a null string.

put time

The time at which a message was put. The initial value is a null string.

reply-to queue manager name

The name of the queue manager to which any reply should be sent. The initial value is a null string.

reply-to queue name

The name of the queue to which any reply should be sent. The initial value is a null string.

report

Feedback information associated with a message. The initial value is MQRO_NONE. The following additional values are possible:

MQRO_EXCEPTION

MQRO_EXCEPTION_WITH_DATA

MQRO_EXCEPTION_WITH_FULL_DATA *

MQRO_EXPIRATION

MQRO_EXPIRATION_WITH_DATA

MQRO_EXPIRATION_WITH_FULL_DATA *

MQRO_COA

MQRO_COA_WITH_DATA

MQRO_COA_WITH_FULL_DATA *

MQRO_COD

MQRO_COD_WITH_DATA

MQRO_COD_WITH_FULL_DATA *

MQRO_PAN

MQRO_NAN

MQRO_NEW_MSG_ID

MQRO_NEW_PASS_ID

MQRO_COPY_MSG_ID_TO_CORREL_ID

MQRO_PASS_CORREL_ID

MQRO_DEAD_LETTER_Q

MQRO_DISCARD_MSG

MQRO_DISCARD_MSG

where * indicates values that are not supported on WebSphere MQ for z/OS.

sequence number

Sequence information identifying a message within a group. The initial value is one. This attribute is not supported on z/OS.

total message length

The number of bytes that were available during the most recent attempt to read a message. This number will be greater than the ImqCache message length if the last message was truncated, or if the last message was not read because truncation would have occurred. This attribute is read-only. The initial value is zero.

This attribute can be useful in any situation involving truncated messages.

user id

A user identity associated with a message. The initial value is a null string.

Constructors

ImqMessage( );

The default constructor.

ImqMessage( const ImqMessage & msg );

The copy constructor. See the operator = method for details.

Object methods (public)

void operator = ( const ImqMessage & msg );

Copies the MQMD and message data from msg. If a buffer has been supplied by the user for this object, the amount of data copied is restricted to the available buffer size. Otherwise, the system ensures that a buffer of adequate size is made available for the copied data.

ImqString applicationIdData( ) const ;

Returns a copy of the application id data.

void setApplicationIdData( const char * data = 0 );

Sets the application id data.

ImqString applicationOriginData( ) const ;

Returns a copy of the application origin data.

void setApplicationOriginData( const char * data = 0 );

Sets the application origin data.

MQLONG backoutCount( ) const ;

Returns the backout count.

MQLONG characterSet( ) const ;

Returns the character set.

void setCharacterSet( const MQLONG ccsid = MQCCSI_Q_MGR );

Sets the character set.

MQLONG encoding( ) const ;

Returns the encoding.

void setEncoding( const MQLONG encoding = MQENC_NATIVE );

Sets the encoding.

MQLONG expiry( ) const ;

Returns the expiry.

void setExpiry( const MQLONG expiry );

Sets the expiry.

ImqString format( ) const ;

Returns a copy of the format, including trailing blanks.

ImqBoolean formatIs( const char * format-to-test ) const ;

Returns TRUE if the format is the same as format-to-test.

void setFormat( const char * name = 0 );

Sets the format, padding to eight characters with trailing blanks.

MQLONG messageFlags( ) const ;

Returns the message flags.

void setMessageFlags( const MQLONG flags );

Sets the message flags.

MQLONG messageType( ) const ;

Returns the message type.

void setMessageType( const MQLONG type );

Sets the message type.

MQLONG offset( ) const ;

Returns the offset.

void setOffset( const MQLONG offset );

Sets the offset.

MQLONG originalLength( ) const ;

Returns the original length.

void setOriginalLength( const MQLONG length );

Sets the original length.

MQLONG persistence( ) const ;

Returns the persistence.

void setPersistence( const MQLONG persistence );

Sets the persistence.

MQLONG priority( ) const ;

Returns the priority.

void setPriority( const MQLONG priority );

Sets the priority.

ImqString putApplicationName( ) const ;

Returns a copy of the put application name.

void setPutApplicationName( const char * name = 0 );

Sets the put application name.

MQLONG putApplicationType( ) const ;

Returns the put application type.

void setPutApplicationType( const MQLONG type = MQAT_NO_CONTEXT );

Sets the put application type.

ImqString putDate( ) const ;

Returns a copy of the put date.

void setPutDate( const char * date = 0 );

Sets the put date.

ImqString putTime( ) const ;

Returns a copy of the put time.

void setPutTime( const char * time = 0 );

Sets the put time.

ImqBoolean readItem( ImqItem & item );

Reads into the item object from the message buffer, using the ImqItem pasteIn method. It returns TRUE if successful.

ImqString replyToQueueManagerName( ) const ;

Returns a copy of the reply-to queue manager name.

void setReplyToQueueManagerName( const char * name = 0 );

Sets the reply-to queue manager name.

ImqString replyToQueueName( ) const ;

Returns a copy of the reply-to queue name.

void setReplyToQueueName( const char * name = 0 );

Sets the reply-to queue name.

MQLONG report( ) const ;

Returns the report.

void setReport( const MQLONG report );

Sets the report.

MQLONG sequenceNumber( ) const ;

Returns the sequence number.

void setSequenceNumber( const MQLONG number );

Sets the sequence number.

size_t totalMessageLength( ) const ;

Returns the total message length.

ImqString userId( ) const ;

Returns a copy of the user id.

void setUserId( const char * id = 0 );

Sets the user id.

ImqBoolean writeItem( ImqItem & item );

Writes from the item object into the message buffer, using the ImqItem copyOut method. Writing may take the form of insertion, replacement or an append: this depends on the class of the item object. This method returns TRUE if successful.

Object data (protected)

MQMD omqmd

The MQMD data structure.