Test session management using scripts

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

1. Initialize a debugging session (initial script).
2. Execute a set of commands during the debugging session (test script).
3. Execute a set of commands at the end of a session (post script).
4. 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 pre-allocated 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. See the Saving and Using Generated Scripts for steps on using a generated script.

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 interactive mode, the initial script member name is specified in the Initial Script field on the selected environment test screen.

In Batch Connect 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:

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

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 interactive mode or Batch Connect 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.

In interactive mode, Code Debug TSO automatically generates 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. The generated test script is accessed by typing the SCRIPT command on the command line of the Test screen after a debugging session. See the Saving and Using Generated Scripts for additional information.

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 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.

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.

Use the SET ABENDSCR command in the JCL job stream to specify the abend script to be executed when an abend occurs. 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.

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

In interactive mode, Code Debug TSO automatically generates a test script of all the commands entered during the debugging session. The following steps will show you how to save and use the script for later use when you want to duplicate the debugging session.

Option 1 - Batch Connect under Code Debug TSO

The following steps apply to Code Debug TSO only:

1. 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.
2. Edit the displayed script according to the guidelines in Creating and Editing Scripts.
3. Press PF3 to save the edited script.
4. On the Data Set Disposition Screen, enter C in the Process Option field to copy the edited script to a partitioned data set (PDS).
5. 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 goto Step 7. Otherwise, go to the next step.
6. 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.
7. 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.
8. Press PF3 to return to the Test screen.

9. 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.

   Important

   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 under ROSCOE

The following steps apply when using the Batch Connect under ROSCOE Environment:

1. 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.
2. 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.

3. Press Enter and you will view the Batch Connect under ROSCOE Script Data set screen as displayed in 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
4. 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.
5. Run your test and upon completion, copy the data from the data set on the XPSCRIPT to a member in your INCLUDE data set.
6. 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 example

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 as follows.

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 Assembler 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.

• 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 Assembler programs.