Easytrieve DISPLAY for Debugging

Why DISPLAY Fits Debugging

Debugging is the art of comparing what you expected with what happened. Easytrieve hides much iteration inside JOB INPUT loops and report procedures, so the executing program can feel like a black box. DISPLAY opens the box one line at a time. Because DISPLAY does not require a REPORT definition, you can insert a trace in minutes, recompile, and see output on the next test run. When the defect is fixed, you remove or comment out the trace. That short feedback loop is why experienced mainframe developers still reach for DISPLAY even when interactive debuggers exist elsewhere in the data center.

DISPLAY is not a replacement for structured logging products or for ABEXIT Error Analysis after an abend. It is a low-ceremony trace mechanism you control in source. Pair DISPLAY with compile listings so you know which statement numbers correspond to your traces if FLOW or STATE options are also enabled.

Default Output Destination: SYSPRINT

When you code DISPLAY without naming a file, Broadcom sends the line to SYSPRINT, the default system print file. In batch, SYSPRINT is almost always allocated in JCL with a spool class or a temporary data set. That is why beginners can add DISPLAY 'HELLO' and see output without defining a new FILE. The visible location—SDSF, a held queue, a development class, or a permanent data set—is determined by your JCL and site rules, not by the DISPLAY statement alone.

1
2
3
4
5
6
//DBGTEST  EXEC PGM=INVRPT
//STEPLIB  DD  DSN=DEV.APP.LOADLIB,DISP=SHR
//         DD  DSN=DEV.EZT.CBAALOAD,DISP=SHR
//INVFILE  DD  DSN=DEV.INVENTORY.SAMPLE,DISP=SHR
//SYSPRINT DD  SYSOUT=*
//INVREP   DD  SYSOUT=A

Diagnostic DISPLAY lines typically appear in the SYSPRINT stream, while the business report routes to INVREP. If you search the wrong DD in SDSF, you will conclude DISPLAY is broken when it simply wrote to a different output stream. Always confirm which DD names your program uses before debugging output routing.

Naming a Display File in JOB Logic

In JOB activities you may optionally code a display-file-name on DISPLAY to write to a named sequential output file defined in your program and allocated in JCL. That pattern separates bulky debug traces from SYSPRINT so operators can discard a DEBUG DD without losing critical abend messages. Whether a given file name is valid depends on your FILE definitions and JCL. If you use a named debug file, document its DD in test JCL only and remove it from production unless operations approves permanent diagnostic data sets.

1
2
3
4
FILE DEBUGTRK FB(80 800)
JOB INPUT INVFILE
  DISPLAY DEBUGTRK 'REC' REC-COUNT EMPNO QTY
  REC-COUNT = REC-COUNT + 1

Here DISPLAY writes trace lines to DEBUGTRK instead of SYSPRINT. JCL must allocate DEBUGTRK with appropriate space and disposition for test. This pattern keeps SYSPRINT readable when traces fire on every input record.

Tracing Branches and Counters

The most common DISPLAY debugging pattern labels a branch. When an IF condition selects records, display a short literal, the key fields, and a counter so you can verify the branch executed the expected number of times. Counters should be ordinary numeric fields initialized in working storage or reset at job start. Seeing SELECT-COUNT = 0 when you expected thousands immediately tells you the condition is wrong or the input order differs from your assumption.

1
2
3
4
5
6
7
8
9
JOB INPUT PERSNL
  READ-COUNT = READ-COUNT + 1
  IF DEPT = 100
     SEL-COUNT = SEL-COUNT + 1
     DISPLAY 'DEPT100' EMPNO DEPT SEL-COUNT
  END-IF
  IF READ-COUNT = 1
     DISPLAY 'FIRST REC' EMPNO DEPT
  END-IF

FIRST REC confirms layout and file open success on the initial record. DEPT100 lines prove the branch fires and show how many selects occurred. Keep literals short and distinctive so you can search SYSPRINT quickly.

Entry and Exit Markers

For procedures, paragraphs, or complex paragraph groups, bookend markers reduce confusion about whether execution reached a section. Display a literal on entry, another before RETURN, and a third after unexpected paths. This pattern is especially helpful when multiple PERFORM or CALL paths exist and FLOW tracing is disabled to save overhead.

1
2
3
4
5
6
7
8
CALC-TAX. PROC
  DISPLAY '>> CALC-TAX ENTER' EMPNO
  TAX = GROSS * RATE
  IF TAX < 0
     DISPLAY '!! NEG TAX' EMPNO GROSS RATE TAX
  END-IF
  DISPLAY '<< CALC-TAX EXIT' TAX
END-PROC

Angle brackets in literals are a visual convention only; Easytrieve prints them as text. If you see ENTER without EXIT for the same employee key, you know control left the procedure abnormally or branched elsewhere before END-PROC.

DISPLAY HEX for Packed and Binary Data

Normal DISPLAY formats fields according to their definitions and masks. Packed decimal, binary, and bit data often print as unexpected characters or apparent blanks. DISPLAY HEX prints the underlying bytes in hexadecimal, which is the standard mainframe approach for inspecting numeric encodings without a full storage dump. Use HEX on the smallest field that is suspect first; dump entire records only when record layout itself is in question.

1
2
3
4
5
IF GROSS = 0 AND HOURS > 0
   DISPLAY 'ZERO GROSS CHECK' EMPNO
   DISPLAY HEX GROSS
   DISPLAY HEX HOURS
END-IF

This trace catches logical inconsistency—hours worked with zero gross pay—and shows whether GROSS is truly zero in packed form or whether a data exception is imminent because the field contains non-numeric bytes.

HEX format reminder

The statement reference documents a separate HEX format of DISPLAY rather than an option on the standard item list. Syntax details appear on the DISPLAY statement page for your release. Do not confuse DISPLAY HEX with ABEXIT SNAP dumps; HEX is a controlled field view, not a capture of the entire address space.

Spacing and Columns for Readable Traces

Unformatted DISPLAY output becomes unreadable when many lines print without structure. Use SKIP to separate sections and COL to align keys and amounts in fixed columns. SKIP 0 overprints the previous line and is rarely useful in modern debugging; prefer explicit column positioning instead. CONTROL carriage control is uncommon in contemporary batch debugging but remains documented for specialized printer environments.

DISPLAY in Report Procedures

Report procedures introduce restrictions beginners stumble on. Broadcom documents that DISPLAY inside report procedures writes only to the system output device, not to arbitrary named data files. DISPLAY lines may also interact with report sequencing—appearing before the first title or interleaved with report activity depending on context. When debugging a report procedure, start with a few DISPLAY lines at BEFORE-LINE or AFTER-LINE hooks with short literals, then expand. If output seems missing, verify you are reading SYSPRINT rather than the formatted report DD.

1
2
3
4
5
REPORT PAY-RPT
  BEFORE-LINE
     DISPLAY 'DETAIL' EMPNO DEPT
  AFTER-LINE
     LINE-CNT = LINE-CNT + 1

This shows each detail line selection on SYSPRINT while the formatted report still routes through PRINT to its report file. You can compare whether PRINT fired for records you expected.

Online and Screen Programs

Screen activities introduce terminal output paths that differ from batch spool. DISPLAY behavior in online Easytrieve may not land in the same SYSOUT classes you use for nightly batch. Some shops route online diagnostics to a log data set, a terminal screen in test mode, or a vendor trace facility. Because this varies by release and installation, treat online DISPLAY destinations as a site question: ask which DD or log file captures diagnostics for screen programs in your test region before assuming batch JCL patterns apply unchanged.

Performance and Data Protection

DISPLAY inside tight loops on million-record files can multiply job time and spool use. Guard traces with conditions so they print only when an error flag is set, on the first N records, or for a known test key. Never print national identifiers, salaries, or account numbers in production SYSPRINT unless policy allows it; use masked fields or test data subsets. Operations teams have rejected promotions because a developer left verbose DISPLAY in a payroll loop.

• Trace on error flags rather than unconditionally on every record when possible.
• Use a dedicated DEBUG DD for high-volume traces in test JCL.
• Remove or disable traces before production promotion.
• Coordinate with dump analysis practices when DISPLAY precedes an abend—SYSPRINT preserves last traces.

DISPLAY vs Other Diagnostic Tools

DISPLAY complements other techniques. Compiler listings catch syntax and many data definition errors before run time. PARM DEBUG STATE and FLOW help after abends. DISPLAY fills the gap during successful or partially successful runs when you need to see intermediate values. Neither DISPLAY nor FLOW replaces the other: DISPLAY shows data values you choose; FLOW shows statement numbers the product recorded.

When to choose each tool

1. Use DISPLAY when logic runs but results look wrong and you need field-level evidence.
2. Use DISPLAY HEX when numeric fields look corrupt or S0C7 is suspected on specific data.
3. Use DEBUG FLOW when execution path is unclear and you can rerun in test with PARM changes.
4. Use Error Analysis when the step already abended and ABEXIT is active.

Cleaning Up Before Production

Treat debug DISPLAY as temporary instrumentation. Before merge to production source libraries, search members for DISPLAY literals you added during investigation. Some teams wrap test-only traces in a flag field set from PARM or a control card; others require complete removal. Also remove test-only DEBUG DD statements from JCL procs so schedulers do not allocate unused data sets. Code review checklists should include a DISPLAY sweep for payroll, healthcare, and financial applications where spool exposure creates compliance risk.

Explain It Like I'm Five

DISPLAY is like shouting a note to yourself while you work. You say, I am on step three, the box count is twelve, and this label looks wrong. You shout to the SYSPRINT notebook, which is taped to the wall where you can read it after the job finishes. HEX is like drawing the secret dots on the label so you can see the real pattern. When the job is fixed, you stop shouting because the wall is full of notes and other people should not see private information.

Exercises

1. Add entry and exit DISPLAY markers around a procedure that calculates tax.
2. Write a guarded trace that prints only when READ-COUNT is less than or equal to 5.
3. Design JCL with separate SYSPRINT and DEBUGTRK DDs and explain which traces go where.
4. Use DISPLAY HEX to investigate a zero balance with nonzero activity.
5. List three reasons to remove debug DISPLAY before production.

Exercise Answers

Exercise 1

Wrap the procedure with DISPLAY '>> TAX ENTER' key-field before calculations and DISPLAY '<< TAX EXIT' result-field after calculations. If ENTER appears without EXIT for the same key, execution left early through an IF branch or abnormal termination before END-PROC.

Exercise 2

Code IF READ-COUNT <= 5 DISPLAY 'SAMPLE' READ-COUNT key-fields END-IF inside the input loop. Only the first five records print, limiting spool volume while you validate layout and basic field values.

Exercise 3

Keep routine messages and abend-related output on SYSPRINT DD SYSOUT=*. Route per-record traces to DEBUGTRK DD with a modest space allocation and DISP suitable for test discard. High-volume traces go to DEBUGTRK; operators retain familiar SYSPRINT for failure triage.

Exercise 4

When balance is zero but activity count is positive, DISPLAY a literal identifying the condition, print readable keys, then DISPLAY HEX on the packed balance and activity fields. Compare hex patterns to valid packed zero versus unreadable nybbles that predict S0C7.

Exercise 5

Debug DISPLAY increases spool volume and job time, may expose sensitive fields on SYSOUT, and clutters operator review of real failures. Production jobs should emit only approved diagnostics.

Frequently Asked Questions