Easytrieve Naming Standards

Language Rules and Length Limits

Broadcom Easytrieve identifiers are traditionally short—often eight characters maximum for field names in many programs, though some constructs allow longer labels in specific contexts. Names consist of letters, digits, and in many cases embedded hyphens depending on statement type. The first character is alphabetic. Names are not case-sensitive in typical mainframe source—the compiler folds to uppercase. Your standard should assume uppercase storage and forbid lowercase in new source to match listing conventions. Always verify exact rules in the Language Reference for your maintenance level because online SCREEN field names and macro parameters can have additional constraints.

Reserved Words and High-Risk Names

Reserved words are tokens the language uses as verbs, clauses, or special names—FILE, JOB, IF, REPORT, SCREEN, VALUE, and hundreds more. A field named VALUE or REPORT is a compile error or ambiguous parse on modern releases. Each upgrade adds reserved words; migration guides publish lists. Standards prohibit using dictionary verbs as field names and require grep scans before check-in. When legacy code uses risky names, rename with a prefix: VALUE becomes WS-VALUE-FLAG or IN-RECORD-VALUE depending on semantics—not VALUE-R renamed minimally if VALUE alone is illegal.

FILE and Field Names

FILE names should match DD names in JCL where shop convention ties them—PAYROLL file in source maps to PAYROLL DD at runtime. Field names inside FILE should mirror enterprise data dictionary abbreviations when possible: EMP-NBR not E9. Document start position only in the macro comment block, not by encoding position in the name (BYTE94-AMT is an anti-pattern). Group related fields with shared stems: PAY-GROSS, PAY-NET, PAY-TAX for readability in REPORT LINE statements.

1
2
3
4
5
6
7
FILE PAYROLL FB(150 1800)
  EMPNAME  17  8  A
  EMP-NBR   9  5  N
  DEPT     98  3  N
  PAY-GROSS 94  4  P  2
 
DEFINE WS-TOT-GROSS W 9 P 2

DEFINE and Working Storage Names

DEFINE creates fields not read directly from files—totals, scratch numerics, date conversions. Prefix every DEFINE with WS- unless it is a report-specific temporary (then RPT-). Avoid reusing FILE field names for DEFINE targets; MOVE and assignment become ambiguous in listings. For packed decimals, suffix P fields with context: WS-AVG-PAY not WS-AVG alone when multiple averages exist. Date fields should include DATE or DT in the name and comment the internal format (CCYYMMDD versus display mask).

REPORT and LINE Names

REPORT names identify layout blocks—PAY-RPT, DEPT-SUM, ERR-LIST. Use a consistent suffix (-RPT, -SUM, -DTL) across the portfolio so PRINT statements are self-explanatory. TITLE and LINE statements reference field names; aligning REPORT field order with readable names speeds column debugging when output columns shift. Do not reuse the same REPORT name in multiple programs unless layouts are identical by standard—colliding names in shared macro libraries cause wrong headings.

Multiple Reports in One Program

When one JOB prints several reports, name each REPORT distinctly: PAY-DETAIL-RPT versus PAY-CONTROL-RPT. PRINT statements name the target explicitly. Standards should forbid PRINT without report name when multiple REPORT blocks exist—relying on defaults is fragile when someone adds a second layout later.

Procedure and Macro Names

User PROC names should be verb phrases: CALC-TOTALS, FORMAT-DATE, VALIDATE-DEPT. Special-name procedures (BEFORE-LINE, BEFORE-SCREEN) are language-defined—do not invent alternate spellings. Macro names are often file-oriented: PAYROLL-FILE-MAC, GL-MASTER-MAC. Version suffixes (-V2) appear during migration when old and new layouts coexist briefly—remove suffix after cutover to avoid permanent clutter.

Screen Field Names

Online programs map screen fields to DEFINE or FILE fields. Prefix SCR- or map names matching BMS/map conventions your site uses. Message fields SCR-MSG-LINE1 should be documented for PF-key help text. Keep screen names distinct from batch-only fields so RESET behavior on SCREEN activities is predictable.

Migration Rename Workflow

1. Extract reserved word list for target release.
2. Grep source libraries for collisions; sort by frequency.
3. Update central macros first; recompile dependents.
4. Apply prefix standard to renamed fields in comments for traceability.
5. Record old-to-new mapping in change ticket for auditors.
6. Run parallel output compare after renames affecting calculations.

Naming Anti-Patterns

• Single-letter names except loop indexes (I, J) in tiny scopes.
• Names that differ by one character across files (AMT1, AMT2, AMT3) without dictionary.
• Embedding department number in field name (DEPT911-TOT)—use data not names.
• Using IF, AND, OR as field stems.
• Renaming only in PRINT masks while logic still uses old symbol via macro alias confusion.

Explain It Like I'm Five

Names are labels on boxes. If every box says STUFF, you cannot find the crayons. If one box says OPEN and that word is also a command the robot understands, the robot gets confused. We use short labels with first letters that mean file box or scratch paper box, and we never use command words as labels. When the robot learns new command words, we relabel boxes before they clash.

Exercises

1. Rewrite cryptic fields E9, G2, FL1 using the prefix table.
2. List five reserved words that would be risky as field names.
3. Name two REPORT layouts for detail and summary in a payroll job.
4. Write a macro rename plan when VALUE becomes reserved.
5. Compare benefits of matching COBOL copybook names versus WS- prefixes.