The Message Handler sample

The Message Handler sample TSO application allows you to browse, forward, and delete messages on a queue. The sample is available in C and COBOL.

Preparing and running the sample

Follow these steps:

  1. Prepare the sample as described in Preparing sample applications for the TSO environment.
  2. Tailor the CLIST (CSQ4RCH1) provided for the sample to define: - The location of the panels - The location of the message file - The location of the load modules

CLIST CSQ4RCH1 may be used to run both the C and the COBOL version of the sample. The supplied version of CSQ4RCH1 runs the C version, and contains instructions on the tailoring necessary for the COBOL version.

Notes:

  1. There are no sample queue definitions provided with the sample.

  2. VS COBOL II does not support multitasking with ISPF, so you should not use the Message Handler sample application on both sides of a split screen. If you do, the results are unpredictable.

Using the sample

Having installed the sample and invoked it from the tailored CLIST CSQ4RCH1, the screen shown in Figure 49 is displayed.

Figure 49. Initial screen for Message Handler sample

+--------------------------------------------------------------------------------+
|----------------------- WebSphere 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 50).

Figure 50. Message list screen for Message Handler sample

+--------------------------------------------------------------------------------+
|----------------------- WebSphere 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\PROGT|
| 03   10/16/1998  13:54:01 MQIMS    NTSFV02      00000002 NTSFV02B              |
| 04   10/16/1998  13:57:22 MQIMS    johnj        00000011 EDIT\CLASSES\BIN\PROGT|
|******************************* 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 the message was put on the queue (GMT)

Put Time HH:MM:SS
Time 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 51.

Figure 51. Chosen message is displayed

+--------------------------------------------------------------------------------+
|----------------------- WebSphere 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 prior to forwarding the message.

The sample design will only allow messages with unique MsgId / CorrelId combinations to be selected and displayed, this is 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.

Design of the sample

This section describes the design of each of the programs that comprise the Message Handler sample application.

Object validation program

This requests a valid queue and queue manager name. If you do not specify a queue manager name, the default queue manager is used, if available. Only local queues can be used; an MQINQ is issued to check the queue type and an error is reported if the queue is not local. If the queue is not opened successfully, or the MQGET call is inhibited on the queue, error messages are returned indicating the CompCode and Reason return code.

Message list program

This displays a list of messages on a queue with information about them such as the putdate, puttime and the message format. The maximum number of messages stored in the list is 99. If there are more messages on the queue than this, the current queue depth is also displayed. To choose a message for display, type the message number into the entry field (the default is 01). If your entry is invalid, you will receive an appropriate error message.

Message content program

This displays message content. The content is formatted and split into two parts:

  1. the message descriptor
  2. the message buffer

The message descriptor shows the contents of each field on a separate line.

The message buffer is formatted depending on its contents. If the buffer holds a dead letter header (MQDLH) or a transmission queue header (MQXQH), these are formatted and displayed before the buffer itself.

Before the buffer data is formatted, a title line shows the buffer length of the message in bytes. The maximum buffer size is 32768 bytes, and any message longer than this is truncated. The full size of the buffer is displayed along with a message indicating that only the first 32768 bytes of the message are displayed.

The buffer data is formatted in two ways:

  1. After the offset into the buffer is printed, the buffer data is displayed in HEX.
  2. The buffer data is then displayed again as EBCDIC values. If any EBCDIC value cannot be printed, it prints a '.' instead.

You may enter 'D' for delete, or 'F' for forward into the action field. If you choose to forward the message, the forward-to queue and queue manager name must be filled in appropriately. The defaults for these fields are read from the message descriptor ReplyToQ and ReplyToQMgr fields.

If you forward a message, any header block stored in the buffer is stripped. If the message is forwarded successfully, it is removed from the original queue. If you enter invalid actions, error messages are displayed.

An example help panel is also available called CSQ4CHP9.



© IBM Corporation 1993, 2002. All Rights Reserved