Easytrieve RECORD-COUNT System Variable

System Counter, Not DEFINE

Like SYSDATE and PAGE-NUMBER, RECORD-COUNT belongs to the Symbols and Reserved Words family. You reference it in IF conditions, DISPLAY diagnostics, and SORT procedure logic. Declaring DEFINE RECORD-COUNT in working storage collides with the reserved system meaning and may fail compile or silently shadow the builtin depending on context—avoid the spelling entirely for user fields. Choose WS-INPUT-COUNT, WS-ROWS-READ, or FILE-READ-TOTAL instead for manual bookkeeping.

File Qualification

Colon qualification mirrors ordinary fields. MASTER:RECORD-COUNT counts records for FILE MASTER; TRANS:RECORD-COUNT counts the transaction file. When JOB names a single default input file, bare RECORD-COUNT may suffice in examples, but production programs with PAY-FILE, DEDUCT-FILE, and LOOKUP-FILE should always qualify. The syntax page groups RECORD-COUNT with FILEONE:RECORD-COUNT to show delimiter roles—comma, period, parentheses—not different variables.

1
2
3
4
5
6
7
8
9
10
FILE MASTER FB 80
FILE AUDIT FB 80
 
JOB PAYRUN
   INPUT MASTER
   IF MASTER:RECORD-COUNT = 0
      DISPLAY 'MASTER FILE EMPTY'
      STOP
   END-IF
   DISPLAY 'RECORDS READ' MASTER:RECORD-COUNT

When the Counter Increments

SORT BEFORE and Record Limits

Development sorts on million-row production extracts waste CPU. BEFORE procedure on SORT can SELECT only test rows, then STOP when RECORD-COUNT exceeds a cap. Broadcom's PERSNL example stops when PERSNL:RECORD-COUNT GT 50—only the first fifty selected records reach the sort output file. Production must remove or raise such caps; auditors comparing input DSN record count to job logs expect RECORD-COUNT or equivalent user totals in TERMINATION DISPLAY. Remember STOP simulates end-of-file; combine carefully with SELECT so you do not drop the boundary record unintentionally.

1
2
3
4
5
6
7
8
9
SORT PERSNL TO SORTOUT USING (NAME) BEFORE SORT-CAP
 
SORT-CAP. PROC
   IF PERSNL:RECORD-COUNT GT 50
      STOP
   ELSE
      SELECT
   END-IF
END-PROC

Empty File Detection

FINISH or TERMINATION procedures often test RECORD-COUNT = 0 after JOB completes to catch empty inputs before downstream steps credit zero-dollar payments. Pair with FILE-STATUS or EOF tests— RECORD-COUNT zero may mean no rows or may mean INPUT never ran. DISPLAY both FILE name and count in SYSPRINT for operations triage. RETURN-CODE elevation when count is zero is a shop standard on critical payroll paths.

RECORD-COUNT Versus User Counters

START. PROC frequently initializes WS-RECORD-COUNT = 0 and ADD 1 inside processing loops. User counters count only rows that pass business rules—valid employees, accepted transactions. RECORD-COUNT reflects file-level processing as the product measures it. Reconciliation DISPLAY should show both when they differ: system count 10000, accepted count 9847 implies 153 rejected by IF logic. Use RECORD-COUNT when you need the engine statistic; use W fields when you need net business totals.

RECORD-COUNT Versus TALLY

TALLY on control reports counts items within the current control break group for averages and summary files—ten-byte component in summary layout documentation. RECORD-COUNT is file-activity oriented, not break-group oriented. BEFORE-BREAK may DISPLAY TALLY for department headcount while JOB TERMINATION DISPLAYs MASTER:RECORD-COUNT for entire file volume. Do not substitute one for the other in audit spreadsheets.

SIZE Parameter on SORT

SORT SIZE record-count passes an estimate of input volume to the sort utility for workspace planning. That parameter is a numeric literal or expression hint—not the same as reading MASTER:RECORD-COUNT at runtime, though teams sometimes derive SIZE from prior run statistics. Confusing the SIZE keyword argument with the RECORD-COUNT system field causes JCL-like tuning errors in Easytrieve source.

DISPLAY and Audit Trails

DISPLAY 'PROCESSED' MASTER:RECORD-COUNT in FINISH. PROC gives operators a quick sanity check against IDCAMS REPRO record counts or DFSORT COUNT. Include job name SYSDATE and file DD in the same message for log correlation. For regulated environments, archive DISPLAY output with retention matching pay records.

SELECT Statement Prescreening

SELECT on SORT or REPORT filters which records continue. RECORD-COUNT still advances for records presented to the activity even when SELECT rejects them in BEFORE logic—understand whether your release counts all reads or only selected rows by testing with a ten-record fixture and SYSPRINT trace. Document the behavior in program prolog comments for maintainers.

Common RECORD-COUNT Mistakes

• DEFINE RECORD-COUNT as user working storage.
• Missing file qualification with multiple FILE definitions.
• Leaving SORT STOP cap in production JCL schedules.
• Equating RECORD-COUNT with TALLY on control reports.
• Expecting count to persist across unrelated JOB activities without verification.
• Confusing SORT SIZE parameter with system RECORD-COUNT.

Explain It Like I'm Five

RECORD-COUNT is the clicker the computer uses when it takes cards from a file box. Each card it picks up clicks once. If you have two boxes, you say which box—MASTER:RECORD-COUNT vs OTHER:RECORD-COUNT—so nobody mixes the counts. You do not make your own clicker with the same name stuck on it; use a different label for your personal counting game. When the clicker still says zero at the end, maybe the box was empty or nobody started reading yet.

Exercises

1. Write IF MASTER:RECORD-COUNT = 0 with DISPLAY and STOP in FINISH. PROC.
2. Add SORT BEFORE cap at 100 records with qualified RECORD-COUNT test.
3. Explain when to use RECORD-COUNT versus WS-ACCEPT-COUNT.
4. Contrast RECORD-COUNT with TALLY on a department control report.
5. Sketch DISPLAY audit line with file name, count, and SYSDATE.