Dynamically calling the IBM MQ stub

Instead of link-editing the IBM MQ stub program with your object code, we can dynamically call the stub from within your program.

We can do this in the batch, IMS, and CICS environments. This facility is not supported in the RRS environment. If the application program uses RRS to coordinate updates, see RRS Considerations.

However, this method:

Increases the complexity of our programs
Increases the storage required by your programs at execution time
Reduces the performance of our programs
Means that we cannot use the same programs in other environments

If you call the stub dynamically, the appropriate stub program and its aliases must be available at execution time. To ensure this, include the IBM MQ for z/OS data set SCSQLOAD:

For batch and IMS, in the STEPLIB concatenation of the JCL.
For CICS, in the CICS DFHRPL concatenation.

For IMS, ensure that the library containing the dynamic stub (built as described in the information about installing the IMS adapter in Set up the IMS adapter ) is ahead of the data set SCSQLOAD in the STEPLIB concatenation of the region JCL.

Use the names shown in Table 1 when you call the stub dynamically. In PL/I, only declare the call names used in your program.

MQI call	Batch (non-RRS) dynamic call names	CICS dynamic call names	IMS dynamic call names
MQBACK	CSQBBACK	not supported	Not supported
MQBUFMH	CSQBBFMH	CSQCBFMH ¹	MQBUFMH
MQCB	CSQBCB	CSQCCB ¹	Not supported
MQCLOSE	CSQBCLOS	CSQCCLOS	MQCLOSE
MQCMIT	CSQBCOMM	not supported	Not supported
MQCONN	CSQBCONN	CSQCCONN	MQCONN
MQCONNX	CSQBCONX	CSQCCONX	MQCONNX
MQCRTMH	CSQBCTMH	CSQCCTMH ¹	MQCRTMH
MQCTL	CSQBCTL	CSQCCTL ¹	Not supported
MQDISC	CSQBDISC	CSQCDISC	MQDISC
MQDLTMH	CSQBDTMH	CSQCDTMH ¹	MQDLTMH
MQDLTMP	CSQBDTMP	CSQCDTMP ¹	MQDLTMP
MQGET	CSQBGET	CSQCGET	MQGET
MQINQ	CSQBINQ	CSQCINQ	MQINQ
MQINQMP	CSQBIQMP	CSQCIQMP ¹	MQINQMP
MQMHBUF	CSQBMHBF	CSQCMHBF ¹	MQMHBUF
MQOPEN	CSQBOPEN	CSQCOPEN	MQOPEN
MQPUT	CSQBPUT	CSQCPUT	MQPUT
MQPUT1	CSQBPUT1	CSQCPUT1	MQPUT1
MQSET	CSQBSET	CSQCSET	MQSET
MQSETMP	CSQBSTMP	CSQCSTMP ¹	MQSETMP
MQSTAT	CSQBSTAT	CSQCSTAT ¹	MQSTAT
MQSUB	CSQBSUB	CSQCSUB ¹	MQSUB
MQSUBRQ	CSQBSUBR	CSQCSUBR ¹	MQSUBRQ

Note: 1. These API calls are available only when using CICS TS 3.2 or later and the CSQCSTUB shipped with CICS must be used. For CICS TS 3.2, APAR PK66866 must be applied. For CICS TS 4.1, APAR PK89844 must be applied. For examples of how to use this technique, see the following figures:

Batch and COBOL: see Figure 1
CICS and COBOL: see Figure 2
IMS and COBOL: see Figure 3
Batch and assembler: see Figure 4
CICS and assembler: see Figure 5
IMS and assembler: see Figure 6
Batch and C: Figure 7
CICS and C: see Figure 8
IMS and C: see Figure 9
Batch and PL/I: see Figure 10
IMS and PL/I: see Figure 11

Figure 1. Dynamic linking using COBOL in the batch environment

...
       WORKING-STORAGE SECTION.
...
          05 WS-MQOPEN                     PIC X(8) VALUE 'CSQBOPEN'.
...
       PROCEDURE DIVISION.
...
           CALL WS-MQOPEN WS-HCONN
                          MQOD
                          WS-OPTIONS
                          WS-HOBJ
                          WS-COMPCODE
                          WS-REASON.
...

Figure 2. Dynamic linking using COBOL in the CICS environment

...
       WORKING-STORAGE SECTION.
...
          05 WS-MQOPEN                     PIC X(8) VALUE 'CSQCOPEN'.
...
       PROCEDURE DIVISION.
...
           CALL WS-MQOPEN WS-HCONN
                          MQOD
                          WS-OPTIONS
                          WS-HOBJ
                          WS-COMPCODE
                          WS-REASON.
...

Figure 3. Dynamic linking using COBOL in the IMS environment

...
       WORKING-STORAGE SECTION.
...
          05 WS-MQOPEN                     PIC X(8) VALUE 'MQOPEN'.
...
       PROCEDURE DIVISION.
...
           CALL WS-MQOPEN WS-HCONN
                          MQOD
                          WS-OPTIONS
                          WS-HOBJ
                          WS-COMPCODE
                          WS-REASON.
...
      * ----------------------------------------------------------- *
      *
      *    If the compilation option 'DYNAM' is specified
      *    then you may code the MQ calls as follows
      *
      * ----------------------------------------------------------- *
...
           CALL 'MQOPEN'  WS-HCONN
                          MQOD
                          WS-OPTIONS
                          WS-HOBJ
                          WS-COMPCODE
                          WS-REASON.
...

Figure 4. Dynamic linking using assembly language in the batch environment

...
         LOAD   EP=CSQBOPEN
...
         CALL (15),(HCONN,MQOD,OPTIONS,HOBJ,COMPCODE,REASON),VL
...
         DELETE EP=CSQBOPEN
...

Figure 5. Dynamic linking using assembly language in the CICS environment

...
         EXEC CICS LOAD PROGRAM('CSQCOPEN') ENTRY(R15)
...
         CALL (15),(HCONN,MQOD,OPTIONS,HOBJ,COMPCODE,REASON),VL
...
         EXEC CICS RELEASE PROGRAM('CSQCOPEN')
...

Figure 6. Dynamic linking using assembly language in the IMS environment

...
         LOAD   EP=MQOPEN
...
         CALL (15),(HCONN,MQOD,OPTIONS,HOBJ,COMPCODE,REASON),VL
...
         DELETE EP=MQOPEN
...

Figure 7. Dynamic linking using C language in the batch environment

...
typedef void CALL_ME();
#pragma linkage(CALL_ME, OS)
...
main()
{
CALL_ME * csqbopen;
...
csqbopen = (CALL_ME *) fetch("CSQBOPEN");
(*csqbopen)(Hconn,&ObjDesc,Options,&Hobj,&CompCode,&Reason);
...

Figure 8. Dynamic linking using C language in the CICS environment

...
typedef void CALL_ME();
#pragma linkage(CALL_ME, OS)
...
main()
{
CALL_ME * csqcopen;
...
  EXEC CICS LOAD PROGRAM("CSQCOPEN") ENTRY(csqcopen);
(*csqcopen)(Hconn,&ObjDesc,Options,&Hobj,&CompCode,&Reason);
...

Figure 9. Dynamic linking using C language in the IMS environment

...
typedef void CALL_ME();
#pragma linkage(CALL_ME, OS)
...
main()
{
CALL_ME * mqopen;
...
mqopen = (CALL_ME *) fetch("MQOPEN");
(*mqopen)(Hconn,&ObjDesc,Options,&Hobj,&CompCode,&Reason);
...

Figure 10. Dynamic linking using PL/I in the batch environment

...
      DCL CSQBOPEN ENTRY EXT OPTIONS(ASSEMBLER INTER);
...
      FETCH CSQBOPEN;

      CALL CSQBOPEN(HQM,
                    MQOD,
                    OPTIONS,
                    HOBJ,
                    COMPCODE,
                    REASON);

      RELEASE CSQBOPEN;

Figure 11. Dynamic linking using PL/I in the IMS environment

...
      DCL MQOPEN   ENTRY EXT OPTIONS(ASSEMBLER INTER);
...
      FETCH MQOPEN;

      CALL   MQOPEN(HQM,
                    MQOD,
                    OPTIONS,
                    HOBJ,
                    COMPCODE,
                    REASON);

      RELEASE   MQOPEN;

RRS Considerations
Consider using this information if the application program uses RRS to coordinate updates.

Parent topic: Building your procedural application on z/OS