ImqMessage C++ class

This class encapsulates an MQMD data structure and also handles the construction and reconstruction of message data.

Figure 1. ImqMessage class


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 that 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

    We can also use a Coded Character Set Id of your choice. For information about this, see Code page conversion.

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

    expiry
    A time-dependent quantity that controls how long IBM 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 constant value is MQFMT_NONE. The following additional constants 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

    We can also use an application-specific string of your choice. For more information about this, see the Format (MQCHAR8) field of the message descriptor (MQMD).

    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

    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

    We can also use an application-specific value of your choice. For more information about this, see the MsgType (MQLONG) field of the message descriptor (MQMD).

    offset
    Offset information. The initial value is zero.

    original length
    The original length of a segmented message. The initial value is MQOL_UNDEFINED.

    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.

    property validation
    Specifies whether validation of properties should take place when a property of the message is set. The initial value is MQCMHO_DEFAULT_VALIDATION. The following additional values are possible:

    • MQCMHO_VALIDATE
    • MQCMHO_NO_VALIDATION
    The following methods act on property validation:

      MQLONG propertyValidation( ) const ;
      Returns the property validation option.

      void setPropertyValidation( const MQLONG option );
      Sets the property validation option.

    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

    We can also use an application-specific string of your choice. For more information about this, see the PutApplType (MQLONG) field of the message descriptor (MQMD).

    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_CORREL_ID
    • MQRO_COPY_MSG_ID_TO_CORREL_ID
    • MQRO_PASS_CORREL_ID
    • MQRO_DEAD_LETTER_Q
    • MQRO_DISCARD_MSG
    where * indicates values that are not supported on IBM MQ for z/OS.

    sequence number
    Sequence information identifying a message within a group. The initial value is one.

    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, padded 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 can 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 methods (protected)

    static void setVersionSupported ( const MQLONG );
    Sets the MQMD version. Defaults to MQMD_VERSION_2.


Object data (protected)

    MQMD1 omqmd
    The MQMD data structure on z/OS.

    MQMD2 omqmd
    The MQMD data structure on Multiplatforms.