LIBRARY attributes

Describes the syntax and attributes of the LIBRARY resource.

data set names

CRITICAL({NO|YES})

Indicates whether this LIBRARY is critical to the running of CICS®. This determines the behavior if the LIBRARY cannot be installed during startup, for example if a data set in the LIBRARY definition is not found or cannot be allocated for one of the following reasons:

If the LIBRARY is CRITICAL
- If the LIBRARY is being created during CICS startup (through grouplist install, BAS install, a PLTPI program or restore from the catalog), a GO or CANCEL message is issued so that the operator can decide whether to override the criticality and allow CICS to start, or to cause the startup to be failed. If the reply is to continue with the startup, the LIBRARY is not recataloged as NONCRITICAL, but the critical status can be changed to NONCRITICAL if you decide that the LIBRARY is not to be regarded as CRITICAL in future.
- If the LIBRARY is not being created during CICS startup, the criticality of the LIBRARY has no impact on the behavior of the installation.

If the LIBRARY is non-CRITICAL
- If the LIBRARY is being created during CICS startup (through grouplist install, BAS install, a PLTPI program or restore from the catalog), the LIBRARY is installed but disabled, a warning message is issued, and CICS startup continues. A later attempt can be made to resolve the problem and enable the LIBRARY.
- If the LIBRARY is not being installed during CICS startup, the criticality of the LIBRARY has no impact on the behavior of the installation.

DFHRPL, the static LIBRARY, is predefined as CRITICAL and cannot be changed. Any problems cause CICS startup to fail and an error message is issued.

For a private LIBRARY resource that is defined in a CICS bundle that is packaged and installed as part of an application bundle or application binding bundle, the CRITICAL attribute is ignored.

DSNAME01-16(Name)

The names of up to 16 data sets that contain program artifacts and that are to make up the LIBRARY concatenation. When the LIBRARY is installed, the data sets are concatenated together in the order in which they are named, for example, DSNAME01 before DSNAME02. It is not necessary for all of the data set attributes to be completed sequentially, for example, DSNAME01 might be blank. However, at least one of the data set attributes must have a value. See Defining a data set naming convention for further information.

GROUP(groupname)

Every resource definition must have a GROUP name. The resource definition becomes a member of the group and is installed in the CICS system when the group is installed.

Acceptable characters: `A-Z 0-9 $ @ #` Any lowercase characters that you enter are converted to uppercase.

The GROUP name can be up to 8 characters in length. Lowercase characters are treated as uppercase characters.

LIBRARY(name)

The name of the LIBRARY resource.

For a LIBRARY resource that is defined in a CICS region, a CICSPlex® SM data repository, or a standalone CICS bundle, the resource name is used as the DD name for the LIBRARY concatenation of data sets. The name of the LIBRARY resource must therefore conform to the rules for a valid DD name (1-8 characters with the first character any of A-Z, $, # or @ and the remaining characters any of A-Z, 1-9, $, # or @). Avoid using names that conflict with other DD names used by the installation. The create of a public LIBRARY resource fails if the chosen name conflicts with a DD name already in use in the system for another public LIBRARY resource.

For a private LIBRARY resource that is defined in a CICS bundle that is packaged and installed as part of an application bundle or application binding bundle, the name of the LIBRARY resource is not used as the DD name for the LIBRARY concatenation of data sets. Instead, CICS requests a unique DD name for the LIBRARY concatenation of data sets when the application is installed on the platform. The resource name can therefore be the same as LIBRARY names used elsewhere in the installation, or by different versions of the application. CICS issues message DFHLD0518 to state the DD name that z/OS® has generated for the LIBRARY concatenation. You can also view the data set names for an installed application in the CICS Explorer®.

The following reserved names are not accepted for a LIBRARY resource:

DFHRPL or any name that starts with DFH
Any name that starts with EYU
CEEDUMP
DUMMY
JOBCAT
JOBLIB
STEPCAT
STEPLIB
SYSABEND
SYSIN
SYSMDUMP
SYSOUT
SYSUDUMP

LIBRARY resource names beginning with DFH or EYU are not accepted, to ensure that these names remain available in future for use by CICS. LIBRARY resource names beginning with CEE should be used with caution, but are accepted. SYSIN and SYSOUT and DUMMY are conventionally used as DD cards and are therefore inadvisable as LIBRARY resource names. The remainder are DD names reserved by MVS™; DFHRPL is reserved for use in the CICS startup JCL as the name of the static LIBRARY.

RANKING(1-99)

RANKING is a fullword binary value that contains a decimal number that determines where this LIBRARY appears in the overall LIBRARY search order. A lower number indicates that this LIBRARY is searched for programs to load before other LIBRARY resources with higher ranking numbers. The ranking is analogous to the concatenation number of a data set in a LIBRARY concatenation, although it has some differences.

RANKING can take values 1 - 99, with a default of 50. The value 10 is reserved for DFHRPL, the static LIBRARY, and cannot be specified.

The DFHRPL concatenation is assigned a predefined ranking of 10, which cannot be changed. This value enables dynamically defined LIBRARY resources to be placed before the DFHRPL concatenation in the overall search order by giving them a ranking value less than 10.

Note:

You should regard having LIBRARY resources with a ranking that places them before DFHRPL in the search order as a temporary situation.
Although the predefined DFHRPL ranking of 10 is intended to discourage the placing of LIBRARY resources before DFHRPL in the search order, it does not limit the total number of LIBRARY resources that can be placed before DFHRPL providing the ranking between the LIBRARY resources themselves is not significant. If you specify a RANKING value of less than 10, a message to say that this LIBRARY appears ahead of DFHRPL in the search order is issued.
No ranking change takes effect until a NEWCOPY or PHASEIN request is issued, or the program is loaded for the first time if it was not already loaded.
The search order of LIBRARYs with the same ranking is undefined, and implies that the relative search order of the LIBRARY resources is unimportant. In practice, the search order is the order in which the LIBRARYs were installed.
A LIBRARY resource that is defined in a CICS bundle as part of an application installed on a platform is private to that version of that application. These LIBRARY concatenations are only searched for tasks for that version of the application.
LIBRARYs can have the same ranking but you should not use equal ranking values for two LIBRARY resources if their relative search positions are of any significance.
The search positions of two LIBRARY resources of the same ranking are not reliable. The search order is related to the time each resource is installed, and can change after a COLD or INITIAL start or when changing the ranking of a LIBRARY. The resource that is installed first appears ahead of the other LIBRARY in the search order.

STATUS({ENABLED|DISABLED})

Indicates whether the LIBRARY is to be enabled or disabled when it is created. When a LIBRARY is created as enabled, CICS attempts to allocate and then concatenate the data sets, before finally opening the LIBRARY concatenation. If any of these steps fail, the steps that are already successful are undone, and the LIBRARY is installed as disabled. A message is issued that indicates which step failed.

When a LIBRARY is created with as disabled, CICS does not attempt to allocate or concatenate the data sets.

This attribute is ignored for LIBRARY resources that are dynamically generated by a CICS bundle. The initial status of a LIBRARY resource is derived from the initial status of the bundle that defines the resource.