Easytrieve FIRST-DETAIL

What FIRST-DETAIL Means

Control reports group detail lines under CONTROL fields such as REGION, BRANCH, and DEPARTMENT. When REGION changes from EAST to WEST, a control break occurs. Totals print, headings may repeat, and the next employee detail line is the first detail line of the new group. FIRST-DETAIL is true at that moment. Page overflow creates a similar moment: when the next detail line would not fit on the current page, the report writer starts a new page and the upcoming detail is the first detail line on that page. FIRST-DETAIL is also true there. On ordinary detail lines in the middle of a group and page, FIRST-DETAIL is false.

Report Procedure Context

Report procedures run at fixed points in the report writer lifecycle. REPORT-INPUT screens data selected by PRINT. BEFORE-LINE runs immediately before a detail line prints. AFTER-LINE follows printing. BEFORE-BREAK and AFTER-BREAK surround total lines. IBM documentation names the detail-building exit BEFORE-DETAIL and makes FIRST-DETAIL available there. Broadcom 11.6 Getting Started and Programming guides document BEFORE-LINE for detail-line events. If your site compiles with Broadcom 11.6, try BEFORE-LINE first when porting legacy BEFORE-DETAIL examples, and confirm with your release manual whether FIRST-DETAIL remains supported as a conditional keyword.

1
2
3
4
5
6
7
8
9
10
11
12
13
REPORT PAY-RPT LINESIZE 80 DTLCTL FIRST
  SEQUENCE DEPT EMPLOYEE-ID
  CONTROL DEPT
  TITLE 1 'PAYROLL DETAIL'
  LINE 01 EMPLOYEE-ID GROSS NET-PAY
 
BEFORE-LINE. PROC
  WS-RUN-DATE = SPACES
  IF FIRST-DETAIL
     WS-RUN-DATE = SYSDATE
     DISPLAY 'AS OF' WS-RUN-DATE
  END-IF
END-PROC

The DISPLAY adds a date annotation only when FIRST-DETAIL is true—after a break or at page top—not on every employee line. SYSDATE is a system date field documented in Broadcom reserved words.

FIRST-DETAIL vs POST-BREAK

IBM also documents POST-BREAK for BEFORE-DETAIL procedures. POST-BREAK is true only for the first detail line after a control break. It does not fire merely because a new page started without a break. Use POST-BREAK when you want break-specific messaging such as entering a new department. Use FIRST-DETAIL when page-top repetition matters too, such as repeating a short column legend after every page advance.

DTLCTL FIRST on REPORT

Beginners often confuse FIRST-DETAIL with DTLCTL FIRST. They solve related but different problems. DTLCTL is a format-determination parameter on REPORT with subparameters EVERY, FIRST, and NONE. DTLCTL FIRST tells the report writer to print CONTROL field values on the first detail line of each page and on the first detail line after each control break. On other detail lines within the group, CONTROL values are suppressed automatically. You do not need a procedure to blank them manually. The install options table also defines a compile-time DTLCTL default that REPORT can override.

1
2
3
4
5
6
7
8
9
10
REPORT SALES-RPT LINESIZE 65 DTLCTL FIRST
  SEQUENCE REGION BRANCH
  CONTROL REGION BRANCH
  LINE 01 SALES-REP AMOUNT
 
* With DTLCTL FIRST:
* - REGION and BRANCH print on first detail after break
* - Subsequent detail lines in same group omit control values
* - Use DTLCTL EVERY to repeat controls on every line
* - Use DTLCTL NONE to suppress controls on detail lines

XML report output changes DTLCTL defaults per Broadcom REPORT documentation—verify XML behavior separately if you generate XML extracts.

BREAK and HIGHEST-BREAK Field-Class Tests

Broadcom 11.6 documents field-class conditions BREAK and HIGHEST-BREAK for CONTROL fields. IF REGION BREAK tests whether REGION is currently processed as a CONTROL field on the report. IF REGION HIGHEST-BREAK tests whether REGION caused the break that is active. These are alternatives to comparing LEVEL or BREAK-LEVEL to specific numeric values. FIELD must appear on a CONTROL statement or be the reserved word FINAL.

1
2
3
4
5
BEFORE-BREAK. PROC
  IF DEPT HIGHEST-BREAK
     DISPLAY '--- DEPARTMENT TOTAL ---'
  END-IF
END-PROC

Combine BREAK tests with FIRST-DETAIL carefully. A field can be an active control without the current line being FIRST-DETAIL, and FIRST-DETAIL can be true without every control field being the highest break.

LEVEL and BREAK-LEVEL System Fields

LEVEL is a system-defined binary field indicating report processing level. Broadcom documents LEVEL 0 during detail line processing, LEVEL n during control totals, and LEVEL n+1 during FINAL totals. BREAK-LEVEL holds the break level of the highest field that broke. FIRST-DETAIL is a higher-level boolean for layout; LEVEL is numeric state for procedural branching. Use LEVEL when you need different math on minor versus major totals. Use FIRST-DETAIL when you need first-line decoration.

Practical Layout Patterns

1. Stamp SYSDATE on first detail after each page or break with FIRST-DETAIL in BEFORE-LINE.
2. Let DTLCTL FIRST repeat CONTROL keys without coding MOVE SPACES on later lines.
3. Use POST-BREAK for break-only banners that should not repeat on mere page advances.
4. Use BEFORE-BREAK to compute averages before total lines print.
5. Use ENDPAGE for footers that belong at physical page bottom regardless of breaks.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
DEFINE WS-TAG W 20 A
 
BEFORE-LINE. PROC
  WS-TAG = SPACES
  IF POST-BREAK
     WS-TAG = '* NEW GROUP *'
  END-IF
  IF FIRST-DETAIL AND WS-TAG SPACES
     WS-TAG = '* PAGE START *'
  END-IF
  IF WS-TAG NOT SPACES
     DISPLAY WS-TAG
  END-IF
END-PROC

DISPLAY in Report Procedures

Broadcom restricts DISPLAY inside report procedures: no file-name parameter, no HEX option, output goes to the associated report only. DISPLAY lines count toward page length and can affect end-of-page determination, but ENDPAGE is not invoked by those DISPLAY lines according to the Programming guide. When FIRST-DETAIL triggers DISPLAY annotations, test page breaks with realistic data volumes so annotations do not push detail unexpectedly.

Version and Product Differences

IBM MU/Easytrieve reserved-keyword documentation explicitly defines FIRST-DETAIL and POST-BREAK for BEFORE-DETAIL. Broadcom 11.6 Symbols and Reserved Words lists FIRST as a reserved word but not FIRST-DETAIL in the alphabetical reserved-word table reviewed for this page. Report procedure names BEFORE-LINE and BEFORE-BREAK are documented in Broadcom 11.6. When maintaining legacy macros, search for BEFORE-DETAIL and FIRST-DETAIL and validate against your compiler. Document the mapping in shop standards so new developers do not mix incompatible procedure names.

Common FIRST-DETAIL Mistakes

1. Expecting FIRST-DETAIL in ordinary JOB INPUT logic outside report procedures.
2. Confusing FIRST-DETAIL with DTLCTL FIRST on REPORT.
3. Using POST-BREAK when page-top repetition is also required.
4. Assuming CONTROL values print on every line while DTLCTL FIRST is in effect.
5. Adding DISPLAY annotations without testing page-length side effects.
6. Porting BEFORE-DETAIL to Broadcom without verifying procedure name support.

Explain It Like I'm Five

A report is a long list of names grouped by classroom. FIRST-DETAIL is true when you are about to write the first name in a new classroom or the first name at the top of a fresh page. It is not true for every name in the middle of the list. DTLCTL FIRST is a printer rule that says write the classroom name only on those first-name lines, not on every line. POST-BREAK is like FIRST-DETAIL but only when the classroom changed, not when you simply ran out of room on the page.

Exercises

1. Write a control report with DTLCTL FIRST and explain control value repetition.
2. Add BEFORE-LINE logic that prints SYSDATE only when FIRST-DETAIL is true.
3. Contrast POST-BREAK and FIRST-DETAIL with a department break example.
4. Use IF DEPT HIGHEST-BREAK in BEFORE-BREAK to annotate department totals.
5. Explain LEVEL 0 versus LEVEL during total line processing.
6. List migration checks when moving BEFORE-DETAIL examples to Broadcom 11.6.