Easytrieve Reusable Report Framework

Why a Framework Instead of Templates

A template is a starting file you duplicate. A framework is live shared code every report calls. Templates drift: developer A widens a column in one copy but not another. Frameworks enforce one definition of heading layout, one PAGE-NUMBER field width, one rule for when FINAL totals print. Easytrieve Library macros expand at compile time—include STD-HEADING once and every REPORT gets identical heading lines. PROC-based frameworks use PERFORM so you can add logic such as reading a control file for holiday banners without recompiling every consumer if you version carefully. Choose macros when layout is static; choose PROCs when headings branch on run options passed through working storage flags.

Framework Layers

Presentation layer never references department-specific field names. Business layer never redefines page width. Violating layer boundaries is the most common framework failure: a payroll developer adds a custom TITLE line inside the shared macro copy, fork the framework, and the next merge overwrites their change.

Library Macro Skeleton

1
2
3
4
5
6
7
8
9
* STD-REPORT-HEADING macro — expand in REPORT TITLE section
MACRO STD-REPORT-HEADING
  TITLE RPT-TITLE
  SKIP 1
  LINE COMPANY-NAME  COL 1
  LINE 'Run Date:' RPT-DATE  MASK DATE-MASK  COL 50
  LINE 'Report ID:' RPT-ID    COL 1
  SKIP 2
END-MACRO

RPT-TITLE, RPT-DATE, and RPT-ID are working storage fields the JOB activity sets before the REPORT runs. MOVE statements in JOB logic populate them from SYSDATE, a parameter file, or JCL symbolic substitution translated through a small driver PROC. MASK DATE-MASK keeps date formatting identical on every report. Consumers include the macro in TITLE and focus HEADING on column titles only.

Driver PROC Pattern

1
2
3
4
5
6
7
8
9
10
INIT-REPORT. PROC
  MOVE ZERO TO PAGE-COUNT LINE-COUNT
  MOVE SYSDATE TO RPT-DATE
  MOVE 'PAYROLL REGISTER' TO RPT-TITLE
  MOVE 'PAYR01' TO RPT-ID
END-PROC
 
TERM-REPORT. PROC
  DISPLAY 'PAGES PRINTED' PAGE-COUNT
END-PROC

JOB activity calls PERFORM INIT-REPORT before the first REPORT and PERFORM TERM-REPORT after the last. PAGE-COUNT and LINE-COUNT are framework fields updated in FOOTING or PAGE procedures. DISPLAY at termination gives operations a quick sanity check in batch logs. Replace DISPLAY with writes to a statistics file if your error-handling pattern requires centralized run metrics.

Sample REPORT Using the Framework

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
JOB INPUT PAYROLL-FILE
 
PERFORM INIT-REPORT
 
REPORT PAYROLL-REGISTER
  TITLE
    %STD-REPORT-HEADING
  HEADING
    LINE 'EMP ID' COL 1  'NAME' COL 12  'GROSS' COL 40
  CONTROL DEPT
  LINE EMP-ID NAME GROSS-PAY MASK MONEY-MASK
  FOOTING
    PERFORM STD-FOOTING
END-REPORT
 
PERFORM TERM-REPORT

PAYROLL-REGISTER supplies CONTROL DEPT and the detail LINE. STD-REPORT-HEADING and PERFORM STD-FOOTING come from the framework. A second REPORT EXCEPTION-LIST in the same JOB reuses INIT-REPORT with different RPT-TITLE moved in a tiny SETUP-EXCEPTION PROC between reports—two listings, one heading standard.

Parameter Conventions

RPT-TITLE

Human-readable report name on the printed listing. Keep under heading width; truncate in INIT-REPORT if longer than MASK allows. Differentiate batch versus on-demand reruns by suffixing RPT-TITLE when a RERUN-FLAG is set.

RPT-DATE and RPT-TIME

SYSDATE and SYSTIME system fields copied at INIT-REPORT capture compile-time versus run-time correctly when you MOVE at execution. Document whether date is processing date or business date read from a control file—auditors care.

RPT-ID

Short code matching job catalog and operations run books. Tie to JCL job name or internal application ID. Error-handling patterns often write RPT-ID into error files when a report aborts.

RUN-OPTION flags

Single-character or numeric flags select detail versus summary, suppress FOOTING, or request NEWPAGE per CONTROL break. Framework PROCs test IF RUN-OPTION = 'S' before printing detail LINE—summary-only mode without duplicating the REPORT block.

Hook Integration

BEFORE-LINE can PERFORM a framework routine that increments detail counters or applies redaction MASKs for sensitive fields. AFTER-BREAK can PERFORM STD-SUBTOTAL-HEADER to print a standard break banner line before quantitative totals. Keep hooks thin: one PERFORM into framework code, not twenty lines of duplicated MASK logic. BEFORE-BREAK at major CONTROL level is the right place to reset LINE-COUNT when your framework limits lines per page and needs custom paging beyond default PAGE statement behavior.

Multi-Report JOB Layout

1. PERFORM INIT-REPORT once at JOB start.
2. For each report: optional SETUP-xxx PROC moves title and options, then REPORT subactivity runs.
3. Shared input files use JOB INPUT once; reports that need different files use GET inside REPORT or separate JOB INPUT blocks per Broadcom activity rules.
4. PERFORM TERM-REPORT once after all REPORT blocks complete.
5. STOP or END-JOB ends processing; framework TERM-REPORT already logged page counts.

Framework Versus One-Off Report

Testing the Framework

1. Compile a stub REPORT that includes only framework macros—verify heading line count and column positions without business data.
2. Run with empty input file—confirm TITLE still prints and TERM-REPORT shows zero pages or one title page per design.
3. Change RPT-TITLE in INIT-REPORT—confirm all linked reports pick up new title without editing macro body.
4. Force page break with many detail lines—verify FOOTING page numbers increment through STD-FOOTING.
5. Regression: compare listing against golden copy after framework version bump.

Common Mistakes

• Embedding DEPT or account fields inside shared TITLE macro.
• Forgetting to PERFORM INIT-REPORT before first REPORT—stale RPT-DATE from prior run in restart scenarios.
• Mixing SCREEN ROW layouts into REPORT framework macros.
• Duplicating PAGE logic in each REPORT instead of STD-FOOTING.
• Framework PROCs that PERFORM business PROCs—creates circular dependencies across layers.
• No version comment on macro—operations cannot tell which heading standard printed.

Explain It Like I'm Five

Imagine every school worksheet must have the same name line and date at the top. Instead of each teacher drawing that by hand on every page, the school prints one master strip of paper everyone tapes on top. The reusable report framework is that master strip. Each teacher only writes the math problems in the middle—the detail lines. When the school changes its logo, they update the master strip once and every worksheet looks right the next day.

Exercises

1. Design three working storage parameter fields and document who sets each before REPORT runs.
2. Write a STD-REPORT-HEADING macro with TITLE, run date, and report ID lines.
3. Sketch a JOB with two REPORT blocks sharing INIT-REPORT and different RPT-TITLE setup PROCs.
4. List five elements that belong in the framework layer versus the business detail layer.
5. Describe how you would test a framework change without running full payroll production data.