OPEN function for CAF

The OPEN function allocates Db2 resources that are needed to run the specified plan or to issue IFI requests. If the requesting task does not already have a connection to the named Db2 subsystem, the OPEN function establishes it.

Using the OPEN function is optional. If you do not call the OPEN function, the actions that the OPEN function perform occur implicitly on the first SQL or IFI call from the task.

Restriction: Do not use the OPEN function if the task already has a plan allocated.

The following diagram shows the syntax for the OPEN function.

DSNALI OPEN function

Read syntax diagramSkip visual syntax diagramCALL DSNALI(function, ssnm, plan,retcode,reascode,groupoverride,queue)
Parameters point to the following areas:
function
A 12-byte area that contains the word OPEN followed by eight blanks.
ssnm
A 4-byte Db2 subsystem name or group attachment or subgroup attachment name (if used in a data sharing group). The OPEN function allocates the specified plan to this Db2 subsystem. Also, if the requesting task does not already have a connection to the named Db2 subsystem, the OPEN function establishes it.

You must specify the ssnm parameter, even if the requesting task also issues a CONNECT call. If a task issues a CONNECT call followed by an OPEN call, the subsystem names for both calls must be the same.

If ssnm is less than four characters long, pad it on the right with blanks to a length of four characters.

plan
An 8-byte Db2 plan name.
retcode
A 4-byte area in which CAF places 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.

groupoverride
An 8-byte area that the application provides. This field is optional. If you do not want group attach to be attempted, specify 'NOGROUP'. This string indicates that the subsystem name that is specified by ssnm is to be used as a Db2 subsystem name, even if ssnm matches a group attachment or subgroup attachment name. If you do not specify groupoverride, ssnm is used as the group attachment and subgroup attachment name if it matches a group attachment or subgroup attachment name. If you specify this parameter in any language except assembler, you must also specify retcode and reascode. In assembler language, you can omit these parameters by specifying commas as placeholders.
Recommendation: Avoid using the groupoverride parameter when possible, because it limits the ability to do dynamic workload routing in a Parallel Sysplex®. However, you should use this parameter in a data sharing environment when you want to connect to a specific member of a data sharing group, and the subsystem name of that member is the same as the group attachment or subgroup attachment name.
Start of changequeueEnd of change
Start of changeAn 8-byte area that contains the string 'NOQUEUE'. This field is optional. Calling the CAF OPEN function results in a request for a Db2 thread to be created. If the create thread request would exceed the maximum number of allied threads that are to be allocated concurrently as specified by the CTHREAD subsystem parameter, the create thread request is queued. When 'NOQUEUE' is specified, the create thread request is rejected with return code 8 and reason code 00F3005A returned to the calling application.End of change

Examples of CAF OPEN calls

The following table shows an OPEN call in each language.

Table 1. Examples of CAF OPEN calls
Language Call example
Assembler 
CALL  DSNALI,(FUNCTN,SSID,PLANNAME, RETCODE,REASCODE,GRPOVER)
C1 
fnret=dsnali(&functn[0],&ssid[0], &planname[0],&retcode, &reascode,&grpover[0]);
COBOL 
CALL  'DSNALI' USING FUNCTN SSID PLANNAME RETCODE REASCODE GRPOVER.
Fortran 
CALL  DSNALI(FUNCTN,SSID,PLANNAME, RETCODE,REASCODE,GRPOVER)
PL/I1 
CALL  DSNALI(FUNCTN,SSID,PLANNAME, RETCODE,REASCODE,GRPOVER);
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.