Table of Contents
The API supported by MQSeries is known as the Message Queue Interface (MQI). There are only 11MQI function calls in total, these allow programs to:
- Connect to, and disconnect from, queue managers
- Open and close queues
- Open, put a message on a queue, and close the queue
- Put messages on queues
- Get messages from a queue, or browse them (leaving them on the queue)
- Inquire about the attributes of all MQSeries objects, and set some of the attributes of queues
- Commit and back out changes made within a unit of work
The MQI provides structures in order to supply input to, and get output from, the calls. It also supplies a large set of named constants to help with the construction of options in the parameters of the calls. The definitions of the calls, structures and constants are given in header files for each of the supported programming languages.
MQSeries Programming Techniques
MQI calls
In order for a program to use a queue it must first connect to the local queue manager. Once connected the program is then able to perform any further queue attribute, or message get and put operations required (with or without unit of work control). Before the program terminates it disconnects from the queue manager. The MQI calls are briefly outlined in the following sections.
Connecting to a queue manager using MQCONN
In general it is possible to connect either to a specific queue manager, or to the default one. In either case the queue manager must be local to the connecting program.
The input to MQCONN is:
- queue manager name
To connect to the default queue manager call MQCONN specifying a name consisting entirely of blanks or starting with a null character.
The output from MQCONN is:
- A connection handle
- A completion code
- A reason code
Disconnecting programs from a queue manager using MQDISC
When a program that has connected to a queue manager using the MQCONN call has finished all interaction with the queue manager, it must break the connection using the MQDISC call.
The input to MQDISC is:
- A connection handle returned from a previous MQCONN call
The output from MQDISC is:
- A completion code
- A reason code
The input connection handle will no longer be accepted in any other MQI call.
Opening a queue using MQOPEN
To perform any of the following operations, the relevant queue must first be opened:
- Put messages onto a queue
- Get or browse messages from a queue
- Inquire or set the attributes of a queue
Use the MQOPEN call to open the object, using the parameters and options of the call to specify what actions are to be performed with the queue. The only exception is if you want to put a single message on a queue, then close the queue immediately afterwards. In this case there is a shorthand method for performing an open, put and close operation all in one: the MQPUT1 call (outlined later).
The input to MQOPEN is:
- A connection handle returned from a previous MQCONN call
- A description of the object to be opened, passed using the object descriptor structure MQOD
- One or more options that control the action of the call (open for input, output, setting or inquiring attributes and so on)
The output from MQOPEN is:
- An object handle that represents the requested access to the queue
- A completion code
- A reason code
Closing queues using MQCLOSE
Once a program has finished all interaction with a queue it is closed using the MQCLOSE call.
Input to MQCLOSE is:
- A connection handle returned from a previous MQCONN call
- The object handle of the queue to be closed, returned from a previous MQOPEN call
Output from MQCLOSE is:
- A completion code
- A reason code
The queue object descriptor will no longer be valid and will not be accepted in any other MQI call.
Putting messages on a queue using MQPUT
Before it is possible to put messages on a queue an application must be connected to a queue manager, and must have issued an MQOPEN call to open the queue for output. Use MQPUT to place messages on the queue. An application can call MQPUT repeatedly to place many messages on the same queue, following the initial MQOPEN call. Once all the messages have been placed on the queue, call MQCLOSE.
If an application wishes to place a single message on a queue and then closes the queue immediately afterwards, it is possible to replace the MQOPEN, MQPUT, MQCLOSE sequence with a single MQPUT1 call (outlined later). If, however, the application needs to place more than one message on the queue it is more efficient to use the MQPUT call.
Input to MQPUT is:
- A connection handle returned from a previous MQCONN call
- The queue object handle returned a previous MQOPEN call for the desired queue
- Routing control information and a description of the message to place on the queue, in the form of a message descriptor structure (MQMD)
- Queue access control information, in the form of a put-message options structure (MQPMO)
- The length of the application data contained in the message
- The message data itself
Output from MQPUT is:
- A completion code
- A reason code
If the call completes successfully it also returns the options structure and the message descriptor structure. The call modifies the options structure to show the name of the queue and queue manager to which the message was sent. If the application requested that the queue manager generate the contents of the message identifier field in the control information section of the message (by using the constant MQMI_NONE), the call inserts the value in the field before the structure is returned. If the application defined the message identifier (by filling in the field prior to making the call) the value is returned unchanged.
An example program is included at the end of this document, it illustrates the use of this call. It reads an ASCII file and turns each line into a new message. Each message is written to the same queue.
Putting a message on a queue using MQPUT1
Use the MQPUT1 call when an application closes the queue immediately after putting a single message on a queue. For example, a server application is likely to use the MQPUT1 call when it is sending replies to many different queues. This call is functionally equivalent to calling MQOPEN, followed by MQPUT and MQCLOSE.
The only difference in the syntax for the MQPUT and the MQPUT1 calls is that for MQPUT a queue object handle must be supplied, whereas for MQPUT1 an object descriptor structure is supplied. This is because the MQPUT1 call needs to open the relevant queue before putting the message on it, whereas in the MQPUT call the queue is already open.
Input to the MQPUT1 call is:
- A connection handle returned from a previous MQCONN call
- A description of the queue to be opened for output, in the form of an object descriptor structure (MQOD)
- Routing control information and a description of the message to place on the queue, in the form of a message descriptor structure (MQMD)
- Queue access control information in the form of a put-message options structure (MQPMO)
- The length of the application data contained in the message
- The message data itself
Output from MQPUT1 is:
- A completion code
- A reason code
If the call completes successfully it also returns the options structure and the message descriptor structure. The call modifies the options structure to show the name of the queue and queue manager to which the message was sent. If the application requested that the queue manager generate the contents of the message identifier field in the control information section of the message (by using the constant MQMI_NONE), the call inserts the value in the field before the structure is returned.
If the application defined the message identifier (by filling in the field prior to making the call) the value is returned unchanged. An example program is included at the end of this document that demonstrates the use of this call. It reads an Oracle table, one of fields providing the name of the queue to receive the rest of the row.
