Retrieving replies to your commands

The command server sends a response to a reply queue for each request message it receives. Any administration application must receive, and handle the reply messages.

When the command processor processes your commands, any reply messages are put onto the reply-to queue specified in the MQPUT call. The command server sends the reply messages with the same persistence as the command message it received.

Waiting for a reply

Use the MQGET call to retrieve a reply from your request message. One request message can produce several reply messages. For details, see Interpreting the reply messages from the command server.

We can specify a time interval that an MQGET call waits for a reply message to be generated. If we do not get a reply, use the checklist beginning in topic If we do not receive a reply.

To use the MQGET call:

1. Set these parameters:

   Hconn

   The connection handle returned by the MQCONN or MQCONNX call.

   Hobj

   The object handle returned by the MQOPEN call for the reply-to queue.

   Buffer

   The name of the area to receive the reply.

   BufferLength

   The length of the buffer to receive the reply. This must be a minimum of 80 bytes.

2. To ensure that you only get the responses from the command that we issued, we must specify the appropriate MsgId and CorrelId fields. These depend on the report options, MQMD_REPORT, you specified in the MQPUT call:

   MQRO_NONE

   Binary zero, '00...00' (24 nulls).

   MQRO_NEW_MSG_ID

   Binary zero, '00...00' (24 nulls).

   This is the default if none of these options has been specified.

   MQRO_PASS_MSG_ID

   The MsgId from the MQPUT.

   MQRO_NONE

   The MsgId from the MQPUT call.

   MQRO_COPY_MSG_ID_TO_CORREL_ID

   The MsgId from the MQPUT call.

   This is the default if none of these options has been specified.

   MQRO_PASS_CORREL_ID

   The CorrelId from the MQPUT call.

   For more details on report options, see Report options and message flags.

3. Set the following GetMsgOpts fields:

   Options

   MQGMO_WAIT

   If we are not using the same code page as the queue manager, set MQGMO_CONVERT, and set CodedCharSetId as appropriate in the MQMD.

   WaitInterval

   For replies from the local queue manager, try 5 seconds. Coded in milliseconds, this becomes 5 000. For replies from a remote queue manager, and channel control and status commands, try 30 seconds. Coded in milliseconds, this becomes 30 000.

Discarded messages

If the command server finds that a request message is not valid, it discards this message and writes the message CSQN205I to the named reply-to queue. If there is no reply-to queue, the CSQN205I message is put onto the dead-letter queue. The return code in this message shows why the original request message was not valid:

00D5020F	It is not of type MQMT_REQUEST.
00D50210	It has zero length.
00D50212	It is longer than 32 762 bytes.
00D50211	It contains all blanks.
00D5483E	It needed converting, but Format was not MQFMT_STRING.
Other	See Command server codes

The command server reply message descriptor

For any reply message, the following MQMD message descriptor fields are set:

MsgType	MQMT_REPLY
Feedback	MQFB_NONE
Encoding	MQENC_NATIVE
Priority	As for the MQMD in the message we issued.
Persistence	As for the MQMD in the message we issued.
CorrelId	Depends on the MQPUT report options.
ReplyToQ	None.

The command server sets the Options field of the MQPMO structure to MQPMO_NO_SYNCPOINT. This means that we can retrieve the replies as they are created, rather than as a group at the next syncpoint.

Parent topic: Writing programs to administer IBM MQ for z/OS