Invoking the call attachment facility

Invoke the call attachment facility (CAF) when you want your application program to establish and control its own connection to Db2. Applications that use CAF can explicitly control the state of their connections to Db2 by using connection functions that CAF supplies.

Before you begin

Before you can invoke CAF, perform the following actions:
  • Ensure that the CAF language interface (DSNALI) is available.
  • Ensure that your application satisfies the requirements for programs that access CAF.
  • Ensure that your application satisfies the general environment characteristics for connecting to Db2.
  • Ensure that you are familiar with the following z/OS® concepts and facilities:
    • The CALL macro and standard module linkage conventions
    • Program addressing and residency options (AMODE and RMODE)
    • Creating and controlling tasks; multitasking
    • Functional recovery facilities such as ESTAE, ESTAI, and FRRs
    • Asynchronous events and TSO attention exits (STAX)
    • Synchronization techniques such as WAIT/POST.

About this task

Applications that use CAF can be written in assembler language, C, COBOL, Fortran, and PL/I. When choosing a language to code your application in, consider the following restrictions:
  • If you need to use z/OS macros (ATTACH, WAIT, POST, and so on), use a programming language that supports them or embed them in modules that are written in assembler language.
  • The CAF TRANSLATE function is not available in Fortran. To use this function, code it in a routine that is written in another language, and then call that routine from Fortran.
Recommendations: For IMS and DSN applications, consider the following recommendations:
  • For IMS batch applications, do not use CAF. Instead use the Db2 DL/I batch support. Although it is possible for IMS batch applications to access Db2 databases through CAF, that method does not coordinate the commitment of work between the IMS and Db2 systems.
  • For DSN applications, do not use CAF unless you provide an application controller to manage the DSN application and replace any needed DSN functions. You might also have to change the application to communicate connection failures to the controller correctly. Running DSN applications with CAF is not advantageous, and the loss of DSN services can affect how well your program runs.

Procedure

To invoke CAF:

Perform one of the following actions:
  • Explicitly invoke CAF by including in your program CALL DSNALI statements with the appropriate options.

    The first option is a CAF connection function, which describes the action that you want CAF to take. The effect of any function depends in part on what functions the program has already run.

    Requirement: For C and PL/I applications, you must also include in your program the compiler directives that are listed in the following table, because DSNALI is an assembler language program.
    Table 1. Compiler directives to include in C and PL/I applications that contain CALL DSNALI statements
    Language Compiler directive to include
    C 
    #pragma linkage(dsnali, OS)
    C++ 
    extern "OS" {
        int DSNALI(
           char * functn,
             ...); }
    PL/I 
    DCL DSNALI ENTRY OPTIONS(ASM,INTER,RETCODE;
  • Implicitly invoke CAF by including SQL statements or IFI calls in your program just as you would in any program. The CAF facility establishes the connections to Db2 with the default values for the subsystem name and plan name.
    Restriction: If your program can make its first SQL call from different modules with different DBRMs, you cannot use a default plan name and thus, you cannot implicitly invoke CAF. Instead, you must explicitly invoke CAF by using the OPEN function.
    Requirement: If your application includes both SQL and IFI calls, you must issue at least one SQL call before you issue any IFI calls. This action ensures that your application uses the correct plan.

    Although doing so is not recommended, you can run existing DSN applications with CAF by allowing them to make implicit connections to Db2. For Db2 to make an implicit connection successfully, the plan name for the application must be the same as the member name of the database request module (DBRM) that Db2 produced when you precompiled the source program that contains the first SQL call. You must also substitute the DSNALI language interface module for the TSO language interface module, DSNELI.

If you do not specify the return code and reason code parameters in your CAF calls or you invoked CAF implicitly, CAF puts a return code in register 15 and a reason code in register 0.
To determine if an implicit connection was successful, the application program should examine the return and reason codes immediately after the first executable SQL statement in the application program by performing one of the following actions:
  • Examining registers 0 and 15 directly.
  • Examining the SQLCA, and if the SQLCODE is -991, obtain the return and reason code from the message text. The return code is the first token, and the reason code is the second token.
If the implicit connection was successful, the application can examine the SQLCODE for the first, and subsequent, SQL statements.

Examples

Example of a CAF configuration
The following figure shows an conceptual example of invoking and using CAF. The application contains statements to load DSNALI, DSNHLI2, and DSNWLI2. The application accesses Db2 by using the CAF Language Interface. It calls DSNALI to handle CAF requests, DSNWLI to handle IFI calls, and DSNHLI to handle SQL calls.
Begin figure summary.The diagram shows the relationship between the application, CAF, and DB2.Detailed description available.
Sample programs that use CAF
You can find a sample assembler program (DSN8CA) and a sample COBOL program (DSN8CC) that use the CAF in library prefix.SDSNSAMP. A PL/I application (DSN8SPM) calls DSN8CA, and a COBOL application (DSN8SCM) calls DSN8CC.