Easytrieve Libraries Overview

What “Library” Means on the Mainframe

A library is a managed dataset that stores related members. A source library might hold Easytrieve programs as text members. A load library holds executable members created by compile and link-edit. A macro library holds reusable snippets that are copied into a program during compilation. A procedure library holds JCL procedures. These libraries are not folders in the Windows sense, but the idea is similar: a named place where the system searches for a member.

Easytrieve depends on library search order. If the same member name exists in two concatenated libraries, z/OS generally uses the first one it finds. That can be a feature or a trap. Test libraries are often placed ahead of production libraries so a developer can override one member without copying the whole production set. The same approach can accidentally run stale source if the concatenation order is wrong.

The Core Easytrieve Library Types

Compile-Time vs Runtime Libraries

Compile-time libraries support source translation. They include the compiler module, source members, macro members, copy or include members, options tables, and listing destinations. Runtime libraries support actual execution. They include application load modules, product runtime modules, input files, output files, and sometimes sort work datasets. A compile job and a run job may share STEPLIB entries, but they do not have the same purpose.

• Compile-time question: where is the compiler and what source should it read?
• Runtime question: where is the executable program and what datasets should it process?
• Promotion question: which load library receives the tested module?
• Operations question: which production libraries are stable enough for the scheduler?

Example Compile Library Layout

1
2
3
4
5
6
7
//EZTCOMP  EXEC PGM=EZTPA00
//STEPLIB  DD  DSN=DEV.EASYTRIEVE.CBAALOAD,DISP=SHR
//         DD  DSN=DEV.APP.LOADLIB,DISP=SHR
//SYSPRINT DD  SYSOUT=*
//SYSIN    DD  DSN=DEV.EZT.SOURCE(PAYRPT),DISP=SHR
//PANDD    DD  DSN=DEV.EZT.MACLIB,DISP=SHR
//SYSLIN   DD  DSN=&&OBJ,UNIT=SYSDA,SPACE=(TRK,(5,5)),DISP=(,PASS)

STEPLIB lets the step find EZTPA00 and related product code. SYSIN points to the source member. PANDD is a common name used in many Easytrieve shops for macro input, though your installation may use another DD name. SYSPRINT captures the listing. SYSLIN holds generated object for a later binder step. Each DD has a different job, so swapping one for another does not work.

Example Runtime Library Layout

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

In runtime JCL, STEPLIB now points first to the application load library because the job is trying to run PAYRPT. The product runtime library follows so referenced runtime services can resolve. PERSNL is the business file, not a library in the source-control sense, but it is still a dataset allocation the runtime depends on. PAYOUT and SYSPRINT route generated output.

Library Concatenation Order

Concatenation means multiple DD lines share one logical DD name. z/OS searches them in order. For STEPLIB, the first load library may contain application modules, followed by vendor runtime libraries. For source or macro DD names, the first library may be a test override, followed by shared production macros. This order is powerful because it supports controlled overrides, but it requires discipline.

Why order matters

• If a test macro library is first, the test macro overrides production for that compile.
• If an old product library is first, the step may load outdated runtime modules.
• If application load library is missing, PGM=PAYRPT may fail before Easytrieve logic starts.
• If two teams use the same member name, a broad concatenation can pick the wrong member.

Source Libraries and Change Control

Easytrieve source may live in a PDS, PDSE, Endevor, Changeman, Git-backed deployment flow, or another enterprise source manager. The library idea still applies because the compiler ultimately reads source text from a DD allocation. In older shops, developers edit PDS members directly in ISPF. In newer shops, source may be promoted through change packages and copied into controlled compile libraries during deployment.

Beginners should always ask three questions before editing or compiling: where is the authoritative source, how is it promoted, and which library does the compile procedure actually read? Editing a personal test member does nothing for production unless the promotion path moves that member into the approved library.

Macro Libraries

Macro libraries reduce repeated source. A shop might have a standard header macro, audit field definitions, company date routines, or report footer logic stored once and expanded into many Easytrieve programs. This keeps standards consistent, but it also means a single macro update can affect many future compiles. That impact is why macro libraries often have tighter change control than ordinary ad hoc report source.

1
2
3
4
5
6
7
* Source member PAYRPT
%STD-HDR
FILE PERSNL FB(150 1800)
%HR-FIELDS
 
JOB INPUT PERSNL
  PRINT PAY-RPT

The percent-prefixed macro style shown here is representative of how many sites present macro calls, but exact syntax and DD names can vary by release and local standards. The key runtime lesson is that the compiler needs the macro library during compile; the finished load module does not reread the macro source at runtime.

Output Libraries and SYSOUT

Not every library is executable or source-oriented. Many batch jobs write report output to SYSOUT classes, archive datasets, GDGs, or distribution products. SYSPRINT may hold diagnostic output, while business report DD names hold printable reports. A report that “ran successfully” but is missing from the recipient queue may have a routing problem, not an Easytrieve logic problem.

Security and Access

RACF, ACF2, or Top Secret protects production libraries. A developer may be allowed to read a source library but not update it; a scheduler ID may run a program but not read test input datasets; a compile procedure may write only to a controlled staging library. Security failures appear as allocation or open errors, so do not assume they are source bugs. The DD name, dataset name, and security message identify the real authority problem.

Practical Checklist for Library Problems

1. Confirm whether the failing step is compile, link, or runtime.
2. List every DD name and decide whether it points to product, source, macro, load, input, or output data.
3. Check concatenation order, especially when test and production libraries are mixed.
4. Verify dataset names, member names, DISP values, volume needs, and security access.
5. Compare the failing job with a recent successful job for the same application.
6. Document the final library set in the run book so the next failure is faster to diagnose.

Explain It Like I'm Five

Imagine building a model airplane. You need the instruction book, the box of parts, the glue, the finished airplane shelf, and a place to put scraps. Easytrieve libraries are those places. Source libraries hold instructions. Load libraries hold finished airplanes. Product libraries hold special tools. Output datasets hold the report you made. If you grab the wrong box, the airplane may not build even if the instructions are good.

Exercises

1. Label every DD statement in a compile JCL as source, product, macro, listing, object, or output.
2. Explain why concatenation order can change which macro member is compiled.
3. Write a short checklist for promoting source to a production load library.
4. Compare an Easytrieve source library with an application load library in plain English.
5. Find one way a security failure could look like a library problem.