Starting a Session With Batch JCL (COBOL User Guide)

This section discusses how to manually change your execution JCL to invoke a Code Debug TSO debugging session in unattended or interactive (Batch Connect) batch modes. No file allocation utility is required, and you can even use your production JCL for IMS/DB, BTS, and Db2 programs.

To debug your program with Code Debug TSO in unattended or interactive batch, follow the steps listed as follows:

Retrieve your standard TSO program execution JCL.
Follow the instructions in member BATCHTSO from the SLXTSAMP data set, and make the appropriate changes to the JCL.
Submit the job. If you are running unattended batch, the test results will be saved in the XPOUT file. If you are using interactive batch, you must connect to the job to complete testing.

The panel displayed in following figure shows JCL that runs a simple job without Code Debug TSO. JCL to Run a Program With Code Debug TSO is an example of the JCL after it is modified to run with Code Debug TSO. For this simple example, the session log, script, and document data sets are printed, then deleted. The actual modifications to your JCL will vary from those shown. See the Setting Up the Batch JCL for an explanation of the modifications.

JCL to Run a Program Without Code Debug TSO

//MYJOB    JOB (ACCOUNTING),
//*            NOTIFY=TSOUSER,
//             CLASS=A,MSGCLASS=A,
//             MSGLEVEL=(1,1),TIME=(,10)
//*
//* RUN TRIMAIN IN BATCH WITHOUT CODE DEBUG TSO
//*
//MYTEST   EXEC PGM=TRIMAIN
//STEPLIB  DD  DSN=USER.LOADLIB,DISP=SHR
//*
//*   ALLOCATE ALL INPUT AND OUTPUT DDNAMES
//*
//INFILE   DD  DSN=CPWR.XT.SLXTSAMP(TRIDATA),
//             DISP=SHR
//OUTFILE  DD  SYSOUT=(*)
//SYSOUT   DD  SYSOUT=(*)

JCL to Run a Program With Code Debug TSO

//MYJOB    JOB (ACCOUNTING),
//*            NOTIFY=TSOUSER,                                       NOTE 1
//             CLASS=A,MSGCLASS=A,                                   NOTE 2
//             MSGLEVEL=(1,1),TIME=(,10)
//*
//* RUN TRIMAIN IN INTERACTIVE BATCH WITH CODE DEBUG TSO
//*
//CREATE   EXEC PGM=IEFBR14                                          NOTE 3
//XPSCRIPT DD DISP=(NEW,PASS),
//             DCB=(LRECL=80,BLKSIZE=3120),
//             UNIT=SYSDA,
//             SPACE=(TRK,(2,2)),
//         DSN=&&XPSCR
//XPDOC    DD DISP=(NEW,PASS),
//             DCB=(LRECL=80,BLKSIZE=3120),
//             UNIT=SYSDA,
//             SPACE=(TRK,(2,2)),
//         DSN=&&XPDOC
//XPOUT    DD DISP=(NEW,PASS),
//             UNIT=SYSDA,
//             SPACE=(TRK,(2,2)),
//         DSN=&&XPLOG
//MYTEST   EXEC PGM=XPTSO,REGION=4098K                               NOTE 4
//XDYNAMIC DD DISP=(NEW,DELETE),                                    NOTE 5
//             UNIT=SYSDA,
//             DCB=(RECFM=U,BLKSIZE=BBBBB,DSORG=PO),
//             SPACE=(CYL,(5,1,10))
//STEPLIB DD DISP=(OLD,DELETE),DSN=*.XDYNAMIC,VOL=REF=*.XDYNAMIC   NOTE 6
//         DD DSN=CPWR.XT.SLXTLOAD,DISP=SHR
//         DD DSN=CPWR.CSS.LOADLIB,DISP=SHR
//         DD DSN=YOUR.USER.LOADLIB,DISP=SHR                        NOTE 7
//*
//*   ALLOCATE ALL INPUT AND OUTPUT DDNAMES
//*
//INFILE   DD DSN=CPWR.XT.SLXTSAMP (TRIDATA),                       NOTE 8
//             DISP=SHR
//OUTFILE DD SYSOUT=(*)
//SYSOUT   DD SYSOUT=(*)
//XPSL0001 DD DISP=SHR,DSN=COMMON.DDIO                              NOTE 9
//XINCLUDE DD DISP=SHR,DSN=SYS2.XPEDITER.V17R02M00.INCLUDE
//XPHELP   DD DISP=SHR,DSN=SYS2.XPEDITER.V17R02M00.HELP
//XOPTIONS DD DISP=SHR,DSN=SYS2.XPEDITER.V17R02M00.XOPTIONS
//XPSCRIPT DD DISP=(MOD,PASS),DSN=&&XPSCR
//XPDOC    DD DISP=(MOD,PASS),DSN=&&XPDOC
//XPOUT    DD DISP=(MOD,PASS),DSN=&&XPLOG
//XPSHOW   DD DISP=(NEW,DELETE),UNIT=SYSDA,
//             DCB=(RECFM=FB,BLKSIZE=6160,LRECL=80),
//             SPACE=(TRK,(2,2))
//XPIN     DD *
XPED TSO
TEST TRIMAIN
//PRINTLOG EXEC PGM=IEBGENER,COND=EVEN
//SYSPRINT DD   SYSOUT=*
//SYSIN    DD   DUMMY
//SYSUT1   DD   DISP=(OLD,PASS),DSN=&&XPLOG
//SYSUT2   DD   SYSOUT=*
//*
//PRINTDOC EXEC PGM=IEBGENER,COND=EVEN
//SYSPRINT DD   SYSOUT=*
//SYSIN    DD   DUMMY
//SYSUT1   DD   DISP=(OLD,PASS),DSN=&&XPDOC
//SYSUT2   DD   SYSOUT=*
//*
//PRINTSCR EXEC PGM=IEBGENER,COND=EVEN
//SYSPRINT DD   SYSOUT=*
//SYSIN    DD   DUMMY
//SYSUT1   DD   DISP=(OLD,PASS),DSN=&&XPSCR
//SYSUT2   DD   SYSOUT=*

Setting Up the Batch JCL

The numbers listed in above figure correspond to the following notes:

Notes

TSO users should modify this to their TSO user ID.
Change to your site’s standard values.
Add this step before the step that executes your program. The CREATE EXEC step creates the session log, script, and document data sets.
Change to PGM=XPTSO to run interactive batch. Change to PGM=XPBATCH to run unattended batch. The region size may need to be increased. See Displaying Available Memory (REGION SIZE) for region recommendations. Keep the original parameter list, if any.
This DD statement creates a dynamic work area that Code Debug TSO requires to execute. Place it before the STEPLIB concatenation. This is a temporary PDS that will be deleted when the job ends. Change the BLKSIZE to be equal to the largest blocksize of any library in the STEPLIB concatenation for the test. This step is required.
In the STEPLIB ddname, concatenate the Code Debug TSO work data set created by the XDYNAMIC ddname at the beginning of STEPLIB. The Code Debug TSO LOADLIB and the CSS LOADLIB must also be in the STEPLIB concatenation.
Change to your user LOADLIB.
Specify your library.
Add the following nine ddnames after the last standard ddname. Make sure the Code Debug TSO ddnames are allocated to the correct data set names.

XPSL000n DD

DDIO data set that contains the source listing members of the compiled modules.

XINCLUDE DD

Optional script file (PDS) to be used with the INCLUDE, INITSCR, and POSTSCR commands. This ddname can be omitted if your site does not support INCLUDE scripts or if INCLUDE, INITSCR, and POSTSCR are not used. If the site-wide script library is desired, it should be first in the concatenation.

XPHELP DD

Code Debug TSO help data set.

XOPTIONS DD

Enhanced FIND function parameters file.

XPSCRIPT DD

The generated script data set. All Code Debug input commands are recorded in this file. System responses are not recorded.

XPDOC DD

The document data set. This data set should only be utilized under the direction of Code Debug Technical Support.

XPOUT DD

The output (session log file) from this job. If running an interactive batch job, XPOUT must be directed to a data set with DISP=MOD.

If you direct the output of XPOUT ddname to a data set rather than to SYSOUT, specify the disposition as MOD. The DCB attributes are:

DCB=(RECFM=VBA,LRECL=137,BLKSIZE=6854)

XPSHOW DD

A temporary work file used in processing Code Debug SHOW commands.

XPIN DD

Enter the commands to execute the test session. The first command must be XPED with the appropriate environment parameter. Then, enter the TEST command with the program name and any required parameters. When running an interactive batch test, this is the only input required. The XPED and TEST commands are described in the Command-and-syntax-reference.

If running unattended batch, the debugging commands follow the TEST command. The debugging commands can be included as a command stream after the TEST command, or a data set containing the commands can be specified on the TEST command. See Creating a Command Stream for more information.

Usage Notes

If you are using a PROC, remember that JCL rules for PROCs prohibit the use of DD * inline data streams. For that reason, each reference to XPIN should be coded:
//XPIN DD DUMMY
or
//XPIN DD DDNAME=SYSIN
or omitted entirely.
Then, in the actual JCL that invokes your new PROC, you must override the XPIN ddname with your inline XPED and TEST (or INTERCEPT for BTS) commands.
When you execute the PROC, insert the //stepname.XPIN DD * statement in the override JCL.
If you are using a job that checks condition codes or abends for recovery or follow-up steps, be aware that Code Debug TSO usually produces a condition code of zero regardless of how the application program or Code Debug TSO actually ends.
No additional tasks are required to implement batch testing of programs compiled with CA-OPTIMIZER. However, it is important to note that Code Debug TSO dynamically turns off DTECT, PFLOW, and XCOUNT if specified. Therefore, a batch job run with both Code Debug TSO and CA-OPTIMIZER receives only Code Debug TSO debugging output.
Even if your application programs would normally find any required Language dependent run-time subroutines (including LE - Language Environment) without being included in the JOBLIB/STEPLIB of the Batch JCL (usually from the LINKLIST or (E)LPA), the libraries must still be specified as part of the test session setup. This will ensure that Code Debug’s Task Library will be properly configured. For manually altered Batch JCL, you should include the run-time libraries in the STEPLIB DD statement concatenations of the JCL steps that were altered to be intercepted.

Creating a Command Stream

Batch mode Code Debug TSO reads in a command stream from the XPIN DD, performs the debugging functions, and writes the results to the XPOUT DD. A command stream is a predefined set of Code Debug TSO commands stored in a PDS member or a sequential file, or included as instream data.

The first step in creating a command stream is to specify the environment in which the program is to be debugged. Enter the XPED command with the type of environment (for example, TSO corresponds to the interactive STANDARD environment).

The next step is to specify the name of the program to be debugged. Enter the TEST command along with the program name if the execution environment was specified as BATCH or IMS. Enter the INTERCEPT command along with the program name if the execution environment was specified as BTS.

Example 1:

XPED TSO
TEST TRIMAIN

Example 2:

XPED IMS
TEST TRIMAIN

Example 3:

XPED BTS
INTERCEPT TRIMAIN

The third step is to list all the debugging tasks to be performed during the batch debugging session. Under the BATCH or IMS environment, you can enter other Code Debug TSO commands following the TEST command; however, you can also alternatively execute a test script stored in a separate file.

All Code Debug TSO commands must be entered in uppercase when creating a command stream. At least one space is required to delimit the keyword from its value. Commands can be entered on one line or on consecutive lines.

Specifying Multiple Debugging Sessions in One Job Stream

Although you cannot change environments during a debugging session, it is expected that you will debug various programs, thus TEST or INTERCEPT can be used as many times as necessary.

Multiple programs within the same environment can be debugged in one batch run. The TEST command is used to specify the program to be debugged in batch mode. Any number of debugging sessions can be run within a single job stream (except for IMS debugging sessions). All Code Debug TSO commands following a TEST command are executed in relation to the program specified by the TEST command, until another TEST or INTERCEPT command is encountered.

The INTERCEPT command is used to change module qualification. Any commands entered following the INTERCEPT command and before another TEST, INTERCEPT, or EXIT command are executed in relation to the program specified on the INTERCEPT command.

For BTS debugging, only the XPED and INTERCEPT commands are allowed within a command stream. All debugging session commands are included in a test script associated with the program specified on the INTERCEPT command.

Creating Batch JCL for Code Debug TSO Options

Database Support (Including IMS/DB and IMS/DB With Db2 Testing Under TSO)

To test your IMS/DB program with unattended or interactive batch, use the steps listed as follows:

Retrieve your IMS/DB program execution JCL.
Copy the member BATCHIMS from the SLXTSAMP data set and follow the instructions in it.
If you are using a PROC, change the XPIN ddname to:
//XPIN DD DUMMY
When you are executing the PROC, insert the //stepname.XPIN DD * statement in the override JCL.
For more information regarding the use of the //XPIN DD statement in a PROC, see Usage Notes.
Submit the job. If you are running unattended batch, the test results will be saved in the XPOUT file. If you are using interactive batch, you must connect to the job to complete testing.

BTS Support

To test your BTS program with unattended or interactive batch, use the steps listed as follows

Retrieve your BTS program execution JCL.
Copy the member BATCHBTS from the SLXTSAMP data set and follow the instructions in it.
If you are using a PROC, change the XPIN ddname to:
//XPIN DD DUMMY
When you are executing the PROC, insert the //stepname.XPIN DD * statement in the override JCL.
For more information regarding the use of the //XPIN DD statement in a PROC, see Usage Notes.
Submit the job. If you are running unattended batch, the test results will be saved in the XPOUT file. If you are using interactive batch, you must connect to the job to complete testing.

Db2 Support

To test your Db2 program with unattended or interactive batch, use the steps listed as follows:

Retrieve your Db2 program execution JCL.
Copy the member BATCHDB2 from the SLXTSAMP data set and follow the instructions in it.
If you are using a PROC, change the XPIN ddname to:
//XPIN DD DUMMY
When you are executing the PROC, insert the //stepname.XPIN DD * statement in the override JCL.
For more information regarding the use of the //XPIN DD statement in a PROC, see Usage Notes.
Submit the job. If you are running unattended batch, the test results will be saved in the XPOUT file. If you are using interactive batch, you must connect to the job to complete testing.