These global variables provide application programs with access to message information from the most recent message sent or received.
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.
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.
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:
|
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:
|
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:
|
LastMsgInGroup |
If:
|
MsgId |
Message identifier. |
MsgInGroup |
If:
|
MsgSeqNumber |
Message sequence number. |
MessageType |
Message type in the form of a decimal number, unless:
|
NegativeActionNotification |
This is a synthesized property, derived from the Report field. The receiving application should generate a negative-action notification (NAN) report.
|
Persistence |
The persistence of the message. If:
|
PositiveActionNotification |
This is a synthesized property derived from the Report field. The receiving application should generate a positive-action notification (PAN) report. If:
|
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.
|
ReplyMsgId |
A synthesized property, derived from the Report field. Denotes what to use 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. |
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:
|
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 |
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
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.
MQ only – contains the ReplyToQmgr name of the last message read.
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�”.
JMS only – contains the schema of the message or a null value. Contains the value of the Adaptive Server property ase_message_body_schema. See the description of the schema option in msgsend and msgpublish.
Functions that set @@msgchema include: msgsend, msgpublish.
Contains either the integer error code of the service provider exception, or zero, if the last operation did not raise an exception.
Functions that set @@msgstatus include: msgsend, msgpublish, msgrecv, msgconsume.
Contains either the error message of the service provider exception, or zero, if the last msgsend, msgpublish, msgrecv, or msgconsume raised an exception, or an empty string.
(MQ) contains provider error message of last messaging operation. The MQ client libraries do not provide localized error messages, so you see an error message such as:
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.
Contains the timestamp included in the message last sent.
Functions that set the variable are: msgsend, msgpublish.
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')
|
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.
These global variables are char datatypes, of length 16384.
You can remove trailing blanks using rtrim.