BATCHCAF — DB2 Call Attach facility interface
Many DB2 batch application programs which do not require the services of a TP environment (e.g. IMS/DC) have been written to execute under the DB2 DSN Processor in a batch TSO job step. Unfortunately, this incurs additional resource consumption, as both TSO and DSN participate in the execution process. In addition, it is very difficult to obtain an accurate application program-generated Return Code from a batch TSO job step.
These shortcomings can be avoided if the application elects to utilize the DB2 Call Attach Facility (CAF), which does not require a batch TSO job step nor is the DSN Processor required. Application programs which use the DB2 CAF are executed directly from the job step EXEC PGM= parameter, incurring no additional overhead and supporting an application Return Code. Unfortunately, coding for the DB2 CAF can be tedious and must contain a large degree of error handling capabilities.
QUICKSTART provides the application program with an implicit interface to the DB2 CAF, called BATCHCAF. The DB2 CAF requires no application programming when converting from a DSN implementation. On the first DB2 SQL “CALL” by the application program, BATCHCAF automatically “CONNECTs” to the appropriate DB2 SubSystem, “OPENs” the appropriate Plan, then passes the SQL Statement to DB2 for processing.
Application programs which currently execute under the DSN Processor can easily convert to CAF and BATCHCAF without any program changes. This is done by simply re-linking the application program with BATCHCAF replacing the DB2 program DSNHLI in the program's Link-Edit JCL. The Linkage-Editor input statements for this exercise are:
INCLUDE SYSLIB(BATCHCAF)
INCLUDE OBJLIB(application-program-name)
ENTRY application-program-name
NAME application-program-name
/*
where //SYSLIB includes the Load Library in which QUICKSTART has been installed, and where //OBJLIB references the PDS Library in which the application program Object Code exists (output of the compile step).
The output of the compile step may instead be a temporary dataset which is fed in to the link step via the //SYSLIN DD card rather than a PDS dataset. If this is the case, simply add a //OBJLIB DD card to the link step referencing the temporary dataset and change the INCLUDE OBJLIB card to not reference a specific dataset name as in the example below:
//SYSLIN DD *
INCLUDE SYSLIB(BATCHCAF)
INCLUDE OBJLIB
ENTRY application-program-name
NAME application-program-name
/*
Also note that some languages require the ENTRY statement to specify a name other than the application-program-name. For example, PLI requires an ENTRY PLISTART.
To use BATCHCAF, COBOL applications should have been compiled using the RES and NODYNAM options. The reason for this is as follows. The DB2 precompiler generates calls of the form CALL 'DSNHLI' which by calling convention is a static call which will get resolved at link time. QUICKSTART's BATCHCAF satisfies the linker for the DSNHLI entry point. If COBOL's DYNAM compile option is used, this call to DSNHLI is forced to be a dynamic call. This means that at run time, COBOL will try to load a new copy of DSNHLI and will find DB2's TSO attach instead of QUICKSTART's Call attach.
If you are using COBOL2 and wish to use DYNAM as a compile option, make sure that the QUICKSTART Load Library comes before the DB2 load library in the //STEPLIB DD concatenation of the run time JCL. Then, when COBOL goes to dynamically CALL DSNHLI the first time, it will find QUICKSTART's CALL Attach first.
If you are using the DYNAM compile option and are having problems getting the wrong attach running with your program, be sure the check the STEPLIB and/or JOBLIB DD cards for the appropriate order of library concatenation.
The JCL necessary to execute the application program can then be changed from a batch TSO job step executing DSN to one which directly executes the application program.
BATCHCAF — Explicit attachment API
Using the BATCHCAF Call Attach Facility, the application program has the ability to invoke any DB2 CAF function by making explicit CALLs to DSNHLI passing as the first parameter the address of a fullword (PIC S9(8) COMP) containing high-values (X'FFFFFFFF'). This ability allows a single application to switch plans or DB2 subsystems in the same run. Member QSISPDB2 of SAMPLIB contains an example of using this facility.
Related topic