Easytrieve Runtime

Runtime vs Source vs JCL

Source defines logic. JCL defines resources. Runtime connects them at execution time. When PGM=INVRPT starts, the load module contains generated instructions plus metadata, but many operations are still performed by Easytrieve runtime routines loaded from product libraries. That is why execute JCL often concatenates both application and Easytrieve product libraries in STEPLIB.

Runtime Libraries

Runtime libraries contain modules that support file access, report writing, sort calls, diagnostics, and optional features such as SQL or environment interfaces depending on installation. Sites usually place them in a Broadcom product load library or a copied site-standard library. The exact library names vary by installation, but the concept is consistent: the application module is not self-contained.

1
2
3
4
5
6
//INVRPT   EXEC PGM=INVRPT
//STEPLIB  DD  DSN=PROD.APP.LOADLIB,DISP=SHR
//         DD  DSN=PROD.EASYTRIEVE.CBAALOAD,DISP=SHR
//INVFILE  DD  DSN=PROD.INVENTORY.MASTER,DISP=SHR
//SYSPRINT DD  SYSOUT=*
//INVREP   DD  SYSOUT=A

Runtime Initialization

At startup, the runtime prepares working storage, applies options, initializes report state, and gets ready to open files when processing begins. Counters start at defined values, page and line state is reset, and buffers are allocated. This state lasts for the job step unless the program writes persistent results to output files. A rerun starts runtime state from the beginning.

File Services at Runtime

Runtime file services open DD allocations, read records, translate them into defined fields, and close files at end of processing. For JOB INPUT processing, the runtime performs the read loop automatically. Field values from the current record become visible to IF conditions, expressions, and PRINT requests. If the DD is missing or the dataset attributes do not match the FILE definition, file services fail before business logic processes records.

Report Writer Services

When source issues PRINT for a report, the report writer handles titles, headings, detail lines, spacing, page breaks, totals, and output routing. This is one of Easytrieve's major productivity advantages. Instead of writing page management code by hand, developers declare REPORT, TITLE, and LINE structures and let runtime services format the output.

1
2
3
REPORT PAY-RPT LINESIZE 80
  TITLE 01 'PERSONNEL REPORT EXAMPLE-1'
  LINE 01 DEPT EMPNAME EMPNO GROSS

At runtime, the report writer uses this definition every time PRINT PAY-RPT is executed for a qualifying record. Titles, page numbers, and column alignment are managed by the runtime rather than explicit developer code.

Sort and Buffering Behavior

Many Easytrieve programs rely on internal or external sort services for ordering input or supporting control breaks. Runtime sort behavior may require SORTWK datasets, adequate region size, and correct file attributes. Buffering choices affect I/O performance on large files. Runtime problems in these areas often appear as sort failures, space abends, or long elapsed times rather than syntax errors.

Runtime Diagnostics

Runtime messages usually appear on SYSPRINT. They may include file open results, record counts, report writer notices, DISPLAY output, and abnormal termination information. Compare runtime messages with JES allocation messages. Allocation failures happen before runtime logic. Data failures may happen deep into record processing after thousands of successful reads.

Runtime Version and Compatibility

Test and production should use compatible runtime library levels for a given application module. Upgrading Easytrieve maintenance without regression testing can change report spacing, diagnostic text, or compatibility behavior. Document the product library level beside each application load library in the run book so upgrade projects know what to retest.

Common Runtime Failures

• Module or runtime service not found in STEPLIB chain.
• File open failure due to DD, DISP, security, or DCB mismatch.
• Invalid packed decimal or other data inconsistent with field definitions.
• Sort work space missing or region too small.
• Report output routed to unexpected class or dataset.
• Program logic selects no records, producing empty or heading-only output.

Runtime Performance Basics

Runtime cost is mostly I/O and sorting, not statement counting. Reduce unnecessary PRINT calls, avoid redundant sorts, read only needed files, and ensure input order matches control break design when possible. Easytrieve hides loop code, but it cannot remove the cost of reading a hundred million records. Performance tuning belongs in the lifecycle after functional correctness is proven.

Explain It Like I'm Five

The runtime is the kitchen staff that actually cooks the meal. The recipe is your source. The delivery address is your JCL. The kitchen staff opens ingredients, follows the recipe, plates the food, and tells you if something burned. Without the kitchen staff, the recipe is just paper.

Exercises

1. Identify runtime libraries in a sample execute JCL and explain why both are needed.
2. List runtime services involved in a simple JOB INPUT report program.
3. Describe how a FILE/DD mismatch fails in runtime rather than compile time.
4. Write a runtime troubleshooting checklist for a successful link but failing execute step.
5. Explain why runtime version compatibility matters during product upgrades.