Easytrieve Tracing

Compile Time Versus Runtime, One More Time

Every Easytrieve run has two phases. The compiler phase reads your source, checks it, and prints the listing. The execution phase runs the checked program against your files. Tracing lives entirely in the second phase. That is why you can have a perfectly clean compiler listing with a return code of zero and still get wrong results: the code is well formed, but the logic did something you did not intend when it met real data. Tracing is how you catch those logic problems, because it lets you observe behavior instead of guessing about it.

The DISPLAY Statement: Tracing You Fully Control

The most reliable tracing tool for a beginner is the DISPLAY statement, because it does exactly what you tell it, wherever you place it, without depending on which debug options a site enables. You put a DISPLAY at a point of interest and it writes a message or the current value of one or more fields. That gives you a precise, readable timeline of the values your program worked with.

1
2
3
4
5
6
7
8
9
10
11
12
13
FILE PERSNL
  EMP-NAME  17 8 A
  EMP-GROSS 25 4 P 2
 
JOB INPUT PERSNL
  DISPLAY 'TRACE: READ ' EMP-NAME ' GROSS=' EMP-GROSS
  IF EMP-GROSS GT 5000
     DISPLAY 'TRACE: HIGH EARNER ' EMP-NAME
  END-IF
  PRINT REPT
 
REPORT REPT
  LINE EMP-NAME EMP-GROSS

Each time a record is read, the first DISPLAY prints the name and gross value the program is currently holding, so you can confirm the field is being read from the right position with the right value. The second DISPLAY only fires for high earners, giving you a filtered trace of just the records that took a particular branch. This pattern — a general trace plus a conditional trace — is often all you need to pinpoint where results diverge from expectations.

Guarding DISPLAY So It Does Not Flood the Output

A DISPLAY inside the main JOB loop runs once per record, so on a large file it can produce an enormous amount of output. Guard it with a condition so it only prints for the cases you are investigating, for example a specific key, a suspicious value range, or the first few records.

1
2
3
4
5
JOB INPUT PERSNL
  IF EMP-NAME = 'SMITH'
     DISPLAY 'TRACE: FOUND SMITH GROSS=' EMP-GROSS
  END-IF
  PRINT REPT

Here the trace only appears for the record you care about, which keeps the output small and the signal clear. When your investigation is finished, remove or comment out the DISPLAY statements so they do not clutter production output or add overhead.

Automatic Flow and Statement Tracing

Beyond DISPLAY, Easytrieve can produce automatic tracing that follows the flow of control without you hand-placing statements. A flow trace records the path execution took through procedures and activities; a statement-level trace can report statement numbers as they execute, which is especially useful for pinpointing where an abend occurred. This behavior is requested through debug options in the parameter area and is governed by the installation options module. The example below shows the general shape; treat the keyword as illustrative because the available option names, their sub-parameters, and defaults are installation and release dependent.

1
2
3
4
5
6
7
8
9
10
11
12
* Example parameter statement requesting runtime debug behavior.
* Keyword names and sub-options are release/installation dependent.
PARM  DEBUG (FLOW STATE)
 
FILE PERSNL
  EMP-NAME 17 8 A
 
JOB INPUT PERSNL
  PRINT REPT
 
REPORT REPT
  LINE EMP-NAME

In this sketch, a flow-style option asks the runtime to record the path of execution, and a statement-state style option asks it to keep track of the current statement so that a failure can report where it happened. Whether these specific keywords exist and how they behave depends entirely on your release and site configuration. Always confirm the exact spelling, the valid sub-options, and the defaults in the Broadcom Easytrieve reference for your version, and check whether your systems programmers have restricted them.

Reading Trace Output

Automatic trace output typically appears in the runtime message or print output of the execution step, which may be a different destination than the compiler listing. When you read it, work from the top down and correlate statement numbers back to the compiler source listing, exactly as you would with a diagnostic message. The trace tells you the order in which things ran; the source listing tells you what each numbered statement is. Reading them side by side is the fastest way to reconstruct what the program did.

Choosing the Right Tracing Approach

A Worked Example: Finding a Wrong Total

Imagine a report total is higher than expected, and you suspect a few records with a bad amount are being included. Rather than trace every record, you add a guarded DISPLAY that only prints records above a plausible ceiling, so the trace instantly surfaces the culprits.

1
2
3
4
5
JOB INPUT PERSNL
  IF EMP-GROSS GT 100000
     DISPLAY 'TRACE: SUSPECT ' EMP-NAME ' GROSS=' EMP-GROSS
  END-IF
  PRINT REPT

When you run this, only the suspicious records appear in the trace, complete with the name and amount. If those amounts are genuinely wrong, you have found a data problem; if they are correct but should have been excluded, you have found a logic problem in the selection criteria. Either way, a narrowly scoped trace turned a vague symptom into a concrete list of records to examine — far more efficient than tracing millions of rows.

Safe Tracing Practices

1. Prefer targeted, guarded DISPLAY over blanket statement tracing on large files.
2. Trace only the records, procedures, or value ranges you are investigating.
3. Correlate trace statement numbers with the compiler source listing to interpret them.
4. Confirm debug option keywords and defaults against your release and site standards.
5. Remove or disable tracing once the investigation is complete.
6. Be mindful of output volume and CPU overhead when tracing in shared environments.

Common Mistakes

• Expecting trace output in the compiler listing instead of the runtime output.
• Leaving an unguarded DISPLAY in the main loop and flooding the spool.
• Assuming a specific debug keyword exists when the site disabled or renamed it.
• Confusing a compile-time cross-reference with a runtime flow trace.
• Forgetting to remove tracing before promoting code to production.
• Reading trace numbers without the source listing to interpret them.

Explain It Like I'm Five

Pretend your toy robot walks across the room and does something wrong. Reading the instructions you gave it beforehand is like the compiler listing. But to see what the robot really did, you put little sticky notes on the floor that say “robot was here” so you can follow its footsteps afterward. Those sticky notes are like DISPLAY tracing. If you put a note on every single tile, the floor gets covered and you cannot see anything, so you only put notes where you think the robot went wrong. That way you follow just the important footsteps.

Quick Recap of the Big Idea

Tracing happens while the program runs, not while it is being checked. DISPLAY is the simple, always-works way to watch values, and you should guard it so it does not print too much. Automatic flow and statement tracing exist too, but the exact option names depend on your version and your shop, so check before you rely on them.

Exercises

1. Add a DISPLAY to print a field value for every record, then run it on a tiny file.
2. Rewrite that DISPLAY so it only prints for one specific key value.
3. Explain in one sentence why a flow trace is runtime and a cross-reference is compile-time.
4. Describe how you would find which records inflate a report total using a guarded DISPLAY.
5. List two reasons heavy statement tracing can be risky on a large production file.