CLOSE function for CAF

The CAF CLOSE function deallocates the plan that was created either explicitly by a call to the OPEN function or implicitly at the first SQL call. Optionally, the CLOSE function also disconnects the task, and possibly the address space, from Db2.

If you did not issue an explicit CONNECT call for the task, the CLOSE function deletes the task's connection to Db2. If no other task in the address space has an active connection to Db2, Db2 also deletes the control block structures that were created for the address space and removes the cross memory authorization.

Using the CLOSE function is optional. Consider the following rules and recommendations about when to use and not use the CLOSE function:

Do not use the CLOSE function when your current task does not have a plan allocated.
If you want to use a new plan, you must issue an explicit CLOSE call, followed by an OPEN call with the new plan name.
When shutting down your application you can improve the performance of this shut down by explicitly calling the CLOSE function before the task terminates. If you omit the CLOSE call, Db2 performs an implicit CLOSE. In this case, Db2 performs the same actions when your task terminates, by using the SYNC parameter if termination is normal and the ABRT parameter if termination is abnormal.
If Db2 terminates, issue an explicit CLOSE call for any task that did not issue a CONNECT call. This action enables CAF to reset its control blocks to allow for future connections. This CLOSE call returns the reset accomplished return code (+004) and reason code X'00C10824'. If you omit the CLOSE call in this case, when Db2 is back on line, the task's next connection request fails. You get either the message YOUR TCB DOES NOT HAVE A CONNECTION, with X'00F30018' in register 0, or the CAF error message DSNA201I or DSNA202I, depending on what your application tried to do. The task must then issue a CLOSE call before it can reconnect to Db2.
A task that issued an explicit CONNECT call should issue a DISCONNECT call instead of a CLOSE call. This action causes CAF to reset its control blocks when Db2 terminates.

The following diagram shows the syntax for the CLOSE function.

DSNALI CLOSE function

Parameters point to the following areas:

function

A 12-byte area that contains the word CLOSE followed by seven blanks.

termop

A 4-byte terminate option, with one of the following values:

SYNC: Specifies that Db2 is to commit any modified data.
ABRT: Specifies that Db2 is to roll back data to the previous commit point.

retcode

A 4-byte area in which CAF is to place the return code.

This field is optional. If you do not specify retcode, CAF places the return code in register 15 and the reason code in register 0.

reascode

A 4-byte area in which CAF places a reason code.

This field is optional. If you do not specify reascode, CAF places the reason code in register 0. If you specify reascode, you must also specify retcode.

Examples of CAF CLOSE calls

The following table shows a CLOSE call in each language.

Table 1. Examples of CAF CLOSE calls
Language	Call example
Assembler	`CALL DSNALI,(FUNCTN,TERMOP,RETCODE, REASCODE)`
C¹	`fnret=dsnali(&functn[0], &termop[0], &retcode,&reascode);`
COBOL	`CALL 'DSNALI' USING FUNCTN TERMOP RETCODE REASCODE.`
Fortran	`CALL DSNALI(FUNCTN,TERMOP, RETCODE,REASCODE)`
PL/I¹	`CALL DSNALI(FUNCTN,TERMOP, RETCODE,REASCODE);`

Note:

For C and PL/I applications, you must include the appropriate compiler directives, because DSNALI is an assembler language program. These compiler directives are described in the instructions for invoking CAF.