MQ Series for OS/390

INTRODUCTION TO MQ SERIES FOR OS/390

MQ stands for Messaging and Queuing
It is a middleware that enables applications to communicate with
one another irrespective of their operating system, processors,
communication protocol.
It allows applications to run independently of each other, at
different speeds, different times, different locations, without
having a logical connection between them.

Messaging & Queuing

To pass data to another application, it can send a message
rather than call the other application directly
Messages are placed on queues in storage and forwarded to the
receiving application. The messages remain in the queue until
the application is ready to process them.
Messaging can be one-way or two-way (Request and Reply).
When applications communicate across different platforms, the
application programs are shielded from the networking
complexities.

INTRODUCTION TO MQ SERIES FOR OS/390

Message :
A message is mainly a string of bytes to be sent from one
program/application to another
A message can take any one of the following types :
Datagram A simple message
Request A message for which a Reply is expected
Reply A reply to a Request message
Report An event descriptor (For eg., delivery
confirmation, error occurances)
A message consists of:
Message Descriptor: Contains the control information such
as message type, unique identifier (24 byte string),
priority. This is a fixed structure of 256 bytes
Message Application Data: Contains the actual data to be
passed on to other applications.

INTRODUCTION TO MQ SERIES FOR OS/390

Message :
FIFO
The first message that is read out of a queue is normally
the first message that was put into the queue.
However, if the application program is looking for a
particular message in the queue, an identifier can be
passed while reading the queue.
Persistence
Persistent messages are logged or backed up so that they
can be restored during system-restart
Non-persistent messages are lost when the system goes
down

INTRODUCTION TO MQ SERIES FOR OS/390

INTRODUCTION TO MQ SERIES FOR OS/390

MQ Series Objects
Queue Manager
Is a system program that provides queuing services to
application programs
Message queues reside in and are managed by the
Queue Manager.
The queue manager provides an Application Program
Interface for the programs to acess the queues.
The queue manager also provides administrative
functions such as :
Creating new queues
Altering properties of a queue
Control operations of a queue

INTRODUCTION TO MQ SERIES FOR OS/390

MQ Series Objects
Queue Manager
A program must be connected to a queue manager
before it can start accessing the queues.
If there are multiple queue managers connected to a
system, the queue manager name must be provided
during the connect MQ API call.
If there is a single queue manager connected to a
system, then the program automatically connects to it
during the connect MQ API call.
Batch environment can have multiple queue managers,
while CICS applications can be connected only to a
single queue manager.

INTRODUCTION TO MQ SERIES FOR OS/390

MQ Series Objects
Message Queue
A queue is the named storage destination to which a
message can be sent to or received from
A queue is a container for the messages
Messages remain in these queues until they are
retrieved by programs that process these queues
Message queues physically reside on data sets
A queue must have a unique name within a queue
manager.
Temporary or Permanent queues can be created
dynamically through the application.
Attributes of queues:
Queue name, Queue type, description, Priority,
Persistence, InhibitGet and InhibitPut

INTRODUCTION TO MQ SERIES FOR OS/390

MQ Series Objects
Message Queue - Types of queues
- Local and Remote Queues
Local queues are message queues that reside in the local queue
manager where the application resides.
Remote queues are message queues that reside in queue
managers other than the local queue manager.
- Shared Queues
Is a local queue that can be accessed by other queue managers
in a queue sharing group
- Model Queues
A template queue based on which you can create queues for
your application, either dynamically or through the MQ Series
control panel
- Cluster Queues
A Cluster is a network of logically associated queue managers. A
cluster queue is managed by a cluster queue manager and is
available to all queue managers within that cluster

INTRODUCTION TO MQ SERIES FOR OS/390

MQ Series Objects
Processes
- Event-driven processing can be achieved by defining a
Process on a message queue. An application can be
started based on an event, like a message arriving in a
queue. For this purpose, the queue manager should be
aware of the attributes of the application to be started
Channels
- Is a communication link between queue managers
- A message channel is unidirectional and are used to
transfer data from one queue manager to another.
There should exist one Send Channel and one Receive
Channel between two queue managers.
- An MQI channel is a bidirectional link to tranfer MQI
calls between MQ Client and Server

INTRODUCTION TO MQ SERIES FOR OS/390

MQ Series Objects
Rules for defining MQ Series Objects
- Upper case and Lower case are different
- Numbers can be used
- Other characters such as . _ / % can be used
- Blanks are not allowed
- Queue names can be upto 48 characters long
- Channels can be upto 20 characters long

Application Programming using MQ Series

MQ API
MQ Series provides a set of API calls with which the
programmer can access the message queues.
The available APIs are :
- Connect / Disconnect from a queue manager
- Open Or Close a Queue
- Put message into a Queue
- Read or Browse messages from a Queue
- Inquire and Set attributes of a Queue
- Perform Queue Commit and Rollback operations
All APIs have the following returncodes
- Compcode :- Completion Code
- MQCC_OK Successful Completion
- MQCC_WARNING Partial Completion
- MQCC_FAILED Error occurred

- Reason : Reason for warning or Failure

- For Eg., MQRC_HCONN_ERROR, MQRC_STORAGE_NOT_AVAILABLE

Application Programming using MQ Series

MQ API
A typical program will have the structure as shown below in the
procedure division
Putting messages into a Queue

[ Connect Queue Manager ]

Open Queue Name
Put Queue Data into Queue Name
Close Queue Name
[ Disconnect Queue Manager ]

Getting messages from a Queue

[ Connect Queue Manager ]

Open Queue Name
Get Queue Data from Queue Name
Close Queue Name
[ Disconnect Queue Manager ]

Application Programming using MQ Series

MQ API
Putting a single message into a Queue
[ Connect Queue Manager ]
Put1 Queue Data into Queue Name
[ Disconnect Queue Manager ]

Putting a request message and Getting a reply message

[ Connect Queue Manager ]

Open Queue Name
Put Queue Data into Request Queue Name
Get Queue Data from Reply Queue Name
Close Queue Name
[ Disconnect Queue Manager ]

Application Programming using MQ Series

MQ API
MQ Connect
The program can connect either to a specific queue
manager or to the default queue manager. The queue
manager should be local to the application.
To connect to a specific queue manager, the name of the
queue manager should be supplied. Whereas, for the
default queue manager, the name of the queue manager
should be blanks or nulls.
For MVS Batch region, MQCONN call must be made to
connect to the queue manager.
For CICS region, it is not necessary to issue this call
because the CICS system itself is connected to the default
queue manager.
Syntax
Call MQCONN Using
Qmanager
HConn
Compcode
Reason

(I)
(O)
(O)
(O)

Q Manager name 48 bytes

Connection Handle
Completion Code
Reason Code

Application Programming using MQ Series

MQ API
MQ Disconnect
The MQDISC call must be issued to disconnect from the
queue manager
Applications running in CICS region need not issue this call.
The field HConn represents the connection to the queue
manager. The value in this field is returned to the
application during the MQCONN call. This value must be
used by the application in all the subsequent calls to MQ
until the MQDISC call is issued.
Syntax
Call MQDISC Using
HConn
Compcode
Reason

(I) Connection Handle

(O) Completion Code
(O) Reason Code

Application Programming using MQ Series

MQ API
MQ Open
The MQ Open command establishes access to a Message
Queue for Put message, Get message, Inquiry, Set attributes.
During the MQOpen call, the options for the action to be done
with the message queue should be set.
The MQOpen statement returns an Object Handle.
Syntax
For Put Action:
Move MQOO-OUTPUT to MQOptions
Move MQNAME to MQOD-OBJECTNAME
Call MQOPEN Using
HConn (I) Connection Handle
ObjDesc (O) Object Descriptor
MQOptions
(I) Options for opening queue
HObj
(O) Object Handle
Compcode
(O) Completion Code
Reason (O) Reason Code

Application Programming using MQ Series

MQ API
MQ Close
The MQ Open call returns the Object Handle which must be
used in all the subsequent calls to MQ for the Opened
Queue, until the MQ Close call is issue.
The MQ Close call releases the Object Handle so that the
queue can no more be accessed.
Syntax
Call MQCLOSE Using
HConn
MQOptions
HObj
Compcode
Reason

(I) Connection Handle

(I) Close options (Dynamic)
(I) Object Handle
(O) Completion Code
(O) Reason Code

Application Programming using MQ Series

MQ API
MQ Put
The MQ Put call puts a message into the queue.
The Queue should already be open in Output mode to put
the message.
This call can be issued repeatedly between the MQOPEN and
MQCLOSE call.
Syntax
Call MQPUT Using
HConn
HObj
MsgDesc
PMOptions
LenPutData
PutData
Compcode
Reason

(I) Connection Handle

(I) Object Handle
(I) Message Descriptor
(I) Put Message Options
(I) Length of data to be Put
(I) Data to be Put
(O) Completion Code
(O) Reason Code

Application Programming using MQ Series

MQ API
MQ Put1
The MQ Put1 call puts ONE message into the queue. The
queue need not be opened or closed for this purpose.
Syntax
Call MQPUT1 Using
HConn
HObj
MsgDesc
PMOptions
LenPutData
PutData
Compcode
Reason

(I) Connection Handle

(I) Object Handle
(I) Message Descriptor
(I) Put Message Options
(I) Length of data to be Put
(I) Data to be Put
(O) Completion Code
(O) Reason Code

Application Programming using MQ Series

MQ API
MQ Get
The MQ Get call retrieves a message from the queue
The Queue should already be open in Input mode to Get the
message.
This call can be issued repeatedly between the MQOPEN and
MQCLOSE call to retrieve all messages from the queue
MQ Get with Read option will delete the message from the
queue and with Browse option will retain the message in
the queue
Syntax
Call MQGET Using
HConn
HObj
MsgDesc
GMOptions
LenGetData
GetData
LenGetData
Compcode
Reason

(I) Connection Handle

(I) Object Handle
(I) Message Descriptor
(I) Get Message Options
(I) Length of data expected
(O) Data Structure to be read
(O) Length of data read
(O) Completion Code
(O) Reason Code

Application Programming using MQ Series

MQ API
MQ Inq
The MQ Inq call returns the attributes of an MQ Object in
the form of integers / characters
Inquiry can be made on Queues, Processes, Queue
managers
The Queue should already be open in Inquiry mode to get
the attributes of a queue.
Syntax
Call MQINQ Using
HConn
(I) Connection Handle
HObj
(I) Object Handle
SelCount
(I) No. of Attr to be inquired
Selectors
(I) Array of Attr to be inquired
IntAttrCnt
(I) No.of Integer Attributes
IntAttr
(O) Array of Integer Attributes
CharAttrLen
(I) No. of Char Attributes
CharAttr
(O) Array of Char Attributes
Compcode
(O) Completion Code
Reason
(O) Reason Code

Application Programming using MQ Series

MQ API
MQ Set
The MQ Set call sets the attributes of an MQ Object
Attribute setting can be made only on Queues.
The Queue should already be open in Set mode to change
the attributes of a queue.
Syntax
Call MQSET Using
HConn
HObj
SelCount
Selectors
IntAttrCnt
IntAttr
CharAttrLen
CharAttr
Compcode
Reason

(I) Connection Handle

(I) Object Handle
(I) No. of Attr to be set
(I) Array of Attr to be set
(I) No.of Integer Attributes
(O) Array of Integer Attributes
(I) No. of Char Attributes
(O) Array of Char Attributes
(O) Completion Code
(O) Reason Code

Application Programming using MQ Series

MQ API
MQ Commit
The MQ Commit call commits the unit of work. All queue
operations done since the beginning of the UOW or since
the previous Commit, are committed.
In case of triggered-events, the message is available to
subsequent applications only when the Put operation has
been committed.
This call should be made only from batch programs. In CICS
region, commit is achieved using EXEC CICS SYNCPOINT
statement.
Syntax
Call MQCMIT Using
Hconn
Compcode
Reason

(I) Connection Handle

(O) Completion Code
(O) Reason Code

Application Programming using MQ Series

MQ API
MQ Rollback
The MQ Rollback calls rolls back the unit of work. All queue
operations done since the beginning of the UOW or since
the previous UOW are rolled back.
All Put messages are deleted and all Get messages go
back into the queue.
This call should be made only from batch programs. In CICS
region, rollback is achieved using EXEC CICS SYNCPOINT
ROLLBACK statement.
Syntax
Call MQBACK Using
Hconn
Compcode
Reason

(I) Connection Handle

(O) Completion Code
(O) Reason Code

Application Programming using MQ Series

MQ API
MQ Begin
The MQ Begin call is used to start a Unit-Of-Work.
This call is used in order to isolate MQ from other resources
such as DB2, CICS.
MQCMIT or MQBACK call can follow the MQBEGIN call to
commit or rollback the MQ actions.
Syntax
Call MQBEGIN Using
HConn
BeginOption
Compcode
Reason

(I) Connection Handle

(I) Options
(O) Completion Code
(O) Reason Code

Application Programming using MQ Series

Triggers
Triggers are used for Event-driven processing
Certain events are recognized by the queue manager to
indicate the occurance of trigger-event.
A process definition is associated with every queue which
requires triggering. This process definition contains information
about the application to be started.
The trigger-monitor application is the program which processes
and monitors triggers.
When a trigger-event occurs, the queue manager moves the
message from the queue to another system queue called
Initiation Queue.
The trigger-monitor application reads the process-definition and
takes care of starting the application which will read the
message in the queue.

Application Programming using MQ Series

Triggers
Every application to be triggered must have one Initiation
queue.
In case of triggered-events, the put-message application and
get-message application are not part of the same unit-ofwork,even if it is a Request-Reply situation.
Triggering of application is possible only for CICS and IMS.
Batch programs cannot be triggered through MQ directly.
Trigger events can be enabled or disabled.
When enabled, trigger-events can be of three types:
First Every first message in the queue must trigger the application
Depth This option is followed by an integer value;
For eg., 10.
When the queue is filled with 10 messages, the application should
be triggerd.
Every Every message that is put into the queue must trigger the
application.

Application Programming using MQ Series

Triggers
The MQTM (MQ Trigger Message) data structure is passed on to the
started application. When a CICS Application is started, the EXEC
CICS RETRIEVE INTO command will transfer the trigger message
into the application.
Following are some of the main fields to be set while defining a
Process :
While defining the queue :
Set trigger-set as Y
Set trigger-type as F or E or D for First, Every or Depth
Mention depth count in case of D
Process name
Set initiation queue name and process definition (the initiation queue
is in-turn connected to a particular CICS region).
While defining the process :
Process name same as the one mentioned in the queue definition
Application type valid values are : CICS, MVS, IMS, DEF (MVS)
Application Id Transaction Id for CICS

Application Programming using MQ Series

Channel
A Channel is a communication link between distributed queue
managers.
Message channels are unidirectional and are used to transfer messages
from one queue manager to another. The two queue managers could be
in the same machine or different machine, same platform or different
platform.
Since the channels are unidirectional, there should be two channels
between two queue managers.
Failure in delivery of messages result in the message being put into a
dead-letter-queue
Message Channel Agent (MCA) is the program which controls the flow
of messages from one queue manager to another.
Inorder to use these Channels, they need to be in the Active or
Started state
Every channel is linked to a transmission queue and a connection
name. The connection is normally identified by an IP Address and a Port
The name of the channel should be the same at the sending and
receiving end.

Application Programming using MQ Series

Request & Reply Queues
When an application makes a request to another application &
expects a reply from that application, Request and Reply Queues are
used
The requesting and responding applications could be in completely
different platform
When the requesting and responding applications are in the same
platform and use the same queue manager, a pair of Request and
Reply queues along with Trigger definitions is sufficient
When the requesting and responding applications are in different
platform or they are using different queue managers, then apart
from the request and reply queues, remote queues and channels
are also required.
The requesting and responding applications are under different
UOW. If the responding application fails to provide a reply within a
specified amount of time, then the requesting application will
encounter a time-out error. In this case the requesting application
must issue a rollback.
Several copies of the requesting and responding applications can
run in parallel.

Application Programming using MQ Series

Request & Reply Queues
The fields MsgId and CorrelId are used by the queue manager and
the application programs to correlate the reply with the requests
It is the responsibility of the responding application to make sure
that the reply message has the same MsgId and CorrelId as the
request message.
Example of Putting a message into Request queue and getting a
reply.
The following logic will remain same irrespective of different
platforms and/or different queue managers
Open MQ Req.Queue in Output Mode
Open MQ Rep.Queue in Input Mode

Move Req.Queue To MQOD-OBJECTNAME

Move MQMT-REQUEST To MQMD-MSGTYPE
Move Rep.Queue To MQMD-REPLYTOQ
Call MQPUT Using..
Compute MQGMO-OPTIONS = MQGMO-WAIT
Move <value in milliseconds> To MQGMO-WAITINTERVAL
Call MQGET Using..

Application Programming using MQ Series

One Way Communucation in the same region / queue manager

MQ Series

CICST1

PROG-X
Initiation Queue

MQOPEN Q1
:
MQPUT Q1
:
MQCLOSE Q1
:

Q1
Trig : T1
InitQ : IQ1
Message Queue

IQ1
Appl :
CICST1
T1
Appl : CICS
ApplId : TR1
Trigger Definition

Trigger Monitor
Application

TR1 : PROG1
PROG1
MQOPEN Q1
:
MQGET Q1
:
MQCLOSE Q1
:

Application Programming using MQ Series

Two Way Communucation in the same region / queue manager

CICST1 Region
Transaction TRNA
starts PROG-A

MQ Series

PROG-A

PROG-B
Request Queue

MQOPEN Q1 OUTPUT
MQOPEN Q2 INPUT
:
MQPUT Q1
:
:
MQGET Q2
With WAIT Option
:
MQCLOSE Q1
MQCLOSE Q2
:

Transaction TRNB
starts PROG-B

Q1
Trig : T1
InitQ : IQ1

Q2
Reply Queue

Initiation Queue

IQ1
Appl :
CICST1
T1
Appl : CICS
ApplId : TRNB
Trigger Definition

Trigger Monitor
Application

MQOPEN Q1 INPUT
MQOPEN Q2 OUTPUT
:
MQGET Q1
:
: <process>
:
:
MQPUT Q2
:
MQCLOSE Q1
MQCLOSE Q2
:

Application Programming using MQ Series

Two Way Communucation in different region / queue manager

Region 1

PROG-A

Region 2

MQ Series
Region 1

MQ Series
Region 2

Request Queue
MQOPEN Q1 OUTPUT
MQOPEN Q2 INPUT
:
MQPUT Q1
:
MQGET Q2
:
MQCLOSE Q1
MQCLOSE Q2
:

Q1
Remote Q
Q2
Local Q
Remote Reply Queue

PROG-B

Remote Request Queue

Sender Channel

Receiver Channel

Q1
Local Q
Q2
Remote Q
Reply Queue

MQOPEN Q1 INPUT
MQOPEN Q2 OUTPUT
:
MQGET Q1
:
: <process>
:
MQPUT Q2
:
MQCLOSE Q1
MQCLOSE Q2
:

Application Programming using MQ Series

Two Way Communucation in different region / queue manager

Region 1
Remote
Request Q1

Region 2
Sender Channel R1R2
Connection : R2IP(Port)
Transmission Q : TXQ1

Receiver Channel R1R2

PRN2
Process
ApplType: MVS
ApplId : CSQX START

TXQ1
Local Q
Init Q : SYSTEM.CHANNEL.INITQ
Process Name : PRN1

TXQ2
Local Q
Init Q : SYSTEM.CHANNEL.INITQ
Process Name : PRN2

PRN1
Process
ApplType: MVS
ApplId : CSQX START

Local
Reply Q2

Local
Request Q1
Process : P1

Receiver Channel R2R1

Sender Channel R2R1

Connection : R1IP(Port)
Transmission Q : TXQ2

Remote
Reply Q2

Application Programming using MQ Series

Coding Considerations for Mainframe
Copybooks to be used :
Copybook ending with V contains the Value clause. Copybook ending
with L does not contain any initial values. (For eg., CMQGMOV or
CMQTML)
CMQGMOx Get message options
CMQPMOx Put message options
CMQMDx Message Descriptor
CMQODx Object Descriptor
CMQTMx Trigger message structure
All copybooks start with 10 level
01 MQ-GetMessageOptions.
Copy CMQGMOL.

Interface between application programs and MQ Series is provided by

adapters. These adapters enable the applications to perform the MQI
calls. For Batch applications must link-edit the adapter CSQBSTUB,
while CICS applications must link-edit the adapter CSQCSTUB.

Application Programming using MQ Series

Coding Considerations for Mainframe
For execution of jobs, use procedure MQDB2BAT / MQDB2BLE or
use the following load libraries in the Steplib:
MQM.SYS.QMXX.UCSQPARM
MQM.SYS.QMXX.SCSQAUTH
MQM.SYS.QMXX.SCSQLOAD

For CICS, no special steps are required because the system is

already connected to MQ.
Some programming tips for CICS :
A message queue triggers a CICS application with transaction id
TRN1
To differentiate between a triggered start of the application and
manual start of the application, the CICS Startcode command can
be used.
The EXEC CICS ASSIGN STARTCODE command returns a 2 byte
code which indicates how the application was started.
SD : With Start Data, S : Without Start Data, TD : Terminal Input

Application Programming using MQ Series

Limitations of MQ Series
Preferrably use MQ Series when the mode of communicating
with other applications is asynchronous
Preferrably use MQ Series when the communication is oneway.
Not a good idea to use MQ Series to communicate between a
Web-based front end and mainframe backend
Not possible to trigger batch jobs directly

MQ Series for OS/390

Authors Name : Jyoti Mani
Email
: jyoti.mani@gmail.com