The Call Attachment Facility

Before a program can pass SQL statements to DB2, a connection known as a "thread" must be established between the task under which the program is running and the DB2 address space. In addition, a plan -- a DB2 object that indicates what kind of processing your program will do -- must be opened. DB2 provides several facilities for creating threads and opening plans. The facility employed by the DB2/SQL Service is the Call Attachment Facility (CAF).

The CAF is a general purpose facility that can be used to establish threads from nearly any MVS address space (IMS and CICS are special exceptions). The DB2/SQL Service of Shadow REXXTOOLS use the CAF in two ways. First, the CAF is called implicitly, whenever an SQL statement is executed and the SQL host command environment routines detect that a plan has not been opened. Second, you can explicitly call the CAF using the DSNALI function. Each of these methods are discussed in the sections that follow.

Implicit OPENs Using DSNALI

Implicit OPENs

The SQL host command environment routines always verify that a plan has been opened prior to processing an SQL statement. If no thread is detected on the current task, a thread is created using a default plan name and a default DB2 subsystem name. These defaults are established when Shadow REXXTOOLS is installed. For information regarding the default values on your system, contact your systems programmer or data base administrator.

Note: You may also dynamically modify the default plan and subsystem name using the OPTIONS statement.

Using DSNALI

You can explicitly control the DB2 subsystem to which your program is connected and the name of the plan to be opened, using the DSNALI function. An example OPEN call is shown in the program fragment that follows:

if dsnali("open", "dsna", "sdbr1010") <> 0 then do
  say "Open for plan failed. RC="rc "REASON="reason
  exit rc
end

In this example, the DB2 subsystem to be connected to is "DSNA" and the plan to be opened is the "SDBR1010" plan that is bound using the "repeatable read" isolation parameter.

DSNALI can also be used with the DB2INFO function to make your programs portable from one system to another. In the following example, DB2INFO is called to determine the name of the default DB2 subsystem (returned in $SWXDB2_SSID), which is then used in the DSNALI OPEN call:

call db2info "defaults"
if dsnali("open", $swxdb2_ssid, "sdbc1010") <> 0 then do
  say "Open for plan failed. RC="rc "REASON="reason
  exit rc
end

To close a plan and terminate an active thread, you use the CLOSE option of DSNALI, shown below:

if dsnali("close", "sync") <> 0 then do
  say "Close for plan failed. RC="rc "REASON="reason
  exit rc
end

The termination option "sync" ensures that DB2 will commit all changes before closing the plan.