Message-related global variables

These global variables provide application programs with access to message information from the most recent message sent or received.

@@msgcorrelation

Contains correlation from last message sent or read.

(MQ) MQ does not verify whether @@msgcorrelation consists of printable characters. Application programs should not rely on @@msgcorrelation being in the current server character set, and should use @@msgcorrelation only as a selector for subsequent messages. If @@msgcorrelation is to be returned to the application, convert it to a varbinary datatype.
(JMS) @@msgcorrelation contains the correlation ID from the the most recent message sent or received.

@@msgheader

Contains message header information from the most recent message received. This variable’s format is in XML. For details about this format, see “<msgheader> and <msgproperties> documents”.

Functions that set @@msgheader include msgrecv and msgconsume.

Table 3-1shows the valid field names for the @@msgheader global variable, and their descriptions for MQ. Table 3-2 lists @@msgheader fields and descriptions for JMS.

**Table 3-1: MQ *@@msgheader* fields and descriptions**
Property name	Description
ApplIdentityData	Application data relating to identity.
ApplOriginData	Application data relating to origin.
CodedCharSetId	Numeric-coded character set identifier.
CorrelId	Correlation identifier.
Encoding	Encoding of binary data in the message. Bit mask of flags in the Encoding field.
DecimalEncoding	This is the encoding for decimal numbers in the message payload, and is a synthesized property derived from the Encoding field. If: BigEndian – decimal numbers are big-endian. LittleEndian – decimal numbers are little-endian. Undefined – decimal numbers are not defined as either big-endian or little-endian.
Feedback	Feedback status.
FloatEncoding	This is the encoding for floating point numbers in the payload, and is a synthesized property derived from the Encoding field. If: BigEndian – floating point numbers are big-endian. LittleEndian – floating point numbers are little-endian. Undefined – floating point numbers are not defined as either big-endian or little-endian.
Format	Format name of message data, can be an MQ-defined format name or an application-defined format name.
GroupId	Group identifier.
IntegerEncoding	Encoding for integers in the payload, and is a synthesized property that is derived from the Encoding field. If: BigEndian – integers are big-endian. LittleEndian – integers are little-endian. Undefined – the endianness of integers is undefined.
LastMsgInGroup	If: true – message is the last message of a group. false – message is not the last message of a group.
MsgId	Message identifier.
MsgInGroup	If: true – message is part of a group. false – message is not part of a group.
MsgSeqNumber	Message sequence number.
MessageType	Message type in the form of a decimal number, unless: request – the message is a request message. reply – the message is a reply message. datagram – the message is a datagram message. report – the message is a report message.
NegativeActionNotification	This is a synthesized property, derived from the Report field. The receiving application should generate a negative-action notification (NAN) report. yes – receiving application should generate a NAN report message, and send it to the destinations specified in the ReplyToQ and ReplyToQMgr fields. no – receiving application should not generate a NAN report message.
Persistence	The persistence of the message. If: persistent – the message is a persistent message. non-persistent – the message is a nonpersistent message.
PositiveActionNotification	This is a synthesized property derived from the Report field. The receiving application should generate a positive-action notification (PAN) report. If: yes – receiving application should generate a PAN report message, and send it to the destinations specified in the ReplyToQ and ReplyToQMgr fields. no – receiving application should not generate a PAN report message.
PutApplName	This is the name of the application that puts the message in the queue.
PutApplType	This is the type of application that puts the message in the queue.
PutDate	This is the date when the message was put in the queue.
PutTime	This is the time when the message was put in the queue.
ReplyCorrelationId	A synthesized property, derived from the Report field. Denotes what to use as the correlation ID of the report message. msgId – the correlation ID of the report message should be set to the message ID of the received message. correlationId – the correlation ID of the report message should be set to the correlation ID of the received message.
ReplyMsgId	A synthesized property, derived from the Report field. Denotes what to use as the message ID of the report message. new – use a new message ID as the message ID of the report message. original – use the message ID received as the message ID of the report message.
ReplyToQ	Name of reply queue.
ReplyToQMgr	Name of the reply queue manager.
Report	Report options from the message. This is a bitmap of MQRO * flags.
UserIdentifier	User identifier.

**Table 3-2: JMS @@msgheader fields and descriptions**
Property name	Description
correlation	Correlation ID from the message
destination	The name of the destination from the message
encoding	The encoding name of the message
messageid	The message ID from the message
mode	Delivery mode of the message: persistent non-persistent
priority	The message priority
redelivered	The redelivery status from the message
replyto	The replyto name from the message
timestamp	The message timestamp
ttl	A time-to-live value from the message that indicates how long a message exists
type	The message type

@@msgid

Contains the ID of the most recent message sent or received.

MQ does not verify that the @@msgid consists of printable characters. Application programs should not rely on @@msgid being in the current server character set, and should only use @@msgid as a selector for subsequent messages. If @@msgid is returning to the application, it should be converted to a varbinary datatype.

Functions that set the variable are:

(JMS) msgsend, msgpublish, msgrecv, msgconsume
(MQ) msgsend, msgrecv

@@msgproperties

Contains message properties information from the most recent message received. This variable’s format is in XML. For details about this format, see “<msgheader> and <msgproperties> documents”.

(JMS) the @@msgproperties are the user properties from the message.
(MQ) if:
- The message contains one or more MQRF headers, the name-value pairs in the MQRF headers are inserted into @@msgproperties.
- Since the name-value pairs in the MQRF header can have nonunique names, the names are made unique by appending a “_ddd,” where ddd is an integer extension for uniqueness. For instance, a MQRF header with these topics:
```
MQPSTopic   */baseball
MQPSTopic   */baseball/world series
MQPSTopic   */sports
```
  Results in these properties in @@msgproperties:
```
MQPSTopic     */baseball
MQPSTopic_1   */baseball/world series
MQPSTopic_2   */sports
```

Functions that set @@msgproperties include:

(JMS) msgrecv, msgconsume
(MQ) msgrecv

The value pairs that are extracted from the RF header if they are present include:

MQPSCommand	MQPSIntData	MQPSReason	MQPSSubIdentity
MQPSCompCode	MQPSParmId	MQPSReasonText	MQPSSubName
MQPSCorrelId	MQPSPubOpts	MQPSRegOpts	MQPSSubUserData
MQPSDelOpts	MQPSPubTime	MQPSSeqNum	MQPSSubUserData
MQPSErrorId	MQPSQMgrName	MQPSStreamName	MQPSTopic
MQPSErrorPos	MQPSQName	MQPSStringData	MQPSUserId

Unrecognized names are ignored. If the value is quoted (“) in the RF header, the surrounding quotes are removed. In a quoted value, if there are escaped quotes (“”) within the value, double quotes are replaced by a single quote.

@@msgreplyqmgr

MQ only – contains the ReplyToQmgr name of the last message read.

@@msgreplytoinfo

Contains the name (provider_url, queue_name, topic_name, user_name) of the topic or queue name used for both sending and replying messages directly. Can be a permanent or temporary destination.

Functions that set @@msgreplytoinfo include:

(JMS) msgconsume, msgpublish, msgrecv, msgsend
(MQ) msgrecv, msgsend

JMS only – the password is not included in the value of @@msgreplytoinfo. To use this destination as an argument in a subsequent msgsend or msgrecv call, add password=<your password>.

MQ only – can contain the syntax for remote_qmgr; @@msgreplytoinfo shows request/reply messaging showing support for the cluster queue manager using @@msgcorrelation:

For example, one Adaptive Server connects to the MASTER_MSCAI queue manager, and sends a message to Q1, located on the SLAVE_MSCAI remote queue manager, with the replyToQueue property specified as MASTERQ. Once you send msgsend, its value becomes the value of @@msgreplytoinfo:��

select msgsend('d','ibm_mq:CH1/tcp/host1(1105)?
qmgr=MASTER,remote_qmgr=SLAVE,queue=Q1,alter_user=yes',
    message property 'replyToQueue=MASTERQ')
go
select @@msgreplytoinfo
go

IBM_MQ:CH1/tcp/host1(1105)?qmgr=MASTER,queue=MASTERQ

The other Adaptive Server connects to the queue manager SLAVE, and receives the previously sent message from Q1. The @@msgreplytoinfo global variable then includes the syntax for remote_qmg, so that the reply queue in this case is the remote queue.

select msgrecv('ibm_mq:CH2/tcp/host2(4810)?
qmgr=SLAVE,queue=Q1,alter_user=yes', option 'timeout=100')
go
select @@msgreplytoinfo
go

ibm_mq:CH2/tcp/host2(4810)?qmgr=SLAVE,remote_qmgr=MASTER,queue=MASTERQ

When using a @@msgreplytoinfo that contains the syntax remote_qmgr to send a reply message, msgrecv, whether the reply message reaches the correct remote queue manager or not, depends on how you have configured your WebSphere MQ. See “Working with remote queue objects�”.

MQ API call failed with reason code '%s' (%d)

The “%s” is substituted with the MQ mnemonic for the MQ reason code.

The “%d” is substituted with the decimal MQ reason code.

Functions that set the variable are:

(JMS) msgsend, msgpublish, msgrecv, msgconsume.
(MQ) msgsend, msgrecv.

@@msgtimestamp

Contains the timestamp included in the message last sent.

Functions that set the variable are: msgsend, msgpublish.

Examples

Example 1

Example 1 MQ only – shows request/reply messaging using both @@msgreplytoinfo and @@msgcorrelation:

Session 1 (requester)	Session 2 (receiver)
select msgsend('sender msessage', 'ibm_mq:channel1/TCP/host1(5678)' + '?qmgr=QM1' + ',queue=Q100', option 'msgType=request', message property 'correlationId=0x123456' + 'replyToQueue=Q200')
	select msgrecv( 'ibm_mq:channel1/TCP/host1(5678)' + '?qmgr=QM1' + ',queue=Q100') select msgsend('receiver reply', @@msgreplytoinfo, option 'msgType=reply' message property 'correlationId=' + @@msgcorrelation)
select msgrecv( 'ibm_mq:channel1/TCP/host1(5678)' + '?qmgr=QM1' + ',queue=Q200' option 'timeout=30ss', + 'correlationID=0x123456')

Session 1 (requester)

Session 2 (receiver)

select msgsend('sender msessage',
   'ibm_mq:channel1/TCP/host1(5678)'
      + '?qmgr=QM1'
      + ',queue=Q100',
   option 'msgType=request',
   message property
      'correlationId=0x123456'
     + 'replyToQueue=Q200')

select msgrecv(
   'ibm_mq:channel1/TCP/host1(5678)'
       + '?qmgr=QM1'
       + ',queue=Q100')

select msgsend('receiver reply',
       @@msgreplytoinfo,
       option 'msgType=reply'
        message property
               'correlationId='
                + @@msgcorrelation)

select msgrecv(
    'ibm_mq:channel1/TCP/host1(5678)'
          + '?qmgr=QM1'
          + ',queue=Q200'
     option 'timeout=30ss',
          + 'correlationID=0x123456')

In this example:

Session 1 sends the request message to Q100, and expects the reply messsage on Q200. It sets the correlation to 0x123456.
Session 2 reads a message from Q100, sends a reply message to Q200, and specifies the correlation to 0x123456. The reply queue is obtained from the message that was just read.
Session 1 reads the reply message from Q200, wanting only message with correlation 0x123456.

Usage

These global variables are char datatypes, of length 16384.
You can remove trailing blanks using rtrim.