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 previous request requires a continuation (return code 4, reason code 0).
- The option CONT=YES is set.
- 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
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).
- 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.
- If both LIB/SUBLIB and CHAINID are specified, LIB/SUBLIB is taken and CHAINID is ignored.
- 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).