LIBRM STATE MEMBER (Search Library Member) Macro

The STATE (MEMBER) function is used to determine whether a particular member exists in a certain sublibrary or a chain of sublibraries.

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

The MEMBER and TYPE operands can be specified generically by giving a prefix of the name followed by an asterisk (for example, PREF*). In this case, all members whose names start with PREF are returned. If only * (without a prefix) is specified, all members are returned. For generic requests with chain processing, the sublibrary with the first match is selected and all matching members within this sublibrary are returned.

The LOCKID operand specifies the lock identifier of the library member to be searched for. The state of the specified member is displayed only if the member is locked with this lockid. Otherwise, return code 8 is issued.

The status information entries of the members are stored contiguously in the area that is specified by DIRINF and DIRINFL. The number of returned entries can be retrieved via DIRNO. If the given space is insufficient, return code 4 is issued. 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 request requires a continuation (return code 4, reason code 0).
  2. The option CONT=YES is set.
  3. The LDCB still defines a STATE,ENTITY=MEMBER 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 members (return code 0), or (2) a processing error occurs (return code > 12), or (3) the caller switches to CONT=NO.

User-provided directory information that is identified by DATAID is returned in DATA, its length in DATALEN. This service is only provided for the STATE of a single member (nongeneric).

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

Format

Read syntax diagramSkip visual syntax diagramlabelLIBRM STATE,ENTITY=MEMBER,LDCB= areaname,LIB= lib,SUBLIB= sublib,CHAINID= chainid,MEMBER= membername,TYPE= membertype,DIRINF= dirinf,DIRINFL= dirinfl_value,DIRNO= dirno,LOCKID= lockid,CONT=YES,CONT=NO,DATAID= did,DATALEN= dlen,DATA= data,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.
CHAINID=chainid
Specifies the address of an area where the sublibrary chain identifier (1 to 8 alphanumeric characters) is stored.
MEMBER=membername
Specifies the address of an area where the member name (1 to 8 alphanumeric characters) is stored.
TYPE=membertype
Specifies the address of an area where the member type (1 to 8 alphanumeric characters) is stored.
DIRINF=dirinf
Specifies the address of the area where member directory 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 returned directory entries is provided.
LOCKID=lockid
Specifies the lock identifier of the library member to be searched for. The state of the specified member is displayed only if the member is locked with this lockid. Otherwise, return code 8 is given indicating that no member locked with the specified lockid was found. If the member is locked, the lockid is copied into the area that is specified by DIRINF and DIRINFL. The lockid (provided in the LIBRM LOCK macro) is a string of up to eight alphanumeric characters.

The lockid can also be specified generically by giving a prefix, followed by an asterisk (for example, PRE*). In this case, information for the specified member is returned only if it is locked with a lockid starting with the specified prefix. If LOCKID=* is specified, the member information is returned only if the member is locked at all (with any lockid).

The lockid in the LDCB is cleared after processing.

CONT=YES | NO
Defines whether the continuation should be requested (CONT=YES) or not (CONT=NO). This option is ignored for a nongeneric specification. CONT=YES is the default.
DATAID=did
Specifies the address of an area where the 1 to 4 character alphanumeric identifier for user-provided directory information is specified.
DATALEN=dlen
Specifies the address of a fullword where the length of the DATA area is given. The actual length of the user-provided information is returned by the service.
DATA=data
Specifies the address of the area where the user-provided directory information is returned. The area that is specified must have a minimal length of DATALEN.
NOTFND=label
Specifies a label to which the service branches, if the member does not exist within the searched sublibraries (return code 8), or the related sublibrary, library, or chain does not exit (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      Member exists (or generic members exist),
                 information is returned in DIRINF.
          4      Member exists (or generic members 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.
                 Continuation is required to free partition GETVIS storage.
          4      Match found for nongeneric or generic specification,
                 but area is too small for a full entry.
                 No information is returned. Continuation is not possible.
  8       0      No match found.
 12       0      The specified sublibrary does not exist.
          4      The specified library does not exist.
          8      The specified chain 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:
  1. You can read the member directory (all members) sequentially by specifying MEMBER=* and TYPE=*, providing a DIRINF area for one entry, and by continuing (return code 4) until return code 0 is passed with the last entry.
  2. If both LIB/SUBLIB and CHAINID are specified, LIB/SUBLIB is taken and CHAINID is ignored.
  3. If user-provided directory information (operands DATA, DATALEN, DATAID) cannot be returned, the fullword that is addressed with DATALEN is set to zero. Return and reason codes are not affected.

    No processing is done for a generic member request and for a nongeneric request if the directory information cannot be returned (return code 0 or 4, with reason code 4).