MQ SERIES

MQSeries is IBMs award winning middleware for commercial messaging and queuing.
It is used by thousands of customers in every major industry in many countries around
the world. MQSeries speeds implementation of distributed applications by simplifying
application development and test.
The MQSeries products enable programs to communicate with each other across a
network of unlike components, such as processors, subsystems, operating systems and
communication protocols. MQSeries programs use a consistent application program
interface (API) across all platforms.
Messaging means that programs communicate with each other by sending data in
messages and not by calling each other directly.
The control information is defined in a message descriptor structure (MQMD) and
contains such things as:
The type of the message
An identifier for the message
The priority for delivery of the message
The structure and content of the application data is determined by the participating
programs, not by MQSeries.
Application data
The application data in a message is defined and supplied by the
application which sends the message. There are no constraints on the
nature of the data in the message; for example, it could consist of one or
more of the following types:
Character strings
Bit strings
Binary integers
Packed-decimal integers
Floating-point numbers.
It is possible for a message to contain no application data. A message
with no data might not seem very useful, but sometimes that is all that is
needed to signal to the receiver that some particular event has occurred.

Control information
The control information in a message is data whose meaning is defined by
the message-queuing service, but whose value is specified by the sending
application. The data defines various properties of the message, and is
used by the message-queuing service to decide how the message should be
processed.
The control information is contained in a data structure called the
message descriptor, which the sending application passes to the queue
manager on the MQPUT or MQPUT1 call. The queue manager returns this
information to the receiving application on the MQGET call. The message
descriptor (MQMD) is defined in detail in topic 7.2.3; the following
sections introduce the more important properties of the message.

Queuing means that programs communicate through queues. Programs communicating

through queues need not be executed concurrently.
Queue Manager
Heart of MQ Series is the message queue manager(MQM), MQ Series run time
program.Its job is to manage queues and messages for applications. It provides an API so
that programs can put messages on and get messages from queues.
Functions of a Queue Manager.

It manages queues of messages for application programs

It provides an application programming interface , the MQI
It uses existing network facilities to transfer messages to other queue managers
when necessary
It coordinates updates to databases and queues using a two-phase commit.
Gets/Puts from/To queues are committed together with SQl updates or backed out
if necessary
It provides additional functions that allow administrators to create/delete queues,
alter the properties of existing queues. MQ series for WINDOWS NT provides
GUI , other platforms use command line interface or panels

For applications to be able to send messages to applications that are connected to

other queue managers, the queue managers must be able to communicate among
themselves.
Process Definition
A Process Definition object defines an application to a queue manager. For e.g it
contains the name of the program (and its path) to be triggered when a message
arrives for it.

Since MQSeries communicates via queues it can be referred to as using indirect programtoprogram communication. The programmer cannot specify the name of the target
application to which a message is sent. However, he or she can specify a target queue
name; and each queue is associated with a program. An application can have one or more
input queues and may have several output queues containing information for other
servers to be processed, or for responses for the client that initiated the transaction.
Message queues are used to store messages sent by programs. There are local queues that
are owned by the local queue manager, and remote queues that belong to a different
queue manager.
o transmit non-persistent messages, a message channel can run at two speeds: fast and
normal. Fast channels improve performance, but (non-persistent) messages can be lost in
case of a channel failure.
A channel can use the following transport types: SNA LU 6.2, TCP/IP, NetBIOS, SPX
and DEC Net. Not all are supported on all platforms.
Queues are defined as objects belonging to a queue manager. MQSeries knows a number
of different queue types, each with a specific purpose. The queues you use are located
either in your machine and belong to the queue manager to which you are connected, or
in your server (if you are a client)
application can use
two modes of communication:

Conversational
If the application uses this mode of communication with the server program, it waits for
the
message to arrive before it continues processing. This means, the reply queue is open and
an

MQGET with wait option has been issued.

The client application must be able to deal with two possibilities:
The message arrives in time.
The timer expires and no message is there.

True asynchronous
When using this mode, the client does not care when the request message arrives.
Usually, the user clicks a push button in a menu window to activate a program that
checks the reply queue for messages. If a message is present, this or another program can
process the reply.
The Message Queuing Interface (MQI)
A program talks directly to its local queue manager. It resides in the same processor or
domain (for clients) as the program itself. The program uses the Message Queuing
Interface (MQI). The MQI is a set of API calls that request services from the queue
manager.
Note: When the connection between a client and its server is broken, no API calls can be
executed, since all objects reside in the server.
An initiation queue into which the queue manager puts a trigger message when a request
for queue QS1 arrives. You can use the default initiation queue.
A process definition that contains the name of the program to be started when the trigger
event occurs (S1).
Persistence
Sometimes the sender of a message wants to be assured that a message will
not be lost if there is a system or network failure; this property of a
message is called persistence.
A persistent message is protected against system failures, and survives
| either until it is retrieved by the receiving application, or until its
| expiry time is exceeded (at which point the queue manager will discard
| it).
The message persistence is defined by the Persistence field in the message
descriptor;
Local Queue
A local queue is a queue that belongs to the queue manager to which the
application has connected using the MQCONN call. A queue of this type can
be opened for input (for use with the MQGET call), or for output (for use

with the MQPUT or MQPUT1 calls).

A local queue is one that can hold messages; it may be implemented as a
buffer or buffers in main storage, or as a file or files on disk or other
permanent storage device. If the queue contains no persistent messages,
it may exist only in main storage.
Remote Queue
A remote queue is a queue that belongs to a queue manager other than the
one to which the application is connected. A queue of this type can be
opened only for output (for use with the MQPUT or MQPUT1 calls); it cannot
be opened for input. (To applications that are connected to that queue
manager, the queue would appear to be a local queue, and so could of
course be opened by those applications for output or input.)
Notes: - A program cannot read messages from a remote queue.
Dynamic Queue
A model queue is used with the MQOPEN call to generate a new queue, called
a dynamic queue; the name of this new queue can be specified by the
application, or assigned by the queue manager. To create a queue, the
application issues the MQOPEN call naming a model queue in the object
descriptor structure MQOD; in response the queue manager creates a local
queue that has the same attributes as the model queue.
Dynamic queues are of two kinds:
Temporary
Permanent.
When a temporary dynamic queue is closed by the application that created
it (using the Hobj handle returned by the MQOPEN call that created the
queue), the queue is deleted, along with any messages that may still be on
it. Temporary dynamic queues are not recovered if the message queuing
queue manager fails, nor can MQPER_PERSISTENT messages be put on them.
Transmission Queues
When an application sends a message to a remote queue, the message queuing
queue manager places the message on a special kind of local queue called a
transmission queue. This type of queue is distinguished by its Usage
local-queue attribute having a value of MQUS_TRANSMISSION (see topic 8.2).

The message waits on the transmission queue until a message channel agent
transmits it successfully to the next queue manager in the network. The
message is then deleted from the transmission queue.

Initiation Queue
An initiation queue is a local queue to which the queue manager writes a trigger message
when certain conditions are met on another local queue, for example, when a message is
put into an empty message queue or in a transmission queue. Such a trigger message is
transparent to the programmer. Two MQSeries applications monitor initiation queues and
read trigger messages, the trigger monitor which starts applications and the channel
initiator which starts the transmission between queue managers.
Note: Applications do not need to be aware of initiation queues, but the triggering
mechanism
implemented through them is a powerfultool to design and write asynchronous
applications.

Syntax for connecting to Queue Manager.

TRANSFER 'OCAMQS03' LINK USING MQTM.
CALL 'MQCONN' USING MQM-QUEUE-MANAGER
MQM-HCONN
MQM-COMPCODE
MQM-REASON.
The application specifies the name of the queue manager required (Name),
and receives in return a handle that represents the connection to that
queue manager (Hconn); this handle is used on all subsequent calls.
CompCode and Reason are returned parameters that indicate the success or
failure of the call.
When a connection to the queue manager has been established, the
application can open one or more queues for activity, usually for putting
or getting messages. A queue is opened by means of the MQOPEN call:
All MQ series related calls are stored in copybook MQFLDSWS
Syntax for Opening the Input Queue.
CALL 'MQOPEN' USING MQM-HCONN
MQOD
MQM-OPTIONS
MQ-SOURCE-HOBJ
MQM-COMPCODE
MQM-REASON.
The application specifies the queue to be opened (ObjDesc), and some open
options that indicate whether the queue is opened for putting or getting
messages (Options), and receives in return a handle to the opened queue
(Hobj); this handle is used on subsequent calls that access that queue.
An application cannot access a queue unless the user of the application is
appropriately authorized for the queue; this check is performed when the
queue is opened. The different ways in which the queue can be opened
require different levels of authorization.

Syntax for Getting data from Queue

CALL MQGET (Hconn, Hobj, MsgDesc, GetMsgOpts, BufferLength, Buffer,
DataLength, CompCode, Reason)
CALL 'MQGET' USING W03-HCONN
W03-SOURCE-HOBJ
MQMD
MQGMO
W03-BUFFER-LENGTH
DTRP015-INPUT-MSG-BUF
W03-DATA-LENGTH
W03-COMPCODE
W03-REASON.
The application specifies a partially filled-in message descriptor
(MsgDesc), some options that control the action of the call (GetMsgOpts),
an empty buffer (Buffer), and the length of that buffer (BufferLength),
and receives in return the message data in the buffer (Buffer), and the
total length of the message data (DataLength). The message descriptor
(MsgDesc) is completed with information about the message just retrieved.
The MQGET call can be used repeatedly to get many messages from the same
queue, without intervening use of the MQOPEN and MQCLOSE calls.
For the get, the nowait option is used. The MQGET needs the length of the buffer as an
input parameter. Since there is no message ID or correlation ID specified, the first
message from the queue is read. You may specify a wait interval (in milliseconds) here.
You can check the return code to find out if the time has expired and no message arrived.
Syntax for Putting data in Queue
CALL MQPUT (Hconn, Hobj, MsgDesc, PutMsgOpts, BufferLength, Buffer,
CompCode, Reason)
CALL 'MQPUT1' USING MQM-HCONN
MQOD
-- Object Description
MQMD
-- Message Description (Strucid, version, report
identifier, message type, priority, correlation-id, backout-count, user identifier, date, time)
MQPMO
-- Put Message Options( Options that control the
action of the call, strucid, version, options, timeout)
MQM-BUFFER-LENGTH
DTRP015-INPUT-MSG-BUF

MQM-COMPCODE
MQM-REASON.
The application specifies information about the message to be put
(MsgDesc), options that control the action of the call (PutMsgOpts), the
length of the message data (BufferLength), and the message data itself
(Buffer).
The MQPUT call can be used repeatedly to put many messages on the same
queue, without intervening use of the MQOPEN and MQCLOSE calls.
The handle of the queue manager (from MQCONN)
The handle of the queue (from MQOPEN)
The message descriptor
A structure containing options for the put (refer to the Application Programming
Reference)
The message length
The buffer containing the data
Syntax for Closing a Message Queue
When the application has finished putting messages on a queue, or getting
messages from a queue, it must close the queue by means of the MQCLOSE
call:
CALL MQCLOSE (Hconn, Hobj, Options, CompCode, Reason)

The application specifies the handle of the queue to be closed (Hobj), and
some options that control the action of the call (Options). After the
call, the queue handle (Hobj) is no longer valid, and messages cannot be
put on the queue or removed from the queue by the application unless it
performs another MQOPEN call.
An application that is reading from a queue does not have to empty the
queue before closing it. Messages left on a permanent queue are retained
by the queue manager, and may be accessed later by the same or another
application. Messages left on a temporary queue are discarded by the
queue manager when the queue is closed by the application which created
it.
When the application has finished all interaction with the queue manager,

the application must sever the connection by means of the MQDISC call:
CALL MQDISC (Hconn, CompCode, Reason)

After the call, the connection handle (Hconn) is no longer valid, and
message-queuing calls cannot be issued by the application unless it
performs another MQCONN call.
Minor calls
CALL MQCMIT (Hconn, CompCode, Reason)

Note: This call commits only MQ resources; it does not affect resources
belonging to other resource managers (such as a database manager).
If the application encounters an error during a series of puts and/or gets
that are part of a unit of work, the application can backout the
operations performed on the queue(s) as part of that unit of work by using
the appropriate environment-specific call. In those environments where
there is no suitable unit-of-work manager, the application can use the
MQBACK call to backout the unit of work:
CALL MQBACK (Hconn, CompCode, Reason)

Note: This call backs out only MQ resources; it does not affect resources
belonging to other resource managers (such as a database manager).
Sometimes an application needs to determine one or more of the properties
of a queue, in order to take appropriate action. For example, a
load-balancing application might want to determine the current depth of
the queue (that is, the number of messages on the queue), so that it could
start another server if messages were arriving more quickly than the
current number of servers could handle.
The attributes of a queue can be determined by means of the MQINQ call:

CALL MQINQ (Hconn, Hobj, SelectorCount, Selectors, IntAttrCount,

IntAttrs, CharAttrLength, CharAttrs, CompCode, Reason)
The application specifies the queue whose attributes are to be determined
(Hobj), the number of attributes required (SelectorCount), and the
selector codes for those attributes (Selectors), and receives in return
the values of those attributes (IntAttrs and CharAttrs).
In order to use the MQINQ call, the queue must be opened using the MQOPEN
call prior to inquiring the attributes, and closed using the MQCLOSE call
when operations on the queue are finished.
The MQINQ call can also be used to inquire about other types of object,
for example, process definitions or the queue manager.
DISABLE TRIGGERING ON THE SOURCE QUEUE
MOVE MQIA-TRIGGER-CONTROL TO W03-SELECTORS(1)
MOVE MQTC-OFF
TO W03-INATTRS (1)
CALL 'MQSET' USING W03-HCONN
W03-SOURCE-HOBJ
W03-SELECTORCOUNT
W03-SELECTORS-TABLE
W03-INATTRCOUNT
W03-INATTRS-TABLE
W03-CHARATTRLENGTH
W03-CHARATTRS-TABLE
W03-COMPCODE
W03-REASON.

Common Programming Errors

SOC4
Passing incorrect parameters in an MQI call; if the wrong number of
parameters are passed, no attempt can be made to complete the
completion code and reason code fields, and the task is abended.
(This will be a X'0C4' abend.)
Failing to define the MQSeries modules to MVS correctly (this will
cause a X'0C4' abend in CSQYASCP).
Passing variables with incorrect lengths specified.
Failing to initialize MsgId and CorrelId correctly
2033
If your MQGET call has timed out, you will see a completion code of 2
and a reason code of 2033 (MQRC_NO_MSG_AVAILABLE).
Queue Error
If you suspect that the problem occurs with only a subset of queues,
select the name of a local queue that you think is having problems.
Use the data displayed to do the following checks:
If triggering is being used:
- Is the trigger monitor running?
- Is the trigger depth too big?
- Is the process name correct?
- Is the queue enabled appropriately for GET and PUT?

Possible causes for looping

The MQGET call usually retrieves the first message from a queue. If you
use the message and correlation identifiers (MsgId and CorrelId) in the
message descriptor to specify a particular message, the queue manager has
to search the queue until it finds that message. The use of the MQGET

call in this way affects the performance of your application.

If your application cannot use messages of a fixed length, another
solution to this problem is to use the MQINQ call to find the maximum size
of messages that the queue can accept, then use this value in your MQGET
call. The maximum size of messages for a queue is stored in the MaxMsgL
attribute of the queue. This method could use large amounts of storage,
however, because the value of this queue attribute could be as high as
4MB, the maximum allowed by MQSeries for MVS/ESA.
If your application uses distributed queuing, you should also consider the
following points:
Are the links available between the two systems?
Check that both systems are available, and connected to MQSeries for
MVS/ESA. Check that the LU6.2 or TCP/IP connection between the two
systems is active or check the connection definitions on any other
systems that you are communicating with.
Is triggering on in the sending system?

Triggering

Prerequisites for triggering

Conditions for a trigger event
Controlling trigger events
Designing an application that uses triggered queues
Trigger monitors
Properties of trigger messages
When triggering does not work

The queue manager defines certain conditions as constituting "trigger

events". If triggering is enabled for a queue and a trigger event occurs,
the queue manager sends a trigger message to a queue called an initiation
queue. The presence of the trigger message on the initiation queue
indicates that a trigger event has occurred.
The program which processes the initiation queue is called a
trigger-monitor application, and its function is to read the trigger
message and take appropriate action, based on the information contained in
the trigger message. Normally this action would be to start some other
application to process the queue which caused the trigger message to be

generated. From the point of view of the queue manager, there is nothing
special about the trigger-monitor application--it is simply another
application that reads messages from a queue (the initiation queue).
If triggering is enabled for a queue, that queue must have associated with
it a process-definition object. This object contains information about
the application that is to be started to process the message which caused
the trigger event. When the queue manager generates the trigger message,
it extracts this information from the relevant process definition and
places it in the trigger message, for use by the trigger-monitor
application. The name of the process definition associated with a queue
is given by the ProcessName local-queue attribute. Each queue can specify
a different process definition, or several queues can share the same
process definition.
Triggering involves:
Application queue
An application queue is a local queue, which, when it has triggering
set on and when the conditions are met, requires that trigger messages
are written.
Process Definition
Each application queue has a process definition object associated with
it that holds details of the application that will get messages from
the application queue. (For more information see "Process definition
objects" in topic 1.4.4.)
Trigger event
A trigger event is an event that causes a trigger message to be
generated by the queue manager. This is usually a message arriving on
an application queue, but it can also occur at other times (see
"Conditions for a trigger event" in topic 2.8.3). MQSeries has a range
of options to allow you to control the conditions that cause a trigger
event (see "Controlling trigger events" in topic 2.8.4).
Trigger message
The queue manager creates a trigger message when it recognizes a
trigger event (see "Conditions for a trigger event" in topic 2.8.3).
It copies into the trigger message information about the application to
be started. This information comes from the application queue and the
process definition object associated with the application queue.
Trigger messages have a fixed format (see "Format of trigger messages"
in topic 2.8.7.4).

Initiation queue
An initiation queue is a local queue on which the queue manager puts
trigger messages. A queue manager can own more than one initiation
queue, and each one is associated with one or more application queues.
Trigger monitor
A trigger monitor is a continuously-running program that serves one or
more initiation queues. When a trigger message arrives on an
initiation queue, the trigger monitor retrieves the message. The
trigger monitor uses the information in the trigger message. It issues
a command to start the application that is to retrieve the messages
arriving on the application queue, passing it information contained in
the trigger message header, which includes the name of the application
queue. (For more information, see "Trigger monitors" in topic 2.8.6.)

Two-phase commit: If two or more data store managers are involved in a

single transaction, the transaction processing system must coordinate the
commitment control process.
In a two-phase commit procedure, the transaction processing system:
1. Asks each resource manager (RM) to prepare to commit
2. When each RM has signalled readiness, asks each to commit, or, if any
RM signals that it cannot commit, asks each to backout.
When transactions in different systems communicate with each other and
perform logically related updates on their respective data stores, at
least two data store managers are involved, and a two-phase commit protocol is required.
The Systems Network Architecture (SNA) Advanced
Program to Program Communication (APPC) and Open Systems Interconnection
Transaction Processing (OSI/TP) protocols include two-phase commit.
Sync points: In the simplest case, assumed above, the decision to commit
or backout changes is taken when a transaction completes successfully or
fails. If the transaction processing system makes it possible, it can be
helpful in application design to synchronize data changes at other logical
points of consistency within transaction execution. All such points of
consistency (including transaction termination) are called commit points
or sync points. In this book, we use the term sync point.

Logical units of work (LUWs): The processing between sync points can be
called a recoverable unit of work, a unit of recovery, or a logical unit
of work (LUW). In this book, we use the term LUW. If any of the data
changes in an LUW has not been successful, then all are reversed (backed
out). Locks are released at the end of an LUW.
Many transaction processing systems automatically take sync points at the
start and end of a transaction. If the system provides the facility for
application programs to explicitly request sync points, programs can be
designed into several LUWs. Figure 1 shows how LUWs end at sync points.
Transaction A has one LUW, and transaction B is a multiple-LUW transaction.