Dialog Box Test Screen – Environments Menu - Option 2 of COBOL

The Dialog Box Test screen, shown in following figure, lets you specify the dialog box environment parameters and initiate a debugging session. The screen is designed to allow programmers to debug ISPF dialog box programs that are running as a part of the larger application process. For instance, programs that are invoked by entering data from an ISPF panel, issuing an edit macro, or executing a CLIST can be debugged in this environment.

All the dialog box components, such as screens, CLISTs, tables, messages, and load modules, must be preallocated before initiating the debugging session unless the dialog box includes a function to use the ISPF LIBDEF facility. See the IBM ISPF Dialog Box Management Services Manual for additional information regarding file allocations for dialog box testing.

Dialog Box Test Screen 

The fields on the above screen are described as follows:

PROGRAM

Required. Enter a series of load module names that you want to debug when the dialog box is invoked. You must specify either the main program or subprograms. Do not specify both.

Six load modules can be specified on this screen. If you want to continue the list, you can scroll down to a subsequent screen.

INITSCR

Enter the member name of a test script if you want to execute a predefined command stream at the beginning of the debugging session. This member will be executed after the inclusion of the site-wide script member @@SITE@@, if defined.

POSTSCR

Enter the member name of a test script if you want to execute a predefined command stream at the end of the debugging session.

START

Enter up to four digits to specify on which occurrence of the program invocation the intercept is to begin. By default, program intercept begins on the first occurrence. When the program is intercepted, the debugging session is initiated and the source is displayed.

MAX

Enter up to four digits to specify the maximum number of times the program intercept is processed. If this field is left blank, the value defaults to an infinite number. If you enter an EXIT command and there are still intercepts remaining, those intercepts are ignored.

ISPF Menu

Required. Specify the driver panel to start your dialog box application. Typically, this is the ISPF/PDF Primary Option Menu, ISR@PRIM. You can initiate your dialog box application through the dialog box test facilities (option 7.1 of ISPF/PDF) and trace the ISPF variables while tracing the host variables and setting breakpoints at the COBOL verbs under Code Debug TSO.

BMC supplies a separate panel, XPPISPFT, which is functionally similar to the ISPF Dialog Box Test option 1. To use this panel to identify the dialog box function to be debugged, enter XPPISPFT in the ISPF Menu field.

OPT

If you use XPPISPFT, leave this field blank. Otherwise, enter the starting point by ISPF option number (for example, 7.1).

APPLID

Enter the application ID.

File List/JCL Member

Enter the data set name that contains the file list, CLIST, or JCL. The File Allocation Utility (FAU) preallocates files and databases that are processed by the program upon entry to the debugging session.

If the member name of a PDS is omitted, a member list is displayed.

If the data set contains a CLIST, Code Debug TSO immediately executes it and begins the debugging session.

If the data set contains a file list or JCL, the FAU is invoked to dynamically allocate the specified files before beginning the debugging session. See Using the File Allocation Utility for detailed information about the FAU.

Preview Files?

Enter YES to enable browse/edit of file allocations. If File-AID is installed, its file browse (FB) and file edit (FE) functions will also be available.

Code Coverage Test?

Enter YES to collect statistics without Test Data Optimization information. Enter TDO to collect statistics and TDO information. The default value is NO.

System Flow?

Enter YES to collect Code Coverage System Flow data. The default value is NO.

Is This a DB2 Test?

Enter YES if the program executes EXEC SQL statements. Code Debug TSO selects the proper Db2 libraries for inclusion in the setup library (XTASKLIB) concatenation.

The Db2 connection must be established, such as executing the TSO DSN RUN command, before initiating the debugging session.

System

Enter the Db2 subsystem name. Use the subsystem name assigned to the Db2 DSNLOAD library to be included in XTASKLIB.

When you press Enter from the Dialog Box screen, the specified ISPF screen is displayed, but you must invoke the program or edit macro as you would if you were debugging without Code Debug TSO.

To invoke a function on the XPPISPFT screen, shown in XPPISPFT - Invoke Dialog Box Function/Selection Panel, only one entry is required in one of the following fields: PANEL, CMD, or PGM.

Effect of Dialog Box Program Intercepts

Each of the programs named on the Dialog Box screen must be an MVS load module name. Programs named in the intercept list must not be referenced within the Code Debug session with the SOURCE or INTERCEPT command. These programs will be intercepted under Code Debug dialog box control when activated by sequences of LOAD/CALL, LINK, or ATTACH. Typical external events that can result in one of these sequences are: running the programs as TSO command processors, naming the programs as the target of a TSO CALL command, or executing the programs via ISPF SELECT services. Each of the programs should be independent of any other program named in the intercept list.

When the programs are not independent, special processing is performed by Code Debug and user interaction is necessary to test multiple programs simultaneously. For example, assume that program PGMA calls program PGMB, which then calls program PGMC. Also, assume that all three programs are named as dialog box intercepts. When PGMA is activated by the user dialog box, an Code Debug session is initiated and the source of PGMA is displayed. During the execution of PGMA, PGMB is eventually activated. However, since Code Debug is already active for the PGMA intercept, PGMB is not intercepted and executes as if no intercept had been set. The same is true for PGMC.

There are two ways in which such a nested sequence of programs can be tested. The first method is to name only PGMA on the Dialog Box screen. When PGMA is intercepted, then SOURCE or INTERCEPT commands can be used to reference PGMB and PGMC. A second method can be used when programs are executed multiple times within the dialog box. The START and MAX values determine when the intercepts are to be active for each program in the list. For example, let PGMA and PGMB both be named in the intercept list with the MAX value for PGMA set to 3. Now when the user dialog box invokes PGMA repetitively, PGMA is intercepted each of the first three times it executes, but on the fourth and subsequent executions, when PGMA calls PGMB, Code Debug intercepts PGMB.

XPPISPFT - Invoke Dialog Box Function/Selection Panel

The fields on the Invoke Dialog Box Function/Selection Panel are described as follows:

PANEL

Name of the ISPF panel to be invoked. Required if CMD or PGM is not specified.

OPT

Optional; the initial option that must be valid on the panel named above.

CMD

The name of a command procedure (CLIST or EXEC), or any TSO command, to be invoked as a dialog box function. Command parameters can be included. Required if PANEL or PGM is not specified.

LANG

Specify APL if the string specified by the CMD keyword is an APL function and the APL2 environment is active. Otherwise, leave blank.

MODE

Determines whether line mode will be entered or not. LINE causes line mode to be entered. FSCR causes full screen mode to be entered. If you leave MODE blank when selecting a command procedure, line mode is entered unless you prefix the command with a percent sign (%).

PGM

The name of a program to be invoked as a dialog box function. The program name must be one of the program names specified in the previous Dialog Box screen. Otherwise, it causes an abend. Required if PANEL or CMD is not specified.

PARM

Optional; parameters to be passed to the program.

TASKLIB

Enter Yes if XTASKLIB is to be searched for the specified program name. The default is No.

NEWAPPL

Specifies the new application ID name, if one is being invoked. If a new application is specified, the next selection menu displayed is the application’s primary option menu.

NEWPOOL

Enter Yes if a new shared variable pool is to be created. This value is ignored if NEWAPPL is specified.

PASSLIB

Enter Yes if the current set of application level ISPF libraries (if any exist) are to be passed to the application being selected. This field is valid only if NEWAPPL is specified.

To invoke a function through the ISPF Menu ISR@PRIM, select option 1 (FUNCTIONS) on the Dialog Box Test Primary Option Menu shown in the following figure.

Dialog Box Test Primary Option Menu

Then specify the function to be invoked in one of the following fields on the Invoke Dialog Box Function/Selection Menu shown in the following figure: PANEL, CMD, or PGM.

ISR@PRIM - Invoke Dialog Box Function/Selection Menu

Press Enter to initiate the debugging session. See Debugging Interactively for information on how to debug your program.