| With the CAF, your application program can establish and control its own connection to DB2. Programs that run in MVS batch, TSO foreground, and TSO background can use CAF. It is also possible for IMS batch applications to access DB2 databases through CAF, though that method does not coordinate the commitment of work between the IMS and DB2 systems. We highly recommend that you use the DB2 DL/I batch support for IMS batch applications. Capabilities Programs using CAF can -
Access DB2 from address spaces where there is no TSO, CICS, or IMS. -
Access the IFI. -
Access DB2 from multiple tasks within an address space. -
Control the connection to DB2 explicitly. -
Connect to DB2 implicitly using a default subsystem ID and plan name . -
Receive a signal from DB2 on startup or shutdown. Task Capabilities Any task in an address space can establish a connection to DB2 through CAF. There can be only one connection for each TCB. A DB2 service request issued by a program running under a given task is associated with that task's connection to DB2. The service request operates independently of any DB2 activity under any other task. Each connected task can run a plan. Multiple tasks in a single address space can specify the same plan, but each instance of a plan runs independently from the others. A task can terminate its plan and run a different plan without fully breaking its connection to DB2. CAF does not generate task structures, nor does it provide attention-processing exits or functional recovery routines. You can provide whatever attention-handling and functional recovery your application needs, but you must use extended specify task abend exit (ESTAE/ESTAI) type recovery routines. You cannot use enabled unlocked task (EUT) functional recovery routines(FRR) . Using multiple simultaneous connections can increase the possibility of deadlocks and DB2 resource contention . Your application design must consider that possibility. Program Preparation Preparing your application program to run in CAF is similar to preparing it to run in other environments, such as CICS, IMS, and TSO. You can prepare a CAF application either in the batch environment or by using the DB2 program preparation process. Restrictions Stored procedures that run in the DB2 Stored Procedure Address Space (SPAS) address space use the CAF implicitly. They should include the interface module in the link-edit step, but must not implement the calls to DSNALI. Requirements To connect to DB2 using CAF, the attachment language interface (DSNALI) module must either be linked into your load module or loaded dynamically. The first parameter passed to DSNALI is called the function. Table 14-3 lists the available functions. Table 14-3. Function Options for DSNALI | Function | Description | | CONNECT | Establishes the TCB as a user of the named DB2 subsystem. When the first task within an address space issues a connection request, the address space is also initialized as a user of DB2. | | OPEN | Allocates a DB2 plan. You must allocate a plan before DB2 can process SQL statements. If you did not request the CONNECT function, OPEN implicitly establishes the task, and optionally the address space, as a user of DB2. | | CLOSE | Optionally commits or abends any database changes and deallocates the plan. If OPEN implicitly requests the CONNECT function, CLOSE removes the task, and possibly the address space, as a user of DB2. | | DISCONNECT | Removes the task as a user of DB2 and, if this is the last or only task in the address space with a DB2 connection, terminates the address space connection to DB2. | | TRANSLATE | Returns a SQLCODE and printable text in the SQLCA that describes a DB2 hexadecimal error reason code. | Implicit Connections If you do not explicitly specify executable SQL statements in a CALL DSNALI statement of your CAF application, CAF initiates implicit CONNECT and OPEN requests to DB2. Although CAF performs these connection requests using the default values defined below, the requests are subject to the same DB2 return codes and reason codes as explicitly specified requests. Implicit connections use the following defaults: Subsystem name. The default subsystem name is specified in the module DSNHDECP. CAF uses the installation default DSNHDECP unless your own DSNHDECP is in a library in a STEPLIB of JOBLIB concatenation, or is in the link list. In a data-sharing group, the default subsystem name is the group attachment name. Plan name. The member name of the database request module (DBRM) that DB2 produced when you precompiled the source program that contains the first SQL call. If your program can make its first SQL call from different modules with different DBRMs, then you cannot use a default plan name; you must use an explicit call using the OPEN function. If your application includes both SQL and IFI calls, you must issue at least one SQL call before you issue any IFI calls. This ensures that your application uses the correct plan. There are different types of implicit connections. The simplest is for the application to run neither CONNECT nor OPEN. You can also use CONNECT only or OPEN only. Each of these implicitly connects your application to DB2. To terminate an implicit connection, you must use the proper calls. Your application program must successfully connect, either implicitly or explicitly, to DB2 before it can execute any SQL calls to the CAF DSNHLI entry point. Therefore, the application program must first determine the success or failure of all implicit connection requests. For implicit connection requests, register 15 contains the return code and register 0 contains the reason code. The return code and reason code are also in the message text for SQLCODE 991. The application program should examine the return and reason codes immediately after the first executable SQL statement within the application program. If the implicit connection was successful, the application can examine the SQLCODE for the first and subsequent SQL statements. Explicit Load of DSNALI To load DSNALI, issue MVS LOAD service requests for entry points DSNALI and DSNHLI2. If you use IFI services, you must also load DSNWLI2. The entry point addresses that LOAD returns are saved for later use with the CALL macro. By explicitly loading the DSNALI module, you beneficially isolate the maintenance of your application from future IBM service to the language interface. If the language interface changes, the change will probably not affect your load module. You must indicate to DB2 which entry point to use. You can do this in one of two ways: -
Specify the precompiler option ATTACH(CAF). This causes DB2 to generate calls that specify entry point DSNHLI2. You cannot use this option if your application is written in FORTRAN. -
Code a dummy entry point named DSNHLI within your load module. If you do not specify the precompiler option ATTACH, the DB2 precompiler generates calls to entry point DSNHLI for each SQL request. The precompiler does not know and is independent of the different DB2 attachment facilities. When the calls generated by the DB2 precompiler pass control to DSNHLI, your code corresponding to the dummy entry point must preserve the option list passed in register 1 and call DSNHLI2, specifying the same option list. Link-Editing DSNALI You can include the CAF language interface module DSNALI in your load module during a link-edit step. The module must be in a load module library, which is included either in the SYSLIB concatenation or another INCLUDE library defined in the linkage editor JCL. Because all language interface modules contain an entry point declaration for DSNHLI, the linkage editor JCL must contain an INCLUDE linkage editor control statement for DSNALI; for example, INCLUDE DB2LIB(DSNALI). By coding these options, you avoid inadvertently picking up the wrong language interface module. If you do not need explicit calls to DSNALI for CAF functions, including DSNALI in your load module has some advantages. When you include DSNALI during the link-edit, you need not code the previously described dummy DSNHLI entry point in your program or specify the precompiler option ATTACH. Module DSNALI contains an entry point for DSNHLI, which is identical to DSNHLI2, and an entry point DSNWLI, which is identical to DSNWLI2. A disadvantage to link-editing DSNALI into your load module is that any IBM service to DSNALI requires a new link-edit of your load module. Execution Programs that use CAF can be invoked from TSO as commands or via the CALL command from a CLIST or REXX program. They can also be executed directly from JCL on an EXEC statement. Units of Work DB2 manages the UOW for CAF programs. Use the SQL COMMIT and ROLLBACK statements as appropriate within your program. Program Characteristics Programs using the CAF have some specific characteristics. Initialization For implicit connections, programs need simply execute their SQL statements normally. It is a good idea to check the standard return code after the first call to detect attachment errors. To establish an explicit connection, first call DSNALI with the CONNECT function, then again with the OPEN function. SQL Processing SQL statements are embedded in CAF programs just as they are in programs that use any of the other attachment facilities. Error Checking Because CAF is a callable interface, you may need to check the standard return code value after an SQL statement and before checking the SQLCODE or SQLSTATE. Errors that occur in the attachment code will return a bad return code, leaving the contents of the SQLCA as they were prior to the call. This type of error is more likely to occur in a stored procedure that is not properly set up to run in the DSNSPAS address space. Termination To explicitly close a CAF connection, call DSNALI using the CLOSE function and again using the DISCONNECT function. Explicitly closing the connection is optional. If a connected task terminates normally before the CLOSE function deallocates the plan, then DB2 commits any database changes that the thread made since the last commit point. If a connected task abends before the CLOSE function deallocates the plan, then DB2 rolls back any database changes since the last commit point. In either case, DB2 deallocates the plan, if necessary, and terminates the task's connection before it allows the task to terminate. A tracing facility provides diagnostic messages that aid in debugging programs and diagnosing errors in the CAF code. In particular, attempts to use CAF incorrectly cause error messages in the trace stream. DB2 Abend If DB2 abends while an application is running, the application is rolled back to the last commit point. If DB2 terminates while processing a commit request, DB2 either commits or rolls back any changes at the next restart. The action taken depends on the state of the commit request when DB2 terminates. | 
