You are on page 1of 16


MQSeries is IBM’s 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.

MQ Series’ run time program.Its job is to manage queues and messages for applications. which the sending application passes to the queue manager on the MQPUT or MQPUT1 call. Queuing means that programs communicate through queues. alter the properties of existing queues. The queue manager returns this information to the receiving application on the MQGET call. Queue Manager Heart of MQ Series is the message queue manager(MQM). The control information is contained in a data structure called the message descriptor.2. MQ series for WINDOWS NT provides GUI . other platforms use command line interface or panels . The message descriptor (MQMD) is defined in detail in topic 7. 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. Functions of a Queue Manager. Programs communicating through queues need not be executed concurrently. 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.      It manages queues of messages for application programs It provides an application programming interface .3.Control information The control information in a message is data whose meaning is defined by the message-queuing service. the following sections introduce the more important properties of the message. but whose value is specified by the sending application. and is used by the message-queuing service to decide how the message should be processed. It provides an API so that programs can put messages on and get messages from queues. The data defines various properties of the message.

There are local queues that are owned by the local queue manager. Process Definition A Process Definition object defines an application to a queue manager. he or she can specify a target queue name. Not all are supported on all platforms. but (non-persistent) messages can be lost in case of a channel failure. the queue managers must be able to communicate among themselves. the reply queue is open and an .g it contains the name of the program (and its path) to be triggered when a message arrives for it. o transmit non-persistent messages. TCP/IP. and each queue is associated with a program. This means. or for responses for the client that initiated the transaction. The programmer cannot specify the name of the target application to which a message is sent.For applications to be able to send messages to applications that are connected to other queue managers. A channel can use the following transport types: SNA LU 6. SPX and DEC Net. MQSeries knows a number of different queue types.2. The queues you use are located either in your machine and belong to the queue manager to which you are connected. it waits for the message to arrive before it continues processing. However. For e. Message queues are used to store messages sent by programs. each with a specific purpose. NetBIOS. 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. An application can have one or more “input” queues and may have several “output” queues containing information for other servers to be processed. a message channel can run at two speeds: fast and normal. Fast channels improve performance. Since MQSeries communicates via queues it can be referred to as using indirect programtoprogram communication. and remote queues that belong to a different queue manager. Queues are defined as objects belonging to a queue manager.

this property of a message is called persistence. Local Queue A local queue is a queue that belongs to the queue manager to which the application has connected using the MQCONN call. If a message is present.MQGET with wait option has been issued. Usually. no API calls can be executed. the user clicks a push button in a menu window to activate a program that checks the reply queue for messages. Note: When the connection between a client and its server is broken. and survives | either until it is retrieved by the receiving application. • A process definition that contains the name of the program to be started when the trigger event occurs (S1). The client application must be able to deal with two possibilities: • The message arrives in time. 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. A persistent message is protected against system failures. The message persistence is defined by the Persistence field in the message descriptor. A queue of this type can be opened for input (for use with the MQGET call). this or another program can process the reply. 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. You can use the default initiation queue. • True asynchronous When using this mode. The program uses the Message Queuing Interface (MQI). An initiation queue into which the queue manager puts a trigger message when a request for queue QS1 arrives. or until its | expiry time is exceeded (at which point the queue manager will discard | it). The MQI is a set of API calls that request services from the queue manager. or for output (for use . since all objects reside in the server. • The timer expires and no message is there. the client does not care when the request message arrives.

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

the trigger monitor which starts applications and the channel initiator which starts the transmission between queue managers. The message is then deleted from the transmission queue. . Two MQSeries applications monitor initiation queues and read trigger messages. Such a trigger message is transparent to the programmer. Note: Applications do not need to be aware of initiation queues.The message waits on the transmission queue until a message channel agent transmits it successfully to the next queue manager in the network. when a message is put into an empty message queue or in a 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. but the triggering mechanism implemented through them is a powerfultool to design and write asynchronous applications. for example.

usually for putting or getting messages. TRANSFER 'OCAMQS03' LINK USING MQTM. and receives in return a handle to the opened queue (Hobj). CompCode and Reason are returned parameters that indicate the success or failure of the call. The application specifies the name of the queue manager required (Name). this check is performed when the queue is opened. and receives in return a handle that represents the connection to that queue manager (Hconn). this handle is used on all subsequent calls. CALL 'MQCONN' USING MQM-QUEUE-MANAGER MQM-HCONN MQM-COMPCODE MQM-REASON. The application specifies the queue to be opened (ObjDesc).Syntax for connecting to Queue Manager. the application can open one or more queues for activity. and some open options that indicate whether the queue is opened for putting or getting messages (Options). this handle is used on subsequent calls that access that queue. The different ways in which the queue can be opened require different levels of authorization. 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. When a connection to the queue manager has been established. An application cannot access a queue unless the user of the application is appropriately authorized for the queue. .

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

The MQPUT call can be used repeatedly to put many messages on the same queue. Options. Messages left on a permanent queue are retained by the queue manager. Hobj. Messages left on a temporary queue are discarded by the queue manager when the queue is closed by the application which created it.MQM-COMPCODE MQM-REASON. and the message data itself (Buffer). or getting messages from a queue. When the application has finished all interaction with the queue manager. An application that is reading from a queue does not have to empty the queue before closing it. options that control the action of the call (PutMsgOpts). the queue handle (Hobj) is no longer valid. Reason) The application specifies the handle of the queue to be closed (Hobj). . and may be accessed later by the same or another application. the length of the message data (BufferLength). it must close the queue by means of the MQCLOSE call: CALL MQCLOSE (Hconn. The application specifies information about the message to be put (MsgDesc). without intervening use of the MQOPEN and MQCLOSE calls. and some options that control the action of the call (Options). and messages cannot be put on the queue or removed from the queue by the application unless it performs another MQOPEN call. After the call. CompCode. •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.

the number of messages on the queue). Reason) After the call. a load-balancing application might want to determine the current depth of the queue (that is. so that it could start another server if messages were arriving more quickly than the current number of servers could handle. it does not affect resources belonging to other resource managers (such as a database manager). Reason) Note: This call backs out only MQ resources. and message-queuing calls cannot be issued by the application unless it performs another MQCONN call. For example. CompCode. CompCode. Sometimes an application needs to determine one or more of the properties of a queue. In those environments where there is no suitable unit-of-work manager. in order to take appropriate action. Reason) Note: This call commits only MQ resources. Minor calls CALL MQCMIT (Hconn. the connection handle (Hconn) is no longer valid. 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 must sever the connection by means of the MQDISC call: CALL MQDISC (Hconn. the application can use the MQBACK call to backout the unit of work: CALL MQBACK (Hconn. 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. The attributes of a queue can be determined by means of the MQINQ call: . CompCode.

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. CharAttrLength. In order to use the MQINQ call.CALL MQINQ (Hconn. for example. process definitions or the queue manager. and closed using the MQCLOSE call when operations on the queue are finished. IntAttrCount. the number of attributes required (SelectorCount). CompCode. Reason) The application specifies the queue whose attributes are to be determined (Hobj). and the selector codes for those attributes (Selectors). . Selectors. The MQINQ call can also be used to inquire about other types of object. and receives in return the values of those attributes (IntAttrs and CharAttrs). IntAttrs. SelectorCount. the queue must be opened using the MQOPEN call prior to inquiring the attributes. CharAttrs. Hobj.

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

This method could use large amounts of storage. in this way affects the performance of your application. Check that the LU6. If your application uses distributed queuing. If your application cannot use messages of a fixed length. The maximum size of messages for a queue is stored in the MaxMsgL attribute of the queue. then use this value in your MQGET call. the maximum allowed by MQSeries for MVS/ESA. The program which processes the initiation queue is called a trigger-monitor application. another solution to this problem is to use the MQINQ call to find the maximum size of messages that the queue can accept. and its function is to read the trigger message and take appropriate action. 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. Normally this action would be to start some other application to process the queue which caused the trigger message to be .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. and connected to MQSeries for MVS/ESA. you should also consider the following points: Are the links available between the two systems? Check that both systems are available. because the value of this queue attribute could be as high as 4MB. based on the information contained in the trigger message.

4. Trigger messages have a fixed format (see "Format of trigger messages" in topic 2. there is nothing special about the trigger-monitor application--it is simply another application that reads messages from a queue (the initiation queue).4). This object contains information about the application that is to be started to process the message which caused the trigger event. Trigger message The queue manager creates a trigger message when it recognizes a trigger event (see "Conditions for a trigger event" in topic 2. (For more information see "Process definition objects" in topic 1. requires that trigger messages are written. When the queue manager generates the trigger message. Each queue can specify a different process definition. The name of the process definition associated with a queue is given by the ProcessName local-queue attribute. for use by the trigger-monitor application.8.3). It copies into the trigger message information about the application to be started.8. . 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. Triggering involves: Application queue An application queue is a local queue.7. which.) Trigger event A trigger event is an event that causes a trigger message to be generated by the queue manager.generated. it extracts this information from the relevant process definition and places it in the trigger message.8. but it can also occur at other times (see "Conditions for a trigger event" in topic 2. From the point of view of the queue manager. This is usually a message arriving on an application queue.3). 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.4).4. when it has triggering set on and when the conditions are met.8. or several queues can share the same process definition. This information comes from the application queue and the process definition object associated with the application queue. If triggering is enabled for a queue. that queue must have associated with it a process-definition object.

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. When a trigger message arrives on an initiation queue. The Systems Network Architecture (SNA) Advanced Program to Program Communication (APPC) and Open Systems Interconnection Transaction Processing (OSI/TP) protocols include two-phase commit. if any RM signals that it cannot commit. 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. it can be helpful in application design to synchronize data changes at other logical points of consistency within transaction execution. . If the transaction processing system makes it possible. Sync points: In the simplest case. assumed above. which includes the name of the application queue. Asks each resource manager (RM) to prepare to commit 2. the transaction processing system must coordinate the commitment control process. When transactions in different systems communicate with each other and perform logically related updates on their respective data stores.6. asks each to commit. In a two-phase commit procedure. the transaction processing system: 1. Trigger monitor A trigger monitor is a continuously-running program that serves one or more initiation queues. passing it information contained in the trigger message header. and each one is associated with one or more application queues. or. at least two data store managers are involved. (For more information. In this book. and a two-phase commit protocol is required.) Two-phase commit: If two or more data store managers are involved in a single transaction. we use the term sync point.8. the trigger monitor retrieves the message. When each RM has signalled readiness. All such points of consistency (including transaction termination) are called commit points or sync points. see "Trigger monitors" in topic 2. the decision to commit or backout changes is taken when a transaction completes successfully or fails. asks each to backout.

Figure 1 shows how LUWs end at sync points. In this book. we use the term LUW. If the system provides the facility for application programs to explicitly request sync points. and transaction B is a multiple-LUW transaction. programs can be designed into several LUWs.Logical units of work (LUWs): The processing between sync points can be called a recoverable unit of work. 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. a unit of recovery. Many transaction processing systems automatically take sync points at the start and end of a transaction. or a logical unit of work (LUW). . Transaction A has one LUW.