Starting an interactive session

To start an interactive debugging session, do the following:

1. Access the Code Debug TSO Primary Menu.

   Important

   If you want to change the defaults for your terminal, PF keys, screen colors, profile, etc., use option 0. See Specifying Session Defaults for more information.

2. Optionally, specify a new or existing profile for the debugging session. When a profile is not specified, a default profile is used. See Using Profiles.
3. Use option 2 (TSO) on the Code Debug TSO Primary Menu. Secondary screens are displayed for specifying the program name and information about the environment in which the program will execute.
   The SETUP command shown on some of the secondary screens can be used to override the installed setup options, such as the name of the load library and DDIO data set, session log disposition, and so on. The Setup Facility is discussed in detail in Specifying Setup Options.
4. Allocate the files and databases that your program will need to execute. See Allocating the Required Files.

Using profiles 

The information you specify for a debugging session is recorded in a user profile that can be used each time you want to execute the same test session again. This information includes the name of the program, the list of files and databases that must be allocated for the program to execute, the setup options for the environment in which the program will execute, and the Code Debug TSO defaults to be associated with the test session. It also contains the defaults established by your systems programming staff during installation of Code Debug TSO.

The profile identifier and description are displayed in the Profile field on the Primary Menu. The Profile field can be used to:

• Create a New Profile
• Use an Existing Profile
• Obtain a List of Profiles.

Changes to a user profile are made through the Code Debug Profile screen shown in Code Debug Profile Screen. This screen can also be accessed through option 0 (Defaults) on the Primary Menu or by entering the PROFILE command from the Primary Menu screen or any test screen. See Specifying User Profiles for information about the Profile facility.

Invoking the test session

The first time you invoke an Code Debug test session using option 2 (TSO) on the Primary Menu, the Environments Menu shown the following figure is displayed.

Environments Menu 

The range of environment options shown on this menu depends on the site defaults set by your installer. More information about the environments is provided in Guidelines for Selecting an Environment.

Each option on the Environments Menu accesses an environment test screen on which you enter information about your program and the test session. For example, if you are testing a program in the standard environment with no special services, you would enter option 1 (STANDARD) on the Environments Menu and the Standard Test screen would be displayed.

Environment test screens are used to specify all of the information required about the program and test session. All environment test screens are described in Code Debug TSO Environment Test Screens.

If you type SETUP on the command line of the environment test screen, the Setup Menu is displayed. The options on the Setup Menu provide additional screens on which you can change the installed values for the listed options, such as load library names, DDIO file name, session log disposition, and so on. All setup menus and screens are described in Specifying Setup Options.

When you complete the test screen and specify all setup information, a Code Debug TSO test session is started. Your source is displayed on the Code Debug TSO source display where all debugging functions are available for your use. The debugging functions are discussed in Debugging Interactively.

Guidelines for selecting an environment

The Code Debug TSO options (1 through 7) on the Environments Menu displayed in Environments Menuinvoke a debugging session and execute the application program in the TSO address space. The Code Debug IMS options (8 through 11) on the Environments Menu invoke a debugging session and execute the IMS/DC application program in the message region, the BMP region, and the Fast Path region.

If you are developing IMS/DC applications, Code Debug IMS provides the capability of debugging IMS/DC programs that are actually running in the IMS dependent regions, whereas Code Debug TSO provides the capability of debugging IMS/DC applications with the use of a simulator (BTS) under TSO. Operations of Code Debug IMS, however, require at least one logical TSO terminal and one logical IMS terminal (it can be an ATM terminal), both on the same CPU.

The following table summarizes the environment options to choose, depending on the type of application you want to debug:

Guidelines for Choosing an Environment

Allocating the required files 

This section tells you how to interactively specify a file list to be used at execution time to allocate the files and databases your program needs.

Allocating the files your program will need is as easy as entering the data set name of an existing file list, a CLIST, or your execution JCL (also identified as Quickstart) in the File List/JCL Member field on the environment test screen.

There may be times when you may need to allocate files after starting a test session. This can be done with the ALLOCATE command, which can be entered from any Code Debug TSO screen.

At other times, you may need to use the File Allocation Utility (FAU), a file list editor that lets you create and edit file lists. The FAU is accessed through option 1 on the Code Debug TSO Primary Menu. When errors occur during file allocations while using the test screen or the ALLOCATE command, the FAU is automatically accessed to assist you in resolving the problem.

Each of these methods is used for a somewhat different purpose. The first two methods are described as follows. A description of the File Allocation Utility is provided in Using the File Allocation Utility.

Allocating from the test screen

The easiest and most commonly used way to allocate the files your program will need is to enter the name of the data set containing the file list, CLIST, or the program execution JCL (also identified as Quickstart) in the File List/JCL Member field on the environment test screen as shown in the following example:

File List/JCL Member ===> ’XT.XT70.FAU(TRIMAIN)’

If the data set contains a file list or CLIST and there are no errors, the files are automatically allocated.

If the data set contains JCL, the following occurs before the files are allocated:

1. If the JCL executes a PROC, the PROC is automatically expanded. See Things to Know About JCL Expansion for more information.
2. JCL DD statements are automatically converted to the file list format. The conversion rules are as follows:
   • SMS keywords, in-stream data, ROUND (and other space parameters), SYSOUT related parameters (HOLD, COPIES, DEST, etc.) are processed.
   • JCL statements that do not have the corresponding SVC 99 support are processed by ignoring the keywords and parameters. This situation will take place, for instance, when VSAM AMP parameters are encountered.
   • The program references EXEC PGM=*.xxx.yyy cannot be processed. Processing will pause, the FAU is accessed, and the appropriate screens that will allow you to correct the problem are displayed.
   • When the program name on the test screen does not match the EXEC PGM in the JCL, an error message is displayed and the FAU is automatically accessed.
3. Automatic Task Library/Parm setup as follows:
   • If the program name that follows the PGM= keyword of one of the steps is equal to the module name to be tested, then Code Debug TSO will dynamically allocate the DDs contained in that step. If the JCL PROC expansion option CONVERT is being used, then the STEPLIB or JOBLIB data sets will be concatenated to Code Debug’s Task Library after the libraries that are specified on the Setup.1 screen.
   • If none of the program names that follow the PGM= keyword of one of the steps is equal to the module name to be tested, then Code Debug TSO copies the JCL to the File Allocation Utility work area, prompts for DD selection, and dynamically allocates the selected files. If the JCL PROC expansion option CONVERT is being used, a STEP (as opposed to DDs) must be selected in order to have the corresponding STEPLIB or JOBLIB data sets concatenated to Code Debug’s Task Library after the libraries that are specified on the Setup.1 screen.
   • If the JCL PROC expansion option CONVERT is being used, and the step you are testing has the PARM= or PARMDD= keyword, Code Debug TSO will use the JCL-supplied parm values (as long as the PARM String field on the screen is blank). To override the use of the JCL-supplied PARM, put two single quotes in the PARM String field to pass a null parameter or supply parm values in the PARM String field.

If no errors occur, the files for the debugging session are automatically allocated. If a problem occurs, the FAU is automatically accessed, and you are presented with the screens needed to correct the problem.

Allocating with the ALLOCATE command

The ALLOCATE command is generally used to allocate files from within an Code Debug test session. It can be entered on the command line of any Code Debug screen. If entered without a data set name, the FAU is accessed and you can specify the information about the file to be allocated. When you exit the FAU, the files are automatically allocated.

If you enter the ALLOCATE command with a data set name, the data set is automatically accessed. If the data set contains a file list and the allocations are successful, you will not see any FAU facilities.

If the data set contains JCL, the FAU is accessed and the JCL data set is displayed on the Select DDNAME screen. On this screen, you can select the DD statements to be copied to the file list. See the Converting JCL to a File List.

If an error occurs during the allocation, the Edit File List screen is displayed with an error message. At this time, you can correct the problem. When you enter END, the files are allocated.

Usage Note

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.

Using Code Debug TSO commands in interactive mode

In interactive mode, debugging is performed by entering Code Debug TSO commands online.

You can also use script files in interactive mode.

• An initial script member name can be specified in the Initial Script field on the selected environment test screen.
• A test script member name can be specified by using the INCLUDE command on the command line during the test session.
• A post script member name can be specified in the Post Script field on the selected environment test screen.
• An abend script is not applicable in interactive mode.

For information about using scripts, see Test Session Management Using Scripts.