Easytrieve Runtime Process

Runtime in One Pass

A typical Easytrieve runtime step follows a predictable chain. JES reads the submitted JCL, z/OS allocates the files named by DD statements, the program and Easytrieve runtime services are loaded from the STEPLIB or link-list path, and control transfers to the generated Easytrieve code. The code initializes working fields, opens files, runs the JOB activity, prints reports, closes resources, writes diagnostics, and returns a condition code.

1. JES selects the job step and validates basic JCL syntax.
2. z/OS allocates DD names such as SYSIN, SYSPRINT, SORTWK, and business files.
3. The loader locates the Easytrieve program and required runtime modules.
4. Runtime initialization prepares buffers, options, working storage, and report state.
5. Input files are opened and records are read according to JOB INPUT or explicit logic.
6. Activity statements evaluate conditions, calculations, PRINT requests, and procedure calls.
7. The report writer formats titles, headings, detail lines, totals, pages, and output datasets.
8. Files are closed, messages are written, and the step returns a condition code.

Load Module and Runtime Library

In a compiled production flow, the JCL step normally runs a load module created earlier by the compiler and binder. That load module does not contain every service it needs. It relies on Easytrieve runtime routines for file handling, report formatting, sorting, and environment services. Those routines are found through STEPLIB, JOBLIB, LNKLST, or a site-specific product library.

This is why two programs with identical source can behave differently across regions. Test may point STEPLIB to one Easytrieve maintenance level while production points to a newer library. Runtime library mismatch can produce missing module errors, option differences, or subtle compatibility behavior. A good operations checklist records the program library, runtime library, and product release together.

DD Allocation Connects Names to Data

Easytrieve source uses logical file names. JCL connects those names to physical datasets with DD statements. If the source says FILE PERSNL, the runtime expects a DD named PERSNL unless the shop has wrapper procedures or dynamic allocation conventions. A compiled program can be perfect and still fail because the dataset was deleted, the DD name is misspelled, the disposition is wrong, or the LRECL does not match the program assumptions.

1
2
3
4
5
//RUNRPT   EXEC PGM=PAYRPT
//STEPLIB  DD  DSN=PROD.EASYTRIEVE.LOADLIB,DISP=SHR
//PERSNL   DD  DSN=PROD.HR.PERSONNEL,DISP=SHR
//SYSPRINT DD  SYSOUT=*
//PAYOUT   DD  SYSOUT=*

In this example, PERSNL is the business input file. SYSPRINT receives messages and diagnostics. PAYOUT might receive a report if the program or site procedure directs report output there. At runtime, z/OS resolves these DD statements before Easytrieve can process records. Missing DD names fail early because the runtime cannot open the file.

JOB INPUT and the Automatic Loop

Easytrieve is popular because a simple JOB INPUT statement hides the repetitive read loop that COBOL programmers usually write by hand. With JOB INPUT PERSNL, the runtime opens PERSNL, reads the first record, executes the activity statements, reads the next record, and repeats until end of file. At EOF, it finishes reports, closes files, and ends the step.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
FILE PERSNL FB(150 1800)
  EMPNAME  17  8  A
  EMPNO     9  5  N
  DEPT     98  3  N
  GROSS    94  4  P  2
 
JOB INPUT PERSNL
  IF DEPT = 911
    PRINT PAY-RPT
  END-IF
 
REPORT PAY-RPT LINESIZE 80
  TITLE 01 'PERSONNEL REPORT'
  LINE 01 DEPT EMPNAME EMPNO GROSS

The important runtime idea is that IF logic runs once per input record. PRINT does not immediately write a finished page in the way a beginner might imagine. It passes detail information to the report writer, which manages headings, line counts, page numbers, breaks, and totals according to the REPORT definition.

Runtime State: Working Fields, Counters, and Reports

At startup, working storage fields receive their defined initial values or product defaults. Counters begin at zero, report page state is reset, and buffers are prepared. During processing, every record may update working fields, accumulate totals, or trigger a report line. That state lives only for the job step unless the program writes it to an output file. Restarting the job starts the runtime state over unless restart logic uses checkpoints or input positioning outside Easytrieve.

Runtime Errors vs Compile Errors

Compile errors are discovered before execution: invalid syntax, undefined field names, missing END-IF statements, incompatible options, or invalid report references. Runtime errors are discovered while processing real data and real JCL. This distinction matters because the fix may belong to a developer, scheduler, storage team, security team, or data provider.

• Allocation failure means the program could not connect a DD name to a usable dataset.
• Open failure means the DD exists but attributes, disposition, security, or catalog state are wrong.
• Bad packed decimal data means the field definition expects packed numeric bytes but the record contains invalid nibbles.
• Space or print failure means output could not be written even though logic was valid.
• Sort failure may indicate missing SORTWK space, invalid sort parameters, or insufficient region size.

Return Codes and Abend Codes

At the end of a runtime step, operations watches the condition code. A zero return code normally means the program ended successfully. A warning or error return code means the job ended but something requires attention. An abend means the step ended abnormally, often with system or user abend information. The exact meanings are site-specific, so beginners should read the message text rather than assuming every RC 4 or RC 8 has the same business meaning.

How to Debug a Runtime Failure

Start from the outside and move inward. First confirm the JCL step that failed. Then read JES allocation messages to see whether DD statements resolved. Next read SYSPRINT for Easytrieve diagnostics. If the program processed some records, use record counts, report totals, DISPLAY lines, or last successful output to locate the data region where failure occurred. Resist changing source before proving the source caused the problem.

1. Record job name, step name, program name, return code, and abend code.
2. Check whether STEPLIB and business DD statements allocated successfully.
3. Read SYSPRINT messages from top to bottom, not only the last line.
4. Compare input dataset attributes with the FILE statement: record format, length, and organization.
5. Review recent scheduler, dataset, security, and Easytrieve library changes.
6. Only then decide whether source, JCL, data, or environment must change.

Runtime Performance Basics

Runtime performance depends on data volume, file organization, buffering, sort volume, report output size, and CPU-heavy calculations. A report that runs quickly against one department may slow down when the input changes from one million records to one hundred million. Easytrieve hides much of the loop code, but it cannot remove I/O cost. Reading fewer records, sorting only necessary fields, using correct input order for control breaks, and avoiding unnecessary PRINT calls are practical beginner optimizations.

Explain It Like I'm Five

Think of compilation as writing instructions for a toy train. Runtime is the moment the train actually runs on the track. The track must be connected, the batteries must work, the stations must have names, and the train must carry the right cars. If the track is broken, the instructions can still be correct, but the train will stop. Easytrieve runtime is the train ride: files are tracks, records are passengers, and SYSPRINT tells you where the train stopped if something went wrong.

Exercises

1. Take a small Easytrieve report and list every DD name it needs at runtime.
2. Explain why a program can compile successfully but fail before reading the first record.
3. Write a debugging checklist for a missing input dataset error.
4. Mark which part of a sample job is compile time and which part is runtime.
5. Describe how JOB INPUT changes the code a COBOL programmer would otherwise write.