Easytrieve DISPLAY Statement

Statement Format

The Broadcom Easytrieve 11.6 Language Reference documents two formats for DISPLAY. The first is the standard data format used for printing fields and literals; the second is the HEX format used for hexadecimal dumps. This is the standard format:

1
2
3
4
5
6
7
8
9
10
11
        [display-file-name] [{TITLE | NOTITLE}]
DISPLAY [                 ] [SKIP skip-integer]                    +
        [SYSPRINT         ] [CONTROL 'carriage-control-character']
 
        [ [            ] field-name ]
        [ [#font-number]            ]
        [ [            ] 'literal'   ]
        [ +offset                   ] ...
        [ -offset                   ]
        [ COL column-number         ]
        [ POS position-number       ]

Reading it left to right: you optionally name the file, optionally control the page and spacing, then list one or more items to print. Everything in square brackets is optional, and the ellipsis means you can repeat the item list as many times as fits on the line. The plus sign at the end of the first block is an Easytrieve continuation character, showing the statement continues on the next source line.

Options Explained One by One

The power of DISPLAY comes from its options. Because each one changes the output in a specific way, the table below defines every option, and the paragraphs that follow show how they behave in practice. Understanding the difference between these values is the key to using DISPLAY well.

Page Control: TITLE Versus NOTITLE

Both TITLE and NOTITLE force a page eject - the printer advances to the top of a fresh page before your data prints. The difference is what happens to headings. TITLE reprints any titles and column headings you defined in a report procedure, so the new page looks like a proper report page. NOTITLE gives you a clean, empty page with just your DISPLAY line, which is what you want for special messages such as an end-of-run summary that should not carry report headings. If you code DISPLAY outside a report procedure, TITLE still ejects the page but there are no titles to print, so the practical effect is the same as NOTITLE.

1
2
3
IF DEPT = 911
   DISPLAY NEWPAGE POLICY SSN DATE-OF-BIRTH
END-IF

In this example the DISPLAY starts a new page and prints three fields beginning in column 1, the default. NEWPAGE is a synonym accepted for the page-eject behaviour in many releases.

Vertical Spacing: SKIP

SKIP inserts blank lines before your data so output is readable rather than cramped. SKIP 3 leaves three blank lines then prints, which visually separates a total from the detail above it. A special case is SKIP 0: instead of skipping, it overlays the new line on top of the previous line at the same print position. Overprinting was historically used for underlining or bolding on impact printers and is rarely needed today, but knowing SKIP 0 does not advance the paper prevents confusing bugs.

1
2
3
IF STATE = 34
   DISPLAY SKIP 3 'THE STATE IS' STATE
END-IF

After skipping three lines this prints the label followed by the STATE value, both starting from column 1. The value of STATE is inserted automatically wherever the field name appears in the item list.

Horizontal Positioning: COL, POS, and Offsets

By default each item prints immediately after the previous one with a single separating space. To line data up in neat columns, use COL to jump to an absolute print column. COL 7 tells Easytrieve the next item starts in column 7 regardless of what came before, which is exactly how you build a tidy trace with aligned labels. The +offset and -offset controls move relative to the current position - handy for nudging an item a few columns without counting from the page edge. POS is similar to COL but is tied to the extended reporting environment and interacts with font sizing, so for ordinary line output COL is the option you will reach for.

1
2
3
IF DEPT = 911
   DISPLAY COL 7 '***  ERROR  ***'
END-IF

Here the literal begins in column 7 instead of the default column 1. Aligning error flags in a consistent column makes them easy to spot when scanning a long SYSPRINT listing.

The HEX Format for Debugging

Packed decimal, binary, and other non-character fields do not print as readable text - they look like random symbols on a normal DISPLAY. The HEX format solves this by printing the hexadecimal byte values instead, so you can see exactly what is stored. This is one of the most valuable debugging tools in Easytrieve because it reveals data that would otherwise be invisible.

1
2
3
4
5
6
7
        [display-file-name] [{TITLE | NOTITLE}]     [ file-name  ]
DISPLAY [                 ] [SKIP skip-integer]  HEX [ field-name ]
        [SYSPRINT         ]
 
* Example: dump the whole input record and one packed field
DISPLAY HEX PERSNL
DISPLAY 'WHO = ' WHO HEX WHO

You can dump an entire record by naming the file, or a single field by naming the field. Comparing the readable value and its HEX bytes side by side quickly explains problems such as a packed field that never got initialized or contains sign nibbles you did not expect.

Where DISPLAY Output Appears

The physical destination depends on where you code DISPLAY. In the logic portion of a JOB activity with output going to a report, the DISPLAY lines are interspersed through an unsequenced report, or printed at the very beginning of a sequenced report - before the first title. Inside a report procedure, DISPLAY is restricted to the system output device only; you cannot DISPLAY to a data file from a report procedure. Knowing this avoids the common surprise of DISPLAY lines appearing in an unexpected order relative to report detail lines.

DISPLAY Versus PRINT

Beginners often ask which output statement to use. PRINT sends a record to a named REPORT and lets the report writer handle titles, headings, column spacing, page breaks, and totals automatically. DISPLAY does none of that automation - it prints one line exactly as listed. Choose PRINT when you want a formatted, professional report. Choose DISPLAY when you want a quick message, a control total at end of job, or a debugging trace that does not belong in the formatted output. Many production jobs use both: PRINT for the report, DISPLAY for operator messages and run statistics.

Common DISPLAY Mistakes

• Expecting packed or binary fields to print readably - use HEX for those.
• Forgetting SKIP 0 overlays instead of advancing, producing overprinted garble.
• Trying to DISPLAY to a data file from inside a report procedure (only the system device is allowed there).
• Assuming DISPLAY lines print in strict order relative to PRINT in a sequenced report - they precede the first title.
• Omitting quotes around literal text, so Easytrieve treats the words as field names and fails at compile.
• Using DISPLAY for a full report when PRINT with a REPORT definition would be cleaner and automatically formatted.

Explain It Like I'm Five

DISPLAY is like writing one line on a whiteboard with a marker. You write the words and numbers you want, right there, straight away. You can leave a few empty lines first (that is SKIP), start writing further along the board (that is COL), or turn to a brand new board (that is a new page). PRINT is different - PRINT is like filling in a neat printed worksheet with headings and boxes. When you just need to jot a quick note, you use DISPLAY. And if the marker looks like scribbles because the thing you are writing is secret computer code, HEX turns it into numbers you can read.

Exercises

1. Write a DISPLAY that prints the literal 'RUN COMPLETE' on a new page with no report titles.
2. Write a DISPLAY that skips two lines then prints a label in column 5 and a total in column 25.
3. Dump an input record and one packed field in hexadecimal to inspect their bytes.
4. Explain in one sentence why SKIP 0 can produce unreadable output.
5. Decide whether DISPLAY or PRINT is correct for an end-of-job record count and justify the choice.