What is in the MQI?

The Message Queue Interface consists of the following:

• Calls through which programs can access the queue manager and its facilities
• Structures that programs use to pass data to, and get data from, the queue manager
• Elementary data types for passing data to, and getting data from, the queue manager

WebSphere MQ for z/OS also supplies:

• Two extra calls through which z/OS batch programs can commit and back out changes.
• Data definition files (sometimes known as copy files, macros, include files, and header files) that define the values of constants supplied with WebSphere MQ for z/OS.
• Stub programs to link-edit to your applications.
• A suite of sample programs that demonstrate how to use the MQI on the z/OS platform. For further information about these samples, see Chapter 36, Sample programs for WebSphere MQ for z/OS.

WebSphere MQ for iSeries also supplies:

• Data definition files (sometimes known as copy files, macros, include files, and header files) that define the values of constants supplied with WebSphere MQ for iSeries.
• Three stub programs to link-edit to your ILE C, ILE COBOL, and ILE RPG applications.
• A suite of sample programs that demonstrate how to use the MQI on the iSeries platform. For further information about these samples, see Chapter 35, Sample programs (all platforms except z/OS).

MQSeries for OS/2 Warp, WebSphere MQ for Windows, MQSeries for Compaq OpenVMS Alpha, and WebSphere MQ on UNIX systems also supply:

• Calls through which MQSeries for OS/2 Warp, WebSphere MQ for Windows, WebSphere MQ for iSeries, and WebSphere MQ on UNIX systems programs can commit and back out changes.
• Include files that define the values of constants supplied on these platforms.
• Library files to link your applications.
• A suite of sample programs that demonstrate how to use the MQI on these platforms.
• Sample source and executable code for bindings to external transaction managers.

MQSeries for Compaq NonStop Kernel also supplies:

• Include files that define the values of constants supplied with MQSeries for Compaq NonStop Kernel.
• Library files to link your applications.
• A suite of sample programs that demonstrate how to use the MQI on the Compaq NonStop Kernel platform.

MQSeries for VSE/ESA also supplies:

• Include files that define the values of constants supplied with MQSeries for VSE/ESA.
• A suite of sample programs that demonstrate how to use the MQI on the VSE/ESA platform.

Calls

The calls in the MQI can be grouped as follows:

MQCONN, MQCONNX, and MQDISC

Use these calls to connect a program to (with or without options), and disconnect a program from, a queue manager. If you write CICS programs for z/OS, or VSE/ESA, you do not need to use these calls. However, you are recommended to use them if you want your application to be portable to other platforms.

MQOPEN and MQCLOSE

Use these calls to open and close an object, such as a queue.

MQPUT and MQPUT1

Use these calls to put a message on a queue.

MQGET

Use this call to browse messages on a queue, or to remove messages from a queue.

MQINQ

Use this call to inquire about the attributes of an object.

MQSET

Use this call to set some of the attributes of a queue. You cannot set the attributes of other types of object.

MQBEGIN, MQCMIT, and MQBACK

Use these calls 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. OS/400 committment controller is used to coordinate global units of work on iSeries. Native start commitment control, commit, and rollback commands are used.

The MQI calls are described fully in WebSphere MQ Application Programming Reference.

Syncpoint calls

Syncpoint calls are available as follows:

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 the 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.)

Note:

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.

OS/400 calls

WebSphere MQ for iSeries provides the MQCMIT and MQBACK commands. You can also use the OS/400 COMMIT and ROLLBACK commands, or any other commands or calls that initiate the OS/400 commitment control facilities (for example, EXEC CICS SYNCPOINT).

MQSeries for Compaq NonStop Kernel calls

The default SYNCPOINT option for the MQPUT and MQGET calls is SYNCPOINT, rather than NO_SYNCPOINT. To use the default (SYNCPOINT) option for MQPUT, MQGET and MQPUT1 operations, the application must have an active TM/MP Transaction that defines the unit of work to be committed.

MQSeries for VSE/ESA calls

Use CICS commands such as EXEC CICS SYNCPOINT and EXEC CICS SYNCPOINT ROLLBACK. The batch interface and server support the MQCMIT and MQBACK calls which are translated into the CICS commands EXEC CICS SYNCPOINT and EXEC CICS SYNCPOINT ROLLBACK respectively. Use these calls in programs to tell the 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.

WebSphere MQ calls on other platforms

The following products provide the MQCMIT and MQBACK calls:

• MQSeries for OS/2 Warp
• WebSphere MQ for Windows
• MQSeries for Compaq OpenVMS Alpha
• WebSphere MQ on UNIX systems

Use syncpoint calls in programs to tell the 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 the CICS environment, use commands such as EXEC CICS SYNCPOINT and EXEC CICS SYNCPOINT ROLLBACK.

Data conversion

The MQXCNVC - convert characters call converts message character data from one character set to another. Except on WebSphere MQ for z/OS, 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. WebSphere MQ for z/OS and WebSphere MQ for iSeries supply files that contain constants for you to use when filling in some of the fields of these structures. For more information on these, see WebSphere MQ data definitions.

All the structures are described fully in the WebSphere MQ Application Programming Reference.

Elementary data types

For the C language, the MQI provides the following elementary data types or unstructured fields:

These data types are described fully in WebSphere MQ Application Programming Reference.

Table 1 shows the Visual Basic^(R) equivalents of the C elementary data types.

Table 1. Visual Basic equivalents of the C elementary data types

For COBOL, assembler, PL/I, or RPG, use the equivalent declarations shown in the relevant native language manual.

WebSphere MQ data definitions

WebSphere MQ for z/OS supplies data definitions in the form of COBOL copy files, assembler-language macros, a single PL/I include file, a single C language include file, and C++ language include files.

WebSphere MQ for iSeries supplies data definitions in the form of COBOL copy files, RPG copy files, C language include files, and C++ language include files.

MQSeries for VSE/ESA supplies data definitions in the form of a C language include file, COBOL copy files, and PL/I include files.

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, you must 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:

Note:

If you use the CSQBRSTB stub program you must 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, you must 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.

For non-threaded applications:

In a threaded application:

If you are using WebSphere MQ for iSeries you can write your 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++.

MQSeries for OS/2 Warp

In MQSeries for OS/2 Warp, you must 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:

WebSphere MQ for Windows

In WebSphere MQ for Windows, you must 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:

WebSphere MQ for AIX

In WebSphere MQ for AIX, you must 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:

In a threaded application:

MQSeries for AT&T GIS UNIX

In MQSeries for AT&T GIS UNIX, you must 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.

MQSeries for Compaq OpenVMS Alpha

In MQSeries for Compaq OpenVMS Alpha, you must 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:

MQSeries for Compaq Tru64 UNIX

In MQSeries for Compaq Tru64 UNIX, you must 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. The files listed are for DIGITAL UNIX Version 4.0D or Version 4.0E, and Compaq Tru64 UNIX Version 4.0F or Version 5.0, except where stated.

In a non-threaded application on V4.0 or any application on V5.0:

In a threaded application on V4.0:

WebSphere MQ for HP-UX

In WebSphere MQ for HP-UX, you must 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:

In a threaded application:

MQSeries for SINIX and DC/OSx

In MQSeries for SINIX and DC/OSx, you must 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:

In a threaded application:

WebSphere MQ for Solaris

In WebSphere MQ for Solaris, you must 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.

MQSeries for VSE/ESA

In MQSeries for VSE/ESA you must link your program to the install sublibrary PRD2.MQSERIES (this is its default name). This sublibrary contains all the required object decks.

MQSeries for Compaq NonStop Kernel

In MQSeries for Compaq NonStop Kernel, you must 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.