LIBRARY statement

The LIBRARY statement can be used to specify:
  • Additional automatic call libraries that contain modules used to resolve external references found in the program.
  • Restricted no-call: External references that are not to be resolved by an automatic library call during the current binder job step.
  • Never-call: External references that are not to be resolved by an automatic library call during this or any subsequent binder job step.

When LIBRARY statements identify additional libraries that can be used, the following search order is applied during final autocall:

  1. The library or libraries associated with the first LIBRARY specification are searched. This may identify a z/OS® UNIX directory, a z/OS UNIX archive, a partitioned data set, or a concatenation of partitioned data sets.
    • For a z/OS UNIX directory, the file names and links in the directory are checked.
    • For a z/OS UNIX archive or C370LIB PDS, all names that have been cataloged by the ar command or Object Library Utility are checked.
    • For other partitioned data sets, only the member names and aliases are checked.
    • If specific names are listed in the LIBRARY specification, only those names can be used for resolution, otherwise any name can be used.
  2. Libraries associated with other LIBRARY specifications are searched in the order the specifications were provided within a LIBRARY statement and the order in which the LIBRARY statements were provided.
  3. The SYSLIB concatenation is searched.
  4. If unresolved symbols remain, the search is restarted from step 1. It is repeated until no symbols are resolved in a complete pass through all libraries.

The syntax of the LIBRARY statement is:

LIBRARY          {{ddname(membername[,…])}
                          {ddname2}
                          {pathname}
                          {(externalreference[,…])}
                          {*(externalreference[,…])}},…
ddname
The name of a DD statement that defines a library from which the listed symbols will be included during automatic library call.
membername
Usually, the name of or an alias for a member of the specified library. If the DDNAME points to a UNIX archive, the names in parentheses can be any external symbols indexed by the ar command. If the DDNAME points to a C370LIB, the names in parentheses can be any external symbols defined by the special C370LIB directory. Conversely, if member names are used for a C370LIB the binder looks at the members only if there are unresolved symbols whose name match the member name.
Here is an example. A C370LIB (DDname MYC3LIB) contains a member named FOO within which there is an external entry FooSez, and that FooSez is in the special C370LIB directory. Also, a program has an unresolved symbol FooSez.
  • If the LIBRARY statement says MYC3LIB(FOO), the symbol is not found.
  • If it says MyC3LIB('FooSez'), it is resolved.
  • If it says MYC3LIB(FOO) and the program also contains unresolved symbol FOO, both are resolved.

Only those members specified are used to resolve references.

ddname2
The name of a DD statement that defines a library that may be used to resolve references during automatic library call. The DD statement can point to a PDS, PDSE, PDS/PDSE concatenation, z/OS UNIX directory, or z/OS UNIX archive library.
pathname
The name of an z/OS UNIX archive library or directory that may be used to resolve references during automatic library call. For a directory, the binder looks for files or links whose name matches the symbol to be resolved.
(externalreference)
An external reference that can be unresolved after primary input processing. The external reference is not to be resolved by automatic library call.
*
Indicates never-call; the external reference should never be resolved from an automatic call library. If the * (asterisk) is missing, the reference is left unresolved during the current binder job step but can be resolved in a subsequent step.

If all binder input modules containing references to a specific symbol were bound with never-call, that symbol is not resolved by automatic library call during this binder run. However, if one or more input modules do not indicate a symbol as never-call, the binder attempts to resolve the symbol from the automatic call library.

Placement: A LIBRARY statement can be placed before, between, or after object modules or other control statements.
Note:
  1. A member or external reference listed in a LIBRARY statement has no affect except when a matching name appears as an unresolved reference in the program.
  2. For C370LIB or archives, the name may be any symbol listed in the archive or special C370LIB directory.
  3. For a non-C370LIB PDS or PDSE, the name must be a member name or alias to be effective.
  4. For a UNIX directory, the name must be a file name or alias to be effective.
  5. If the NCAL option is specified, the LIBRARY statement has no effect.
  6. Members included by automatic library call are placed in the root segment of an overlay program, unless they are repositioned with an INSERT statement.
  7. The LIBRARY control statement is not processed immediately. If the same symbol appears on more than one LIBRARY statement, only the last occurrence is used.
  8. Specifying an external reference for restricted no-call or never-call by means of the LIBRARY statement prevents the external reference from being resolved by automatic inclusion of the necessary module from an automatic call library; it does not prevent the external reference from being resolved if the module necessary to resolve the reference is specifically included or is included as part of an input module.
  9. The LIBRARY statement is not allowed in a data set that is included from an automatic call library.