ESD - External Symbol Dictionary

Enhanced Definition

The External Symbol Dictionary (ESD) is a crucial component within an `object module` or `load module` on z/OS. It serves as a directory that lists all external symbols—such as `control sections (CSECTs)`, `entry points`, and `external references`—that are defined within or referenced by that module. Its primary purpose is to provide the `linkage editor` or `binder` with the necessary information to resolve cross-module references and combine separately compiled program units into an executable `load module` or `program object`. The External Symbol Dictionary (ESD) is a critical component of an object module or `LOAD` module on z/OS, containing a list of all external symbols defined within the module, as well as those referenced from other modules. It provides essential information for the z/OS `Linkage Editor` or `Binder` to resolve cross-module references and construct an executable program.

Key Characteristics

- Symbol Information: Each entry in the ESD typically includes the symbol name, its type (e.g., SD for CSECT, LD for ENTRY, ER for EXTRN), its length, and its relative address or offset within the module.
- Resolution Mechanism: The linkage editor or binder uses the ESD from all input object modules to match external references (ER type) in one module with entry points (LD type) or control sections (SD type) defined in another.
- Module Structure: The ESD is one of several sections within an object module, alongside the Text (TXT) section (containing executable code and data) and the Relocation Dictionary (RLD).
- Load Module Content: For a load module or program object, the ESD contains the resolved addresses and definitions of all external symbols, enabling the operating system to correctly load and execute the program.
- Control Section (CSECT): A CSECT is a named, contiguous block of code or data within a program that can be independently relocated. Each CSECT typically has an entry in the ESD.
- Entry Point: An ENTRY symbol in the ESD designates a specific address within a CSECT that can be called or branched to from another program unit.

Use Cases

- Program Linking: The fundamental use case is enabling the linkage editor or binder to combine multiple object modules (e.g., compiled COBOL programs, assembled routines) into a single executable load module.
- Subroutine Calls: Facilitates calls to subroutines or functions that reside in different object modules or load libraries by providing the linkage editor with the necessary address information.
- Shared Data Areas: Allows programs to reference and share common data areas (CSECTs) that are defined in separate modules, promoting modularity and reusability.
- Dynamic Program Loading: For program objects in PDSEs, the ESD information is used by the z/OS loader to resolve external references at load time, supporting dynamic linking concepts.
- Debugging and Analysis: Utilities like AMBLIST or IPCS can display the ESD information of object modules or load modules, which is invaluable for diagnosing linkage editor errors (e.g., UNRESOLVED EXTERNAL REFERENCE) or understanding program structure.

Related Concepts

The ESD is intrinsically linked to the object module and load module formats, forming a critical part of how programs are constructed and executed on z/OS. The linkage editor or binder is the utility that processes the ESDs from various input object modules, along with their Text and Relocation Dictionary sections, to produce a final load module or program object. Control Sections (CSECTs) and Entry Points are the primary types of symbols defined within the ESD, while External References (EXTRNs) are symbols referenced by the module but defined elsewhere, requiring resolution by the linkage editor.

Best Practices:

Descriptive Symbol Names: Use clear and meaningful names for CSECTs and ENTRY points to improve readability, maintainability, and debugging efforts.
Avoid Duplicate Entry Points: Ensure that ENTRY names are unique across all object modules that will be linked together to prevent linkage editor errors (e.g., DUPLICATE SYMBOL DEFINITION).
Manage External References Carefully: Explicitly declare all external references (EXTRN in assembler, EXTERNAL in some compilers) and ensure that the corresponding entry points or CSECTs are available in the input object modules or load libraries during the link-edit step.
Utilize AMBLIST or MAP Option: Generate a load map using the AMBLIST utility or the MAP option in the linkage editor to review the ESD information, identify unresolved references,