Easytrieve Error Handling Pattern

Severity Levels

Map VAL-STATUS codes from validation to severity in HANDLE-VALIDATION-ERROR—format errors might be level 2, control total failure level 4. Document the matrix in Library comments. Screen programs map level 2 to GOTO SCREEN with message; level 4 might DISPLAY and EXIT SCREEN activity with error panel.

HANDLE-ERROR PROC Skeleton

1
2
3
4
5
6
7
8
9
10
11
12
13
14
HANDLE-VALIDATION-ERROR. PROC
  PERFORM GET-MSG-FOR-CODE
  WRITE ERROR-FILE
  ADD 1 TO ERR-COUNT
  IF ERR-COUNT GT ERR-LIMIT
     PERFORM LOG-FATAL
     STOP
  END-IF
END-PROC
 
LOG-FATAL. PROC
  DISPLAY 'FATAL: ERR-COUNT EXCEEDED LIMIT'
  DISPLAY MSG-TEXT
END-PROC

ERR-LIMIT is a parameter from control file or INIT-JOB—100 for daily loads, zero for balance files requiring perfection. LOG-FATAL centralizes final DISPLAY text so operations search one string in syslog. STOP prevents further UPDATE after too many rejects pollute partial output.

ERROR-FILE Layout

Define ERROR-FILE in Library with fixed layout: run date, program ID, error code, key fields from input, optional full input record image, message text. Fixed length simplifies downstream reprocess JOB that JOB INPUT ERROR-FILE and attempts correction. Include sequence number for duplicate key diagnosis. WRITE in HANDLE-ERROR after MOVE fields from current input buffer—do not WRITE after buffer overwritten by next read.

1
2
3
4
5
6
7
FILE ERROR-FILE SEQUENTIAL
  ERR-RUN-DATE  8  N
  ERR-CODE      4  N
  ERR-KEY      20  A
  ERR-MSG      60  A
  ERR-RECORD  200  A
END-FILE

DISPLAY Strategy

Development

DEBUG-FLAG = 'Y' enables DISPLAY of record keys and VAL-STATUS each iteration. Developers see flow in batch output without debugger attachment.

Production

DISPLAY only at INIT, TERM, and LOG-FATAL. Per-record failures go to ERROR-FILE. TERM-JOB DISPLAY summarizes READ-COUNT ERR-COUNT OK-COUNT in three lines operators paste into tickets.

Batch Error Flow

1
2
3
4
5
6
7
8
9
10
11
JOB INPUT TRANS-FILE
  PERFORM VALIDATE-RECORD
  IF VAL-STATUS NE ZERO
     PERFORM HANDLE-VALIDATION-ERROR
  ELSE
     PERFORM UPDATE-MASTER
     ADD 1 TO OK-COUNT
  END-IF
END-JOB
 
PERFORM TERM-JOB

TERM-JOB checks IF ERR-COUNT GT ZERO DISPLAY warning summary even when job completed—JCL might still return zero but operations see yellow flag in log. Some shops set RETURN-CODE field if product supports passing to JCL—document availability per release.

Screen Error Flow

INITIATION errors—file OPEN fail—DISPLAY on screen message row if supported or abort SCREEN with clear text. AFTER-SCREEN validation errors MOVE MSG-TEXT to error line, set cursor field, GOTO SCREEN. Unrecoverable errors in TERMINATION CLOSE files cleanly. Do not STOP mid-conversation without message—operators think session hung.

Environmental Failures

Missing DD, SPACE not allocated, OPEN failure on master file—these are severity 4 in INIT-JOB. Test file status fields or first READ result per FILE documentation. HANDLE-ENV-ERROR DISPLAY DD name and STOP before JOB INPUT processes zero records that look like success. Empty driver file might be warning or fatal depending on business—document which; payroll rerun expects fatal, optional enrichment file might warn and continue.

Compiler Versus Runtime

Compiler errors block execution—fix source, no runtime HANDLE applies. Runtime errors—divide by zero, invalid file status—need prevention via validation and IF guards. Runtime abends from product may not pass through HANDLE-ERROR; design defensive IF before risky operations. Warnings in listing deserve zero-warning policy for production compiles—see compiler options tutorials.

Threshold Design

JCL and Operations Coordination

Document expected dataset outputs when ERROR-FILE empty versus nonempty. Operations rerun from ERROR-FILE correction JOB when severity 2 only. Fatal STOP triggers pager—ensure DISPLAY text includes job name and step. GDG roll-off for ERROR-FILE retains history. Pair with reusable report framework to print exception listing from same ERROR-FILE automatically in TERM phase.

Common Mistakes

• STOP inside validation PROC—use HANDLE layer.
• Success exit with ERR-COUNT high but no TERM warning.
• ERROR-FILE WRITE after next JOB INPUT read overwrote buffer.
• Unbounded DISPLAY in production loop.
• No ERR-LIMIT on destructive UPDATE jobs.
• Screen STOP without user-visible message.

Explain It Like I'm Five

When something goes wrong on a field trip, the teacher has a plan: small problem—note it in a notebook and keep going; too many problems—call the school and everyone goes home. Error handling is that plan. The notebook is the error file. Calling the school is STOP. The teacher does not ask every kid to shout the problem at once—that would be too many DISPLAY messages.

Exercises

1. Define ERROR-FILE layout with six fields and explain each.
2. Write HANDLE-VALIDATION-ERROR with ERR-LIMIT check and STOP.
3. Map three VAL-STATUS codes to severity levels and actions.
4. Write TERM-JOB DISPLAY summary for operations.
5. Describe INIT-JOB behavior when OPEN fails on master file.