Easytrieve Maintainability Best Practices

The Cost of Unmaintainable Code

Unmaintainable Easytrieve looks fine until the original author leaves. Then every change risks breaking control totals, tax buckets, or GDG generation because nobody knows which counter field is authoritative. Audits ask when logic last changed and whether anyone tested it—copy-paste FILE definitions without library control fail both questions. Incident mean time to repair grows: on-call engineers grep for field names instead of opening a PROC named CALC-STATE-TAX. Enterprise TCO includes maintainer hours; upfront maintainability pays compound interest.

Documentation Layers

Program Header Template

Start each production member with a fixed header block. Consistency matters more than length. Include program name, business function, primary input and output files, schedule frequency, maintainer contact or team mailbox, and last significant change ticket. When an on-call engineer opens the member during an abend, the header answers whether this job feeds the general ledger or only a departmental preview.

1
2
3
4
5
6
7
8
9
* =============================================================
* PROGRAM : PAYRPT01
* PURPOSE : Weekly payroll exception listing by cost center
* INPUT   : PAYROLL.PERSNL.WEEKLY (+1 GDG)
* OUTPUT  : PRT.PAYROLL.EXCEP(+1), SYSOUT control totals
* SCHED   : Sunday 02:00 after PAYEXT completes
* OWNER   : Payroll apps team / ticket queue PAY-APP
* HISTORY : 2026-04-01 CHG12345 added local tax field LOC-TAX
* =============================================================

Readable Structure

Maintainability overlaps modular design: PERFORM named procedures, group FILE and macro invocations at the top, separate JOB logic from REPORT activities visually with comment banners. Use formatting standards from your site—consistent indentation and column alignment so diffs in Endevor show logic changes instead of whitespace noise. Avoid clever GOTO chains; explicit PERFORM and labeled exit paths age better. Keep working storage in Library with meaningful field names (TOT-GROSS-PAY not T17). Future you will thank present you.

Macro and Library Governance

Shared macros are maintainability assets when governed: one owner team, semantic versioning or parallel macro names for breaking changes, regression compile list attached to promotions. Breaking a positional parameter without updating callers silently shifts field offsets—a maintainability disaster discovered at month-end reconcile. Document parameter meaning in the macro prototype comment. When a layout change affects forty programs, the macro diff is one review; forty copy-paste edits are forty chances to miss column 47.

Testing for Maintainability

Maintainable code includes known-good test cases: small input files, expected totals, edge cases documented in the ticket or README. Store them in a team dataset or test repo referenced from the header. Before promoting changes, rerun those cases and compare SYSPRINT control totals or report extracts. Tests need not be automated on day one—but without them, maintainability is theoretical. After macro library updates, regression-compile at least one program from each business area that invokes the macro.

Operations Handoff

• Document normal record counts and runtime range so ops detects anomalies.
• State restartability: can the job restart from step 2 or must files be recovered?
• List upstream dependencies (extract job name) and downstream consumers.
• Provide sample abend messages and whether they indicate data versus code issues.
• Keep DISPLAY out of production or document expected SYSPRINT volume.

Operations staff maintain batch windows; developers maintain code. Maintainability includes the bridge between them. When runbooks lie—job renamed but wiki not updated—trust erodes and hot fixes skip process.

Refactoring Safely

Large maintainability refactors (splitting god PROC, introducing macros) should behave identically before and after. Refactor in dedicated change tickets, not bundled with new business rules. Compare outputs byte-for-byte or total-for-total on test data. Use version control history to bisect when regressions appear. Teaching moment for beginners: cosmetic reformat-only commits help future diffs but still need compile verification.

Deprecation and Migration Notes

When syntax deprecates across Easytrieve releases, maintainable programs carry migration comments: which release removes the old form, which replacement to use, and whether compatibility macros exist. Link to site migration pages and reserved word changes. Teams that ignore deprecation accumulate compile surprises during forced upgrades.

Explain It Like I'm Five

Maintainability is writing a recipe so someone else can bake the cake when you are not in the kitchen. You label the jars (field names), write how much sugar means what (business rules in comments), and keep one master list of ingredients (macros) instead of scribbling on fifty sticky notes. You also leave a note that says who to call if the oven smokes (operations runbook). If you only keep the recipe in your head, nobody can fix dinner when you are sick.

Exercises

1. Write a program header for a fictional daily sales report job.
2. List five items belong in an operations runbook for that job.
3. Describe regression steps after changing a shared PERSNL FILE macro.
4. Identify three maintainability problems in a monolithic 500-line JOB INPUT pseudocode.
5. Draft a change ticket description including test evidence requirements.