Easytrieve System Variables Overview

System Variables Versus User Variables

User variables come from FILE layouts, DEFINE in Library or activities, and W or S working storage you control. System variables and reserved symbols come from the language product. You assign NET-PAY from GROSS and DEDUCT; you do not DEFINE NET-PAY as a keyword. Likewise you DISPLAY FILE-STATUS after STATUS on READ, but you do not DECLARE FILE-STATUS as a new W field unless documentation explicitly allows a homonym—which it generally does not.

Qualification matters for file-related symbols. Broadcom documents qualified forms such as file-name:RECORD-COUNT and delimiter examples with FILEONE:RECORD-COUNT in syntax topics. The qualifier tells the compiler which file context applies when multiple FILE definitions are active. Report symbols such as PAGE-NUMBER apply in REPORT hooks documented for your release, not arbitrarily in every PROC paragraph.

How to Verify Symbols on Your Release

Internet examples and classroom slides age poorly across Classic, Plus, and Report Generator 11.x function mode. New reserved words arrive in migration bulletins; old field names that matched new keywords fail compile until renamed. The reliable workflow is:

1. Open Symbols and Reserved Words for your installed Broadcom documentation level.
2. Read New Reserved Words if you migrated to 11.6 or later function mode.
3. Write a minimal program referencing only the symbols you need.
4. Compile with listing options your site uses and read the cross-reference section.
5. Compare accepted tokens against examples in this tutorial and your prior codebase.

Site EZOPTBL entries, macro libraries, and procedure defaults can change runtime behavior without changing source spelling. Two LPARs on the same version number can still differ in date format or user identity returned by environment facilities. Treat environment values as deployment-specific unless you have verified both compile and execute on the target system.

File Status and Presence (Documented I/O State)

The most operationally important system values for batch file processing are file status after explicit I/O and file-presence conditions for loop control. These are documented across Language Reference FILE topics, READ and GET statements, and file-presence condition pages—not invented names.

FILE-STATUS

When you code STATUS on READ, GET, PUT, WRITE, or related verbs, Easytrieve sets FILE-STATUS to the access-method return code for that operation. Production error PROCs test FILE-STATUS after keyed READ on VSAM masters, after PUT during replace loops, and after GET on sequential files when SEQUENTIAL is declared on FILE. Pattern: perform the I/O verb with STATUS; branch on zero versus nonzero; log unexpected nonzero values to SYSPRINT before STOP or ABEND.

1
2
3
4
5
6
7
READ MASTER STATUS
IF FILE-STATUS NE 0
   DISPLAY 'MASTER READ FAILED' FILE-STATUS CHG-KEY
   PERFORM ERROR-PROC
ELSE
   MOVE MASTER:NAME TO OUT-NAME
END-IF

Exact numeric meanings for not-found, duplicate key, and physical errors are documented in Messages and Codes and FILE organization topics for your release. Do not assume COBOL-style STATUS KEY literals without checking the Easytrieve manual for your file type.

EOF and NOT file-name

EOF is a file-presence condition: IF EOF file-name is true when the named file has no current record because input is exhausted in supported controlled or synchronized modes. IF NOT file-name tests absence of a successful retrieval in keyed contexts—distinct from whole-file EOF. Automatic JOB INPUT uses a different lifecycle: FINISH procedures handle end processing; Broadcom documents that EOF cannot be true for automatic input files in the same way as controlled GET loops.

1
2
3
4
5
6
7
JOB INPUT PAYROLL
  DO WHILE NOT EOF PAYROLL
     GET PAYROLL
     IF DEPT EQ 100
        PRINT DEPT-RPT
     END-IF
  END-DO

Confusing EOF with nonzero FILE-STATUS is a common beginner defect. EOF means no more sequential input in the loop model you chose. FILE-STATUS means the last operation succeeded or failed with a return code. A keyed READ can fail with not-found while the file still contains other records.

RECORD-COUNT and File-Qualified Statistics

Broadcom syntax documentation illustrates RECORD-COUNT with bare, qualified, and parenthesized forms to teach delimiter rules. In runtime contexts, record-count-related symbols reflect statistics tied to file or report processing depending on statement and release. Before using RECORD-COUNT in STOP logic or FINISH procedures, read the automatic versus controlled input rules for your file type. Child pages in this chapter drill into page number, record count, and current line where documented for Report Generator 11.6.

Report and Control-Break System Fields

Report writing introduces system fields that make no sense before PRINT or outside REPORT subactivities. Documentation and syntax overviews commonly reference LEVEL and BREAK-LEVEL during control breaks, TALLY for counting within break groups, LINE-COUNT and PAGE-NUMBER for layout, and LINE-related hooks such as BEFORE-LINE and AFTER-LINE as reserved PROC names. These are not generic working storage you create for any JOB paragraph.

PAGE-NUMBER and LINE-COUNT

PAGE-NUMBER supports page-oriented TITLE and footing logic. LINE-COUNT tracks vertical position within a page for skip and line placement decisions. Values update as the report engine emits lines. Referencing PAGE-NUMBER in unrelated batch extraction jobs without REPORT activity may compile differently or fail depending on context rules—another reason to verify on your listing.

LEVEL, BREAK-LEVEL, and TALLY

CONTROL reports compare break fields and invoke procedures at hierarchy changes. LEVEL and BREAK-LEVEL relate to which control break fired. TALLY accumulates counts within break processing documented in report tutorials. BREAK-LEVEL became a newly reserved word in 11.6 migration material; legacy user fields with that name require renames before function-mode compile.

1
2
3
4
5
6
REPORT DEPT-RPT
  CONTROL DEPT
  BEFORE-BREAK
     DISPLAY 'BREAK DEPT' DEPT ' LEVEL ' LEVEL
  AFTER-BREAK
     LINE 'COUNT' TALLY

Exact spellings and which hooks are reserved PROC identifiers versus assignable fields belong in Symbols and Reserved Words. Copy REPORT examples from your installed manual, not from abbreviated cheat sheets alone.

Environment, Date, Time, and Identity Values

Environment-related symbols answer audit questions: what date is the processor using, what time did processing start, which job name appears on JCL, which user submitted the step. Report Generator reserved-words material documents SYSDATE and SYSTIME as system date and time fields. Easytrieve Plus Application Reference describes overlapping information as system functions that may use different spellings such as $DATE and $TIME. Treat these as parallel families until you confirm which your compile accepts.

SYSUSERID appears in New Reserved Words migration lists for 11.6. If legacy programs defined a field named SYSUSERID, migration renames are required. For audit headers, prefer documented identity retrieval for your product line rather than hard-coding TSO ids in source. Security products may map submitter, proxy, or batch user differently; document what your test LPAR returns on SYSPRINT when you DISPLAY the symbol.

RETURN-CODE and step completion

RETURN-CODE or step return-code-related symbols connect Easytrieve logic to JCL COND and scheduler retry policy. Patterns include setting return codes before STOP when validation fails, or propagating business severity levels. Exact mechanism and reserved spelling are release-specific; batch operations often pair DISPLAY on SYSPRINT with a chosen return code convention the run book documents.

1
2
3
4
5
6
7
FINISH. PROC
  TITLE 01 'RUN DATE' SYSDATE ' TIME ' SYSTIME
  IF ERROR-COUNT GT 0
     DISPLAY 'VALIDATION ERRORS' ERROR-COUNT
     STOP
  END-IF
END-PROC

The snippet illustrates report-oriented date and time symbols in TITLE context. If your compile rejects SYSDATE, check whether your site uses function assignment from the system functions index instead, then format for TITLE with EDIT or formatting builtins documented on your release.

System Functions Versus System Fields

This overview focuses on reserved variables and symbols you reference as fields or conditions. Easytrieve Plus also exposes environment information through system functions documented in the Application Reference. A complete solution may assign a working-storage RUN-DATE from a function, then print RUN-DATE on TITLE, rather than referencing SYSDATE directly. Both patterns appear in real shops. The wrong pattern is guessing a function name from a Plus manual while compiling Report Generator source without checking the listing. See the system functions index and child pages for system date, time, job name, user id, and program name detail.

What This Overview Deliberately Does Not Claim

• A single universal table of every system variable name across all Easytrieve products and releases.
• That every symbol in classroom slides compiles on your LPAR without verification.
• That environment values match production when you run on a test clock or simulated date facility.
• That FILE-STATUS zero always means business success—only that the last I/O operation completed as the access method reported.
• That report counters apply in non-REPORT batch extraction jobs.
• That newly reserved migration words can remain user field names in 11.6 function mode.

Child tutorials under this chapter cover individual symbols where Broadcom documents them for Report Generator 11.6: system date, system time, job name, user id, program name, page number, record count, and current line. Read those pages after you confirm the symbol appears in your Symbols reference. When documentation is silent, ask your site compiler support team or open a minimal compile case—do not invent a reserved variable and expect portable behavior.

Practical Patterns for Beginners

1. After every keyed READ with business impact, test NOT file-name or FILE-STATUS before using buffer fields.
2. Use STATUS on PUT in replace and update loops; STOP or branch on nonzero FILE-STATUS.
3. Capture run date once for TITLE if unchanged for the job; avoid per-record date calls unless required.
4. Keep report system symbols inside REPORT and documented PROC hooks.
5. Log job context lines on SYSPRINT at startup when diagnosing multi-step procs.
6. Rename user fields that collide with New Reserved Words before 11.6 migration compile.

Common System Variable Mistakes

• DEFINE a user field named SYSDATE or BREAK-LEVEL and confuse the compiler with reserved symbols.
• Treat EOF as equivalent to FILE-STATUS not zero on keyed files.
• Reference PAGE-NUMBER in batch jobs with no REPORT activity.
• Assume $DATE from Plus docs compiles in Report Generator without a listing test.
• Ignore STATUS and rely on default termination when READ fails.
• Use display-formatted dates in numeric IF comparisons.
• Copy qualified RECORD-COUNT examples without the correct file-name qualifier.

Explain It Like I'm Five

System variables are labels the Easytrieve teacher already put on the classroom wall: what page of the workbook you are on, whether the file box is empty, what today's date is, and whether the last trip to the file cabinet worked. You do not make those labels yourself with DEFINE. You look at the wall when you need the answer. Different schools may use slightly different wall charts, so you check the chart in your actual classroom —the compiler book for your release—instead of memorizing a chart from another school.

Exercises

1. Compile a one-statement program that references SYSDATE; note accept or reject on the listing.
2. Write READ with STATUS and branch on FILE-STATUS for a test VSAM not-found key.
3. Explain in your own words why EOF and FILE-STATUS answer different questions.
4. List three report system symbols and where documentation says they are valid.
5. Find one New Reserved Word from 11.6 migration that could collide with old field names.
6. Design a SYSPRINT startup line using job context symbols verified on your test LPAR.