Easytrieve Naming Conventions

Goals of Good Names

A good Easytrieve name answers three questions at a glance: what data it holds, where it lives (file versus working storage), and whether it is input, output, or control. Names should resist future reserved word lists, survive 80-column listings without truncation confusion, and match downstream COBOL or DB2 terminology when systems share files. Cryptic three-letter legacy names may remain when maintaining old programs, but new development should favor clarity over brevity within reasonable line length.

Working Storage Prefixes

Most shops prefix working storage fields defined after W in DEFINE statements. WS- is the most common prefix in North American sites; W- or WK- appear in others. The prefix signals that a name is not a column in a FILE layout—a critical distinction when reading IF statements and MOVE operations during incident triage at 2 a.m.

1
2
3
DEFINE WS-HOLD-STATUS W 1 A
DEFINE WS-TOTAL-GROSS  W 9 N 2 DECIMALS
DEFINE WS-ERR-COUNT    W 5 N 0

FILE Field Names

FILE field names should mirror record layouts in copybooks, data dictionaries, or file documentation. When EMP-NO is the enterprise standard, do not rename to EMPLOYEE_NUMBER in Easytrieve unless the entire pipeline adopts the change. POSITION and LENGTH must align with physical layout—naming cannot fix wrong offsets. Use the same abbreviations COBOL uses for the file so cross-team conversations stay aligned.

Qualification Conventions

When the same name appears in multiple files or in WORK and a FILE, qualify every reference in maintainable code—even when the compiler might infer context. FILEA:STATUS and FILEB:STATUS beat ambiguous STATUS in nested IF logic. Broadcom allows flexible spacing around the colon: FILEA:FLD1, FILEA : FLD1. Pick one spacing style per shop and stay consistent.

1
2
3
IF PERSNL:DEPT EQ WORK:SAVE-DEPT
   MOVE PERSNL:GROSS TO WS-LINE-GROSS
END-IF

Labels for PROC, JOB, and GOTO

Procedure labels should verb-noun describe action: CALC-TAX, VALIDATE-REGION, WRITE-TRAILER. JOB activity names often reflect business function: JOB-PAYROLL-EXTRACT. GOTO labels like SKIP-INVALID-REC should state why the branch exists. Avoid generic names—PROCESS, LOOP1, AGAIN—that appear hundreds of times in a library. Labels cannot be all numeric and cannot contain delimiter characters.

REPORT and SCREEN Names

REPORT names tie to PRINT statements. Use names operations recognize: PAY-DETAIL-RPT, PAY-EXCEPTION-RPT. Do not reuse FILE names as REPORT names—PRINT PERSNL reads like printing a file, not formatting a report. SCREEN names for online activities should indicate panel purpose: SCR-EMP-INQUIRY. Document mapping from report name to SYSOUT DD in run books.

Avoiding Reserved and System Names

Broadcom reserves uppercase English keywords and many system field names—SYSDATE, SYSTIME, RETURN-CODE. New 11.6 reserved words include EXECUTE, SET, LOGICAL-RECORD. Run periodic scans before upgrade projects. Prefer ws-execute or custSet over bare EXECUTE or SET. Non-reserved keywords used as field names may compile but confuse readers who see MOVE as both keyword and identifier in different lines.

Length and Readability

One hundred twenty-eight characters is the technical maximum; practical maximum depends on your editor and listing width. Names longer than thirty characters may wrap awkwardly in compile listings. Balance descriptiveness: WS-TOTAL-GROSS-PAY-USD beats WS-TGP for a new hire reading the program, but WS-TOTAL-GROSS-PAY-AMOUNT-FOR-CURRENT-PAY-PERIOD-USD may exceed sensible line width when qualified with file names.

National Characters

Field names may start with national characters #, @, $. Some shops use @ for temporary migration fields or # for constants. Document any special national-character meaning in team standards so #TAX-RATE is understood as a table key prefix, not a social media tag.

Team Standards Document

1. Keyword case: UPPERCASE in all new source.
2. Field case: mixedCase or lowercase for developer-defined symbols.
3. Mandatory WS- prefix for working storage unless exempt legacy module.
4. Qualify all multi-file references explicitly.
5. REPORT names end with -RPT when producing spool output.
6. Prohibited names list synced with each Easytrieve upgrade release notes.

Common Naming Mistakes

• Reusing STATUS in three files without qualification.
• Naming a field COUNT when COUNT is a system or report keyword context.
• Mixing WS-, W-, and no prefix in one program.
• FILE field names that disagree with copybook layout names.
• REPORT name identical to PRINT file name causing reader confusion.

Explain It Like I'm Five

Naming conventions are like color codes on boxes in a big warehouse. Red stickers mean temporary storage, blue stickers mean shipped from the factory file, and each sticker uses words everyone agreed on so no one opens the wrong box. If two boxes need the same word, you add the aisle name before the word so pickers know which aisle to visit.

Exercises

1. Rename fields TOTAL, SET, and STATUS to shop-safe names with prefixes.
2. Write qualified names for GROSS in files PAYROLL and HISTORY.
3. Draft six rules for your team naming standard document.
4. Name a REPORT and matching PRINT for an exception-only listing.
5. Explain when FILE names should match COBOL copybooks exactly.