Test Session Management Using Scripts (COBOL User Guide)

A script is a predefined stream of Code Debug TSO commands that can be used to:

Initialize a debugging session (initial script).
Execute a set of commands during the debugging session (test script).
Execute a set of commands at the end of a session (post script).
Execute a set of commands when an abend occurs in an unattended batch session (abend script).

Scripts enable you to:

Eliminate redundant keystrokes.
Play back the commands established during a previous session.
Run regression testing.

You create and maintain the scripts and the script libraries you use. A script library is a partitioned data set (PDS) that can be FB 80 (fixed block with a record length of 80) or a VB 255 (variable blocked with a maximum record length of 255). If you use FB 80, only the data in columns 1 through 72 is recognized.

If you intend to use a script during the test session, the script library must be preallocated before the session begins. Use the SETUP command and select Option 3 (INCLUDES) on the Setup Menu to allocate the library, unless the script member is contained in a site-wide library specified at installation time.

Initial Scripts

An initial script is executed at the beginning of the debugging session or at the before breakpoint of each module. It can be used to:

Set initial PF key values.
Specify Code Debug TSO debugging session processing options with the SET command.
Set initial breakpoints in modules.
Initialize data items within the program (using MOVE command).

In Code Debug TSO interactive mode, the initial script member name is specified in the Initial Script field on the selected environment test screen.

In Batch Connect and Batch Connect under ROSCOE interactive or unattended mode, the initial script member name is specified in the INITSCR field on the Select Job Step screen, or you can edit your execution JCL and use the INITSCR parameter on the TEST or INTERCEPT command.

The Multi-Batch screen includes an optional Initial Script field in which you can enter an initial script member name.

The ability to process SET commands before the program is loaded is the most useful feature of the initial script. The following SET commands either configure Code Debug TSO or control the manner in which Code Debug TSO loads programs:

SET CBLTRAP SET STATIC
SET DYNAMIC SET TRANSFER
SET EXCLUDE

The following commands determine the size of the session log and the way information is represented.

SET HEXMODE
SET LOGSIZE
SET NONDISP

See the Command-and-syntax-reference for further information regarding the use of the SET command parameters.

Test Scripts

A test script is used to execute Code Debug TSO debugging commands during a debugging session. The commands in the test script are executed in the order they are read, as if they had been entered serially from the terminal.

In Code Debug TSO interactive, Batch Connect interactive, and Batch Connect under ROSCOE interactive, use the INCLUDE command with the test script member name at any time within the session to execute a test script command stream.

In unattended batch, the test script member name is specified by using the INCLUDE command in the JCL job stream.

Code Debug TSO interactive, Batch Connect interactive, and Batch Connect under ROSCOE interactive automatically generate a test script of all the commands entered during the debugging session. The generated file can be edited and copied into a script library for later use when you want to duplicate the debugging session. For a Code Debug TSO interactive test, the generated test script is accessed by typing the SCRIPT command on the command line of the Test screen after a debugging session. For Batch Connect interactive and Batch Connect under ROSCOE interactive, the generated test script is written to the file referenced in the XPSCRIPT DD. The way in which you defined this file in the SETUP panel for the SCRIPT option will determine whether the information is available after the test has completed.

Post Scripts

A post script is comprised of a command or set of commands that are executed when the end of the program is encountered. The commands are effectively executed after the debugging session is ended, but before the Code Debug TSO environment is exited.

A post script has many purposes. For instance, it lets you display (PEEK) the value of variables at the close of the debugging session and show the COUNT tallied on program statements.

In Code Debug TSO interactive mode, a post script member name is specified in the Post Script field on the selected environment test screen.

In Batch Connect interactive or unattended mode, a post script member name is specified in the POSTSCR field on the Select Job Step screen, or by editing your execution JCL and using the POSTSCR parameter on the TEST or INTERCEPT commands.

In Batch Connect under ROSCOE interactive or unattended mode, a post script member name is specified by editing your execution JCL and using the POSTSCR parameter on the TEST or INTERCEPT commands.

Note

It is suggested that you use PEEK instead of KEEP in a post script.

When debugging VS COBOL II programs compiled with DATA(31) and RENT, and linked with AMODE(31) and RMODE(ANY), post scripts cannot be used to execute the PEEK, KEEP, and MOVE commands.

Abend Scripts

An abend script is a Code Debug TSO command or set of commands that are executed when an abend occurs. You can use an abend script only when debugging in unattended mode.

Specify the abend script to be executed when an abend occurs by using the SET ABENDSCR command in an initial script or by editing the JCL job stream to incorporate the command in any one of several acceptable configurations. The commands included in that script are executed whenever an abend occurs until another SET ABENDSCR command is executed. Any number of SET ABENDSCR commands can be included in a job stream.

Note

It is suggested that you use PEEK instead of KEEP in an abend script.

Creating and Editing Scripts

In a script, the following must be observed:

Commands cannot exceed 100 characters.
Only one Code Debug TSO command can be entered on a single line.
A command can be continued beyond a single line without a continuation character.
A quoted string must be contained on one line.
Test scripts can be nested without limit by inserting additional INCLUDE commands within the test script.
Comment lines can be included by entering an asterisk (*) in column 1.
When used within inserted code, the INCLUDE command is executed when the inserted code is executed.

Scripts are extremely useful under certain debugging circumstances. For example, suppose you end a debugging session knowing that at some later time you intend to retest the program along the same lines. A script is an efficient way to quickly reproduce that session without having to reenter the commands individually.

Saving and Using Generated Scripts

Option 1 - Code Debug TSO Interactive

When the debugging session is completed, the message Log and Script Created appears in the upper right corner of the Test screen. Enter SCRIPT on the command line of the Test screen.
Edit the displayed script.
Press PF3 to save the edited script.
On the Data Set Disposition Screen, enter C in the Process Option field to copy the edited script to a partitioned data set (PDS).
If you have already allocated a PDS for this purpose, enter the PDS name in the DSNAME field of this screen and a name for the edited script in the Member Name field. Press Enter and go to Step 7. Otherwise, go to the next step.
If you have not allocated a PDS, you can do so at this time by entering a library name in the DSNAME field of the screen and a name for the edited script in the Member Name field. Press Enter and the New Data set Allocation screen is displayed with the data set name you selected pre-filled in the Data set Name field. Enter the parameters for the data set according to your site standards and press Enter to process.
You are returned to the Test screen and a message specifying the number of lines that were copied is displayed in the upper right corner of the screen. If your PDS is not specified in setup on the Test Script Libraries screen, enter SETUP from the Test screen and enter 3 on the Setup Menu screen. Then enter the PDS name on the Test Script Libraries screen. Press Enter to process.
Press PF3 to return to the Test screen.
When you want to use the script for a subsequent test session, specify the PDS member name of the script in the Test screen’s Initial Script field or use the INCLUDE command followed by the PDS member name to execute the script after the source is displayed.
Note
The LOG and SCRIPT commands are still displayed on the Test screen. This means that the session log and script files from the previous session are still active. If you intend to start another debugging session and want to use fresh session log and script files, press PF3 to return to the Code Debug TSO Primary Menu and then enter option 2 to return to the Test screen. This deletes the previous session log and script files, and you are ready to begin a new session.

Option 2 - Batch Connect

Before generating the modified Batch Connect JCL, it is necessary to set up the script data set values so that the data set will be available after the test.

From either the Process Execute JCL screen or the Select Job Step screen, enter the SETUP command and press Enter.
In the OPTION field, type 5 and press Enter. The Script Data set screen (See the following figure) is displayed.
Script Data set Screen
--------------------------------- SCRIPT DATASET -----------------------
COMMAND ===>

Script Dataset Name:             (DSNAME will be generated if blank)
          DSNAME ===>

Allocation Parameters:                   Process Options: A (Append)
      Data Class ===>                                     D (Delete)
     Space Units ===>                                     K (Keep)
         Primary ===>                                    PD (Print-Delete)
       Secondary ===>                                    PK (Print-Keep)
   Storage Class ===>                                     ? (Prompt)
            Unit ===>
          Volume ===>

Disposition After the Test:
  Process Option ===>           (D, K, PD, PK, or ?)

Disposition Before the Test:
  Process Option ===>           (A, D, or ? Used only if DSNAME is specified)
                                (Under Multi-Batch, ? = Append)

          Press ENTER to process or enter END command to terminate
In order to keep your script data set after the test has completed, the Disposition After the Test, Process Option field must be a K, PK, or ?. The K and PK values will always keep the script data set. The ? will only keep the script data set if the DSNAME field is not blanks. Type in one of the values.
If you leave the DSNAME field blank, Code Debug TSO will generate a script file data set name for you using the following format: userid.XPSCR.mmmdd.Thhmmss. If you would p to enter your own data set name, type it into the DSNAME field. Data set names without quotes will have the userID added as the first node. If the data set does not exist, then it will be created.
Note
Choosing the ? in Step 3 requires that you enter a data set name in the DSNAME field. Otherwise the script data set will be deleted at the end of the test.
Fill in any of the other fields that may be necessary at your site. When you have finished, press Enter. You will return to the SETUP screen.
Press PF3 to return to your original screen display.
Run your Batch Connect test. Upon completion, your script file will be kept.
In order to use the generated script in a test, it is necessary to copy the script file to one of the files that will be in your XINCLUDE DD concatenation. These files can be found in the SETUP screen, option 3, INCLUDES.
From this point forward, you need to include the script on the Select Job Step screen as your initial script or you must issue the INCLUDE script name while in the source.

Option 3 - Batch Connect Under ROSCOE

Create a data set that will be used in the test session while the Batch Connect job is running. This data set should be allocated as follows: DSORG=PS, RECFM=FB, LRECL=80, and BLKSIZE=3120.
Go to the SETUP menu on any of the ROSCOE Front End screens and go to the OPTION field and select 6 from the menu choices.
Press Enter and you will view the Batch Connect under ROSCOE Script Data set screen as displayed in the following figure.
Batch Connect Under ROSCOE Script Data set Screen
-------------------------- XPEDITER/ROS-SCRIPT DATASET -----------------------
COMMAND ===>

Script Dataset Name: (DSNAME must be pre-allocated as:
                      DSORG=PS,RECFM=FB,LRECL=80,BLKSIZE=3120)
          DSNAME ===>

Allocation Parameters:                 Process Options: A (Append)
      Data Class ===>                                  D (Delete)
     Space Units ===>
         Primary ===>
       Secondary ===>
   Storage Class ===>
            Unit ===>
          Volume ===>

Disposition Before Test:
  Process Option ===>        (A,D Used only if DSNAME is specified)

         Press ENTER to process or enter END command to terminate
Specify the data set name allocated in Step 1 and set the process option based on whether you wish to append or delete the old content.
Run your test and, upon completion, copy the data from the data set on the Script Data set screen to a member in your INCLUDE data set.
From this point forward, you need to include the script on the Select Job Step screen as your initial script or you must issue the INCLUDE script name while in the source.

Script Examples

Example 1:

Suppose you are debugging TRIRPT as a stand-alone program. To do so, you need to MOVE values that have been passed from TRIMAIN to variables in the Linkage Section. The Linkage Section of TRIRPT is shown in the following figure.

Linkage Section of the TRIRPT Program

  000028    LINKAGE SECTION.
000029    01 TABLE-OF-NAMES-N-CNTRS.
000030        05 N-N-C               OCCURS 4 TIMES
000031                                INDEXED BY TX.
000032            10 T-NAME           PIC X(21).
000033            10 T-CNTR           PIC 9(04).

In this case, use a script to move valid data to the variables in the Linkage Section before beginning the debugging session. For example, the script shown in the following figure moves valid data to the table variables and counter. This script can be executed as a test script with the INCLUDE command within a debugging session, or the MOVE commands can be made part of an initial script command stream executed at the outset of the debugging session.

Script with MOVES Passing Values from TRIMAIN to TRIRPT Variables

MOVE ’EQUILATERAL TRIANGLES’ TO T-NAME(1)
MOVE ’ISOSCELES TRIANGLES’ TO T-NAME(2)
MOVE ’SCALENE TRIANGLES’ TO T-NAME(3)
MOVE ’INVALID TRIANGLES’ TO T-NAME(4)
MOVE 2 TO T-CNTR(1)
MOVE 3 TO T-CNTR(2)
MOVE 6 TO T-CNTR(3)
MOVE 4 TO T-CNTR(4)

Example 2:

Suppose you want to set a number of breakpoints that are sufficiently spaced apart and require you to scroll up after setting each breakpoint. A script comprised of these breakpoint commands could initialize the session, setting the breakpoints. This would eliminate the need to scroll in order to enter the commands. Such a script is illustrated in the following figure.

Sample Script

BEFORE 34 41 TRIMAIN:
AFTER 40 94 132 TRITST: TRIRPT:WRITE-DTLS
COUNT 43 55 93 101
SKIP 98 THRU 134 WRITE-REPORT

Using Code Debug TSO Commands in a Script (Interactive)

See the INCLUDE command in the Command-and-syntax-reference for a list of the commands that can and cannot be included in a script for interactive debugging of COBOL programs.

Using Code Debug TSO Commands in a Script (Unattended)

Since all of the commands entered in a script for unattended debugging are executed before the first statement in the program is encountered, careful planning of the debugging session is critical. Here are some considerations:

Store all your command streams as members of your INCLUDE library. Then you are able to keep track of all data streams you have used. It also saves time by not having to reenter all the commands for each session.
AFTER, BEFORE, ONETIME, and TRACE commands give approximately the same information. All three update the Keep window.
When an AFTER command is executed and changes are logged, the session log entry for the command identifies the statements before and after the place where execution is paused. Therefore, use of the AFTER command is a good means of tracking the flow of execution. It is particularly useful following a conditional statement when you are uncertain of the execution path.

To track a value change in a variable, using the WHEN command is better than using the TRACE command, which produces a large amount of output in the session log file.
PEEK is an immediate command, which means the display to the session log occurs as soon as the PEEK command is encountered. PEEK is most useful if you want to see a field at the very beginning or at the very end of a program, and you only want to see the value once. It can be useful within inserted code. You could insert a PEEK after the statement you want executed. The PEEK command would be executed each time the statement was executed.
In general, the KEEP command is used more often than the PEEK command because a keep causes the value of a data item to be displayed repeatedly. KEEP displays a value only at the location of a breakpoint and only when a value has changed. Therefore the best way to watch data change within a program is to set breakpoints (AFTER, BEFORE, or TRACE) on key statements and keep all the data items you want to monitor.
Warning
In post and abend scripts, use the PEEK command instead of the KEEP command.

The COUNT command can be used to monitor statement execution in a batch program that processes large amounts of data. To see the results of the COUNT command, issue the SHOW COUNTS command in a post script at the end of the debugging session.
One of the problems with unattended debugging is that normally all commands need to be executed at the beginning of the debugging session. This can create more output than the user needs. An INSERT command allows Code Debug TSO commands to have delayed execution. The Code Debug TSO commands within an INSERT are not executed until the inserted code is executed; that is, when the previous statement is executed. INSERT can be a very powerful command in an unattended batch debugging session.

See the INCLUDE command in the Command-and-syntax-reference for a list of the commands that can and cannot be used in a script for an unattended debugging session for COBOL programs.