LIBRM STATE LIB (Search Library) Macro

The STATE (LIB) function is used to determine whether a particular library exists.

If it exists, the library attributes are provided in the area that is specified by DIRINF and DIRINFL (DSECT INLCLBST).

The status information for a library is variable in size. It starts with logical library attributes like 'number of sublibs' or 'number of used (free) blocks' as a fixed part. One to 16 extent information records then follow. The extent information describes the physical location of the library. The number of returned extent records is provided in the halfword LBSTXTRT.

The LIB operand cannot be specified generically.

See also Library Macro Notation for details on register notation and possible operand specifications.

Format

Read syntax diagramSkip visual syntax diagramlabelLIBRM STATE,ENTITY=LIB,LDCB= areaname,LIB= lib,DIRINF= dirinf,DIRINFL= dirinfl_value,NOTFND= label,EROPT=RET,EROPT=CANCEL,ERRAD= label

Requirements for the caller

AMODE:
24 or 31
RMODE:
ANY
ASC Mode:
Primary

Parameters

LDCB=areaname
Specifies the address of the LDCB (Librarian Data Control Block) for the request.
LIB=lib
Specifies the address of an area where the library name (1 to 7 alphanumeric characters) is stored. A generic specification for the library name is not possible.
DIRINF=dirinf
Specifies the address of an area where library descriptor information is returned.
DIRINFL=dirinfl-value
Specifies the length (numeric value) of the DIRINF area.
NOTFND=label
Specifies a label to which the service branches, if the library does not exist or is not accessible (return code 8).
EROPT=RET | CANCEL
Defines an error handling option, which is taken, if the function cannot be performed (return code > 12).
RET
Processing is continued, either by a normal return or by branching to the ERRAD exit.
CANCEL
Processing is canceled. A librarian error message is issued to SYSLOG.
ERRAD=label
Specifies a label to which the Librarian branches, if the above function cannot be performed because of an error (return code > 12).

Return Codes 

Return  Reason   Meaning
 Code    Code
 
  0       0      Library exists, information is returned in DIRINF.
          4      Library exists, but no information is returned,
                 because DIRINF was not specified.
  4       0      Library exists, but the area is too small to
                 return all available extent records.  LBSTXTRT
                 contains the number of records actually
                 returned.  LBSTXTRT can be zero.
          4      Library exists, but the area is too small to
                 hold even the fixed part of the status information.
                 No information is returned at all.
  8       0      The specified library does not exist.
 16      xx      External system error with feedback code and message.
 20      xx      Internal system error with feedback code and message.
 32       0      Access control failed (with message L163I).
The external system error feedback codes are described in Librarian Feedback Codes. All other (internal) feedback codes are described in http://publibfp.dhe.ibm.com/epubs/pdf/ieslde10.pdf.
Note: To have access to a library, the library must exist on a volume accessible by the system, and the user must provide the correct labels for it. Otherwise, the library is treated as nonexistent.