IDENTIFY function for RRSAF
The RRSAF IDENTIFY function initializes a connection to Db2.
The IDENTIFY function establishes the caller's task as a user of Db2 services. If no other task in the address space currently is connected to the specified subsystem, the IDENTIFY function also initializes the address space to communicate with the Db2 address spaces. The IDENTIFY function establishes the cross-memory authorization of the address space to Db2 and builds address space control blocks.
The following diagram shows the syntax for the IDENTIFY function.
Parameters point to the following areas:
- function
- An 18-byte area that contains IDENTIFY followed by 10 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.
- ribptr
- A 4-byte area in which RRSAF places the address of the release
information block (RIB) after the call. You can use the RIB to determine
the release level of the Db2 subsystem
to which the application is connected. 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 ssnm names 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.
This parameter is required. However, the application does not need to refer to the returned information.
- eibptr
- A 4-byte area in which RRSAF places the address of the environment information block (EIB) after
the call. The EIB contains environment
information, such as the data sharing group, the name of the Db2 member to which the IDENTIFY request was issued, and whether new functions are activated
in the subsystem. If the Db2 subsystem is not in a data sharing group, RRSAF sets the data
sharing group and member names to blanks. If the EIB is not available (for example, if
ssnm names a subsystem that does not exist), RRSAF sets the 4-byte area to
zeros.
The area to which eibptr points is above the 16-MB line.
This parameter is required. However, the application does not need to refer to the returned information.
- termecb
- The address of the application's event control block (ECB) that
is used for Db2 termination. Db2 posts this ECB when the system
operator enters the STOP DB2 command
or when Db2 is terminating abnormally.
Specify a value of 0 if you do not want to use a termination ECB.
The ECB is ignored when Db2 is already stopped. The application program must examine any nonzero RRSAF or Db2 reason codes before issuing a WAIT request on this ECB.
RRSAF puts a POST code in the ECB to indicate the type of termination as shown in the following table.Table 1. Post codes for types of Db2 termination POST code Termination type 8 QUIESCE 12 FORCE 16 ABTERM - startecb
- The address of the application's startup ECB. If Db2 has not started when the application issues the
IDENTIFY call, Db2 posts the ECB when
Db2 has started. If Db2 is already started, the startup ECB is ignored. and is not applied to the next Db2 startup. If Db2 is not started, and the startup ECB is queued,
the termination ECB is ignored.
Enter a value of zero if you do not want to use a startup ECB. Db2 posts no more than one startup ECB per address space. The ECB that is posted is associated with the most recent IDENTIFY call from that address space. The application program must examine any nonzero RRSAF or Db2 reason codes before issuing a WAIT request on this ECB.
- retcode
- A 4-byte area in which RRSAF places the return code.
This parameter is optional. If you do not specify retcode, RRSAF places the return code in register 15 and the reason code in register 0.
- reascode
- A 4-byte area in which RRSAF places a reason code.
This parameter is optional. If you do not specify reascode, RRSAF places the reason code in register 0.
If you specify reascode, you must also specify retcode or its default. You can specify a default for retcode by specifying a comma or zero, depending on the language.
- 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 the retcode and reascode parameters. In assembler language, you can omit the retcode and reascode parameters by specifying commas as place-holders.
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 RRSAF is to put the address of the DSNHDECP or a 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 is above the 16-MB line.
If you specify this parameter in any language except assembler, you must also specify the retcode, reascode, and groupoverride parameters. In assembler language, you can omit the retcode, reascode, and groupoverride parameters by specifying commas as placeholders.
Example of RRSAF IDENTIFY function calls
The following table shows an IDENTIFY call in each language.
| Language | Call example |
|---|---|
| Assembler | |
| C1 | |
| COBOL | |
| Fortran | |
| PL/I1 | |
- For C, C++, and PL/I applications, you must include the appropriate compiler directives, because DSNRLI is an assembler language program. These compiler directives are described in the instructions for invoking RRSAF.
Internal processing for the IDENTIFY function
When you call the IDENTIFY function, Db2 performs the following steps:
- Db2 determines whether the
user address space is authorized to connect to Db2. Db2 invokes
the z/OS® SAF and passes a primary
authorization ID to SAF. That authorization ID is the 7-byte user
ID that is associated with the address space, unless an authorized
function has built an ACEE for the address space. If an authorized
function has built an ACEE, Db2 passes
the 8-byte user ID from the ACEE. SAF calls an external security product,
such as RACF®, to determine
if the task is authorized to use the following items:
- The Db2 resource class (CLASS=DSNR)
- The Db2 subsystem (SUBSYS=ssnm)
- Connection type RRSAF
- If that check is successful, Db2 calls the Db2 connection exit routine to perform additional verification and possibly change the authorization ID.
- Db2 searches for a matching
trusted context in the system cache and then the catalog based on
the following criteria:
- The primary authorization ID matches a trusted context SYSTEM AUTHID.
- The job or started task name matches the JOBNAME attribute that is defined for the identified trusted context.
If a trusted context is defined, Db2 checks if SECURITY LABEL is defined in the trusted context. If SECURITY LABEL is defined, Db2 verifies the SECURITY LABEL with RACF by using the RACROUTE VERIFY request. This security label is used to verify multi-level security for SYSTEM AUTHID.
If a matching trusted context is defined, Db2 establishes the connection as trusted. Otherwise, the connection is established without any additional privileges. - Db2 then sets the connection name to RRSAF and the connection type to RRSAF.