Easytrieve Compatibility

Layers of Compatibility

Think of compatibility in four stacked layers. Source compatibility asks whether the compiler accepts your Library and Activity code. Compile-time options compatibility asks whether PARM lines and the site options table produce the language dialect you expect—COMPAT mode versus new-function mode is the classic split. Runtime compatibility matches load modules to STEPLIB product libraries and module sizes (REGION=0M is common on modern releases). Environmental compatibility covers JCL DD names, SORT product, VSAM cluster definitions, and z/OS levels that the Easytrieve runtime calls. A failure at any layer can look like a mysterious abend or a silent one-cent difference in a financial total.

PARM COMPAT and New-Function Mode

Broadcom recommends that shops migrating from release 6.4 begin testing in compatibility mode. PARM COMPAT (or equivalent settings in the options table) tells the compiler and runtime to preserve behaviors closer to the older product—useful when thousands of programs must compile before you can refactor each one. New-function mode enables 11.x semantics: stricter rules, new statements, and defaults that match current Language Reference documentation. Neither mode is permanently wrong; they are stages. A common migration pattern compiles the portfolio in COMPAT, fixes reserved words and deprecated syntax, runs parallel output compares, then recompiles pilot jobs without COMPAT to discover behavioral deltas documented in release notes.

1
2
3
4
5
PARM COMPAT DEBUG(PMAP) LIST FILE
* Initial migration compile — review listing, then plan COMPAT removal
 
PARM LIST FILE
* Target production profile after compatibility testing passes

COMPAT does not excuse invalid syntax—it only adjusts selected semantics. Programs with fundamental statement errors still fail compile. Also note that site-wide EZOPTBL may set default compatibility flags so individual programs omit PARM COMPAT yet still run in a compatibility-oriented profile until the options table is updated.

Source Portability Across Releases

Easytrieve source is remarkably portable compared to rewriting in COBOL—but portability is not automatic. FILE and field definitions copied from 1980s Classic programs often compile on 11.6 after macro updates. Problems cluster around reserved words (a field DEPT is fine; a field named like a new verb is not), deprecated FILE options (legacy VS keyword versus modern organization codes), and macros that embed obsolete PARM values. Central FILE macros in a shared library improve compatibility: rename a field once in the macro instead of in four hundred programs. The migration-new-reserved-words and reserved-words-by-release pages list patterns to grep across source libraries before mass compile.

Cross-LPAR Source Compatibility

Developers sometimes compile on a training LPAR and promote load modules to production. Source compatibility requires the same compiler maintenance on both—or at least a forward-compatible compile on the lower level. Promoting source members without recompiling on production's level hides runtime mismatches until execution. Best practice: compile and link-edit on the LPAR that will execute the job, using production EZOPTBL and PARM standards.

Runtime and Load Module Alignment

Easytrieve produces link-edited load modules for production batch and online programs. The load module embeds assumptions about runtime entry points and module layout. Executing with an older STEPLIB while the module was built with a newer compiler—or the reverse—causes unpredictable failures. Operations teams track product library concatenation order; developers track compile listings for the maintenance level string. After every compiler SMP apply, schedule a smoke compile and run of representative jobs before declaring the LPAR ready.

JCL and DD Compatibility

JCL compatibility is easy to overlook because source compiled clean. Modern Easytrieve may require WORKFILE datasets, larger REGION, additional SYSPRINT routing, or SORT work data sets that Classic jobs omitted. BUFNO and EXLGD options on FILE statements interact with BLKSIZE and device types—identical source with different JCL can change read performance or trigger capacity exits. Maintain a golden JCL proc per application and version-stamp it when migration changes DD names documented in Broadcom release notes.

1
2
3
4
5
6
7
8
//EZTPROC  PROC
//EZTSTEP  EXEC PGM=EZTPA00,REGION=0M
//STEPLIB  DD  DSN=PROD.EZT1106.SLOAD,DISP=SHR
//         DD  DSN=PROD.CEE.SCEERUN,DISP=SHR
//SYSPRINT DD  SYSOUT=*
//SYSIN    DD  DSN=PROD.EZT.SOURCE(PAYRPT),DISP=SHR
//PAYROLL  DD  DSN=PROD.PAYROLL.DATA,DISP=SHR
//SORTWK01 DD  UNIT=SYSDA,SPACE=(CYL,(5,5))

Macro Library and COPY Compatibility

Macros expand at compile time. A macro compiled successfully on Plus may expand into statements rejected on 11.6 if the macro author used deprecated syntax. Version macro libraries alongside compiler levels—DEV.EZT.MACROS.V11 versus legacy MACROS.OLD—and point SYSLIB or macro DDs explicitly in compile JCL. When one macro fix clears dozens of program errors, compatibility work is macro work as much as application work.

Options Table (EZOPTBL) Compatibility

The options table stores installation defaults: listing format, diagnostic level, compatibility flags, report spacing, and features enabled site-wide. Two programmers with identical source and PARM can get different listings if they compile on LPARs with different EZOPTBL members. Migration projects should copy or regenerate the options table using Broadcom conversion utilities rather than assuming the old table works unchanged. Document which table member production compile procs reference.

Data and File Definition Compatibility

Easytrieve FILE definitions describe record layout—they do not automatically change when the physical file changes. A payroll file lengthened for a new column without updating the Easytrieve FILE block reads misaligned fields silently or with garbage in numeric fields. VSAM KSDS key changes, GDG rollover, and catalog aliases break compatibility without a compile error. Include file layout verification in compatibility test plans when upstream systems change copybooks or record lengths.

Testing Compatibility Systematically

1. Select pilot programs: high value, moderate complexity, mix of batch and online if applicable.
2. Compile on target with documented PARM; archive listing and error count.
3. Execute with frozen test input; capture SYSPRINT and report files.
4. Compare record counts, control totals, and hash sums to baseline from old release.
5. Investigate deltas against release notes—some formatting changes are expected.
6. Recompile without COMPAT on pilots; repeat compare for semantic differences.
7. Scale compile sweep; categorize errors for macro versus program fixes.
8. Sign off with change control evidence before production cutover.

Compatibility Versus Identical Output

Business compatibility does not always mean byte-identical reports. A new release may print dates in a different format, adjust page headers, or round packed decimals consistently with updated rules—documented in release notes. Agree with finance and operations which differences are acceptable. Legal or regulatory reports may require identical totals even if headers change; marketing summaries may tolerate header differences if detail lines match.

Common Compatibility Mistakes

• Assuming compile success equals runtime compatibility.
• Leaving DEBUG SNAP in production PARM after test compiles.
• Ignoring options table differences between LPARs.
• Renaming fields in one program but not in shared macros.
• Skipping SORT and WORKFILE DD updates documented for 11.x.
• Cutting over without parallel-run evidence for financial jobs.

Explain It Like I'm Five

Imagine you have a recipe written for an old oven. Compatibility means checking whether the same recipe still works in a new oven. Sometimes you press the compatibility button so the new oven heats like the old one. Sometimes you must rename an ingredient because the new oven thinks sugar is a special command word. You also need the right pans (JCL), the right shelf (STEPLIB), and the same ingredients (input files). You bake two cakes—old oven and new oven—and compare them before serving cake to the whole school.

Exercises

1. List the four compatibility layers and give one example failure for each.
2. Write two PARM lines: one for initial 6.4 migration, one for production after testing.
3. Explain why identical source can produce different output on two LPARs.
4. Draft a parallel-run compare checklist for a payroll report job.
5. Identify three JCL DD categories to verify when moving from Classic to 11.6.