Use the Message Handler sample on z/OS

Having installed the sample and invoked it from the tailored CLIST CSQ4RCH1, the screen shown in Figure 1 is displayed.
Figure 1. Initial screen for Message Handler sample
----------------------- IBM MQ for z/OS -- Samples ------------------------
COMMAND ===>
User Id : JOHNJ




Enter information. Press ENTER :


Queue Manager Name  : ________________________________________________ :

Queue Name      : ________________________________________________ :









F1=HELP   F2=SPLIT   F3=END    F4=RETURN  F5=RFIND   F6=RCHANGE
F7=UP    F8=DOWN   F9=SWAP   F10=LEFT   F11=RIGHT  F12=RETRIEVE
Enter the queue manager and queue name to be viewed (case sensitive) and the message list screen is displayed (see Figure 2 ).
Figure 2. Message list screen for Message Handler sample
----------------------- IBM MQ for z/OS -- Samples ------- Row 1 to 4 of 4
COMMAND ==>

Queue Manager  : VM03                       :
Queue      : MQEI.IMS.BRIDGE.QUEUE              :

Message number  01 of 04

Msg  Put Date  Put Time Format   User   Put Application
No  MM/DD/YYYY HH:MM:SS Name  Identifier  Type   Name
01  10/16/1998 13:51:19 MQIMS  NTSFV02   00000002 NTSFV02A
02  10/16/1998 13:55:45 MQIMS  JOHNJ    00000011 EDIT\CLASSES\BIN\PROGTS
03  10/16/1998 13:54:01 MQIMS  NTSFV02   00000002 NTSFV02B
04  10/16/1998 13:57:22 MQIMS  johnj    00000011 EDIT\CLASSES\BIN\PROGTS
******************************* Bottom of data ********************************
This screen shows the first 99 messages on the queue and, for each, shows the following fields:

    Msg No
    Message number

    Put Date MM/DD/YYYY
    Date that the message was put on the queue (GMT)

    Put Time HH:MM:SS
    Time that the message was put on the queue (GMT)

    Format Name
    MQMD.Format field

    User Identifier
    MQMD.UserIdentifier field

    Put Application Type
    MQMD.PutApplType field

    Put Application Name
    MQMD.PutApplName field

The total number of messages on the queue is also displayed.

From this screen a message can be chosen, by number not by cursor position, and then displayed. For an example, see Figure 3.
Figure 3. Chosen message is displayed
----------------------- IBM MQ for z/OS -- Samples ----- Row 1 to 35 of 35
COMMAND ==>

Queue Manager  : VM03                       :
Queue      : MQEI.IMS.BRIDGE.QUEUE              :
Forward to Q Mgr : VM03                       :
Forward to Queue : QL.TEST.ISCRES1                 :

Action : _ :  (D)elete (F)orward

Message Content :
-------------------------------------------------------------------------------
Message Descriptor
StrucId     : `MD `
Version     : 000000001
Report      : 000000000
MsgType     : 000000001
Expiry      : -00000001
Feedback     : 000000000
Encoding     : 000000785
CodedCharSetId  : 000000500
Format      : `MQIMS  `
Priority     : 000000000
Persistence   : 000000001
MsgId      : `C3E2D840E5D4F0F34040404040404040AF6B30F0A89B7605`X
CorrelId     : `000000000000000000000000000000000000000000000000`X
BackoutCount   : 000000000
ReplyToQ     : `QL.TEST.ISCRES1                 `
ReplyToQMgr   : `VM03                      `
UserIdentifier  : `NTSFV02   `
AccountingToken :
`06F2F5F5F3F0F100000000000000000000000000000000000000000000000000`X
ApplIdentityData : `                `
PutApplType   : 000000002
PutApplName   : `NTSFV02A          `
PutDate     : `19971016`
PutTime     : `13511903`
ApplOriginData  : `  `

Message Buffer :  108 byte(s)
00000000 : C9C9 C840 0000 0001 0000 0054 0000 0311 `IIH ............`
00000010 : 0000 0000 4040 4040 4040 4040 0000 0000 `....    ....`
00000020 : 4040 4040 4040 4040 4040 4040 4040 4040 `        `
00000030 : 4040 4040 4040 4040 4040 4040 4040 4040 `        `
00000040 : 0000 0000 0000 0000 0000 0000 0000 0000 `................`
00000050 : 40F1 C300 0018 0000 C9C1 D7D4 C4C9 F2F8 ` 1C.....IAPMDI28`
00000060 : 40C8 C5D3 D3D6 40E6 D6D9 D3C4      ` HELLO WORLD  `
******************************* Bottom of data ********************************

Once the message has been displayed it can be deleted, left on the queue, or forwarded to another queue. The Forward to Q Mgr and Forward to Queue fields are initialized with values from the MQMD, these can be changed before forwarding the message.

The sample design allows only messages with unique MsgId / CorrelId combinations to be selected and displayed, because the message is retrieved using the MsgId and CorrelId as the key. If the key is not unique the sample cannot retrieve the chosen message with certainty.

Note: When we use the SCSQCLST(CSQ4RCH1) sample to browse messages, each invocation causes the backout count of the message to increase. To change the behavior of this sample, copy the sample and modify the contents as necessary. We should be aware that other applications that rely on this backout count can be influenced by this increasing count. Parent topic: The Message Handler sample on z/OS