STEPLIB in Easytrieve JCL

Why STEPLIB Matters for Easytrieve

Easytrieve is not just a source language. It has compiler modules, runtime modules, report writer routines, sort interfaces, optional SQL or environment support, and application programs produced by the binder. z/OS must find those executable pieces before source logic can run. STEPLIB controls that lookup for one step. When STEPLIB is wrong, the step may fail before Easytrieve reads SYSIN, opens a business file, or writes a single line to a report.

This makes STEPLIB one of the first places to check when a job fails with module-not-found messages, unexpected release behavior, or differences between test and production. It is also a promotion control point. A scheduler can run the same JCL skeleton against test or production modules by changing which libraries appear in STEPLIB.

STEPLIB in a Compile Step

A compile step usually runs PGM=EZTPA00, the Easytrieve processor. The loader must find EZTPA00 and any supporting product modules. Some sites place these modules in a product library named with Broadcom’s installed high-level qualifier; others copy or alias them into site-standard load libraries. The DD name is still STEPLIB if the step defines a step-specific search path.

1
2
3
4
5
//COMPILE  EXEC PGM=EZTPA00
//STEPLIB  DD  DSN=TEST.EASYTRIEVE.CBAALOAD,DISP=SHR
//         DD  DSN=TEST.APP.LOADLIB,DISP=SHR
//SYSPRINT DD  SYSOUT=*
//SYSIN    DD  DSN=TEST.EZT.SOURCE(SALESRPT),DISP=SHR

The first STEPLIB line points to the Easytrieve product load library in this example. The second line extends the same STEPLIB concatenation to an application load library. During compile, the most important module is EZTPA00. During link or compile-and-go, other runtime routines may also be needed.

STEPLIB in a Runtime Step

A production runtime step usually runs PGM=your program name, not PGM=EZTPA00. That program name must exist in an application load library. After it is found, its references to Easytrieve runtime routines must resolve through the same STEPLIB chain or the system link list. That is why application libraries and product runtime libraries often appear together.

1
2
3
4
5
6
//RUNRPT   EXEC PGM=SALESRPT
//STEPLIB  DD  DSN=PROD.APP.EZT.LOADLIB,DISP=SHR
//         DD  DSN=PROD.EASYTRIEVE.CBAALOAD,DISP=SHR
//SALESIN  DD  DSN=PROD.SALES.DAILY,DISP=SHR
//SYSPRINT DD  SYSOUT=*
//REPORT   DD  SYSOUT=A

Here, z/OS searches PROD.APP.EZT.LOADLIB first for SALESRPT. If SALESRPT needs product services not built into the module, the loader can continue into PROD.EASYTRIEVE.CBAALOAD to resolve them. If the application library is omitted, PGM=SALESRPT may fail. If the product library is omitted, the program may start loading but fail when a runtime service cannot be found.

Concatenation Order

STEPLIB concatenation is ordered. The first DD statement under STEPLIB is searched first, then the second, and so on. This order matters whenever the same module name appears in more than one library. A common test setup places a developer or QA library first, then shared production libraries. That lets one changed module override production for a controlled test without copying every module.

STEPLIB vs JOBLIB vs Link List

STEPLIB applies to one job step. JOBLIB applies to the job as a whole for steps that do not have their own STEPLIB. The system link list is a system-managed search path for commonly available modules. Easytrieve jobs can use any combination depending on site standards. Many production JCL procedures use STEPLIB because it makes the exact release and application load library visible in the step output.

APF Authorization and Site Controls

Some load libraries are APF-authorized because they contain privileged modules. If a program requires authorized services, every library in the STEPLIB concatenation may need to meet site authorization rules. Easytrieve report jobs usually do not require you to understand APF deeply, but you should recognize authorization messages as environment issues. Do not “fix” them by moving libraries around without systems programming review.

Common STEPLIB Failure Patterns

• CSV003I or similar module-not-found messages for EZTPA00, the application program, or runtime support.
• Test job accidentally points to production load libraries and runs old code.
• Production job points to a decommissioned product library after an Easytrieve upgrade.
• Library exists but scheduler ID lacks READ authority.
• Concatenation contains an incompatible mix of product releases.
• A catalog alias change makes a previously valid DSN resolve incorrectly or not at all.

How to Troubleshoot STEPLIB

Troubleshooting STEPLIB is systematic. First identify the exact module named in the error. Then identify each load library in the step. Confirm the module exists where you expect, that the dataset is cataloged, that the running user has access, and that the order places the intended module before alternatives. Compare with a recent successful job rather than guessing.

1. Find the failing step and module name in JES output.
2. List each STEPLIB DSN in order and classify it as application, product, or shared support.
3. Check whether the module exists in the expected library member list.
4. Verify the executing ID has read access to every library in the concatenation.
5. Compare product release levels if an upgrade or maintenance window occurred recently.
6. Fix JCL or procedure symbols in the scheduler, not a one-off copy, when the issue is systemic.

Good STEPLIB Practices

Keep STEPLIB small and intentional. Broad concatenations slow diagnosis and increase the chance of picking up the wrong member. Use symbolic variables in procedures when moving between DEV, QA, and PROD, but make the resolved dataset names visible in job output. Document which Easytrieve product library belongs to each application release. Avoid mixing test and production libraries unless a controlled test plan requires it.

Relationship to Easytrieve Source

STEPLIB does not read Easytrieve source. SYSIN, source management tools, or compile procedures handle source. STEPLIB is only about load modules. This distinction prevents a common beginner mistake: changing SYSIN source and expecting a runtime step to pick it up. A runtime step using PGM=SALESRPT reads the load module from STEPLIB; it does not recompile source unless the job is explicitly a compile-and-go flow.

Explain It Like I'm Five

STEPLIB is like telling a teacher which cupboard holds the class toys for today. If the teacher looks in the wrong cupboard, the toy is missing. If two cupboards have a toy with the same name, the teacher takes the first one. Easytrieve jobs need the right cupboard order so they use the right program and the right Easytrieve tools.

Exercises

1. Write a STEPLIB concatenation for a runtime step that searches an application load library before a product library.
2. Explain why source changes are not picked up by a runtime-only PGM= report step.
3. Given two libraries with the same module name, predict which one z/OS uses.
4. List three checks for a module-not-found error in an Easytrieve compile step.
5. Compare STEPLIB, JOBLIB, and link list in one sentence each.