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 our application program uses RRS to coordinate updates, see RRS Considerations.

However, this method:

  • Increases the complexity of your programs
  • Increases the storage required by your programs at execution time
  • Reduces the performance of your 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.
Table 1. Call names for dynamic linking
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 1 MQBUFMH
MQCB CSQBCB CSQCCB 1 Not supported
MQCLOSE CSQBCLOS CSQCCLOS MQCLOSE
MQCMIT CSQBCOMM not supported Not supported
MQCONN CSQBCONN CSQCCONN MQCONN
MQCONNX CSQBCONX CSQCCONX MQCONNX
MQCRTMH CSQBCTMH CSQCCTMH 1 MQCRTMH
MQCTL CSQBCTL CSQCCTL 1 Not supported
MQDISC CSQBDISC CSQCDISC MQDISC
MQDLTMH CSQBDTMH CSQCDTMH 1 MQDLTMH
MQDLTMP CSQBDTMP CSQCDTMP 1 MQDLTMP
MQGET CSQBGET CSQCGET MQGET
MQINQ CSQBINQ CSQCINQ MQINQ
MQINQMP CSQBIQMP CSQCIQMP 1 MQINQMP
MQMHBUF CSQBMHBF CSQCMHBF 1 MQMHBUF
MQOPEN CSQBOPEN CSQCOPEN MQOPEN
MQPUT CSQBPUT CSQCPUT MQPUT
MQPUT1 CSQBPUT1 CSQCPUT1 MQPUT1
MQSET CSQBSET CSQCSET MQSET
MQSETMP CSQBSTMP CSQCSTMP 1 MQSETMP
MQSTAT CSQBSTAT CSQCSTAT 1 MQSTAT
MQSUB CSQBSUB CSQCSUB 1 MQSUB
MQSUBRQ CSQBSUBR CSQCSUBR 1 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:

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;