COBOL programming

Information to help you use the MQI from the COBOL programming language.

COPY files

Various COPY files are provided to help you write COBOL application programs that use the MQI. There are two files containing named constants, and two files for each of the structures.

Each structure is provided in two forms: a form with initial values, and a form without:
  • Use the structures with initial values in the WORKING-STORAGE SECTION of a COBOL program; they are contained in COPY files with names suffixed with the letter V (for Values).
  • Use the structures without initial values in the LINKAGE SECTION of a COBOL program; they are contained in COPY files with names suffixed with the letter L (for Linkage).

The COPY files are summarized in the following table. Not all the files listed are available in all environments.

Table 1. COBOL COPY files
File (with initial values) File (without initial values) Contents
CMQAIRV CMQAIRL Authentication information record
CMQBOV CMQBOL Begin options structure
CMQCIHV CMQCIHL CICS® information header structure
CMQCNOV CMQCNOL Connect options structure
CMQDHV CMQDHL Distribution header structure
CMQDLHV CMQDLHL Dead letter header structure
CMQDXPV CMQDXPL Data conversion exit parameter structure
CMQGMOV CMQGMOL Get message options structure
CMQIIHV CMQIIHL IMS information header structure
CMQMDV CMQMDL Message descriptor structure
CMQMDEV CMQMDEL Message descriptor extension structure
CMQMD1V CMQMD1L Message descriptor structure version 1
CMQODV CMQODL Object descriptor structure
CMQORV CMQORL Object record structure
CMQPMOV CMQPMOL Put message options structure
CMQRFHV CMQRFHL Rules and formatting header structure
CMQRFH2V CMQRFH2L Rules and formatting header structure version 2
CMQRMHV CMQRMHL Reference message header structure
CMQRRV CMQRRL Response record structure
CMQSCOV CMQSCOL TLS configuration options
CMQTMV CMQTML Trigger message structure
CMQTMCV CMQTMCL Trigger message structure (character format)
CMQTMC2V CMQTMC2L Trigger message structure (character format) version 2
CMQWIHV CMQWIHL Work information header structure
CMQXQHV CMQXQHL Transmission queue header structure
CMQV - Named constants for main MQI
CMQXV - Named constants for data conversion exit
CMQMD2V CMQMD2L Message descriptor structure version 2

Structures

In the COPY file, each structure declaration begins with a level-10 item; this enables you to declare several instances of the structure by coding the level-01 declaration and then using the COPY statement to copy in the remainder of the structure declaration. To refer to the appropriate instance, use the IN keyword: 
* Declare two instances of MQMD
 01  MY-MQMD.
     COPY CMQMDV.
 01  MY-OTHER-MQMD.
     COPY CMQMDV.
*
* Set MSGTYPE field in MY-OTHER-MQMD
     MOVE MQMT-REQUEST TO MQMD-MSGTYPE IN MY-OTHER-MQMD.

Align the structures on appropriate boundaries. If you use the COPY statement to include a structure following an item that is not the level-01 item, ensure that the structure begins at the appropriate offset from the start of the level-01 item. Most MQI structures require 4-byte alignment; the exceptions to this are MQCNO, MQOD, and MQPMO, which require 16-byte alignment on IBM® i.

In this section, the names of fields in structures are shown without a prefix. In COBOL, the field names are prefixed with the name of the structure followed by a hyphen. However, if the structure name ends with a numeric digit, indicating that the structure is a second or later version of the original structure, the numeric digit is omitted from the prefix. Field names in COBOL are shown in uppercase (although lowercase or mixed case can be used if required). For example, the field MsgType described in MQMD - Message descriptor becomes MQMD-MSGTYPE in COBOL.

The V-suffix structures are declared with initial values for all the fields; you need to set only those fields where you want a value that is different from the supplied initial value.

Pointers

Some structures need to address optional data that might be discontiguous with the structure, such as the MQOR and MQRR records addressed by the MQOD structure.

To address this optional data, the structures contain fields that are declared with the pointer data type. However, COBOL does not support the pointer data type in all environments. Because of this, the optional data can also be addressed using fields that contain the offset of the data from the start of the structure.

If you want to port an application between environments, ascertain whether the pointer data type is available in all the intended environments. If it is not, the application must address the optional data using the offset fields instead of the pointer fields.

In those environments where pointers are not supported, declare the pointer fields as byte strings of the appropriate length, with the initial value being the all-null byte string. Do not alter this initial value if you are using the offset fields.

Named constants

In this information, the names of constants are shown containing the underscore character (_) as part of the name. In COBOL, use the hyphen character (-) in place of the underscore.

Constants that have character-string values use the single quotation mark as the string delimiter ('). In some environments, you might have to specify an appropriate compiler option to cause the compiler to accept the single quotation mark as the string delimiter in place of the double quotation mark.

The named constants are declared in the COPY files as level-10 items. To use the constants, declare the level-01 item explicitly, and then use the COPY statement to copy in the declarations of the constants: 
* Declare a structure to hold the constants
 01  MY-MQ-CONSTANTS.
     COPY CMQV.
The preceding method causes the constants to occupy storage in the program even if they are not referenced. If you include the constants in many separate programs within the same run unit, multiple copies of the constants exist, consuming main storage unnecessarily. Avoid this effect by using one of the following techniques:
  • Add the GLOBAL clause to the level-01 declaration: 
    * Declare a global structure to hold the constants
 01  MY-MQ-CONSTANTS GLOBAL.
     COPY CMQV.

    This allocates storage for only one set of constants within the run unit. The constants, however, can be referenced by any program within the run unit, not just the program that contains the level-01 declaration.

    Note: The GLOBAL clause is not supported in all environments.
  • Manually copy into each program only those constants that are referenced by that program. Do not use the COPY statement to copy all the constants into the program.

Notation conventions

Previous sections in this topic show how to invoke calls and declare parameters. In some cases, the parameters are tables or character strings the size of which is not fixed. For these, a lowercase n is used to represent a numeric constant. When you code the declaration for that parameter, replace the n with the numeric value required.