Building z/OS batch applications using Language Environment

IBM MQ for z/OS® provides a set of dynamic link libraries (DLLs) that must be used when you link-edit our applications.

There are two variants of the libraries which allow the application to use one of the following calling interfaces:

The 31-bit Language Environment calling interface.
The 31-bit XPLINK calling interface. z/OS XPLINK is a high performance calling convention available for C applications.

To use the DLLs, the application is bound or linked against so called sidedecks, instead of the stubs provided with earlier versions. The sidedecks are found in the SCSQDEFS library (instead of the SCSQLOAD library).

Table 1. Variants of dynamic link libraries
Commit	31-bit Language Environment DLL	31-bit XPLINK DLL	Equivalent stub name
1 phase commit MQI libraries	CSQBMQ1	CSQBMQ1X	CSQBSTUB
2 phase commit with RRS co-ordination using RRS transaction-control verbs	CSQBRR1	CSQBRR1X	CSQBRSTB
2 phase commit with RRS co-ordination using MQI transaction-control verbs	CSQBRI1	CSQBRI1X	CSQBRRSI

Note: All sidedecks contain a definition of the data conversion entry point, MQXCNVC, previously resolved by including CSQASTUB. Common issues:

The following message appears on the job log if our application uses asynchronous message consume (MQCB, MQCTL or MQSUB calls) and the previous DLL interface is not used:
```
CSQB001E Language environment programs running in z/OS batch or USS must use the DLL interface to IBM MQ
```
Solution: Rebuild our application using sidedecks instead of stubs as detailed previously.
At program build time, the following message appears
```
IEW2469E The Attributes of a reference to MQAPI-NAME from section your-code do not match the attributes of
the target symbol
```
Reason: This means that we have compiled your XPLINK program with V701 (or later) version of cmqc.h, but are not binding with sidedecks.

Solution: Change your program's build file to bind against the appropriate sidedeck from SCSQDEFS instead of a stub from SCSQLOAD

The following sample JCL demonstrates how we can compile and link-edit a C program to use the 31 bit Language Environment DLL calling interface:

//CLG EXEC EDCCB,
//  INFILE=MYPROGS.CPROGS(MYPROGRAM),
//  CPARM='OPTF(DD:OPTF)',
//  BPARM='XREF,MAP,DYNAM=DLL'           < LINKEDIT OPTIONS
//COMPILE.OPTF DD *
RENT,CHECKOUT(ALL),SSCOM,DEFINE(MVS),NOMARGINS,NOSEQ,DLL
SE(DD:SYSLIBV)
//COMPILE.SYSLIB DD
//               DD
//               DD DISP=SHR,DSN=hlq.SCSQC370
//COMPILE.SYSLIBV DD DISP=SHR,DSN=hlq.BASE.H
/*
//BIND.SYSOBJ DD DISP=SHR,DSN=CEE.SCEEOBJ
//            DD DISP=SHR,DSN=hlq.SCSQDEFS
//BIND.SYSLMOD DD DISP=SHR,DSN=hlq.LOAD(MYPROGAM)
//BIND.SYSIN  DD *
 ENTRY CEESTART
 INCLUDE SYSOBJ(CSQBMQ1)
 NAME MYPROGAM(R)
//

Note: The compilation uses the DLL option. The link-edit uses DYNAM=DLL option and the references the CSQBMQ1 library. The following sample JCL demonstrates how we can compile and link-edit a C program to use the 31 bit XPLINK DLL calling interface:

//CLG  EXEC EDCXCB,
//  INFILE=MYPROGS.CPROGS(MYPROGRAM),                           
//  CPARM='OPTF(DD:OPTF)',                                       
//  BPARM='XREF,MAP,DYNAM=DLL'           < LINKEDIT OPTIONS      
//COMPILE.OPTF DD *                                              
RENT,CHECKOUT(ALL),SSCOM,DEFINE(MVS),NOMARGINS,NOSEQ,XPLINK,DLL  
SE(DD:SYSLIBV)                                                   
//COMPILE.SYSLIB DD                                             
//               DD                                             
//               DD DISP=SHR,DSN=hlq.SCSQC370     
//COMPILE.SYSLIBV DD DISP=SHR,DSN=hlq.BASE.H 
/*         
//BIND.SYSOBJ DD DISP=SHR,DSN=CEE.SCEEOBJ                       
//            DD DISP=SHR,DSN=hlq.SCSQDEFS        
//BIND.SYSLMOD DD DISP=SHR,DSN=hlq.LOAD(MYPROGAM)      
//BIND.SYSIN  DD *                                              
 ENTRY CEESTART                                                 
 INCLUDE SYSOBJ(CSQBMQ1X)                                       
 NAME MYPROGAM(R)                                               
//

Note: The compilation uses the XPLINK and DLL options. The link-edit uses DYNAM=DLL option and references the CSQBMQ1X library.

Ensure that you add the compilation option DLL to each program in the module. Messages such as IEW2456E 9207 SYMBOL CSQ1BAK UNRESOLVED are an indication that you need to check that all of the programs have been compiled with the DLL option.