LIBRM STATE SUBLIB (Search Sublibrary) Macro

The STATE (SUBLIB) function is used to determine whether a particular sublibrary exists in a certain library.

If it is found, the sublibrary attributes are provided in the area that is specified by DIRINF and DIRINFL (DSECT INLCSBST).

The SUBLIB operand can be specified generically by giving a prefix of the name followed by an asterisk (for example, PREF*). In this case, all sublibraries whose names start with PREF are returned. If only * (without a prefix) is specified, all sublibraries are returned.

The status information entries of the sublibraries are stored contiguously in the area that is specified by DIRINF and DIRINFL. The number of returned entries can be retrieved with DIRNO. If the given space is insufficient, return code 4 is returned. A continuation request is possible.

The library access service will treat the logically next call as a continuation request under the following conditions:
  1. The previous call requires a continuation (return code 4, reason code 0).
  2. The option CONT=YES is set.
  3. The LDCB still defines a STATE,ENTITY=SUBLIB function.

The caller should not change the LDCB (and any fields that are referenced by the LDCB) while processing continuation requests.

The continuation logic is reset if (1) the space that is defined by DIRINF and DIRINFL is sufficient to hold the returned sublibraries (return code 0), or (2) a processing error occurs (return code > 12), or (3) the caller switches to CONT=NO.

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

Format

Read syntax diagramSkip visual syntax diagramlabelLIBRM STATE,ENTITY=SUBLIB,LDCB= areaname,LIB= lib,SUBLIB= sublib,DIRINF= dirinf,DIRINFL= dirinfl_value,DIRNO= dirno,CONT=YES,CONT=NO,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.
SUBLIB=sublib
Specifies the address of an area where the sublibrary name (1 to 8 alphanumeric characters) is stored.
DIRINF=dirinf
Specifies the address of an area where sublibrary directory (INLCSBST) information is returned.
DIRINFL=dirinfl-value
Specifies the length (numeric value) of the DIRINF area.
DIRNO=dirno
Specifies the address of a fullword where the number of directory entries is returned.
CONT=YES | NO
Defines whether continuation should be requested (CONT=YES) or not (CONT=NO). This option is ignored for a nongeneric specification. CONT=YES is the default.
NOTFND=label
Specifies a label to which the service branches, if the sublibrary does not exist within the given library (return code 8), or the related library does not exit or is not accessible (return code 12).
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      Sublibrary exists (or generic sublibraries exist),
                 information is returned in DIRINF.
          4      Sublibrary exists (or generic sublibraries exist),
                 but no information is returned,
                 because DIRINF was not specified.
  4       0      Match found for generic specification, but
                 DIRINF is too small to contain all entries.
                 If CONT=YES (default) is specified, a continuation
                 request is required to free partition GETVIS storage.
          4      Match found for nongeneric or generic specification,
                 but the area is too small to contain a full entry.
                 No information is returned. Continuation is not possible.
  8       0      No match found.
 12       4      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: You can read the sublibrary directory sequentially by specifying SUBLIB=*, providing a DIRINF area for one entry, and by continuing (return code 4) until return code 0 is passed with the last entry.