Testing Procedures › Guidelines for Novice Users

Guidelines for Novice Users

This chapter provides an overview and checklist for novice users of the Foreground option. The following sections assist you in preparing your programs for testing and using the application panels and commands to test your programs. For detailed information on the application panels used with the Foreground Option, see the chapter “Debugging Panels”, and for detailed information concerning the commands used with the Foreground Option, see the chapter "Debugging Commands."

Preparation for Test Execution

Use the following steps to compile a program to be tested under the control of the application and to begin foreground test execution.

If you are testing an IMS program, first read this section, then read Testing IMS Applications. Also, if you are testing a DB2 application, see Testing IBM DB2 Applications. If you are testing an application that uses any database, batch link is the suggested method for debugging.

1. Compile the program that you wish to test using the procedure set up by your installer. This procedure has a post-compile step that generates the symbolic information needed to debug your program. Alternatively, you can do the following:
   • Add the symbolic information using the Utilities panel if you have the listing available.
   • Take advantage of the dynamic symbolic support feature, if you have CA Endevor SCM r7 SP2 or later installed.
2. Log in to TSO and enter the TSO command PROFILE WTPMSG. This command causes all messages that normally appear in the batch job log (write-to-programmer messages) to be sent to the terminal.

   If you place the PROFILE WTPMSG in the application CLIST, you will not need to reenter it each time you invoke the application.

3. Invoke the application (ask you technical support personnel for instructions, if needed).

   If you are testing an IMS or DL/I program, also review the instructions given in the section Testing IMS Applications.

   If you are testing under CA Roscoe, also review the instructions in the section Testing Under CA Roscoe.

4. When the Primary Option Menu displays, select Option 1: Foreground.
5. Fill in the relevant information on the Execution Control panel. Enter the name of the main program of the application that you want to debug, the execution parameters, if there are any, and the STEPLIB to be used for this test. If your execution JCL was converted to ALIB format, you can specify that ALIB data set and member here. Then all the information, described previously will be extracted from the ALIB file and the DDs that are required for execution will also be allocated. If you do not have an ALIB for this application, you will need to allocate any required DDs through the TSO ALLOC command or through Option 3: Allocate off of the Primary Option Menu.

   If you are testing an IMS or DL/I program, also review the instructions given in the section Testing IMS Applications.

6. Fill in the name of the program that you wish to debug in the Monitored Programs section of the Monitor Control panel. The name of the program is the PROTSYM member name for the program to be tested. Also fill in the data set name of the Symbolic file, the PROTSYM that was used when the program was compiled and post-processed. When all the information has been filled in, press Enter.

   If any of the programs specified on the Monitor Control panel are Visual Age PL/I for OS/390 programs and you entered a Y in the Monitor PL/I field, the PL/I PROTSYM/Load Module Map panel displays. Fill in the load module names for any PL/I programs that you want to debug.

   If you are using CA Endevor SCM to manage your load module and listing libraries, you can activate the dynamic symbolic support feature (DSS) by designating a PROTSYM file as the receiver for DSS post processor-created symbolic files. This reduces your pre-testing setup time and ensures you will always debug with the correct symbolic file associated with the load module being monitored.

   The execution of the application begins.

7. If no errors are encountered, the Initial Intercept panel displays. This is a display of the source statements beginning with the first executable statement. The title line should read *INITIAL* Intercept.
8. The program is ready to execute the application. Enter the GO command in the Command field and press Enter, or press the PF key set to GO.

   The program executes until one of the following conditions is encountered:

   • An abend occurs: The Intercept panel is displayed, highlighting the statement where the abend was detected.
   • The program runs to normal completion. The Execution Control panel displays with the return code in the upper right corner indicating that the run has completed.

Execute a Program Until an Error Occurs

When an abend occurs, use application commands to correct the bad data and continue the test.

For example, consider the following COBOL statements:

041600    MOVE +20       TO VARIABLE‑LENGTH‑1.
041700    MOVE FIELD1    TO SALARY‑TO‑DATE.
041800    MOVE +30       TO VARIABLE‑LENGTH‑3.

If FIELD1 contains invalid numeric data such as spaces, an S0C7 occurs when an attempt is made to execute statement 041700. When the S0C7 occurs, the Intercept panel displays: the abend reason code appears on the title line and statement 041700 is highlighted.

To check the contents of FIELD1, use the DISPLAY command to format and display WORKING STORAGE. To change the contents of FIELD1, move the cursor under the data displayed at the right of the data item, and key in the new value for the data item.

Press the END key to return to the Intercept panel. Then issue the GO command to resume the test session.

Stop a Looping Program

Press the Attention key or PA1 key to stop a looping program. This causes the debugger to stop execution at the next executed statement. The Attention key works for terminals that are attached to the system through an SNA controller. The PA1 key works for terminals attached to the system using other means. To have the PA1 key work on most terminals, you must first press the RESET key.

If you cannot locate the Attention or RESET and PA1 keys, ask your technical support person for assistance.

Note: If you are attempting to break from a looping program and the PA1 key does not work, press RESET and then the PA1 key.

Trace a Program in Reverse

A program can be stepped backward from the point of an abend to determine the cause of the abend condition.

Use the PREV command to trace the program's execution in reverse. The PREV command does not affect the contents of the application's variables. It also does not change the location where the GO command will resume execution.

To view the statement that has been executed, enter P or PREV in the Command field of the Intercept panel and press Enter.

Stop a Program at a Particular Statement

Stop a program at selected statements by setting unconditional breakpoints at those statements. From the Intercept panel, locate the statement where the program will be stopped, then use the U line command or the UNCOND command to set the unconditional breakpoint. To access the Intercept panel, review the Preparation for Test Execution section.

For example, consider the following COBOL statements:

041400  0000‑INITIALIZATION SECTION.
041500
041600       MOVE +20 TO VARIABLE‑LENGTH‑1.
041700       MOVE +25 TO VARIABLE‑LENGTH‑2.

041800       MOVE +30 TO VARIABLE‑LENGTH‑3.

The program is stopped at the first line of this code so that you can examine the value of the VARIABLE‑LENGTH variables used in the next three lines.

Set the breakpoint by typing a U in the left margin where the breakpoint will be set. In this example, type a U at statement 41400 and press Enter. Type GO and press Enter.

Use the UNCOND command also to set the breakpoint. It is especially useful if you want to automatically execute commands at the breakpoint. Assume that VARIABLE‑LENGTH‑4 was a data‑item that should have been initialized in this paragraph. The MOVE +45 TO VARIABLE‑LENGTH‑4 statement was omitted from the program source code. Add the statement by setting a breakpoint and specifying the SET command on the UNCOND command.

Set the breakpoint using either of the following UNCOND command formats:

UNCOND 41400 (SET VARIABLE‑LENGTH‑4 = +45)
    or
UNCOND 0000‑INITIALIZATION (SET VARIABLE‑LENGTH‑4 = +45)

Press Enter to set the breakpoint and then issue the GO command to execute the program. When the program begins execution of statement 041400, the Intercept panel displays. The title line reads BREAKPOINT INTERCEPT and line 041400 is highlighted. The Breakpoint Intercept panel displays before the statement is executed. The assignment of +45 to VARIABLE‑LENGTH‑4 has been done automatically.

Stop at a Statement and Step by Verb

Step through a section of code by setting unconditional breakpoints at particular statements and then use the STEP and GO commands to execute each verb. For example, consider the following statements:

049400  DIVIDE CONV‑YEAR BY 4
049500      GIVING CONV‑LEAP‑COUNT
049600      REMAINDER CONV‑LEAP‑REMAINDER.
049700  ADD +1 TO CONV‑LEAP‑COUNT.
049800  IF CONV‑LEAP‑REMAINDER IS EQUAL TO ZERO
049900      THEN
050000      SUBTRACT +1 FROM CONV‑LEAP‑COUNT.
050100
050200  IF CONV‑DAY IS NOT EQUAL TO ZERO
050300      THEN
050400      SUBTRACT +1 FROM CONV‑DAY.
050500
050600  COMPUTE CONV‑TOD =
050700      (((((((CONV‑YEAR * 365) + CONV‑LEAP‑COUNT + CONV‑DAY)
050800      * 24) + CONV‑TIME‑HOUR) * 60) * CONV‑TIME‑MINUTE)
050900      * 60) + CONV‑TIME‑SST.
051000

Assume that one of the IF clauses in the previous example is not functioning as expected. Step through this section of the code by using the following command sequence:

Assume that statement 050600 has been reached and you want to execute the program until this loop is reentered without entering GO commands for each statement. To reset the program to normal execution, you must turn off the step count and enter the GO command once more:

Note: As an alternative to using the STEP 1 command in conjunction with the GO command, you can use the NEXT command. This command executes up to the next verb.

Stop a Program When a Subscript Overflows

Many S0C4 abends are caused by a subscript exceeding its expected range (overflowing). This causes unrelated data in a program to be overlaid or garbled. The application can stop a program when a particular data item contains or exceeds a value or another data item. This is done by setting a conditional breakpoint using the WHEN command.

For example, assume that subscript SUBS1 is exceeding its range (1 through 30). To stop the program at the statement where SUBS1 exceeds 30, enter the following command:

WHEN SUBSCRIP SUBS1 GT 30

This command stops the program when SUBS1 is greater than 30. The character string SUBSCRIP in the command is the name assigned to the WHEN condition. It is displayed in the title of the W when‑name Intercept panel whenever this condition is encountered; for example, the title of the Intercept panel reads:

WHEN SUBSCRIP BEFORE INTERCEPT

The when‑name identifies which WHEN condition was encountered. The when‑name can also be a statement number. For example, assume that SUBS1 is updated in statement 15200 and that SUBS1 exceeds its range.

Enter the WHEN condition as follows:

WHEN 15200 SUBS1 GT 30

This way the condition will only be checked when the specified statement number is being executed.