Message Queue Interface (MQI)
Overview
The Message Queue Interface consists of the following:
- Calls for accessing a queue manager
- Stuctures and elementary data types for passing data to queue managers
- Calls for committing and backing out changes
- Include files for defining the values of constants
- Library files for linking applications
- A suite of sample programs
- Sample code for binding to external transaction managers
Calls in the MQI can be grouped as follows:
MQCONN MQCONNX MQDISC Connect to a queue manager. MQOPEN MQCLOSE Open and close an object, such as a queue. MQPUT MQPUT1 Put a message on a queue. MQGET Browse messages on a queue, or to remove messages from a queue. MQINQ Inquire about the attributes of an object. MQSET Set some of the attributes of a queue. You cannot set the attributes of other types of object. MQBEGIN MQCMIT MQBACK Used when WebSphere MQ is the coordinator of a unit of work. MQBEGIN starts the unit of work. MQCMIT and MQBACK end the unit of work, either committing or rolling back the updates made during the unit of work.
Syncpoint calls
WebSphere MQ for z/OS calls
WebSphere MQ for z/OS provides the MQCMIT and MQBACK calls. Use these calls in z/OS batch programs to tell a queue manager that all the MQGET and MQPUT operations since the last syncpoint are to be made permanent (committed) or are to be backed out. To commit and back out changes in other environments:
- CICS
Use commands such as EXEC CICS SYNCPOINT and EXEC CICS SYNCPOINT ROLLBACK.
- IMS
Use the IMS syncpoint facilities, such as the GU (get unique) to the IOPCB, CHKP (checkpoint), and ROLB (rollback) calls.
- RRS
Use MQCMIT and MQBACK or SRRCMIT and SRRBACK as appropriate. (See Transaction management and recoverable resource manager services.)
SRRCMIT and SRRBACK are "native" RRS commands, they are not MQI calls.""
For backward compatibility, the CSQBCMT and CSQBBAK calls are available as synonyms for MQCMIT and MQBACK. These are described fully in WebSphere MQ Application Programming Reference.
Data conversion
The MQXCNVC - convert characters call converts message character data from one character set to another. This call is used only from a data-conversion exit.
See the WebSphere MQ Application Programming Reference manual for the syntax used with the MQXCNVC call, and Chapter 11, Writing data-conversion exits for guidance on writing and invoking data conversion exits.
Structures
Structures, used with the MQI calls listed in Calls, are supplied in data definition files for each of the supported programming languages.
All the structures are described fully in the WebSphere MQ Application Programming Reference.
Elementary data types
For the supported programming languages, the MQI provides elementary data types or unstructured fields. These data types are described fully in the WebSphere MQ Application Programming Reference.
WebSphere MQ data definitions
The data definition files supplied with WebSphere MQ contain:
- Definitions of all the WebSphere MQ constants and return codes
- Definitions of the WebSphere MQ structures and data types
- Constant definitions for initializing the structures
- Function prototypes for each of the calls (for PL/I and the C language only)
For a full description of WebSphere MQ data definition files, see Appendix F, WebSphere MQ data definition files.
WebSphere MQ stub programs and library files
The stub programs and library files provided are listed here, for each platform.
For more information about how to use stub programs and library files when you build an executable application, see Part 3, Building a WebSphere MQ application. For information about linking to C++ library files, see WebSphere MQ Using C++.
WebSphere MQ for z/OS
Before you can run a program written with WebSphere MQ for z/OS, link-edit it to the stub program supplied with WebSphere MQ for z/OS for the environment in which you are running the application. The stub program provides the first stage of the processing of your calls into requests that WebSphere MQ for z/OS can process.
WebSphere MQ for z/OS supplies the following stub programs:
CSQBSTUB Stub program for z/OS batch programs CSQBRRSI Stub program for z/OS batch programs using RRS via the MQI CSQBRSTB Stub program for z/OS batch programs using RRS directly CSQCSTUB Stub program for CICS programs CSQQSTUB Stub program for IMS programs CSQXSTUB Stub program for distributed queuing non-CICS exits CSQASTUB Stub program for data-conversion exits If you use the CSQBRSTB stub program link-edit with ATRSCSS from SYS1.CSSLIB. (SYS1.CSSLIB is also known as the "Callable Services Library"). For more information about RRS see Transaction management and recoverable resource manager services.
Alternatively, you can dynamically call the stub from within your program. This technique is described in Dynamically calling the WebSphere MQ stub.
In IMS, you may also need to use a special language interface module that is supplied by WebSphere MQ.
WebSphere MQ for iSeries
In WebSphere MQ for iSeries, link your program to the MQI library files supplied for the environment in which you are running the application, in addition to those provided by the operating system.
For non-threaded applications:
AMQZSTUB Server service program provided for compatibility with releases before V5R1M0 AMQVSTUB Data conversion service program provided for compatibility with releases before V5R1M0 LIBMQM Server service program LIBMQIC Client service program IMQB23I4 C++ base service program IMQS23I4 C++ server service program LIBMQMZF Installable exits for C In a threaded application:
LIBMQM_R Server service program IMQB23I4_R C++ base service program IMQS23I4_R C++ server service program LIBMQMZF_R Installable exits for C If you are using WebSphere MQ for iSeries you can write applications in C++. To see how to link your C++ applications, and for full details of all aspects of using C++, see WebSphere MQ Using C++.
WebSphere MQ for AIX
In WebSphere MQ for AIX, link your program to the MQI library files supplied for the environment in which you are running your application, in addition to those provided by the operating system.
In a non-threaded application:
libmqm.a Server for C libmqic.a Client for C libmqmzf.a Installable service exits for C libmqmxa.a XA interface for C libmqmcbrt.o WebSphere MQ run-time library for Micro Focus COBOL support libmqmcb.a Server for COBOL libmqicb.a Client for COBOL libimqc23ia.a Client for C++ libimqs23ia.a Server for C++ In a threaded application:
libmqm_r.a Server for C libmqic_r.a Client for C libmqmzf_r.a Installable service exits for C libmqmxa_r.a XA interface for C libimqc23ia_r.a Client for C++ libimqs23ia_r.a Server for C++ libmqmxa_r.a For Encina
WebSphere MQ for Linux
In WebSphere MQ for Linux, link your program to the MQI library files supplied for the environment in which you are running your application, in addition to those provided by the operating system.
In a non-threaded application:
libmqm.so Server for C libmqic.so Client for C libmqmzf.so Installable service exits for C libmqmxa.so XA interface for C libimqc23gl.so Client for C++ libimqs23gl.so Server for C++ In a threaded application:
libmqm_r.so Server for C libmqic_r.so Client for C libmqmzf_r.so Installable service exits for C libmqmxa_r.so XA interface for C libimqc23gl_r.so Client for C++ libimqs23gl_r.so Server for C++
WebSphere MQ for Solaris
In WebSphere MQ for Solaris, link your program to the MQI library files supplied for the environment in which you are running your application in addition to those provided by the operating system.
libmqm.so Server for C libmqmzse.so For C libmqic.so Client for C libmqmcs.so Client for C libmqmzf.so Installable service exits for C libmqmxa.a XA interface for C libimqc23as.a Client for C++ libimqs23as.a Server for C++ WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.
IBM is a trademark of the IBM Corporation in the United States, other countries, or both.