CIUSPTSR Stored Procedure

With the help of this CICS® IA External Interface, you can produce threadsafe reports directly from your application.

What is the CIUSPTSR Stored Procedure?

CIUSPTSR is a DB2® Stored Procedure that gathers threadsafe information for the specified programs. It queries the CICS IA interdependency database, gets all necessary data, and returns either a summary or detailed threadsafe information for the specified programs in a result set. It can be called from a user application with a SQL CALL statement.

Syntax

To call the CIUSPTSR procedure with a SQL CALL statement, use this syntax:
EXEC SQL 
CALL CIUSPTSR (ctype, collid, applid, qarg, cicslevel, rc, sqlcode, errmsg); 

Procedure parameters

There are several input parameters that manage the CIUSPTSR processing and several output parameters that inform about the process completion and errors, if any.

The following table lists all CIUSPTSR parameters.
Table 1. CIUSPTSR parameters
Parameter name input/output Type Description
ctype INPUT CHAR(4) Call type
collid INPUT CHAR(16) CICS IA collection identifier (COLLECTION_ID)
applid INPUT CHAR(8) CICS TS region APPLID
qarg INPUT VARCHAR(8) Query argument
cicslevel INPUT CHAR(4) Version of the CICS TS
rc OUTPUT INTEGER Return code
sqlcode OUTPUT INTEGER SQLCODE
errmsg OUTPUT VARCHAR(300) Error message text

CIUSPTSR INPUT parameters (ctype, collid, applid, qarg, cicslevel)

Table 2 describes the parameters and their matching values.
Table 2. Input parameters
Parameter Description and values
ctype Mandatory parameter.

The ctype parameter defines the type of the returned program threadsafe information, either summary or detailed, and the method which is used to gather this information, that is by specified program or by transaction.

Values:
PGMS
For a summary threadsafe information for the specified program.
TRNS
For a summary threadsafe information for the programs that are started by the specified transaction.
PGMD
For a detailed threadsafe information , a list of called commands, for the specified program.
collid Mandatory parameter.

The collection ID parameter specifies the CICS IA collection ID under which data was collected.

A wildcard mask, "%", is valid only for call types PGMS and TRNS.

applid Mandatory parameter.

The applid parameter specifies the CICS region in which the program or transaction to be reported on was running.

A wildcard mask, "%", is valid only for call types PGMS and TRNS.

qarg Mandatory parameter.

The query argument must specify either the program name or the transaction, depending on the specified ctype parameter.

Wildcard masks are not permissible.

cicslevel Optional parameter.

The cicslevel parameter defines the version of CICS TS to be used to determine the threadsafe status of the commands that are issued by the specified program.

Values:

null or blank
Produce a threadsafe report that is based on the threadsafe status of the commands of the CICS TS version of the region on which the specified program was run and collected.
3.1
Produce a threadsafe report that is based on the threadsafe status of the CICS TS 3.1 commands.
4.1
Produce a threadsafe report that is based on the threadsafe status of the CICS TS 4.1 commands.
4.2
Produce a threadsafe report that is based on the threadsafe status of the CICS TS 4.2 commands.
5.1
Produce a threadsafe report that is based on the threadsafe status of the CICS TS 5.1 commands.

CIUSPTSR OUTPUT parameters (rc, sqlcode, errmsg)

The rc parameter contains value of the CIUSPTSR return code. Possible rc values are listed in the following table.
Table 3. rc values
Return code Description
0 CIUSPTSR procedure that completed successfully.
4 CIUSPTSR procedure that completed successfully, but one or more SQL warning conditions were received.
8 CIUSPTSR procedure that failed because of a critical error that is caused by incorrect input parameter values.
12 CIUSPTSR procedure that failed because of a disastrous error that is caused by SQL Exception conditions during SQL statement execution.
The sqlcode parameter values depend on the return code and can be found in the following table.
Table 4. sqlcode values
Return code sqlcode value
0 0
4 Shows sqlcode for the last statement that caused the SQL warning condition.
8 0
12 Shows sqlcode of the failed SQL statement.
errmsg contains message text that describes the error or warning:
  • For rc=4, it contains the SQL message of the last SQL statement that caused the warning condition.
  • For rc=8, it provides the invalid parameter value that caused the error.
  • For rc=12, it provides SQL error message for the failed SQL statement.

Returned result sets

The CIUSPTSR stored procedure returns result sets. The number and structure of the result sets is dependent on the input parameters values. A result set is a set of rows that are associated with a cursor opened in the stored procedure and returned to caller program. A result set is effectively a table. You can access the data that is returned in a result set by running an SQL ASSOCIATE LOCATORS, followed by an SQL ALLOCATE cursor, and then the SQL FETCH loop as shown in the COBOL example for the CIUSPAPP stored procedure. The following information describes the result sets that are returned by the CIUSPTSR procedure.
List summary threadsafe information about specified program
To list summary threadsafe information about the specified program, you must set the input parameters as follows:
ctype     = 'PGMS'
collid    = collection ID
applid    = applid
qarg      = program name
cicslevel = CICS TS level
If you want to list summary threadsafe information for all existing collection IDs, set collid to %.
If you want to list summary threadsafe information for all existing applids, set applid to %.
If you want to list summary threadsafe information for all existing programs, set qarg to %
Set cicslevel either to a particular CICS TS version or set it to null to use the CICS TS version of the region on which the program was run and collected. Null is the default.
This call returns one result set with all columns of the CIU_THREADSAFE_SUMMARY global temporary table.
List summary threadsafe information about programs that are started by the specified transaction
To list summary threadsafe information about the programs that were started by the specified transaction, you must set the input parameters as follows:
ctype     = 'TRNS'
collid    = collection ID
applid    = APPLID
qarg      = program name
cicslevel = CICS TS level
If you want to list summary threadsafe information for all existing collection IDs, set collid to %.
If you want to list summary threadsafe information for all existing APPLIDs, set applid to %.
If you want to list summary threadsafe information for programs that were started under any of existing transaction set qarg to %.
Set cicslevel either to particular CICS TS version or set it to null to use CICS TS version of the region on which the program was run and collected. Null is the default.
This call returns one result set with all columns of the CIU_THREADSAFE_DETAIL global temporary table.
List detailed threadsafe information about specified program
To list detailed threadsafe information about the specified program, you must set the input parameters as follows:
ctype     = 'DTLD'
collid    = collection ID
applid    = APPLID
qarg      = program name
cicslevel = CICS TS level
Set COLLID to existing CICS IA resources collection ID. Set APPLID to existing CICS TS region APPLID.
Set QARG to existing collected program name.
Set CICSLEVEL either to particular CICS TS version or set it to null to use CICS TS version of the region on which the program was run and collected. Null is the default.
This call returns one result set with all columns of the CIU_THREADSAFE_DETAIL global temporary table.

Concept Concept

Feedback


Timestamp icon Last updated: Friday, 8 February 2013


http://pic.dhe.ibm.com/infocenter/cicsts/v5r1/topic//ciusptsr.html