Use of a REXX routine with the ADBTEP2 program

A REXX routine can provide statements to ADBTEP2 for processing.

You call a REXX routine from ADBTEP2:

REXX %<name> [parm];

To provide input to ADBTEP2, you use a functional comment before the syntax. The comment informs ADBTEP2 that the REXX routine is providing information for ADBTEP2 to process. You can provide input for the following functions:

User statements that are in a form that can be processed by ADBTEP2, for example SQL statements, Db2 commands, or DSN commands.
Iterative processing

You end the input statements with a semicolon (;).

You must issue DSNREXX DISCONNECT in the REXX routine before you can use any command that requires ADBTEP2 to connect to Db2.

You can provide information to ADBTEP2 through the user (USERINFO) and utility information (UTILINFO) functions. You can specify a tolerance threshold for utility errors. And you can allocate output from REXX-provided statements processed by ADBTEP2 to a USRPRINT file.

User input

The user input function enables the REXX routine to provide statements on the REXX data stack to ADBTEP2.

Use the following syntax:

--#GET INPUT FROM STACK
REXX %<name> [parms];

The return code from the REXX routine specifies the action that ADBTEP2 takes:

RC=0: Statements are present on the data stack. The REXX routine writes statements onto the data stack for ADBTEP2 to process. ADBTEP2 pulls the statements from the data stack and processes statements until all statements are processed or until an error occurs.
RC=4: No statements are present on the data stack.
RC<>0, RC<>4: An error occurred and ADBTEP2 is directed to end processing.

Iterative input

The iterative input function prompts ADBTEP2 to repeat invocation of a REXX routine.

The syntax is as follows:

--#GET INPUT FROM STACK WITH ITERATION
REXX %<name> [parms];

The return code from the REXX routine specifies the action that ADBTEP2 takes:

RC=0: Statements are present on the data stack. ADBTEP2 pulls the statements from the data stack and processes statements until all statements are processed or until an error occurs.
RC=4: No statements are present on the data stack.
Until RC=4: ADBTEP2 reinvokes the REXX routine to get more statements until the REXX routine ends with RC=4.
RC<>0, RC<>4: An error occurred and ADBTEP2 is directed to end processing.

User information

The user information function enables the REXX routine to provide information for iterative REXX calls. The user information function is for iterative input only.

The syntax that prompts ADBTEP2 to process a REXX statement is as follows:

USERINFO <string>;

The user information statement enables the REXX routine to identify the work that is passed to ADBTEP2. ADBTEP2 writes the statement back to the data stack when the REXX routine is invoked the next time, and only if the call is part of iterative input processing.

The following example shows how you can call a REXX routine that passes a USERINFO string to ADBTEP2 and directs ADBTEP2 to run statistics on a tablespace:

/* rexx */                                     
arg exitrc                                     
queue "USERINFO RUN RUNSTATS ON A TABLE SPACE;
queue "RUNSTATS TABLESPACE ADBDCHG.ADBSPF1", 
        "  INDEX",                             
        "   (",                                
        "    ALL",                             
        "   )",                                
        "  SHRLEVEL CHANGE;"                   
queue ""                                       
exit exitrc

Utility Information

The utility information function enables a REXX routine to provide utility identification information, through ADBTEP2, to Db2.

The syntax that prompts ADBTEP2 to receive utility identification information from a REXX routine and to pass the information to Db2 is as follows:

UTILINFO [SYSTEM<ssid>,][UID=<utility-id>],[UTPROC=<utproc-string>];

The UTILINFO statement must precede the utility statements to which they apply. Multiple parameters must be separated by a comma. The statement must end with a semi-colon (;).

When parameters are not provided in the REXX statement, the default action is for ADBTEP2 to use parameters that are passed to ADBTEP2:

SYSTEM: The value of the SSID() parameter that is passed to ADBTEP2 and then is passed to Db2
UID: The value of the WORKLIST() parameter that is passed to ADBTEP2 and then is passed to Db2
UTPROC: blank. Passes the supplied JCL procedure, if any, to Db2.

You can call a REXX routine that directs ADBTEP2 to pass Db2 utility parameters, SYSTEM and UID, to Db2. In the following example, the system name and utility ID are passed to ADBTEP2, and then ADBTEP2 runs the RUNSTATS utility:

/* rexx */                                                                             
arg exitrc                                                                              
queue "UTILINFO SYSTEM='DSNX',UID='VNDR2';"                                       
queue "RUNSTATS TABLESPACE ADBDCHG.ADBSPF1",                                           
        "  INDEX",                                                                    
        "   (",                                                                         
        "    ALL",                                                                       
        "   )",                                                                         
        "  SHRLEVEL CHANGE;"                                                              
queue ""                                       
exit 0

Tolerance threshold for Db2 utility command error return codes

The tolerance threshold enables you to specify the error return code number, for a Db2 utility command error, to be tolerated during the processing of REXX statements. When the specified threshold is exceeded, ADBTEP2 stops processing.

The syntax that specifies the return code of errors that are tolerated is as follows:

--#SET TOLUTILERR n

The value of n is the return code number and must be an integer between 4 to 32767. When processing iterative statements in a REXX routine, the REXX routine, that includes Db2 utility commands, iterates until a return code that is beyond the threshold is encountered or until ADPTEP2 completes execution.

The following example shows that you specify return code tolerance before you specify a user input statement:

--#SET TOLUTILERR 7                                
--#GET        INPUT    FROM STACK WITH ITERATION   
REXX T2IN2 0;

In the example, if the return code for a Db2 utility command error exceeds the value 7, ADPTEP2 stops processing.

User Print

The user print function enables you to send output from REXX statements processed by ADBTEP2 to a USRPRINT file.

A USRPRINT file contains output only from Db2. USRPRINT is processed only when a USRPRINT DD statement is provided.

To use USRPRINT, the following requirements must be met:

SYSPRINT and USRPRINT must be preallocated.
SYSPRINT must be allocated as a non-spool data set with the DISP option as MOD.
USRPRINT must use the same data set attributes except the DISP option.

Use SYSPRINT and USRPRINT DD statements in the JCL to allocate the data sets, as shown in the following example:

//SYSPRINT DD DSN=<your data set>,
//            DISP=(MOD,CATLG,CATLG),                                
//            SPACE=(TRK,(10,10,0)),LRECL=137,RECFM=VB,BLKSIZE=141   
//USRPRINT DD DSN=<your data set>,                                   
//            DISP=(NEW,CATLG,CATLG),                                
//            SPACE=(TRK,(10,10,0)),LRECL=137,RECFM=VB,BLKSIZE=141, 
//            VOL=SER=<volume name>