Language considerations

This topic contains information to help we use the MQI from the RPG programming language.

Some of these language considerations are:


COPY files

Various COPY files are provided to assist with the writing of RPG application programs that use message queuing. There are three sets of COPY files:

  • COPY files with names ending with the letter G are for use with programs that use static linkage. These files are initialized with the exceptions stated in Structures.
  • COPY files with names ending with the letter H are for use with programs that use static linkage, but are not initialized.
  • COPY files with names ending with the letter R are for use with programs that use dynamic linkage. These files are initialized with the exceptions stated in Structures.

The COPY files reside in QRPGLESRC in the QMQM library.

For each set of COPY files, there are two files containing named constants, and one file for each of the structures. The COPY files are summarized in Table 1.

Table 1. RPG COPY files
File name (static linkage, initialized, CMQ*G) File name (static linkage, not initialized, CMQ*H) File name (dynamic linkage, initialized, CMQ*R) Contents
CMQBOG CMQBOH - Begin options structure
CMQCDG CMQCDH CMQCDR Channel definition structure
CMQCFBFG CMQCFBFH - PCF bit filter parameter
CMQCFG - - Constants for PCF and events
CMQCFBSG CMQCFBSH - PCF byte string
CMQCFGRG CMQCFGRH - PCF group parameter
CMQCFIFG CMQCFIFH - PCF integer filter parameter
CMQCFHG CMQCFHH - PCF header
CMQCFILG CMQCFILH - PCF integer list parameter structure
CMQCFING CMQCFINH - PCF integer parameter structure
CMQCFSFG CMQCFSFH - PCF string filter parameter
CMQCFSLG CMQCFSLH - PCF string list parameter structure
CMQCFSTG CMQCFSTH - PCF string parameter structure
CMQCFXLG CMQCFXLH - PCF short name for CFIL64
CMQCFXNG CMQCFXNH - PCF short name for CFIN64
CMQCIHG CMQCIHH - CICS® information header structure
CMQCNOG CMQCNOH - Connect options structure
CMQCSPG CMQCSPH - Security parameters
CMQCXPG CMQCXPH CMQCXPR Channel exit parameter structure
CMQDHG CMQDHH CMQDHR Distribution header structure
CMQDLHG CMQDLHH CMQDLHR Dead letter header structure
CMQDXPG CMQDXPH CMQDXPR Data conversion exit parameter structure
CMQEPHG CMQEPHH - Embedded PCF header structure
CMQG - CMQR Named constants for main MQI
CMQGMOG CMQGMOH CMQGMOR Get message options structure
CMQIIHG CMQIIHH CMQIIHR IMS information header structure
CMQMDEG CMQMDEH CMQMDER Message descriptor extension structure
CMQMDG CMQMDH CMQMDR Message descriptor structure
CMQMD1G CMQMD1H CMQMD1R Message descriptor structure version 1
CMQMD2G CMQMD2H - Message descriptor structure version 2
CMQODG CMQODH CMQODR Object descriptor structure
CMQORG CMQORH CMQORR Object record structure
CMQPMOG CMQPMOH CMQPMOR Put message options structure
CMQPSG - - Constants for publish/subscribe
CMQRFHG CMQRFHH - Rules and formatting header structure
CMQRFH2G CMQRFH2H - Rules and formatting header 2 structure
CMQRMHG CMQRMHH CMQRMHR Reference message header structure
CMQRRG CMQRRH CMQRRR Response record structure
CMQTMCG CMQTMCH CMQTMCR Trigger message structure (character format)
CMQTMC2G CMQTMC2H CMQTMC2R Trigger message structure (character format) version 2
CMQTMG CMQTMH CMQTMR Trigger message structure
CMQWIHG CMQWIHH - Work information header structure
CMQXG - CMQXR Named constants for data conversion exit
CMQXQHG CMQXQHH CMQXQHR Transmission queue header structure


Calls

Calls are described using their individual names.


Call parameters

Some parameters passed to the MQI can have more than one concurrent function. This is because the integer value passed is often tested on the setting of individual bits within the field, and not on its total value. This allows you to 'add' several functions together and pass them as a single parameter.


Structures

All IBM MQ structures are defined with initial values for the fields, with the following exceptions:

  • Any structure with a suffix of H.
  • MQTMC
  • MQTMC2
These initial values are defined in the relevant table for each structure. The structure declarations do not contain DS statements. This allows the application to declare either a single data structure or a multiple-occurrence data structure, by coding the DS statement and then using the /COPY statement to copy in the remainder of the declaration: 
D*..1....:....2....:....3....:....4....:....5....:....6....:....7
D* Declare an MQMD data structure with 5 occurrences
DMYMD        DS                          5
D/COPY CMQMDR


Named constants

There are many integer and character values that provide data interchange between our application program and the queue manager. To facilitate a more readable and consistent approach to using these values, named constants are defined for them. We can use these named constants and not the values they represent, as this improves the readability of the program source code.

When the COPY file CMQG is included in a program to define the constants, the RPG compiler will issue many severity-zero messages for the constants that are not used by the program; these messages are benign, and can safely be ignored.


MQI procedures

When using the ILE bound calls, you must bind to the MQI procedures when you create your program. These procedures are exported from the following service programs as appropriate:

    QMQM/LIBMQM
    This service program contains the single-threaded bindings for version 5.1 and above. See the following section for special considerations when writing threaded applications.

    QMQM/LIBMQM_R
    This service program contains the multi-threaded bindings for version 5.1 and above. See the following section for special considerations when writing threaded applications.

    QMQM/LIBMQIC
    This service program is for binding non-threaded client applications.

    QMQM/LIBMQIC_R
    This service program is for binding threaded client applications.

Use the CRTPGM command to create your programs. For example, the following command creates a single-threaded program that uses the ILE bound calls: 

CRTPGM PGM(MYPROGRAM) BNDSRVPGM(QMQM/LIBMQM)


Threading considerations

The RPG compiler used for IBM i is part of the WebSphere Development Toolset and WebSphere Development Studio for IBM i and is known as the ILE RPG IV Compiler.

In general, RPG programs should not use the multi-threaded service programs. Exceptions are RPG programs created using the ILE RPG IV Compiler, and containing the THREAD(*SERIALIZE) keyword in the control specification. However, even though these programs are thread safe, careful consideration must be given to the overall application design, as THREAD(*SERIALIZE) forces serialization of RPG procedures at the module level, and this might have an adverse affect on overall performance.

Where RPG programs are used as data-conversion exits, they must be made thread-safe, and should be recompiled using the version 4.4 ILE RPG compiler or above, with THREAD(*SERIALIZE) specified in the control specification.

For further information about threading, see the IBM i IBM MQ Development Studio: ILE RPG Reference, and the IBM i IBM MQ Development Studio: ILE RPG Programmer's Guide.


Commitment control

The MQI syncpoint functions MQCMIT and MQBACK are available to ILE RPG programs running in normal mode; these calls allow the program to commit and back out changes to MQ resources.


Coding the bound calls

MQI ILE procedures are listed in Table 2.

Table 2. ILE RPG bound calls supported by each service program
Name of call LIBMQM and LIBMQM_R LIBMQIC and LIBMQIC_R
MQBACK Y Y
MQBEGIN Y Y
MQCMIT Y Y
MQCLOSE Y Y
MQCONN Y Y
MQCONNX Y Y
MQDISC Y Y
MQGET Y Y
MQINQ Y Y
MQOPEN Y Y
MQPUT Y Y
MQPUT1 Y Y
MQSET Y Y
MQXCNVC Y Y
To use these procedures you need to:
  1. Define the external procedures in your 'D' specifications. These are all available within the COPY file member CMQG containing the named constants.
  2. Use the CALLP operation code to call the procedure along with its parameters.
For example the MQOPEN call requires the inclusion of the following code: 
   D******************************************************************
   D**  MQOPEN Call -- Open Object  (From COPY file CMQG)           **
   D******************************************************************
   D*
   D*..1....:....2....:....3....:....4....:....5....:....6....:....7..
   DMQOPEN           PR                  EXTPROC('MQOPEN')
   D* Connection handle
   D HCONN                         10I 0 VALUE
   D* Object descriptor
   D OBJDSC                       224A
   D* Options that control the action of MQOPEN
   D OPTS                          10I 0 VALUE
   D* Object handle
   D HOBJ                          10I 0
   D* Completion code
   D CMPCOD                        10I 0
   D* Reason code qualifying CMPCOD
   D REASON                        10I 0
   D*
To call the procedure, after initializing the various parameters, you need the following code: 
 ...+... 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ...+....8
     C                   CALLP     MQOPEN(HCONN : MQOD : OPTS : HOBJ :
     C                             CMPCOD : REASON)

Here, the structure MQOD is defined using the COPY member CMQODG which breaks it down into its components.


Notational conventions

The latter topics in this section show how the:

  • Calls should be invoked
  • Parameters should be declared
  • Various data types should be declared

In a number of cases, parameters are arrays or character strings with a size that is not fixed. For these, a lowercase n is used to represent a numeric constant. When the declaration for that parameter is coded, the n must be replaced by the numeric value required.