Easytrieve Validation Framework

Framework Components

RETURN-CODE Convention

Pick one working storage field—VAL-STATUS, RETURN-CODE, or CHECK-RESULT—and use it everywhere. Every validation PROC sets it to zero on success or a positive numeric code on failure. Callers test IF VAL-STATUS NE ZERO before UPDATE. Never overload multiple meanings into one code without documentation; reserve ranges: 1–99 format errors, 100–199 referential errors, 200+ business rule violations. Document the table in a shared comment member operations can search. Matching codes across batch and screen programs lets the same training materials explain rejects whether they appear on a terminal or in an error file.

1
2
3
4
5
6
7
8
VALIDATE-DATE. PROC
  MOVE ZERO TO VAL-STATUS
  IF IN-DATE LT '19000101' OR IN-DATE GT '20991231'
     MOVE 12 TO VAL-STATUS
     EXIT
  END-IF
  * Additional calendar logic (month/day) sets code 13, 14, ...
END-PROC

Batch Record Validation Flow

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

VALIDATE-RECORD internally PERFORMs field-level PROCs—date, amount sign, key existence via READ on reference file—and stops at first failure or accumulates multiple codes depending on framework policy. Fail-fast is simpler for beginners; accumulate-all suits regulatory listings showing every error on one record. WRITE-ERROR-RECORD moves input buffer, VAL-STATUS, and message text to ERROR-FILE layout defined in Library FILE section.

Screen Validation Layers

Declarative layer

ROW field definitions use VALUE lists, NUMERIC, MUSTENTER, and ERROR message clauses. Easytrieve catches invalid keystrokes before AFTER-SCREEN runs. This layer handles format—digits only, allowed Y/N—not whether the account exists on the master file.

Procedural layer

AFTER-SCREEN PERFORMs the same VALIDATE-ACCOUNT PROC batch uses. On failure MOVE message from error table to screen MSG field and GOTO SCREEN. Framework ensures message text matches batch error file text for the same VAL-STATUS code—operators recognize one vocabulary.

1
2
3
4
5
6
7
8
9
AFTER-SCREEN. PROC
  PERFORM VALIDATE-ACCOUNT
  IF VAL-STATUS NE ZERO
     PERFORM GET-MSG-FOR-CODE
     MOVE MSG-TEXT TO SCR-ERROR-LINE
     GOTO SCREEN
  END-IF
  PERFORM UPDATE-MASTER
END-PROC

Error Code Table Pattern

Store codes and messages in a static table loaded at INIT or hard-coded in GET-MSG-FOR-CODE CASE structure. For large message sets use a small reference file and SEARCH or sequential READ in GET-MSG-FOR-CODE. Table driven frameworks let non-programmers update messages in a flat file if your change process allows. Keep codes stable across releases; add new codes at unused numbers rather than renumbering—historical error files remain interpretable.

Soft Versus Hard Failures

Soft failure writes the record to ERROR-FILE and continues processing—typical for large batch loads where a few bad rows should not stop millions of good ones. Hard failure sets a JOB-ABORT flag, DISPLAY or writes a severe message, and STOPs when control totals fail or reference files are missing. Framework documents which PROCs use which severity. VALIDATE-CONTROL-TOTAL might be hard; VALIDATE-ZIP-CODE might be soft. Mixing severities without documentation causes overnight jobs to stop when operations expected only an error file.

Composable VALIDATE PROCs

Small PROCs compose into VALIDATE-RECORD. VALIDATE-DATE knows nothing about accounts. VALIDATE-ACCOUNT READs master and sets code 41. VALIDATE-AMOUNT checks sign and decimal rules. VALIDATE-RECORD sequences PERFORMs and optionally short-circuits on first error. Composition beats monolithic thousand-line PROCs you cannot unit test. Naming convention VALIDATE-entity and CHECK-entity helps new developers find the right routine in the Library index.

Integration With Error Handling Pattern

Validation sets VAL-STATUS; error-handling pattern decides DISPLAY versus ERROR-FILE versus STOP. Keep validation PROCs free of STOP—they only set status. A separate HANDLE-VALIDATION-ERROR PROC increments counters, writes files, and evaluates JOB-ABORT threshold such as IF ERR-COUNT GT 100 STOP. Separation lets screen programs HANDLE without STOP while batch uses STOP on threshold breach.

Testing Strategy

1. Build a test file with one row per error code—golden reject set.
2. Run batch JOB and confirm each row lands in ERROR-FILE with correct code and message.
3. Screen test: enter each bad value, confirm AFTER-SCREEN message matches batch text.
4. Zero-error file: all records pass—OK-COUNT equals READ-COUNT, ERR-COUNT zero.
5. Control total failure triggers hard stop when configured.

Common Mistakes

• UPDATE before PERFORM VALIDATE-RECORD completes.
• Different message text for same code in screen versus batch.
• Validation PROC that STOPs instead of setting RETURN-CODE.
• No ERROR-FILE for batch—only DISPLAY lost in syslog.
• Monolithic VALIDATE-EVERYTHING PROC unmaintainable after first release.
• Ignoring declarative ROW checks and revalidating format in AFTER-SCREEN redundantly.

Explain It Like I'm Five

Before homework goes in the teacher's basket, someone checks each page: name written, numbers in the right boxes, answers not blank. The validation framework is that checker team with the same red stamp for each mistake—stamp 12 always means bad date. Batch homework goes in a reject pile; screen homework gets handed back to you to fix before it counts. Same stamps, same rules, different place the paper goes.

Exercises

1. Define five error codes with ranges and message text for a payroll file.
2. Write VALIDATE-DATE PROC setting VAL-STATUS 12 on empty date.
3. Sketch AFTER-SCREEN flow using framework PROC and GOTO SCREEN.
4. Compare soft versus hard failure for control total mismatch—justify choice.
5. List three checks belonging in declarative ROW versus procedural AFTER-SCREEN.