MQSeries API

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. 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. Getting messages from a queue using MQGET Applications can get messages from a queue in 2 ways: by removing the message from the queue such that no other program can see it by copying the message, leaving the original on the queue. This technique is known as browsing. The application can subsequently remove the message if needed. In both the above cases the application uses the MQGET call, but it must first have been connected to the queue manager using MQCONN and have opened a queue for input using MQOPEN. When the queue has been opened MQGET can be called repeatedly to browse or remove messages from the same queue. The application calls MQCLOSE when the application has finished getting all the messages it requires from the queue. Input to the MQGET call is: A connection handle returned from a previous MQCONN call The queue object handle returned a previous MQOPEN call for the desired queue A description of the message to get from the queue, in the form of a message descriptor structure (MQMD) Queue access control information in the form of a get-message options structure (MQGMO) The size of the buffer assigned to hold the message The address of the buffer Output from MQGET is: A completion code A reason code The message in the buffer specified, if the call completed successfully The message descriptor structure populated with information from the message The length of the application data in the message It is possible to control how messages are retrieved from the queue via a combination of the message descriptor structure and the options structure, for example: Whether to poll, or wait, for a message The amount of time to wait (in seconds), if waiting is selected Which message is retrieved from the queue Whether the message is removed or copied Whether the get is included within the current unit of work Inquiring about queue attributes using MQINQ Attributes are the properties that define the characteristics of an MQSeries object, including queues. They affect the way the object is handled by the queue manager. Some attributes are set when the object is initially defined, and can only be changed via MQSeries commands. An application can inquire about all the queue attributes using the MQINQ call. The MQI also provides the MQSET call (outlined later) in order to allow applications to change some of the queue attributes. The MQINQ call uses an array of selectors to identify those attributes whose current values are to be inquired about. There is a selector for each of the attributes an application can work with. Before an application can use MQINQ it must first have been connected to the queue manager using MQCONN and have opened a queue for inquiry using MQOPEN. Input to the MQINQ call is: A connection handle returned from a previous MQCONN call The queue object handle returned a previous MQOPEN call for the desired queue The number of selectors in the attribute selector array An array of attribute selectors whose values are set via the MQSeries named constants. Each selector represents an attribute whose current value is to be inquired about. Selectors can be specified in any order in the array The number of integer type attributes to be inquired about. Specify zero if no integer type attributes are specified in the selectors array The address of an integer array with enough elements to hold the output integer attribute values The length of the character attributes buffer. This must be at least the sum of the lengths required to hold each character attribute string being inquired about. Specify zero if no character type attributes are inquired about The address of the character buffer to hold the returned attribute values Output from MQINQ is: A completion code A reason code A set of integer attribute values copied into the specified integer array The buffer in which character attribute values have been copied Setting queue attributes using MQSET Applications can change a subset of the queue attributes using the MQSET call: Get inhibit Put inhibit Trigger control Trigger type Trigger depth Trigger message priority Trigger data The MQSET call has the same parameters as the MQINQ call. However for MQSET, all parameters except the completion code and reason code are input parameters. Input to the MQSET call is: A connection handle returned from a previous MQCONN call The queue object handle returned a previous MQOPEN call for the desired queue The number of selectors in the attribute selector array An array of attribute selectors whose values are set via the MQSeries named constants. Each selector represents an attribute whose current value is to be set. Selectors can be specified in any order in the array The number of integer type attributes to be set. Specify zero if no integer type attributes are specified in the selectors array The address of an integer array that contains the integer attribute values The length of the character attributes buffer. This must be at least the sum of the lengths required to hold each character attribute string being set. Specify zero if no character type attributes are inquired about The address of the character buffer that holds the attribute values Output from MQSET is: A completion code A reason code Committing a unit of work using MQCMIT When a program puts a message on, or gets a message from, a queue, it can decide whether that message is to be included within the current unit of work. This decision is reflected in the put-message or get-message options structure passed to the MQPUT, MQPUT1, or MQGET call. When a message is put on a queue within the unit of work, it is made visible to other programs only when the putting program commits that unit of work using MQCMIT. If the program detects an error and decides that the put operation should not be made permanent, it can back out the unit of work using MQBACK (outlined later). Similarly when a program gets a message from a queue within a unit of work, that message remains on the queue until the program commits the unit of work, but the message is not available to be retrieved by other programs. By default messages are excluded from the current unit of work, therefore any message that is to be included must be done so explicitly in the associated MQPUT, MQPUT1, or MQGET call. The current unit of work encompasses all included messages sent or received since the last MQCMIT or MQBACK call. Input to the MQCMIT call is: A connection handle return from a previous MQCONN call Output from MQCMIT is: A completion code A reason code As can be seen from the input to MQCMIT there is no way in which to specify a single queue to the call, this means that the unit of work covers all queues that were opened using the given connection handle. Therefore when MQCMIT is called all the put and get operations on queues associated with the connection handle are committed. Backing out a unit of work using MQBACK When a program backs out a unit of work MQSeries restores the queue to the state it was in before the program performed the first put or get operation within the unit of work. However any operation that was performed outside the unit of work will not be restored. Input to MQBACK is: A connection handle returned from a previous MQCONN call Output from MQBACK is: A completion code A reason code As can be seen from the input to MQBACK there is no way in which to specify a single queue to the call, this means that the unit of work covers all queues that were opened using the given connection handle. Therefore when MQBACK is called all the put and get operations on queues associated with the connection handle are backed out.