CONTEXT SIGNON function for RRSAF

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

Requirement: Before you invoke CONTEXT SIGNON, you must have called the RRS context services function Set Context Data (CTXSDTA) to store a primary authorization ID and optionally, the address of an ACEE in the context data whose context key you supply as input to CONTEXT SIGNON.

The CONTEXT SIGNON function uses the context key to retrieve the primary authorization ID from data that is associated with the current RRS context. Db2 uses the RRS context services function Retrieve Context Data (CTXRDTA) to retrieve context data that contains the authorization ID and ACEE address. The context data must have the following format:

Version number: A 4-byte area that contains the version number of the context data. Set this area to 1.
Server product name: An 8-byte area that contains the name of the server product that set the context data.
ALET: A 4-byte area that can contain an ALET value. Db2 does not reference this area.
ACEE address: A 4-byte area that contains an ACEE address or 0 if an ACEE is not provided. Db2 requires that the ACEE is in the home address space of the task.
If you pass an ACEE address, the CONTEXT SIGNON function uses the value in ACEEGRPN as the secondary authorization ID if the length of the group name (ACEEGRPL) is not 0.
primary-authid: An 8-byte area that contains the primary authorization ID to be used. If the authorization ID is less than 8 bytes in length, pad it on the right with blank characters to a length of 8 bytes.
If the new primary authorization ID is not different than the current primary authorization ID (which was established when the IDENTIFY function was invoked or at a previous SIGNON invocation), Db2 invokes only the signon exit. If the value has changed, Db2 establishes a new primary authorization ID and new SQL authorization ID and then invokes the signon exit.

Generally, you issue a CONTEXT SIGNON call after an IDENTIFY call and before a CREATE THREAD call. You can also issue a CONTEXT 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), a SIGNON call is permitted only if the primary authorization ID has not changed.

The following diagram shows the syntax for the CONTEXT SIGNON function.

DSNRLI CONTEXT SIGNON function

Parameters point to the following areas:

function

An 18-byte area that contains CONTEXT SIGNON followed by four 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, AUTH 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.

context-key

A 32-byte area in which you put the context key that you specified when you called the RRS Set Context Data (CTXSDTA) service to save the primary authorization ID and an optional ACEE address.

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 reascode, 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 parameter 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.

You can also change the value of the workstation name with the RRSAF functions SIGNON, AUTH SIGNON, or SET_CLIENT_ID. You can retrieve the workstation name with the 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 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 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.

Example of RRSAF CONTEXT SIGNON calls

The following table shows a CONTEXT SIGNON call in each language.

Table 1. Examples of RRSAF CONTEXT SIGNON calls
Language	Call example
Assembler	`CALL DSNRLI,(CSGNONFN,CORRID,ACCTTKN,ACCTINT,CTXTKEY, RETCODE,REASCODE,USERID,APPLNAME, WSNAME,XIDPTR)`
C¹	`fnret=dsnrli(&csgnonfn[0], &corrid[0], &accttkn[0], &acctint[0], &ctxtkey[0], &retcode, &reascode, &userid[0], &applname[0], &wsname[0], &xidptr);`
COBOL	`CALL 'DSNRLI' USING CSGNONFN CORRID ACCTTKN ACCTINT CTXTKEY RETCODE REASCODE USERID APPLNAME WSNAME XIDPTR.`
Fortran	`CALL DSNRLI(CSGNONFN,CORRID,ACCTTKN,ACCTINT,CTXTKEY, RETCODE,REASCODE, USERID,APPLNAME, WSNAME,XIDPTR)`
PL/I¹	`CALL DSNRLI(CSGNONFN,CORRID,ACCTTKN,ACCTINT,CTXTKEY, 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.