Easytrieve Lifecycle Error Handling

Errors Belong to a Phase

Lifecycle error handling starts with classification. Ask which phase was running when the job ended. A compile step that ends RC=12 never reached execution. A link-edit step with S878 or unresolved external symbols never produced a valid load module. An execute step that ends RC=0 may still have written warning messages you should not ignore. Mapping symptoms to phases prevents random changes and speeds recovery.

Compile-Time Error Handling

Compile errors stop before object code is accepted. The compiler validates Library definitions, Activity logic, REPORT layouts, and PARM options. Messages reference source line numbers when possible. The most efficient fix strategy is to read the first error, correct the root cause—often a missing DEFINE or misspelled FILE name—and recompile. Many subsequent errors disappear once the first definition problem is resolved.

1
2
3
4
5
6
7
8
PARM LINK(MYPAYRPT)
FILE PERSNL FB(150 1800)
  EMPNO    1   5   N
  EMPNAME  6   8   A
JOB INPUT PERSNL
  IF DEPT EQ 'BAD'
     PRINT EMPNAME
  END-IF

If DEPT was never defined in the FILE layout or as working storage, the compiler flags an undefined field. If PERSNL DD is missing in JCL that is a runtime or allocation issue, not a compile issue—the compiler may still accept the source. Keeping compile failures separate from JCL failures avoids editing working source when the job never compiled successfully in the first place.

• Fix Library section definitions before debugging complex Activity logic.
• Verify macro libraries and COPY members when many symbols fail at once.
• Confirm options table and EZTINI settings when PARM options behave unexpectedly.
• Save compiler listings for audit when production migrations require proof of clean compile.

Link-Time Error Handling

After a clean compile, the link-edit step combines object modules into an executable load module. Failures here often look like system abends or binder messages rather than Easytrieve source line references. Unresolved external symbols mean the binder could not find a referenced module—commonly an Easytrieve runtime entry or a called COBOL subprogram. Wrong SYSLIN input or missing object data sets produce immediate link step failures without any execute attempt.

Link errors are owned jointly by developers and build support. Developers confirm the program CALL statements and subprogram names. Build teams confirm object libraries, binder control cards, and promotion of the resulting load module to the correct LOAD library used at execute time. A compile success followed by execute S806 often means the link output never reached the STEPLIB data set the runtime job uses.

Execute-Time and Runtime Errors

Execute-time errors occur when the load module runs against real files and real JCL DD statements. File-not-found conditions usually mean the DD name in JCL does not match the FILE name in source, or the data set does not exist in that environment. Data exceptions such as S0C7 indicate invalid numeric data or arithmetic on non-numeric fields. VSAM empty-file behavior depends on site options such as MTVSERR—some installations treat an empty VSAM input as an immediate abnormal termination.

Easytrieve prints runtime diagnostics to SYSPRINT. When the program abends and ABEXIT processing is active, you may also receive an Error Analysis report with program name, abend code, and optional statement flow information. Treat SYSPRINT as the primary developer transcript and the Error Analysis report as the structured abend summary.

Error Analysis Report and ABEXIT

Broadcom documents the Error Analysis report for abnormal terminations when ABEXIT SNAP or ABEXIT NOSNAP is specified on the PARM statement. SNAP requests a dump in addition to the report; NOSNAP produces the report without a dump. The report identifies the program, describes the error that caused termination, and may include a flow table when FLOW tracing was active. Message EZABX016 shows recently executed statement numbers, newest first, which helps you locate the failing instruction in a large program.

1
2
3
4
5
PARM LINK(PAYAUD) ABEXIT(SNAP) DEBUG(STATE,FLOW) FLOWSIZ(20)
FILE PERSNL FB(150 1800)
  GROSS  40  7  P 2
JOB INPUT PERSNL
  TOTAL = TOTAL + GROSS

In this pattern, ABEXIT SNAP enables dump and analysis output on abend. DEBUG STATE records the statement number of the instruction executing at failure time. DEBUG FLOW maintains a rolling table of recent statement numbers. FLOWSIZ controls how many entries the flow table retains. During testing these options are invaluable; in high-volume production they add storage and CPU cost, so sites often rely on lighter defaults.

DEBUG Options Compared

Return Codes and Severity

z/OS jobs return a condition code summarizing step severity. Easytrieve compile steps commonly use RC=4 for warnings and RC=12 or higher for errors. Operations may treat RC=4 as success with review or as failure depending on shop standards. Runtime programs may complete with RC=0 while SYSPRINT contains file status messages you should investigate. Do not equate “job green” with “business correct.”

Batch schedulers often propagate the highest return code from any step. A compile step RC=12 prevents downstream execute steps from running in well-controlled pipelines. When debugging ad hoc jobs, confirm which step actually failed before opening the wrong listing. JESJCL shows step completion codes in order.

JCL and DD Errors vs Program Errors

Many “Easytrieve failures” never enter Easytrieve logic. S013 allocation errors, missing STEPLIB, wrong DISP on a GDG, and security access denials fail during JCL processing or dataset open before meaningful program output appears. These require JCL and operations correction, not source edits. Conversely, a perfectly allocated file with corrupt packed decimal data is a program and data-quality issue solved with FLDCHK during test, better input validation, or upstream data fixes.

1. Read JES messages for allocation and security failures.
2. Confirm STEPLIB contains EZTPA00 or your application load module.
3. Match every FILE statement to a DD name in the execute JCL.
4. Only then analyze Easytrieve SYSPRINT and source logic.

Production Escalation Practices

Mature shops document who acts on each failure type. Developers own source defects and unit-test reruns. Build services own link and promotion gaps. Operations owns scheduler definitions, production dataset availability, and spool routing. Incidents handed to operations should include job name, job ID, failing step, return code, abend code if any, relevant DD names, and whether SYSPRINT or Error Analysis output was captured before spool purge.

Change control ties lifecycle error handling to audit. When a production payroll job fails after a promote, compare compile listing dates, load module timestamps, and JCL proc versions against the last successful cycle. Rollback decisions depend on evidence, not guesses about which programmer edited which member last night.

Preventive Habits

• Compile in development with the same PARM options tables intended for production.
• Run representative test files before promotion, including empty files and edge cases.
• Separate diagnostic SYSOUT from business report DDs so failures are easy to find.
• Document ABEXIT and DEBUG usage so production jobs do not inherit test settings accidentally.
• Keep a checklist per application: compile, link, execute JCL members and owner contacts.

Explain It Like I'm Five

Making an Easytrieve report is like baking a cake in a factory. First someone writes the recipe—that is your source. The compiler checks the recipe for mistakes. The linker puts the finished mix into a box you can ship—the load module. The oven run is execution. If the recipe has a typo, fix the paper before baking. If the oven never turned on, that is a JCL problem, not a recipe problem. Lifecycle error handling means knowing which kitchen step failed and looking at the right clipboard for clues.

Exercises

1. List four lifecycle phases and one typical error source for each.
2. Write a PARM line with ABEXIT SNAP and DEBUG(STATE,FLOW) and explain each piece.
3. Describe how you would distinguish a compile RC=12 from an execute S806.
4. Create an escalation note template with job ID, step, RC, and output DD names.
5. Explain why FLOW should usually be disabled after testing completes.