Cross-reference options control whether the compiler builds an alphabetical index of where each symbol is defined and referenced—a maintenance tool as valuable as ISPF search when you inherit a payroll program written decades ago. DEBUG XREF on PARM requests the section; DEBUG XREF LONG expands detail; NOXREF suppresses it when site defaults would otherwise print pages of indices. Configuration Manager Options Table XREF accepts L, S, or N values establishing installation baseline overridable per compile. Beginners confuse XREF with DMAP: DMAP answers byte offsets in records; XREF answers who uses the name NET-PAY across JOB, REPORT, and PROC sections. Duplicate field names between FILE and working storage, typos between EMPLNO and EMP-NO, dead DEFINE fields never referenced—all surface faster in XREF than manual scrolling. This page explains enabling XREF, LONG versus SHORT trade-offs, reading define and reference columns, workflow with compiler listings, pairing with LIST options, production listing diet, and migration when old Plus listings used different section headers.
Primary control is PARM DEBUG clause. Typical development line includes XREF alongside DMAP and PMAP. Options Table XREF=L sets long form site-wide; individual program can shorten with DEBUG XREF SHORT or disable with DEBUG NOXREF when compiling stable modules in mass rebuild.
12345678910PARM DEBUG(PMAP DMAP XREF LONG) LIST FILE FILE PERSNL FB(80 800) EMP-NO 1 6 N NAME 7 20 A DEFINE TOT-GROSS W 7 P 2 JOB INPUT PERSNL TOT-GROSS = TOT-GROSS + GROSS
After compile, open XREF section—search EMP-NO, TOT-GROSS, PERSNL. Reference list shows statement numbers for JOB arithmetic, FILE definition, and any REPORT LINE usage.
| Value | Meaning | PARM override |
|---|---|---|
| L (Long) | Detailed cross-reference listing | DEBUG XREF LONG or SHORT |
| S (Short) | Abbreviated cross-reference | DEBUG XREF SHORT |
| N (None) | No cross-reference unless PARM requests | DEBUG XREF |
Symbols appear alphabetically. Each entry lists definition statement number—FILE DEFINE line or PROC label—and reference lines where compiler saw the name in expressions, IF tests, LINE lists, or SORT keys. Qualified names may show FILE:FIELD form when ambiguity exists. Statement numbers tie back to numbered column in statement listing—jump in ISPF with SEU or PDF editor using listing as map.
Duplicate names across FILE and W storage require qualification in logic—XREF reveals unqualified references that might bind wrong symbol. Fields defined but never referenced appear with definition only—candidates for cleanup though some DEFINE fields exist for future expansion or external copybook contract. REPORT-only fields used solely in LINE may show sparse reference list—normal.
LONG multiplies pages on programs with thousands of symbols—macro-heavy libraries worst case. Nightly mass compile of unchanged sources may use NOXREF or site SHORT default. Active defect investigation on one member uses LONG for single compile cost acceptable.
ISPF search finds text but not semantic symbol table after macros expand differently than you expect. Compiler XREF reflects post-macro symbol universe for that compile. External repository cross-ref tools may lag if not rebuilt after compile—listing XREF is authoritative for that object version.
Cross-reference is the index at the back of a textbook telling every page where each character name appears. LONG index lists every mention in detail; SHORT index summarizes. If you skip the index, finding where NET-PAY is used means reading the whole book.
1. DEBUG XREF on PARM requests:
2. DEBUG XREF LONG compared to SHORT:
3. Options Table XREF setting:
4. XREF helps find:
5. NOXREF on PARM: