AUTH SIGNON function for RRSAF
The RRSAF AUTH SIGNON function enables an APF authorization program to pass an ID to Db2.
An APF-authorized program can pass to Db2 either a primary authorization ID and, optionally, one or more secondary authorization IDs, or an ACEE that is used for authorization checking. These IDs are then associated with the connection.
- The value of reuse in the CREATE THREAD call was RESET.
- The value of reuse in the CREATE THREAD call was INITIAL, no held cursors are open, the package or plan is bound with KEEPDYNAMIC(NO), and all special registers are at their initial state. If open held cursors exist or the package or plan is bound with KEEPDYNAMIC(YES), a SIGNON call is permitted only if the primary authorization ID has not changed.
The following diagram shows the syntax for the AUTH SIGNON function.
- function
- An 18-byte area that contains AUTH SIGNON followed by seven blanks.
- correlation-id
- A 12-byte area in which you can put a Db2 correlation ID. The correlation ID is displayed in Db2 accounting and statistics trace records. You can use the correlation ID to correlate work units. This token appears in output from the DISPLAY THREAD command. If you do not want to specify a correlation ID, fill the 12-byte area with blanks.
- accounting-token
- A 22-byte area in which you can put a value for a Db2 accounting token. This value is displayed
in Db2 accounting and statistics
trace records in the QWHCTOKN field, which is mapped by DSNDQWHC DSECT.
Setting the value of the accounting token sets the value of the CURRENT
CLIENT_ACCTNG special register. If accounting-token is
less than 22 characters long, you must pad it on the right with blanks
to a length of 22 characters. If you do not want to specify an accounting
token, fill the 22-byte area with blanks.
You can also change the value of the Db2 accounting token with RRSAF functions SIGNON, CONTEXT SIGNON, or SET_CLIENT_ID. You can retrieve the Db2 accounting token with the CURRENT CLIENT_ACCTNG special register only if the DDF accounting string is not set.
- accounting-interval
- A 6-byte area with that specifies when Db2 writes an
accounting record.
If you specify COMMIT in that area, Db2 writes an accounting record each time that the application issues SRRCMIT. This accounting record is written at the end of the second phase of a two-phase commit. If the accounting interval is COMMIT, and an SRRCMIT is issued while a held cursor is open, the accounting interval spans that commit and ends at the next valid accounting interval end point (such as the next SRRCMIT that is issued without open held cursors, application termination, or SIGNON with a new authorization ID).
If you specify any other value, Db2 writes an accounting record when the application terminates or when you call the SIGNON function with a new authorization ID.
- primary-authid
- An 8-byte area in which you can put a primary authorization ID. If you are not passing the authorization ID to Db2 explicitly, put X'00' or a blank in the first byte of the area.
- ACEE-address
- The 4-byte address of an ACEE that you pass to Db2. If you do not want to provide an ACEE, specify 0 in this field.
If you use an external security product such as RACF for authorization control of Db2 objects, you must provide an ACEE for the primary authorization ID specified in the AUTH SIGNON.
- secondary-authid
- An 8-byte area in which you can put a secondary authorization ID. If you do not pass the authorization ID to Db2 explicitly, put X'00' or a blank in the first byte of the area. If you enter a secondary authorization ID, you must also enter a primary authorization ID.
- 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 the reason code.
This parameter is optional. If you do not specify reascode, RRSAF places the reason code in register 0.
If you specify reascoder, you must also specify retcode.
- user
- A 16-byte area that contains the user ID of the client user. You
can use this parameter to provide the identity of the client user
for accounting and monitoring purposes. Db2 displays
this user ID in the output from the DISPLAY THREAD command and in Db2 accounting and statistics trace
records. Setting the user ID sets the value of the CURRENT CLIENT_USERID
special register. If user is less than 16
characters long, you must pad it on the right with blanks to a length
of 16 characters.
This parameter is optional. If you specify user, you must also specify retcode and reascode. If you do not specify this parameter, no user ID is associated with the connection.
- appl
- A 32-byte area that contains the application or transaction name
of the user's application. You can use this parameter to provide the
identity of the client user for accounting and monitoring purposes. Db2 displays the application name
in the output from the DISPLAY THREAD command and in Db2 accounting and statistics trace records.
Setting the application name sets the value of the CURRENT CLIENT_APPLNAME
special register. If appl is less than 32
characters long, you must pad it on the right with blanks to a length
of 32 characters.
This parameter is optional. If you specify appl, you must also specify retcode, reascode, and user. If you do not specify this parameter, no application or transaction is associated with the connection.
- ws
- An 18-byte area that contains the workstation name of the client
user. You can use this parameter to provide the identity of the client
user for accounting and monitoring purposes. Db2 displays the workstation name in the output
from the DISPLAY THREAD command and in Db2 accounting
and statistics trace records. Setting the workstation name sets the
value of the CURRENT CLIENT_WRKSTNNAME special register. If ws is
less than 18 characters long, you must pad it on the right with blanks
to a length of 18 characters.
This parameter is optional. If you specify ws, you must also specify retcode, reascode, user, and appl. If you do not specify this parameter, no workstation name is associated with the connection.
You can also change the value of the workstation name with RRSAF functions SIGNON, CONTEXT SIGNON, or SET_CLIENT_ID. You can retrieve the workstation name with the CURRENT CLIENT_WRKSTNNAME special register.
- xid
- A 4-byte area that indicates whether the thread is part of a global
transaction. A Db2 thread that
is part of a global transaction can share locks with other Db2 threads that are part of the
same global transaction and can access and modify the same data. A
global transaction exists until one of the threads that is part of
the global transaction is committed or rolled back.
You can specify one of the following values for xid:
- 0
- Indicates that the thread is not part of a global transaction. The value 0 must be specified as a binary integer.
- 1
- Indicates that the thread is part of a global transaction and that Db2 should retrieve the global transaction ID from RRS. If a global transaction ID already exists for the task, the thread becomes part of the associated global transaction. Otherwise, RRS generates a new global transaction ID. The value 1 must be specified as a binary integer. Alternatively, if you want Db2 to return the generated global transaction ID to the caller, specify an address instead of 1.
- address
- The 4-byte address of an area into which you enter a global transaction
ID for the thread. If the global transaction ID already exists, the
thread becomes part of the associated global transaction. Otherwise,
RRS creates a new global transaction with the ID that you specify.
Alternatively, if you want Db2 to generate and return a global transaction ID, pass the address of a null global transaction ID by setting the format ID field of the global transaction ID to binary -1 ('FFFFFFF'X). Db2 then replaces the contents of the area with the generated transaction ID. The area at the specified address must be in writable storage and have a length of at least 140 bytes to accommodate the largest possible transaction ID value.
The format of a global transaction ID is shown in the description of the RRSAF SIGNON function.
- accounting-string
- A 1-byte length field and a 255-byte area in which you can put
a value for a Db2 accounting
string. This value is placed in the DDF accounting trace records in
the QMDASQLI field, which is mapped by DSNDQMDA DSECT. If accounting-string is
less than 255 characters, you must pad it on the right with zeros
to a length of 255 bytes. The entire 256 bytes is mapped by DSNDQMDA
DSECT.
This parameter is optional. If you specify this accounting-string, you must also specify retcode, reascode, user, appl, and xid. If you do not specify this parameter, no accounting string is associated with the connection.
You can also change the value of the accounting string with RRSAF functions AUTH SIGNON, CONTEXT SIGNON, or SET_CLIENT_ID.
You can retrieve the DDF suffix portion of the accounting string with the CURRENT CLIENT_ACCTNG special register. The suffix portion of accounting-string can contain a maximum of 200 characters. The QMDASFLN field contains the accounting suffix length, and the QMDASUFX field contains the accounting suffix value. If the DDF accounting string is set, you cannot query the accounting token with the CURRENT CLIENT_ACCTNG special register.
The following parameters are optional and positional. These parameters override values specified earlier in the parameter list. To provide a value for a length, value pair, you must provide a value or specify a 0 length for previous parameters in the parameter list.
- user-length, user-longname
- A pair of parameters that consist of a 2-byte integer length and
128-byte string area. A comma separates the parameters. You can provide
the user ID of the client user for accounting and monitoring purposes
in user-longname. Db2 displays this user ID in the output from
the DISPLAY THREAD command and in Db2 accounting
and statistics trace records. Setting the user ID sets the value of
the CURRENT CLIENT_USERID special register. Trailing blanks in user-longname are
truncated and the length in user-length is
updated.
These parameters are optional, to specify them you must also specify a value for accounting-string. A value of 0 in user-length skips processing of user-longname.
Important: These parameters override any value that is provided in user. - appl-length, appl-longname
- A pair of parameters that consist of a 2-byte integer length and
255-byte string area. A comma separates the parameters. You can provide
the application or transaction name of the client user for accounting
and monitoring purposes in appl-longname. Db2 displays this application name
in the output from the DISPLAY THREAD command and in Db2 accounting and statistics trace records.
Setting the application name sets the value of the CURRENT CLIENT_APPLNAME
special register. Trailing blanks in appl-longname are
truncated and the length in appl-length is
updated.
These parameters are optional, to specify them you must also specify a value for user-length, user-longname. A value of 0 in appl-length skips processing of appl-longname.
Important: These parameters override any value that is provided in appl. - ws-length, ws-longname
- A pair of parameters that consist of a 2-byte integer length and
255-byte string area. A comma separates the parameters. You can provide
the workstation name of the client user for accounting and monitoring
purposes in ws-longname. Db2 displays this workstation name in the output
from the DISPLAY THREAD command and in Db2 accounting
and statistics trace records. Setting the workstation name sets the
value of the CURRENT CLIENT_WRKSTNNAME special register. Trailing
blanks in ws-longname are truncated and
the length in ws-length is updated.
These parameters are optional, to specify them you must also specify a value for appl-length, appl-longname. A value of 0 in ws-length skips processing of ws-longname.
Important: These parameters override any value that is provided in ws. - correlation-length, correlation-longname
- A pair of parameters that consist of a 2-byte integer length and 255-byte string area. A comma separates the parameters. You can provide a unique value to correlate your business process names with Db2 threads in correlation-longname. Db2 displays this correlation token in the output
from the DISPLAY THREAD DETAIL command. The CURRENT CLIENT_CORR_TOKEN
special register contains the client correlation token. Trailing blanks
in correlation-longname are truncated and
the length in correlation-length is updated.
These parameters are optional, to specify them you must also specify a value for ws-length, ws-longname. A value of 0 in correlation-length skips processing of correlation-longname.
You can also change the value of the client correlation token with the RRSAF AUTH SIGNON function and the SET_CLIENT_ID function.
Example of RRSAF AUTH SIGNON calls
The following table shows a AUTH SIGNON 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.
The following example shows an AUTH SIGNON call in C 1 with all parameters passed in. Parameters that are numbers are passed in as integers and strings as character arrays. In this example, if &useridlen is larger than 0, then the value of CURRENT CLIENT_USERID special register is the value that is stored in &luserid[0].
fnret = dsnrli(&authsgnfn[0],&corrid[0],&acctkn[0],&accint[0],&pauthid[0],
&aceeptr,&sauthid[0],&retcode,&reascode,&userid[0],&applname[0],
&wsname[0],&xidptr,&lacctngid[0],&useridlen,&luserid[0],&applidlen,
&lapplid[0],&wsidlen,&lwsid[0],&corrtkidlen,&lcorrtkid[0]);- For C 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.