CL Programming

Traces

A trace is the process of recording the sequence in which the statements in a program are processed. A trace differs from a breakpoint in that you are not given control during the trace. The system records the traced statements that were processed. However, the trace information is not automatically displayed when the program completes processing. You must request the display of trace information using the Display Trace Data (DSPTRCDTA) command. The display shows the sequence in which the statements were processed and, if requested, the values of the variables specified on the Add Trace (ADDTRC) command.

Adding Traces to Programs

Adding a trace consists of specifying what statements are to be traced and, if you want, the names of program variables. Before a traced statement processes, the value of the variable is recorded. Also, you can specify that the values of the variables are to be recorded only if they have changed from the last time a traced statement was processed. These variables can be displayed in character format or hexadecimal format.

To specify which statements are to be traced, you can specify:

On the STRDBG or CHGDBG command, you can specify how many statement traces can be recorded for a job and what action the system should take when the maximum is reached. When the maximum is reached, the system performs one of the following actions (depending on what you specify):

You can change the maximum and the default action any time during the debug job using the Change Debug (CHGDBG) command. However, the change does not affect traces that have already been recorded.

You can only specify a total of five statement ranges for a single program at any one time, which is a total taken from all the Add Trace (ADDTRC) commands for the program. In addition, only 10 variables can be specified for each statement range.

In high-level language programs, different statements and labels may be mapped to the same internal instruction. This happens when there are several inoperable statements (such as DO, END) following one another in a program. You can use the IRP list to determine which statements or labels are mapped to the same instruction.

When you specify CL variables, you must enclose the & and the variable name in single apostrophes. For example:

ADDTRC PGMVAR('&IN01')

When you specify a statement range, the source statement number for the stop statement is ordinarily larger than the number for the start statement. Tracing, however, is performed with machine interface (MI) instructions, and some compilers (notably RPG/400) generate programs in which the order of MI instructions is not the same as the order of the source statements. Therefore, in some cases, the MI number of the stop statement may not be larger than the MI number of the start statement, and you will receive message CPF1982.

When you receive this message, you should do one of the following:

The following Add Trace (ADDTRC) command adds a trace to the program CUS310. CUS310 is the default program, so it does not have to be specified. The value of the variable &TOTBAL is recorded only if its value changes between the times each traced statement is processed.

ADDTRC STMT((900 2700))  PGMVAR('&TOTBAL')  OUTVAR(*CHG)

The following displays result from this trace and are displayed using the Display Trace Data (DSPTRCDTA) command. Note that column headers are not supplied for all displays.

+--------------------------------------------------------------------------------+
|                            Display Trace Data                                  |
|                                                                                |
|                 Statement/                                                     |
|Program          Instruction           Recursion level       Sequence number    |
|CUS310           900                          1                           1     |
|                                                                                |
| Start position  . . . . . . . . . . . . :   1                                  |
| Length  . . . . . . . . . . . . . . . . :   *DCL                               |
| Format  . . . . . . . . . . . . . . . . :   *CHAR                              |
|                                                                                |
| Variable  . . . . . . . . . . . . . . . :   &TOTBAL                            |
|   Type  . . . . . . . . . . . . . . . . :     PACKED                           |
|   Length  . . . . . . . . . . . . . . . :     5 2                              |
|  '    .00'                                                                     |
|                                                                                |
|                 Statement/                                                     |
|Program          Instruction           Recursion level       Sequence number    |
|CUS310           1000                         1                           2     |
|CUS310           1100                         1                           3  +  |
|                                                                                |
|Press Enter to continue.                                                        |
|                                                                                |
|F3=Exit   F12=Cancel                                                            |
|                                                                                |
+--------------------------------------------------------------------------------+
+--------------------------------------------------------------------------------+
|                            Display Trace Data                                  |
|                                                                                |
|                                                                                |
| Start position  . . . . . . . . . . . . :   1                                  |
| Length  . . . . . . . . . . . . . . . . :   *DCL                               |
| Format  . . . . . . . . . . . . . . . . :   *CHAR                              |
|                                                                                |
|*Variable  . . . . . . . . . . . . . . . :   &TOTBAL                            |
|   Type  . . . . . . . . . . . . . . . . :     PACKED                           |
|   Length  . . . . . . . . . . . . . . . :     5 2                              |
|  '   1.00'                                                                     |
|                                                                                |
|                 Statement/                                                     |
|Program          Instruction           Recursion level       Sequence number    |
|CUS310           1600                         1                           4     |
|CUS310           1700                         1                           5     |
|CUS310           2100                         1                           6     |
|CUS310           2200                         1                           7     |
|CUS310           2600                         1                           8  +  |
|                                                                                |
|Press Enter to continue.                                                        |
|                                                                                |
|F3=Exit   F12=Cancel                                                            |
|                                                                                |
+--------------------------------------------------------------------------------+
+--------------------------------------------------------------------------------+
|                            Display Trace Data                                  |
|                                                                                |
|CUS310           2700                         1                           9     |
|                                                                                |
| Start position  . . . . . . . . . . . . :   1                                  |
| Length  . . . . . . . . . . . . . . . . :   *DCL                               |
| Format  . . . . . . . . . . . . . . . . :   *CHAR                              |
|                                                                                |
|*Variable  . . . . . . . . . . . . . . . :   &TOTBAL                            |
|   Type  . . . . . . . . . . . . . . . . :     PACKED                           |
|   Length  . . . . . . . . . . . . . . . :     5 2                              |
|  '   2.00'                                                                     |
|                                                                                |
|                                                                                |
|                                                                                |
|                                                                                |
|                                                                                |
|                                                                                |
|                                                                                |
|                                                                                |
|Press Enter to continue.                                                        |
|                                                                                |
|F3=Exit   F12=Cancel                                                            |
|                                                                                |
+--------------------------------------------------------------------------------+

Instruction Stepping

You can step through the instructions of a program by using the STRDBG or CHGDBG commands and setting the MAXTRC parameter to 1 and the TRCFULL parameter to *STOPTRC. When you specify a trace range (ADDTRC command) and the program processes an instruction within that range, a breakpoint display with an error message appears. If you press Enter, another breakpoint display with the same error message appears for the next instruction processed in the trace range. When tracing is completed, the trace data contains a list of the instructions traced. You can display this data by entering the Display Trace Data (DSPTRCDTA) command.

Using Breakpoints within Traces

Breakpoints can be used within a trace range. At a breakpoint within a trace, you can display the trace data (DSPTRCDTA command) to determine if you need to take some action. The trace data is recorded before the breakpoint occurs. The trace information contains the value of any variables before the statement was processed.

Removing Trace Information from the System

On the DSPTRCDTA command, you can specify whether the trace information is removed from the system or left on the system after the information is displayed. If you leave the trace information on the system, any other traces are added to it. The information remains on the system (unless removed) until the debug job ends or the ENDDBG command is submitted. You can also use the Clear Trace Data (CLRTRCDTA) command to remove trace information from the system.

Removing Traces from Programs

The Remove Trace (RMVTRC) command removes all or some of the ranges specified in one or more Add Trace (ADDTRC) commands. Removing a trace range consists of specifying the statement identifiers used on the RMVTRC command, or specifying that all ranges be removed.

You can use the STMT parameter on the RMVTRC command to specify:

The RMVPGM and ENDDBG commands also remove traces, but they also remove the program from debug mode.


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]