CREATE THREAD function for RRSAF

The RRSAF CREATE THREAD function allocates the Db2 resources that are required for an application to issue SQL or IFI requests. This function must complete before the application can execute SQL statements or IFI requests.

The following diagram shows the syntax of the CREATE THREAD function.

DSNRLI CREATE THREAD function

Parameters point to the following areas:

function

An 18-byte area that contains CREATE THREAD followed by five blanks.

plan

An 8-byte Db2 plan name. RRSAF allocates the named plan.

If you provide a collection name instead of a plan name, specify the question mark character (?) in the first byte of this field. Db2 then allocates a special plan named ?RRSAF and uses the value that you specify for collection . When Db2 allocates a plan named ?RRSAF, Db2 checks authorization to execute the package in the same way as it checks authorization to execute a package from a requester other than Db2 for z/OS®.

If you do not provide a collection name in the collection field, you must enter a valid plan name in this field.

collection

An 18-byte area in which you enter a collection name. Db2 uses the collection names to locate a package that is associated with the first SQL statement in the program.

When you provide a collection name and put the question mark character (?) in the plan field, Db2 allocates a plan named ?RRSAF and a package list that contains the following two entries:

The specified collection name.
An entry that contains * for the location, collection name, and package name. (This entry lets the application access remote locations and access packages in collections other than the default collection that is specified at create thread time.)

The application can use the SET CURRENT PACKAGESET statement to change the collection ID that Db2 uses to locate a package.

If you provide a plan name in the plan field, Db2 ignores the value in the collection field.

reuse

An 8-byte area that controls the action that Db2 takes if a SIGNON call is issued after a CREATE THREAD call. Specify one of the following values in this field:

RESET: Releases any held cursors and reinitializes the special registers
INITIAL: Does not allow the SIGNON call

This parameter is required. If the 8-byte area does not contain either RESET or INITIAL, the default value is INITIAL.

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.

pklistptr

A 4-byte field that contains a pointer to a user-supplied data area that contains a list of collection IDs. A collection ID is an SQL identifier of 1 to 128 letters, digits, or the underscore character that identifies a collection of packages. The length of the data area is a maximum of 2050 bytes. The data area contains a 2-byte length field, followed by up to 2048 bytes of collection ID entries, separated by commas.

When you specify pklistptr and the question mark character (?) in the plan field, Db2 allocates a special plan named ?RRSAF and a package list that contains the following entries:

The collection names that you specify in the data area to which pklistptr points
An entry that contains * for the location, collection ID, and package name

If you also specify collection, Db2 ignores that value.

Each collection entry must be of the form collection-ID.*, *.collection-ID.*, or *.*.*. collection-ID and must follow the naming conventions for a collection ID, as described in the description of the BIND and REBIND options.

Db2 uses the collection names to locate a package that is associated with the first SQL statement in the program. The entry that contains *.*.* lets the application access remote locations and access packages in collections other than the default collection that is specified at create thread time.

The application can use the SET CURRENT PACKAGESET statement to change the collection ID that Db2 uses to locate a package.

This parameter is optional. If you specify this parameter, you must also specify retcode and reascode.

If you provide a plan name in the plan field, Db2 ignores the pklistptr value.

Recommendation: Using a package list can have a negative impact on performance. For better performance, specify a short package list.

Example of RRSAF CREATE THREAD calls

The following table shows a CREATE THREAD call in each language.

Table 1. Examples of RRSAF CREATE THREAD calls
Language	Call example
Assembler	`CALL DSNRLI,(CRTHRDFN,PLAN,COLLID,REUSE,RETCODE,REASCODE,PKLISTPTR)`
C¹	`fnret=dsnrli(&crthrdfn[0], &plan[0], &collid[0], &reuse[0], &retcode, &reascode, &pklistptr);`
COBOL	`CALL 'DSNRLI' USING CRTHRDFN PLAN COLLID REUSE RETCODE REASCODE PKLSTPTR.`
Fortran	`CALL DSNRLI(CRTHRDFN,PLAN,COLLID,REUSE,RETCODE,REASCODE,PKLSTPTR)`
PL/I¹	`CALL DSNRLI(CRTHRDFN,PLAN,COLLID,REUSE,RETCODE,REASCODE,PKLSTPTR);`

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.