Coding in System/390 assembler language (Message queue interface)
Note the information in the following sections when coding IBM® MQ for z/OS® programs in assembler language.
Names
The names of parameters in the descriptions of calls, and the names of fields in the descriptions of structures are shown in mixed case. In the assembler-language macros supplied with IBM MQ, all names are in uppercase.
Using the MQI calls
The MQI is a call interface, so assembler-language programs must observe the OS linkage convention.
In particular, before they issue an MQI call, assembler-language programs must point register R13 at a save area of at least 18 full words. This save area provides storage for the called program. It stores the registers of the caller before their contents are destroyed, and restores the contents of the caller's registers on return.
Declaring constants
Most constants are declared as equates in macro CMQA.
- MQACT_NONE
- MQCI_NONE
- MQFMT_NONE
- MQFMT_ADMIN
- MQFMT_COMMAND_1
- MQFMT_COMMAND_2
- MQFMT_DEAD_LETTER_HEADER
- MQFMT_EVENT
- MQFMT_IMS
- MQFMT_IMS_VAR_STRING
- MQFMT_PCF
- MQFMT_STRING
- MQFMT_TRIGGER
- MQFMT_XMIT_Q_HEADER
- MQMI_NONE
CMQA is protected against multiple declaration, so you can include it many times. However, the keyword EQUONLY takes effect only the first time that the macro is included.
Specifying the name of a structure
To allow more than one instance of a structure to be declared, the macro that generates the structure prefixes the name of each field with a user-specifiable string and an underscore character (_).
Specify the string when you invoke the macro. If you do not specify a string, the macro uses the name of the structure to construct the prefix:
* Declare two object descriptors
CMQODA Prefix used="MQOD_" (the default)
MY_MQOD CMQODA Prefix used="MY_MQOD_"
The structure declarations in Call descriptions show the default prefix.
Specifying the form of a structure
- DSECT=YES
- An assembler-language DSECT instruction is used to start a new data section; the structure definition immediately follows the DSECT statement. No storage is allocated, so no initialization is possible. The label on the macro invocation is used as the name of the data section; if no label is specified, the name of the structure is used.
- DSECT=NO
- Assembler-language DC instructions are used to define the structure at the current position in the routine. The fields are initialized with values, which you can specify by coding the relevant parameters on the macro invocation. Fields for which no values are specified on the macro invocation are initialized with default values.
DSECT=NO is assumed if the DSECT parameter is not specified.
Controlling the listing
- LIST=YES
- The structure declaration appears in the assembler-language listing.
- LIST=NO
- The structure declaration does not appear in the assembler-language listing. This is assumed if the LIST parameter is not specified.
Specifying initial values for fields
You can specify the value to be used to initialize a field in a structure by coding the name of that field (without the prefix) as a parameter on the macro invocation, accompanied by the value required.
For example, to declare a message descriptor structure with the MsgType
field initialized with MQMT_REQUEST, and the ReplyToQ
field initialized with the string MY_REPLY_TO_QUEUE, use the following code:
MY_MQMD CMQMDA MSGTYPE=MQMT_REQUEST, X
REPLYTOQ=MY_REPLY_TO_QUEUE
If you specify a named constant (or equate) as a value on the macro invocation, use the CMQA macro to define the named constant. You must not enclose in single quotation marks (' ') values that are character strings.
Writing reenterable programs
- Define working storage versions of the structures as DSECTs, or define the structures inline within an already-defined DSECT. Then copy the DSECT to storage that is obtained using:
- For batch and TSO programs, the STORAGE or GETMAIN z/OS assembler macros
- For CICS, the working storage DSECT (DFHEISTG) or the EXEC CICS GETMAIN command
Note: The MQMD and MQXQH structures are each more than 256 bytes long. To copy these structures to storage, use the MVCL assembler instruction. - Reserve space in storage by using the LIST form (
MF=L
) of the CALL macro. When you use the CALL macro to make an MQI call, use the EXECUTE form (MF=E
) of the macro, using the storage reserved earlier, as shown in the example under Using CEDF. For more examples of how to do this, see the assembler language sample programs as shipped with IBM MQ.
Use the assembler language RENT option to help you to determine if your program is reenterable.
For information on writing reenterable programs, see z/OS MVS Application Development Guide: Assembler Language Programs.
Using CEDF
If you want to use the CICS-supplied transaction, CEDF ( CICS Execution Diagnostic Facility) to help you to debug your program, add the ,VL
keyword to each CALL
statement, for example:
CALL MQCONN,(NAME,HCONN,COMPCODE,REASON),MF=(E,PARMAREA),VL
The previous example is reenterable assembler-language code where PARMAREA
is an area in the working storage that you specified.