SIGNON function for RRSAF

The RRSAF SIGNON function establishes a primary authorization ID and, optionally, one or more secondary authorization IDs for a connection.

Requirement: Your program does not need to be an authorized program to issue the SIGNON call. For that reason, before you issue the SIGNON call, you must issue the RACF® external security interface macro RACROUTE REQUEST=VERIFY to perform the following actions:

Define and populate an ACEE to identify the user of the program.
Associate the ACEE with the user's TCB.
Verify that the user is defined to RACF and authorized to use the application.

Generally, you issue a SIGNON call after an IDENTIFY call and before a CREATE THREAD call. You can also issue a SIGNON call if the application is at a point of consistency, and one of the following conditions is true:

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), you can issue a SIGNON call only if the primary authorization ID has not changed.

After you issue a SIGNON call, subsequent SQL statements return an error (SQLCODE -900) if the both of following conditions are true:

The connection was established as trusted when it was initialized.
The primary authorization ID that was used when you issued the SIGNON call is not allowed to use the trusted connection.

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.

The following diagram shows the syntax for the SIGNON function.

DSNRLI SIGNON function

more-parameters

long-user

long-appl

long-ws

long-correlation

Parameters point to the following areas:

function

An 18-byte area that contains SIGNON followed by twelve 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 the 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.

Alternatively, you change the value of the Db2 accounting token with RRSAF functions AUTH 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 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.

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 this parameter, 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 user, 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 appl, 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 field is optional. If you specify ws, you must also specify retcode, reascode, user, and appl. If you do not specify ws, no workstation name is associated with the connection.

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 in 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 following table shows the format of a global transaction ID.

Table 1. Format of a user-created global transaction ID
Field description	Length in bytes	Data type
Format ID	4	Integer
Global transaction ID length (1–64)	4	Integer
Branch qualifier length (1–64)	4	Integer
Global transaction ID	1 to 64	Character
Branch qualifier	0 to 64	Character

accounting-string

A one-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 accounting-string, you must also specify retcode, reascode, user, appl and xid. If you do not specify accounting-string, 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.

trc-parent-len, trc-parent

A pair of parameters that consist of a 2-byte integer length and string area, which together represent the OpenTelemetry (OTel) trace parent value that Db2 associates with this thread. A comma separates the parameters. The trc-parent value must be in a valid W3C format and EBCDIC encoding.

These parameters are optional. To specify them you must also specify values for all prior positional parameters. A value of 0 in trc-parent-len, skips processing of trc-parent, and Db2 removes the trace parent value associated with this thread.

trc-state-len, trc-state

A pair of parameters that consist of a 2-byte integer length and string area, which together represent the OTel trace state value that Db2 associates with this thread. A comma separates the parameters. The trc-state value must be in a valid W3C format and EBCDIC encoding.

These parameters are optional. To specify them, you must also specify values for all prior positional parameters. In addition, a non-zero trc-state-len value requires that a valid, non-zero traceparent is also specified. A value of 0 in trc-state-len, skips processing of trc-state, and Db2 removes the trace state value associated with this thread.

baggage-len, baggage

A pair of parameters that consist of a 2-byte integer length and string area, which together represent the OTel trace baggage value that Db2 associates with this thread. A comma separates the parameters. The baggage value must be in a valid W3C format and EBCDIC encoding.

These parameters are optional. To specify them, you must also specify values for all of the prior positional parameters. In addition, a non-zero baggage-len value requires that a valid, non-zero traceparent is also specified. A value of 0 in baggage-len, skips processing of baggage, and Db2 removes the baggage value associated with this thread.

Example of RRSAF SIGNON calls

The following table shows a SIGNON call in each language.

Table 2. Examples of RRSAF SIGNON calls
Language	Call example
assembler	`CALL DSNRLI,(SGNONFN,CORRID,ACCTTKN,ACCTINT, RETCODE,REASCODE,USERID,APPLNAME,WSNAME,XIDPTR)`
C¹	`fnret=dsnrli(&sgnonfn[0], &corrid[0], &accttkn[0], &acctint[0], &retcode, &reascode, &userid[0], &applname[0], &wsname[0], &xidptr);`
COBOL	`CALL 'DSNRLI' USING SGNONFN CORRID ACCTTKN ACCTINT RETCODE REASCODE USERID APPLNAME WSNAME XIDPTR.`
Fortran	`CALL DSNRLI(SGNONFN,CORRID,ACCTTKN,ACCTINT, RETCODE,REASCODE,USERID,APPLNAME,WSNAME,XIDPTR)`
PL/I¹	`CALL DSNRLI(SGNONFN,CORRID,ACCTTKN,ACCTINT, RETCODE,REASCODE,USERID,APPLNAME,WSNAME,XIDPTR);`

Note:

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 a SIGNON call in C ¹ 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(&sgnonfn[0],&corrid[0],&accttkn[0],&acctint[0],&retcode,&reascode, 
&userid[0],&applname[0],&wsname[0],&xidptr,&lacctngid[0],
&useridlen,&luserid[0],&applidlen,&lapplid[0],&wsidlen,&lwsid[0],
&corrtkidlen,&lcorrtkid[0]);

Note:

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.