INQUIRE LIBRARY

Retrieve information about a LIBRARY resource.

INQUIRE LIBRARY

Read syntax diagramSkip visual syntax diagramINQUIRE LIBRARY( data-value)APPLICATION( data-area)APPLMAJORVER( data-area)APPLMINORVER( data-area)APPLMICROVER( data-area)CHANGEAGENT( cvda)CHANGEAGREL( data-area)CHANGETIME( data-area)CHANGEUSRID( data-area)CRITICALST( cvda)DEFINESOURCE( data-area)DEFINETIME( data-area)DSNAMELIST( ptr-ref)DSNAME01( data-area)DSNAME02( data-area)DSNAME03( data-area)DSNAME04( data-area)DSNAME05( data-area)DSNAME06( data-area)DSNAME07( data-area)DSNAME08( data-area)DSNAME09( data-area)DSNAME10( data-area)DSNAME11( data-area)DSNAME12( data-area)DSNAME13( data-area)DSNAME14( data-area)DSNAME15( data-area)DSNAME16( data-area)ENABLESTATUS( cvda)INSTALLAGENT( cvda)INSTALLUSRID( data-area)INSTALLTIME( data-area)NUMDSNAMES( data-area)PLATFORM( data-area)RANKING( data-area)SEARCHPOS( data-area)

Conditions: APPNOTFOUND, END, ILLOGIC, NOTAUTH, NOTFND

For more information about the use of CVDAs, see CICS-value data areas (CVDAs).

This command is threadsafe

Description

The INQUIRE LIBRARY command returns information about a particular LIBRARY resource installed in your CICS system.

Browsing

You can also browse through the LIBRARY resources in your system by using the browse options, START, NEXT, and END, on INQUIRE LIBRARY commands. In browse mode, the LIBRARY resources are returned in search order, starting with the first LIBRARY concatenation in the search order. See Browsing resource definitions for general information about browsing, including syntax, exception conditions, and examples.

Start of change

Private resources for applications

A LIBRARY concatenation that is defined as part of an application installed on a platform is private to that version of that application. For supported resource types, including LIBRARY concatenations, a resource is private if the resource is defined in a CICS® bundle that is packaged and installed as part of an application, either as part of the application bundle, or as part of the application binding bundle. A LIBRARY concatenation that is defined by any other method is publicly available for all tasks, and is known as a public LIBRARY concatenation.

You can inquire on or browse private resources using the EXEC CICS INQUIRE system programming command for the resource type. By default, CICS searches for the resources that are available to the program where the EXEC CICS INQUIRE command is issued. You can also choose to browse private resources for a specified application.

  • When you issue an EXEC CICS INQUIRE LIBRARY command from a public program, information is returned about the named public LIBRARY resource. If the LIBRARY resource is not available as a public resource, a NOTFND condition is returned.
  • When you issue an EXEC CICS INQUIRE LIBRARY command from a program that is running with an application context, information is returned about the named private LIBRARY resource for that application, if it exists. If the application does not have a private LIBRARY resource with that name, information is returned about a public LIBRARY resource with the specified name. If the resource is not available as a private LIBRARY resource for that application or as a public LIBRARY resource, a NOTFND condition is returned.
  • When you use an EXEC CICS INQUIRE LIBRARY command in browse mode, the resources that are returned depend on the program where the command is issued, and whether you specify a particular application context. For more information about browsing private resources, including examples of browsing in a different application context, see Browsing resource definitions.
End of change

The resource signature

You can use this command to retrieve the resource signature fields. You can use these fields to manage resources by capturing details of when the resource was defined, installed, and last changed. For more information, see Auditing resources. The resource signature fields are BUNDLE, CHANGEAGENT, CHANGEAGREL, CHANGETIME, CHANGEUSRID, DEFINESOURCE, DEFINETIME, INSTALLAGENT, INSTALLTIME, and INSTALLUSRID. See Summary of the resource signature field values for detailed information about the content of the resource signature fields.

Options

Start of changeAPPLICATION(data-area) End of change
Start of changeSpecifies the application name element of the application context. The application name can be up to 64 characters in length.End of change
Start of changeTo browse private resources for an application deployed on a platform, use the APPLICATION, APPLMAJORVER, APPLMINORVER, APPLMICROVER, and PLATFORM options with the browse command START to specify the platform, application name, and full version number for the application whose resources you want to browse.End of change
Start of changeAPPLMAJORVER(data-area) End of change
Start of changeStart of changeSpecifies the application major version element of the application context, in fullword binary form.End of changeEnd of change
Start of changeAPPLMINORVER(data-area) End of change
Start of changeStart of changeSpecifies the application minor version element of the application context, in fullword binary form.End of changeEnd of change
Start of changeAPPLMICROVER(data-area) End of change
Start of changeStart of changeSpecifies the application micro version element of the application context, in fullword binary form.End of changeEnd of change
CHANGEAGENT(cvda)
Returns a CVDA value that identifies the agent that made the last change to the resource definition. The possible values are as follows:
CREATESPI
The resource definition was last changed by an EXEC CICS CREATE command.
CSDAPI
The resource definition was last changed by a CEDA transaction or the programmable interface to DFHEDAP.
CSDBATCH
The resource definition was last changed by a DFHCSDUP job.
DREPAPI
The resource definition was last changed by a CICSPlex SM BAS API command.
SYSTEM
The resource definition was last changed by the CICS or CICSPlex system.
CHANGEAGREL(data-area)
Returns a 4-digit number of the CICS release that was running when the resource definition was last changed.
CHANGETIME(data-area)
Returns an ABSTIME value that represents the time stamp when the resource definition was last changed. For more information about the format of the ABSTIME value, see FORMATTIME.
CHANGEUSRID(data-area)
Returns the 8-character user ID that ran the change agent.
CRITICALST(cvda)
Returns a CVDA value identifying whether the LIBRARY concatenation is critical to CICS starting. CVDA values are as follows:
CRITICAL
The LIBRARY is critical to CICS startup. If the library cannot be successfully installed during CICS startup for any reason, then a GO or CANCEL message is issued. The operator can decide whether to override the critical status and allow CICS to start or not. If CICS is allowed to continue, the library is installed in a DISABLED status, unless install was not possible at all; for example, because of a short-on-storage condition.

If the reply is to continue with the startup, the library is not recatalogued as NONCRITICAL, so the critical status must be explicitly set to NONCRITICAL you decide that the library is not to be regarded as CRITICAL in future.

NONCRITICAL
The library is not critical to CICS startup. If the library cannot be successfully installed during CICS startup, the library is left in an installed but disabled state. If installation is not possible for the LIBRARY, a warning message is issued and CICS startup continues.
LIBRARY(data-value)
Specifies the 8-character name of the LIBRARY about which you are inquiring.
DEFINESOURCE(data-area)
Returns the 8-character source of the resource definition. The DEFINESOURCE value depends on the CHANGEAGENT value. For more information, see Summary of the resource signature field values.
DEFINETIME(data-area)
Returns an ABSTIME value that represents the time stamp when the resource definition was created.
DSNAMELIST(ptr-ref)
Returns the address of a buffer containing all the data sets in the LIBRARY concatenation. The buffer contains an array of 44-character data set names. This buffer is intended for use when the DFHRPL concatenation contains more than 16 data sets. The number of data sets is indicated by the NUMDSNAMES parameter, but, if the library is not DFHRPL, some of the slots in the list will be empty if the data set names at those positions are not specified on the dynamic LIBRARY definition.
DSNAME01-16(data-area)
Returns the 44-character names of data sets in the library concatenation. If this library is a dynamically defined, these are the data sets specified on the LIBRARY definition, all but one of which can be blank. If this DFHRPL is the statically defined, then these are the first 16 data sets in the DFHRPL concatenation, or as many data sets as are specified up to 16, with the remaining DSNAMExx fields being blank. The DFHRPL concatenation contains more than 16 data sets, you can use the DSNAMELIST option to obtain all of the data sets.
ENABLESTATUS(cvda)
Returns a CVDA value identifying whether the library is currently included in the overall library search order. CVDA values are as follows:
DISABLED
The LIBRARY is disabled, and is not currently included in the library search order. The data sets in this LIBRARY concatenation are not searched for program artifacts to load.
DISABLING
A request to disable the library has been received, but is still being processed.
ENABLED
The library is enabled, and is currently included in the library search order. The data sets in this library concatenation will be searched for program artifacts to load.
ENABLING
A request to enable the library has been received, but is still being processed.
DISCARDING
A request to discard the LIBRARY from the CICS system has been received, but is still being processed.
INSTALLAGENT(cvda)
Returns a CVDA value that identifies the agent that installed the resource. The possible values are as follows:
BUNDLE
The resource was installed by a bundle deployment.
CREATESPI
The resource was installed by an EXEC CICS CREATE command.
CSDAPI
The resource was installed by a CEDA transaction or the programmable interface to DFHEDAP.
GRPLIST
The resource was installed by GRPLIST INSTALL.
SYSTEM
The resource was installed by the CICS or CICSPlex SM system.
INSTALLTIME(data-area)
Returns an ABSTIME value that represents the time stamp when the resource was installed.
INSTALLUSRID(data-area)
Returns the 8-character user ID that installed the resource.
NUMDSNAMES(data-area)
Returns a fullword binary value containing the number of data sets in the library concatenation. For a dynamically defined library, this value is the number of non blank DSNAMExx values, and cannot be a value larger than 16. For the statically defined DFHRPL, this value is the number of data sets in the concatenation, and can be a value larger than 16.
Start of changePLATFORM(data-area) End of change
Start of changeSpecifies the platform name element of the application context. The platform name can be up to 64 characters in length.End of change
RANKING(data-area)
Returns a fullword binary value that indicates where this library appears in the overall LIBRARY search order relative to other LIBRARY concatenations. A lower number indicates that this LIBRARY is searched for programs to load before other LIBRARY resources with higher ranking numbers. Libraries appear in the search order, in order of ranking. However libraries of equal RANKING appear in the search order in the order in which they were installed or created in the local CICS system, with a library that was installed earlier appearing before one that was installed later.
SEARCHPOS(data-area)
Returns a fullword binary value containing the current absolute position of this library in the overall LIBRARY search order. The first enabled library in the search order has a SEARCHPOS of 1, the next enabled library will have a SEARCHPOS of 2, and so on. The SEARCHPOS is not the same as the RANKING, although its value is determined by the relative ranking values of the various library resources in the system.

The SEARCHPOS values, relative to other library resources with the same RANKING value, are related to installation or create time, but their SEARCHPOS values relative to each other are retained across a warm or emergency restart. There is no guarantee that the relative SEARCHPOS values of library resources with the same RANKING will be the same after a cold or initial start.

If the library is disabled, the SEARCHPOS is 0, indicating that the library does not participate in the overall search.

Conditions

Start of changeAPPNOTFOUNDEnd of change
Start of changeRESP2 values:
1
A START command has been issued specifying an application context. The named application is not found.
End of change
END
RESP2 values:
2
There are no more resource definitions of this type.
ILLOGIC
RESP2 values:
1
A START command has been issued when a browse of library resources is already in progress, or a NEXT or an END command has been issued when a browse of library resources is not in progress.
NOTAUTH
RESP2 values:
100
The user associated with the issuing task is not authorized to use this command.
NOTFND
RESP2 values:
1
The named library cannot be found.