System Overview

CA InterTest Batch is a full-screen, interactive, menu-driven testing and debugging facility for application programmers. It complements the
CA InterTest for CICS product. The programmer controls the test session with the application commands.

This guide describes how to test a program using application batch commands and panels. The system is supported with HELP panels and an online tutorial, which describes the application options and commands.

You can use this product to test Assembler programs (assembled with Assembler F, Assembler H, or the High Level Assembler), COBOL programs (compiled with any COBOL compiler supported by IBM) or PL/I programs (compiled with any PL/I compiler supported by IBM).

This product grants the programmer complete access to the program as it is executing. You can stop the program and the Intercept panel displayed at user-specified intercept points. From the Intercept panel, you can browse the program listing in full-screen mode, using program function keys (PFKs) to scroll backward or forward through the program. You can examine and repair problem areas without ending the test session, or issue commands to set new intercept points and resume testing. Each application panel is supported with a HELP panel. An online tutorial describes the product system.

During a test session, you can do the following actions:

Stop the test at any executable statement in the program.
View the program listing while the test session is stopped.
Trace the program's execution and browse the trace table entries.
Display and alter data-item values.
Step through the program in increments of any number of statements.
Check the number of times each statement in the program is executed.
Step through the program execution in reverse order.
Access the other options such as Core.

The application runs under IBM's ISPF and CA Roscoe Interactive Environment (CA Roscoe) under ETSO. Therefore, programmers familiar with these environments need little or no training to use this product.

During a test session using the ISPF dialog manager, programmers can perform the following functions:

Split the screen to access other ISPF options, such as EDIT.
Print to the ISPF listing data set.
Enter ISPF or TSO commands from any panel.

During a test session using CA Roscoe, programmers can perform the following functions:

Split the screen to perform other CA InterTest Batch or CA Roscoe functions.
Suspend the application session to perform other CA Roscoe functions.
Print to an application data set, which can be allocated to the AWS or any MVS data set.
Use the CA Roscoe print facility.

This section contains the following topics:

Operating Environment

Conventions

Primary Option Menu

System Structure

Operating Environment

Use your product to test any load module that runs under MVS, excluding those requiring authorization. COBOL and PL/I programs to be tested must be compiled with a compiler supported by IBM. Assembler programs must be assembled with the High Level Assembler.

The application ISPF requires the TSO environment with at least 1.5 megabytes of virtual storage specified in the SIZE operand of the LOGON command.

The application supports IBM's ISPF product release 2.1.0 and higher and CA Roscoe 6.0 and higher.

We recommend that the TSO command PROFILE WTPMSG be issued at logon. This command causes all messages that would normally appear in the job log of a batch job (write-to-programmer messages) to be sent to the terminal session.

Conventions

Panel Display Formats

The application uses full screen displays to prompt you for option selection and data entry, and to display source data, listings, and other information.

The first two lines are the header lines; they have a common format for all displays. The remainder of the screen contains a list of options, input fields and prompts, or scrollable data. The panel display format is shown next:

line 1 -->	Program Name	Title	Short Message
line 2 -->	Prompt or Input		Scroll Field

Line one of the application panel contains the panel title and short message area. The title line identifies the reason for the panel being displayed, and, where appropriate, data set information. The short message area displays the following information:

Current line number (in BROWSE)
Notice of successful completion of a processing function
Notice of an error condition (accompanied by an audible alarm, if one is installed on the terminal)
A frequency count in response to an Info line command

Line two, the prompt or input area, is used to enter an option, selection, or command.

You can scroll in any application panel containing a SCROLL field in line two. The application recognizes PAGE (P), HALF (H), MAX (M), or four numeric digits. The default is PAGE. Enter a numeric value in the SCROLL field to control the number of lines scrolled when a SCROLL key is pressed.

A scroll field value of cursor (CSR) is supported under CA InterTest Batch ISPF and CA Roscoe.

The application does not display ISPF long messages.

Program Function and Program Access Keys

For ISPF users, the application uses the PF keys as set from the ISPF option. For CA Roscoe users, the application uses the PF keys as set from the CA InterTest Batch Primary Option Menu.

Program Access Keys

The program access keys are defined as follows:

ATTENTION (PA1)	Interrupts the currently executing program and displays the ATTENTION INTERCEPT panel at the next executable statement in a monitored program. If the program is in a loop, you may need to press RESET before pressing PA1.
RESHOW (PA2)	Redisplays the contents of the screen. It may be useful if the CLEAR key was pressed accidentally, or if unwanted information has been typed but the Enter key (or a PF key) has not yet been pressed.

Note: The ATTENTION key can be either the PA1 key or the ATTN key, depending on the terminal type and how it is attached to the system.

Command Syntax Definition

The command syntax is described next. Valid long names and short names are shown in the examples of each command.

The following notation conventions are used to illustrate application commands:

Uppercase letters and special characters are entered as shown.
Lowercase italic letters are a generic description of a variable parameter's value.
Brackets (< >) enclose optional values.
Vertical bars (|) separate alternatives.
Ellipses (...) specify that a parameter can be repeated.
Default values are underlined.

Enter commands in uppercase or lowercase. Some commands can be abbreviated. The shortest abbreviation is the short name. If no short name is shown, you cannot abbreviate the command. You can abbreviate a long name a letter at a time down to the short name. All abbreviated versions of the command are valid.

Synonyms

Some commands have synonyms that you may find easier to remember, especially if you are a CA InterTest for CICS user. These synonyms can be used interchangeably. For example, you can enter the AT command, which sets an unconditional breakpoint, as UNCOND. As another example, you can enter LDI, which lists a data item in a keep window, as KEEP.

COBOL Statement Numbers

Some commands require a statement number in the command's syntax. For COBOL programs, these are the statement numbers that have been generated by the COBOL compiler. The compiler-generated statement numbers are the ones farthest to the left in the compilation listings and in application displays. These numbers must be used in all commands that require a statement number.

Assembler Offsets

When debugging an Assembler program, set breakpoints by using the statement number, as in COBOL programs, or by using the offset. When using an offset, the offset must be prefixed by the + sign.

For example, you may set a breakpoint at offset 78 by entering AT +78 in the Command area of the Intercept panel. Or use the Breakpoint panel and enter S in the Option field and +78 in the Statement field.

Debug Optimized Applications

This product supports the debugging of programs that have been optimized, either by the COBOL compiler's OPTIMIZE option or by
CA Optimizer or CA Optimizer/II. However, debugging these programs can sometimes result in unexpected behavior.

Note: The PL/I compilers are optimizing compilers.

Often as part of the optimization process, a compiler relocates individual instructions, statements, or even entire paragraphs so that the optimized program runs more efficiently. This means that some or all of the instructions generated for a given statement may be moved to another statement, or that some or all of the statements in a paragraph may be moved to another paragraph. When this type of optimization occurs, the resulting object program and corresponding listing may not accurately represent the relationship between the source statements and their generated object code, or even between a paragraph label and the statements contained within the paragraph. As a result, there may be times when the breakpoint intercept does not occur, or when the wrong sequence of statements appears to be executed while single‑stepping. There may also be times when the debugger appears to highlight the wrong statement at a breakpoint intercept.

These unexpected displays do not indicate that a program is being executed incorrectly. They simply indicate that the debugger sometimes cannot accurately identify exactly which object code corresponds to which source statement, or which statement is contained within which paragraph.

The application uses the information in the compiler-generated procedure map or offset report to establish the program offset for each statement and label in the program. During execution, the debugger recognizes the start of the new statement or label by matching the program offset of the currently executing instruction with the PROTSYM information obtained from the compiler listing. Therefore, the accuracy with which the debugger can represent a breakpoint or other intercept is only as good as the information in the compiler listing.

Inaccuracies may include, but will not be limited to the following instances:

Incorrect execution when using the SKIP, GO stmt# or CS stmt# commands
Failure to stop at a breakpoint at a paragraph label or statement
Unexpected or out of sequence highlighting of statements when single‑stepping

Additionally, application abends may result from the use of the SKIP, GO stmt#, or CS stmt# commands because the optimized object code may have register requirements that do not support changes to the flow of control. These commands should be avoided when debugging an optimized program.

For the best debugging results, avoid using optimization whenever possible in your testing environment. Production applications may be compiled with optimization, and debugging these applications, as they exist without recompiling, is supported. However, be aware that you may experience some of the inaccuracies listed previously under these circumstances.

Primary Option Menu

The Primary Option Menu for ISPF users is displayed when you select the option on the ISPF/PDF Primary Option Menu.

You can access the following options from the Primary Option Menu:

1–Foreground: Test a program in foreground
2–Core: Display and alter virtual storage
3–Allocation: Allocations and JCL conversion
4–Map: Address space map
5–Batch: Batch link facility
U–Utilities: Symbolic utilities and preferences
X–Exit: Terminate the session

The Primary Option Menu for CA Roscoe users is displayed when you either select the CA InterTest Batch Option on the CA Roscoe menu or enter the following commands:

[xxx.]IBALLOC
[xxx.]IBRUN

where xxx is the prefix of the library where the application is installed. Omit this prefix if the application is installed in a common execution library.

You can access the following options from the Primary Option Menu for CA Roscoe:

1–Foreground: Test a program in foreground
2–Core: Display and alter virtual storage
4–Map: Address space map
5–Batch: Batch link facility
K–Keys: Display PF Keys
U–Utilities: Symbolic utilities and preferences
X–Exit: Terminate the session

System Structure

The following table shows the options. Availability of individual options depends on whether you are using ISPF or CA Roscoe. The application's primary function is option 1, Foreground. Other options are provided to support the test and debug facility, as shown in the following table:

Option	Name	Description
Option 1	Foreground	Lets you set up and control a test execution of a program.
Option 2	Core	Displays virtual memory in hexadecimal and character format. Use SCROLL keys and commands to locate and find data in virtual storage. Note: The application lets the programmer display/modify data with various commands. If it is necessary to place invalid data in a variable, use the Core Option.
Option 3	Allocation	Lets ISPF users allocate ddnames and allows conversion of JCL into a CLIST or ALIB.
Option 4	Map	Provides several address space-related displays that are most often used to debug complex system-related problems.
Option 5	Batch	Lets you set up and test a program to be executed in Batch.
Option K	Keys	Lets CA Roscoe users set their PF keys for CA InterTest Batch. Type over the default assignments on the PF Key Definition panel and press Enter to change the PF keys. The default key assignments are as follows: PF1–Help PF2–Split PF3–End PF4–Return PF5–Find PF6–Go PF7–Up PF8–Down PF9–Swap PF10–Left PF11–Right PF12–Print Valid PF key commands are HELP, SPLIT, END, RETURN, FIND, GO, UP, DOWN, SWAP, LEFT, RIGHT, and PRINT.
Option U	Utilities	Provides the ability to display and update the contents of your PROTSYM file. Also lets you define which programs are to be excluded from auto-monitoring.
Option X	Exit	Terminates the application. The ISPF End key (normally PF3) or CA Roscoe End Key (normally PF4) also terminate the application from the Main Menu.
ISPF-HELP	Help	Displays the Tutorial Table of Contents from the Primary Option Menu. The tutorial summarizes the features and commands. You can page through the tutorial or select a subject from the Tutorial Table of Contents.