CONNECT function for CAF

The CAF CONNECT function initializes a connection to Db2. This function is different than the SQL CONNECT statement that accesses a remote location within Db2.

The CONNECT function establishes the caller's task as a user of Db2 services. If no other task in the address space currently holds a connection with the specified subsystem, the CONNECT function also initializes the address space for communication to the Db2 address spaces. The CONNECT function establishes the address space's cross memory authorization to Db2 and builds address space control blocks. You can issue a CONNECT request from any or all tasks in the address space, but the address space level is initialized only once when the first task connects.

Using the CONNECT function is optional. If you do not call the CONNECT function, make an implicit connection by calling neither the CONNECT function nor the OPEN function. In a program that does not contain the CONNECT or OPEN functions, when the first SQL statement is executed, the implicit connection is made to the default Db2 subsystem. The default Db2 subsystem name is the subsystem name that is specified by the SSID=xxxx parameter in installation job DSNTIJUA. Job DSNTIJUA assembles the Db2 data-only application defaults module.

If you do not call the CONNECT function, the first request from a task, either an OPEN request or an SQL or IFI call, causes CAF to issue an implicit CONNECT request. If a task is connected implicitly, the connection to Db2 is terminated either when you call the CLOSE function or when the task terminates.

Call the CONNECT function in all of the following situations:

You need to specify a particular subsystem name (ssnm) other than the default subsystem name.
You need the value of the CURRENT DEGREE special register to last as long as the connection (srdura).
You need to monitor the Db2 startup ECB (startecb), the Db2 termination ECB (termecb), or the Db2 release level.
You plan to have multiple tasks in the address space open and close plans or a single task in the address space open and close plans more than once.
Establishing task and address space level connections involves significant overhead. Using the CONNECT function to establish a task connection explicitly minimizes this overhead by ensuring that the connection to Db2 remains after the CLOSE function deallocates a plan. In this case, the connection terminates only when you use the DISCONNECT function or when the task terminates.

The CONNECT function also enables the caller to learn the following items:

That the operator has issued a STOP DB2 command. When this event occurs, Db2 posts the termination ECB, termecb. Your application can either wait on or just look at the ECB.
That Db2 is abnormally terminating. When this event occurs happens, Db2 posts the termination ECB, termecb.
That Db2 is available again after a connection attempt that failed because Db2 was down. Your application can either wait or look at the startup ECB, startecb. Db2 ignores this ECB if it was active at the time of the CONNECT request.
The current release level of Db2. To find this information, access the RIBREL field in the release information block (RIB). If RIBREL is '999', the actual version, release, and modification level of Db2 is indicated in the RIBRELX field and its subfields.

Restriction: Do not issue CONNECT requests from a TCB that already has an active Db2 connection.

Recommendation: Do not mix explicit CONNECT and OPEN requests with implicitly established connections in the same address space. Either explicitly specify which Db2 subsystem you want to use or allow all requests to use the default subsystem.

The following diagram shows the syntax for the CONNECT function.

DSNALI CONNECT function

Parameters point to the following areas:

function

A 12-byte area that contains CONNECT followed by five blanks.

ssnm

A 4-byte Db2 subsystem name or group attachment or subgroup attachment name (if used in a data sharing group) to which the connection is made.

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

termecb

A 4-byte integer representing the application's event control block (ECB) for Db2 termination. Db2 posts this ECB when the operator enters the STOP DB2 command or when Db2 is abnormally terminating. The ECB indicates the type of termination by a POST code, as shown in the following table:

Table 1. POST codes and related termination types
POST code	Termination type
8	QUIESCE
12	FORCE
16	ABTERM

Before you check termecb in your CAF application program, first check the return code and reason code from the CONNECT call to ensure that the call completed successfully.

startecb

A 4-byte integer representing the application's startup ECB. If Db2 has not yet started when the application issues the call, Db2 posts the ECB when it successfully completes its startup processing. Db2 posts at most one startup ECB per address space. The ECB is the one associated with the most recent CONNECT call from that address space. Your application program must examine any nonzero CAF and Db2 reason codes before issuing a WAIT on this ECB.

If ssnm is a group attachment or subgroup attachment name, the first Db2 subsystem that starts on the local z/OS® system and matches the specified group attachment name posts the ECB.

ribptr

A 4-byte area in which CAF places the address of the release information block (RIB) after the call. You can determine what release level of Db2 you are currently running by examining the RIBREL field. If RIBREL is '999', the actual version, release, and modification level of Db2 is indicated in the RIBRELX field and its subfields.You can determine the modification level within the release level by examining the RIBCNUMB and RIBCINFO fields. If the value in the RIBCNUMB field is greater than zero, check the RIBCINFO field for modification levels.

If the RIB is not available (for example, if you name a subsystem that does not exist), Db2 sets the 4-byte area to zeros.

The area to which ribptr points is below the 16-MB line.

Your program does not have to use the release information block, but it cannot omit the ribptr parameter.

Macro DSNDRIB maps the release information block (RIB). It can be found in prefix.SDSNMACS(DSNDRIB).

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.

srdura

A 10-byte area that contains the string 'SRDURA(CD)'. This field is optional. If you specify srdura, the value in the CURRENT DEGREE special register stays in effect from the time of the CONNECT call until the time of the DISCONNECT call. If you do not specify srdura, the value in the CURRENT DEGREE special register stays in effect from the time of the OPEN call until the time of the CLOSE call. 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.

eibptr

A 4-byte area in which CAF puts the address of the environment information block (EIB). The EIB contains information that you can use if you are connecting to a Db2 subsystem that is part of a data sharing group. For example, you can determine the name of the data sharing group, the member to which you are connecting, and whether new functions are activated on the subsystem. If the Db2 subsystem that you connect to is not part of a data sharing group, the fields in the EIB that are related to data sharing are blank. If the EIB is not available (for example, if you name a subsystem that does not exist), Db2 sets the 4-byte area to zeros.

The area to which eibptr points is above the 16-MB line.

You can omit this parameter when you make a CONNECT call.

If you specify this parameter in any language except assembler, you must also specify retcode, reascode, and srdura. In assembler language, you can omit retcode, reascode, and srdura by specifying commas as placeholders.

Macro DSNDEIB maps the EIB. It can be found in prefix.SDSNMACS(DSNDEIB).

groupoverride

An 8-byte area that the application provides. This parameter 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 groupoverride is not provided, ssnm is used as the group attachment or 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, reascode, srdura, and eibptr. In assembler language, you can omit retcode, reascode, srdura, and eibptr 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.

decpptr

A 4-byte area in which CAF is to put the address of the DSNHDECP control block or user-specified application defaults module that was loaded by subsystem ssnm when that subsystem was started. This 4-byte area is a 31-bit pointer. If ssnm is not found, the 4-byte area is set to 0.

The area to which decpptr points may be above the 16-MB line.

If you specify this parameter in any language except assembler, you must also specify the retcode, reascode, srdura, eibptr, and groupoverride parameters. In assembler language, you can omit the retcode, reascode, srdura, eibptr, and groupoverride parameters by specifying commas as placeholders.

Example of CAF CONNECT function calls

The following table shows a CONNECT call in each language.

Table 2. Examples of CAF CONNECT function calls
Language	Call example
Assembler	`CALL DSNALI,(FUNCTN,SSID,TERMECB,STARTECB,RIBPTR,RETCODE,REASCODE,SRDURA, EIBPTR, GRPOVER)`
C¹	`fnret=dsnali(&functn[0],&ssid[0], &tecb, &secb,&ribptr,&retcode, &reascode, &srdura[0], &eibptr, &grpover[0]);`
COBOL	`CALL 'DSNALI' USING FUNCTN SSID TERMECB STARTECB RIBPTR RETCODE REASCODE SRDURA EIBPTR GRPOVER.`
Fortran	`CALL DSNALI(FUNCTN,SSID,TERMECB,STARTECB,RIBPTR,RETCODE,REASCODE,SRDURA, EIBPTR,GRPOVER)`
PL/I¹	`CALL DSNALI(FUNCTN,SSID,TERMECB,STARTECB,RIBPTR,RETCODE,REASCODE,SRDURA, EIBPTR,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.