INTEROPERABILITY BY TOM KRUCZEK
INSIGHTS
The necessary application
code and object definitions
for communicating
between two messaging-
enabled programs are
described in Part II
of this three-part series
on MQSeries.
MQSeries: Part II —
Program-to-Program
Communication
P
art I (January 1996) presented an overview of Message Queuing
using IBM’s MQSeries. This installment will present the necessary
application code and MQSeries object definitions required to
communicate between two messaging-enabled programs. The
concluding article will discuss the concept of Distributed Queue Management
(DQM) for connecting MQSeries queue managers.
The Message Queuing Interface (MQI) is I suggest using some method to maintain
how MQSeries programs communicate with your MQSeries objects externally from the
one another. Messages are passed between queue managers themselves. At my installa-
programs via PUTs and GETs to “queues”. tion, DB2 is used for MVS/ESA objects.
Programs don’t know (or usually care) where AIX and OS/2 objects are maintained on a
the message came from, or where the file server and are grouped by application.
response (if any) goes. The definition of This allows the installation administrator to
MQSeries objects and the successful naviga- easily move, change, etc., MQSeries objects
tion of messages across the MQSeries net- across platforms.
work is the responsibility of the installations’
MQ administrator(s). QUEUES
For application queue names I chose to
NAMING AND MAINTAINING follow our standard MVS data set naming
MQSERIES OBJECTS conventions. However, when an application
Although object naming conventions and refers to a queue, it is really referring to the
maintenance procedures need to be determined ALIAS name of that queue. This allows the
by each installation, I recommend taking con- system administrator more flexibility and
trol of these issues right from the start because easier maintainability of MQSeries objects by
they can quickly get out of hand. All MQSeries adding a “level of indirection”. Do not
objects at my installation (Figure 1) define queues with naming conventions that
contain a suffix indicating the basic type of incorporate information about where the
object, i.e., QUEUE, PROCESS, CHAN (for queue exists or its type, e.g., LOCAL
channel), and NAMELIST. Channels and or REMOTE, etc. For example, an installa-
transmission queues indicate source and target tion might choose to name a queue
queue managers in their names. “NASPA.MQSERIES.CSQ1.LOCAL.QUEUE”.
Figure 1: Sample MQSeries Object Names
OBJECT NAME OBJECT TYPE PLATFORM LOCATION/QMGR
NASPA.T.MQSERIES.QUEUE QLOCAL MVS/ESA CSQ1
NASPA.MQSERIES.QUEUE QALIAS MVS/ESA CSQ1
NASPA.T.MQSERIES.PROCESS PROCESS MVS/ESA CSQ1
CSQ1.CSQ2.CHAN SNDR CHAN MVS TO MVS CSQ1
CSQ1.CSQ2.CHAN RCVR CHAN MVS TO MVS CSQ2
CSQ1.CSQ2.QUEUE TX QUEUE MVS TO MVS CSQ1
TECHNICAL SUPPORT FEBRUARY 1996
 INTEROPERABILITY INSIGHTS

Figure 2: How to Define MQSeries Objects From MVS Batch The name of this queue includes its location—”CSQ1” and its type—
”LOCAL”. This might seem okay in the beginning, but names like this
//SMPLQDEF JOB ...
//* quickly create problems and confusion for the system administrator(s).
//COMMAND EXEC PGM=CSQUTIL,PARM=’CSQ1’ Today, the queue might exist on an MVS queue manager called CSQ1,
//STEPLIB DD DSN=yourhighlevelqualifier(s).SCSQAUTH,DISP=SHR
//SYSPRINT DD SYSOUT=*
but to increase throughput, might be moved to an AIX queue manager
//SYSIN DD * called QM01. Also, if another queue manager called CSQ2 needs
COMMAND to send messages to this queue, using this convention, the CSQ2
/*
//CSQUCMD DD * queue manager would have to refer to this queue as
DEFINE QLOCAL(NASPA.T.MQSERIES.QUEUE) +
LIKE(SYSTEM.DEFAULT.LOCAL.QUEUE) +
TRIGGER TRIGTYPE(EVERY) INITQ(CSQ1.INITQ) + Figure 3: continued
PROCESS(NASPA.T.MQSERIES.PROCESS)
DEFINE PROCESS(NASPA.T.MQSERIES.PROCESS) APPLTYPE(CICS) APPLICID(NSPA) *
DEFINE QALIAS(NASPA.MQSERIES.QUEUE) TARGQ(NASPA.T.MQSERIES.QUEUE) * TAKE SOME ACTION BECAUSE THE CONNECT FAILED!
/* *
// END-IF.
P220-MQOPEN.
MOVE MQOT-Q TO MQOD-OBJECTTYPE.
Figure 3: MQSeries PUT Program (MVS Batch) MOVE WS01-QUEUE-NAME TO MQOD-OBJECTNAME.
*
IDENTIFICATION DIVISION. COMPUTE WS01-OPTIONS = MQOO-OUTPUT.
PROGRAM-ID. PUTPROG. *
. CALL ‘MQOPEN’ USING WS01-HCONN
. MQOD
. WS01-OPTIONS
* —————————————————————————————— * WS01-HOBJ
WORKING-STORAGE SECTION. WS01-COMPCODE
* —————————————————————————————— * WS01-REASON.
01 WS01-HCONN PIC S9(9) BINARY VALUE ZERO. *
01 WS01-HOBJ-INQUIRY PIC S9(9) BINARY. IF WS01-COMPCODE NOT = MQCC-OK
01 WS01-OPTIONS PIC S9(9) BINARY. *
01 WS01-BUFFLEN PIC S9(9) BINARY. * TAKE SOME ACTION BECAUSE THE OPEN FAILED!
01 WS01-COMPCODE PIC S9(9) BINARY. *
01 WS01-REASON PIC S9(9) BINARY. END-IF.
01 WS01-QUEUE-NAME PIC X(48) VALUE P240-MQPUT.
‘NASPA.MQSERIES.QUEUE’. MOVE MQMT-DATAGRAM TO MQMD-MSGTYPE.
01 WS01-QMANAGER-NAME PIC X(48) VALUE MOVE MQCI-NONE TO MQMD-CORRELID.
‘CSQ1’. MOVE MQMI-NONE TO MQMD-MSGID.
01 WS01-PUT-BUFFER. COMPUTE MQPMO-OPTIONS = MQPMO-NO-SYNCPOINT +
05 FILLER PIC X(80) VALUE MQPMO-FAIL-IF-QUIESCING
‘THIS IS A TEST MQSERIES MESSAGE!’. MQPMO-DEFAULT-CONTEXT.
* *
* API CONTROL BLOCKS * GET THE LENGTH OF THE MESSAGE TO PUT - SEE WS01-PUT-BUFFER ABOVE
* MOVE LENGTH OF WS01-PUT-BUFFER TO WS01-BUFFLEN.
01 MQM-MESSAGE-DESCRIPTOR. *
COPY CMQMDV. CALL ‘MQPUT’ USING WS01-HCONN
* WS01-HOBJ-INQUIRY
* CMQPMOV DEFINES PUT OPTIONS (MQPMO) MQMD
* MQPMO
01 MQM-PUT-MESSAGE-OPTIONS. WS01-BUFFLEN
COPY CMQPMOV. WS01-PUT-BUFFER
* WS01-COMPCODE
* MQV CONTAINS CONTROL BLOCK CONSTANTS AND RETURN CODE VALUES WS01-REASON.
* USED TO TEST AGAINST MQI CALLS.
* IF WS01-COMPCODE NOT = MQCC-OK
01 MQM-CONSTANTS. *
COPY CMQV SUPPRESS. * TAKE SOME ACTION BECAUSE THE PUT FAILED!
* *
* CMQODV defines the object descriptor (MQOD) END-IF.
* P260-MQCLOSE.
01 MQM-OBJECT-DESCRIPTOR. MOVE MQCO-NONE TO WS01-OPTIONS.
COPY CMQODV. *
. CALL ‘MQCLOSE’ USING WS01-HCONN
. WS01-HOBJ
. WS01-OPTIONS
PROCEDURE DIVISION. WS01-COMPCODE
. WS01-REASON.
. *
. IF (WS01-COMPCODE NOT = MQCC-OK) THEN
PERFORM P200-MQCONN. *
PERFORM P220-MQOPEN. * TAKE SOME ACTION BECAUSE THE CLOSE FAILED!
PERFORM P240-MQPUT. *
PERFORM P260-MQCLOSE. END-IF.
PERFORM P280-MQDISC. P280-MQDISC.
. CALL ‘MQDISC’ USING WS01-HCONN
. WS01-COMPCODE
. WS01-REASON.
P200-MQCONN. *
CALL ‘MQCONN’ USING WS01-QMANAGER-NAME IF (WS01-COMPCODE NOT = MQCC-OK) THEN
WS01-HCONN *
WS01-COMPCODE * TAKE SOME ACTION BECAUSE THE DISCONNECT FAILED!
WS01-REASON. *
* END-IF.
IF (WS01-COMPCODE NOT = MQCC-OK) THEN
 INTEROPERABILITY INSIGHTS

“NASPA.MQSERIES.CSQ1.REMOTE.QUEUE”. I would have simply Figure 4: MQSeries GET Program (CICS)

called this queue “NASPA.T.MQSERIES.QUEUE”. Its name doesn’t IDENTIFICATION DIVISION.
reflect the location or type of queue (although it does indicate “T” for test PROGRAM-ID. GETPROG.
or “P” for production). To simplify things even more, I would also create .
.
an ALIAS queue definition for “NASPA.T.MQSERIES.QUEUE”, .
calling it “NASPA.MQSERIES.QUEUE”. Application programs would * ——————————————————————————————- *
then refer to this queue using only its ALIAS name. WORKING-STORAGE SECTION.
* ——————————————————————————————- *
01 WS01-HCONN PIC S9(9) BINARY VALUE ZERO.
PROCESS 01 WS01-HOBJ PIC S9(9) BINARY.
01 WS01-OPTIONS PIC S9(9) BINARY.
Except for the object suffix of “PROCESS”, process definitions 01 WS01-BUFFER-LENGTH PIC S9(9) BINARY.
match the queue name that required that associated process. Using the 01 WS01-DATA-LENGTH PIC S9(9) BINARY.
previous example, if a process definition was required, I would call it 01 WS01-COMP-CODE PIC S9(9) BINARY.
01 WS01-REASON-CODE PIC S9(9) BINARY.
“NASPA.T.MQSERIES.PROCESS”. 01 WS01-QUEUE-NAME PIC X(48) VALUE
‘NASPA.MQSERIES.QUEUE’.
CHANNELS 01 WS01-GET-BUFFER PIC X(80).
*
Channel definitions incorporate queue manager names into their * MQ/API CONTROL BLOCKS
naming conventions. I use “source” queue manager and “target” queue *
01 MQM-MESSAGE-DESCRIPTOR.
manager plus the object type of “CHAN” as the suffix. For example, COPY CMQMDV.
a Sender channel for an MVS queue manager called CSQ1 sending to *
another MVS queue manager called CSQ2 would be called * CMQGMOV DEFINES GET OPTIONS FOR MQGMO
*
CSQ1.CSQ2.CHAN. SinceSender/Receiver channel names must match 01 MQM-GET-MESSAGE-OPTIONS.
at each end of the connection, the Receiver channel name at CSQ2 would COPY CMQGMOV.
be called the same name—CSQ1.CSQ2.CHAN, except this would be *
* MQV CONTAINS CONTROL BLOCK CONSTANTS AND RETURN CODE VALUES
a Receiver type of channel. For transmission queues, I follow channel * USED TO TEST AGAINST MQI CALLS.
naming conventions, except I add “QUEUE” as the objects’suffix. *
01 MQM-CONSTANTS.
COPY CMQV SUPPRESS.
DEFINING MQSERIES OBJECTS *
There are several ways to define MQSeries objects: * CMQODV DEFINES THE MQ OBJECT DESCRIPTOR - MQOD
*
01 MQM-OBJECT-DESCRIPTOR.
1. CSQUTIL, an MVS/ESA batch utility provided by IBM, is used COPY CMQODV.
to display, create, alter, and delete MVS/ESA MQSeries objects. See .
.
Figure 2. .
PROCEDURE DIVISION.
.
2. From TSO/ISPF, the system administrator can issue commands to .
display, create, alter, and delete MQSeries objects using a procedure .
called CSQOREXX, also provided by IBM. PERFORM P220-MQOPEN.
PERFORM P240-MQGET.
PERFORM P260-MQCLOSE.
3. Programmable Command Formats (PCFs) are provided so instal- .
lation- or vendor-developed programs can issue MQSeries commands .
.
to control MQSeries objects. P220-MQOPEN.
MOVE MQOT-Q TO MQOD-OBJECTTYPE.
MOVE WS01-QUEUE-NAME TO MQOD-OBJECTNAME.
4. MQSeries Version 2 provides a utility that can control MQSeries *
objects either interactively or by batching commands through the use COMPUTE WS01-OPTIONS = MQOO-INPUT-SHARED.
of an input data set. *
CALL ‘MQOPEN’ USING WS01-HCONN
MQOD
5. Using DQM, some queue managers have the ability to configure WS01-OPTIONS
other (remote) queue managers. This means the system administrator WS01-HOBJ
WS01-COMP-CODE
can display, create, alter, and delete MQSeries objects across different WS01-REASON-CODE.
platforms in a client/server fashion. However, some limitations do *
IF WS01-COMP-CODE NOT= MQCC-OK
exist on what platforms support this feature. *
* TAKE SOME ACTION BECAUSE THE OPEN FAILED!
6. Other methods specific to the platform and version of MQSeries *
END-IF.
being used.
P240-MQGET.
For simplicity, I’ve chosen to discuss the first type, using the *
* CORRELID AND MSGID ARE SET TO LOW-VALUES TO RETRIEVE ANY MSG
CSQUTIL MVS batch utility (Figure 2). *
MOVE MQCI-NONE TO MQMD-CORRELID.
MOVE MQMI-NONE TO MQMD-MSGID.
SIMPLE MQSERIES APPLICATION *
Figures 3 and 4 represent fictitious MQSeries application programs * SET THE GET OPTIONS TO NOT WAIT FOR A MESSAGE OR FAIL IF THE
called “PUTPROG” and “GETPROG”. For the sake of this discussion, * QUEUE MANAGER IS BEING SHUTDOWN.
*
PUTPROG and GETPROG execute on the same MVS image. COMPUTE MQGMO-OPTIONS = MQGMO-NO-WAIT +
PUTPROG is executed as part of an MVS batch job, and “PUTs” a MQGMO-FAIL-IF-QUIESCING.
message to a local MVS queue called “NASPA.MQSERIES.QUEUE”. *
MOVE LENGTH OF WS01-GET-BUFFER TO WS01-BUFFER-LENGTH.
Note that “NASPA.MQSERIES.QUEUE” is an ALIAS name for the

TECHNICAL SUPPORT FEBRUARY 1996

 INTEROPERABILITY INSIGHTS

Figure 4: continued image. This means that all spaces or low values in position 1 can be
*
CALL ‘MQGET’ USING WS01-HCONN
used for the queue manager name instead of hardcoding a name like
WS01-HOBJ “CSQ1” in your application program(s).
MQMD A CICS program called GETPROG is associated with a CICS
MQGMO
WS01-BUFFER-LENGTH TRAN-ID called “NSPA”. GETPROG and NSPA are defined to the
WS01-GET-BUFFER CICS region the normal way using CEDA. Notice that GETPROG
WS01-DATA-LENGTH doesn’t need to issue MQCONN or MQDISC MQI calls. This is
WS01-COMP-CODE
WS01-REASON-CODE. because the CICS region has already connected to the MVS queue
manager “CSQ1” during startup.
IF (WS01-COMP-CODE = MQCC-OK) AND
(WS01-REASON-CODE = MQRC-NONE)
GETPROG is automatically started (triggered) whenever a message
* arrives on the local queue NASPA.T.MQSERIES.QUEUE. This is
* PROCESS THE MESSAGE HERE because of the queue’s associated PROCESS definition (see Figure 2),
*
ELSE which defines the APPLTYPE of CICS and APPLICID (TRAN-ID)
* of NSPA and the queue’s INITQ parameter.
* CONTINUE CHECKING MQRC VALUES TO DETERMINE WHAT THE When GETPROG is triggered, it simply “GETs” a message from
* PROBLEM IS AND TAKE SOME ACTION BECAUSE THE GET FAILED!
* NASPA.MQSERIES.QUEUE. What action is taken when this message
END-IF. is received is left up to your imagination. At some point, if additional
P260-MQCLOSE.
MOVE MQCO-NONE TO WS01-OPTIONS.
messages are “PUT” to NASPA.MQSERIES.QUEUE by other
* executions of PUTPROG, GETPROG is again triggered and the
CALL ‘MQCLOSE’ USING WS01-HCONN process repeats itself.
WS01-HOBJ
WS01-OPTIONS Part III will examine the concept of DQM for connecting MQSeries
WS01-COMP-CODE queue managers. ts
WS01-REASON-CODE.
*
IF (WS01-COMP-CODE NOT = MQCC-OK) THEN
* Tom Kruczek has worked for Connecticut Mutual for 18 years, two of those
* TAKE SOME ACTION BECAUSE THE CLOSE FAILED!
years in applications, and 16 years as a systems programmer. His respon -
*
END-IF. sibilities include MQSeries and CICS installation and support.

actual LOCAL queue call “NASPA.T.MQSERIES.QUEUE”. It’s also ©1996 Technical Enterprises, Inc. Reprinted with permission of
worth noting that MQSeries batch programs, such as PUTPROG, can Technical Support magazine. For subscription information, email
be linkedited to connect to the default queue manager on an MVS mbrship@naspa.net or call 414-768-8000, Ext. 116.

TECHNICAL SUPPORT FEBRUARY 1996