CSLRMQRY: query resources

This request is supported in assembler language.

CSLRMQRY parameters

ECB=symbol

ECB=(r2-r12)

(Optional) - Specifies the address of a z/OS® ECB used for asynchronous requests. When the request is complete, the ECB specified is posted. If an ECB is not specified, the task is suspended until the request is complete. If an ECB is specified, the invoker of the request must issue a WAIT (or equivalent) after receiving control from CSLRM QRY before using or examining any data returned by this request (including the RETCODE and RSNCODE fields).

LIST=symbol

LIST=(r2-r12)

(Required) - Specifies the query resource list built by the caller. Each list entry is a separate query request. The list length can vary, depending upon the number of list entries.

The list contains a header and one or more list entries. The list entries must reside in contiguous storage. Each query list entry contains the following:

• Resource name - the client-defined name of the resource. The resource name can be a wildcard name. If it is a wildcard name, all resources that match the wildcard name are returned.
• Resource type - the resource type is a client-defined physical grouping of resources on the resource structure. Valid values are 1-255.
• Query options (optional) - options that indicate special processing to perform for the query.
• Owner (optional) - the owner of the resource. If you specify the owner, the resource is returned only if the resource name and owner match a resource on the resource structure. Specify binary zeroes to omit the owner, and the query returns the owner name in the RQYO_OWNER field in the output list entry.
• User (optional) - a user field set by the caller, which is passed back in the output list entry associated with the input list entry.

LISTLEN=symbol

LISTLEN=(r2-r12)

(Required) - Specifies the 4-byte query resource list length.

OUTLEN=symbol

OUTLEN=(r2-r12)

(Required) - Specifies a 4-byte field to receive the length of the output buffer returned by the CSLRMQRY request. OUTLEN contains the length of the output buffer pointed to by the OUTPUT parameter. The length of the output data (header and entries) is passed in the output header data, mapped by CSLRQRYO.

OUTPUT=output

OUTPUT=(r2-r12)

(Required) - Specifies a 4-byte field to receive the address of the variable length output returned by the CSLRMQRY request. The output contains a header and one or more query entries for resource queries that were attempted. The output length is returned in the OUTLEN field.

The output address is zero if no output was built, for example, if an error was detected before any output could be built.

The CSLRQRYO macro maps the output that is returned. The output contains a header and one or more list entries. The header contains the following:

• an eyecatcher
• the output length
• CSLRQRYO version
• CSLRQRYO header length (offset to start of entries)
• minimum entry length (offset to DATA2)
• resource entry count
• time stamp

Each output entry represents a resource query that was attempted. Each entry contains the following parameters:

• Output entry length - the list entry length can vary, depending upon whether DATA2 is returned.
• Name type - the name type is a client-defined value associated with a resource type that ensures uniqueness of client-defined resource names within a name type. Valid values are 1-255.
• Resource name - client-defined name of the resource.
• Resource type - the resource type is a client-defined physical grouping of resources on the resource structure. Valid values are 1-255.
• Version - the resource version, which is the number of times the resource has been updated.
• DATA2 flag byte - flag byte indicating if DATA2 was read.
• Resource name status flag - the resource name status indicates how the resource name in the query output list entry is associated with the input resource parameter. This enables you to tie the input resource parameter to the output query list entries that are generated. The following resource name status are possible:

  Specific parameter

  A specific resource name was specified. This query list entry contains the resource name that matches the input parameter.

  Wildcard Parameter

  A wildcard parameter was specified. This query list entry contains the wildcard parameter and a completion code. This query list entry does not contain information about a specific resource. If the completion code is zero, one or more wildcard match list entries follow.

  Wildcard match

  A wildcard parameter was specified. This entry contains information about one resource that matches the input wildcard parameter. All wildcard match list entries follow contiguously after a wildcard parameter list entry.

• Owner - owner of a resource.
• DATA1- a small piece of client data (fixed length, contained in the adjunct area of a data entry) associated with an existing resource.
• DATA2 length - length of a large piece of client data associated with an existing resource, if DATA2 exists and the option to read DATA2 was set.
• Optional User field - optional 4 byte user field passed back to the caller in the output list entry associated with the input list entry.
• DATA2 - a large piece of client data (variable length, contained in one or more data elements of a data entry) associated with an existing resource, if DATA2 exists, and the option to read DATA2 was set. The maximum size of DATA2 is 61312 bytes (X'EF80').
• Completion code for the query request - completion codes are mapped by CSLRRR. Possible completion codes are:

X'00000000'

Query request succeeded. At least one resource matching the query parameters is returned in the output buffer specified by OUTPUT=.

X'00000004'

No resources found.

X'00000008'

Invalid resource type.

X'0000000C'

Invalid name type.

X'00000024'

Resource structure is unavailable.

X'00000034'

Invalid options specified.

X'00000038'

Query failed because of CQS internal error.

X'0000003C'

Query failed because RM incorrectly built the CQSBRWSE list entry.

The output buffer is not preallocated by the caller. After the request returns it, this word contains the address of a buffer containing the query output. It is the caller's responsibility to release this storage by issuing the CSLSCBFR FUNC=RELEASE request when it is through with the storage. The length of the buffer is returned in the OUTLEN= field.

PARM=symbol

PARM=(r2-r12)

(Required) - Specifies the CSLRMQRY parameter list. The length of the parameter list must be equal to the parameter list length EQU value defined by RQRY_PARMLN.

PROTOCOL=RQST

(Optional) - SCI protocol for sending the request to RM. RQST sends the query request using SCI request interface.

RETCODE=symbol

RETCODE=(r2-r12)

(Required) - specifies a 4-byte field to receive the return code on output. RM return codes are defined in CSLRRR. SCI return codes are defined in CSLSRR. Possible return codes are described in the following table.

RETNAME=symbol

RETNAME=(r2-r12)

(Optional) - Specifies an 8-byte field to receive the RM name returned to the caller. This is the CSL member name of the target RM address space to which SCI sent the request.

RETTOKEN=symbol

RETTOKEN=(r2-r12)

(Optional) - Specifies a 16-byte field to receive RM's SCI token returned to the caller. This is the SCI token for the target RM address space to which SCI sent the request.

RSNCODE=symbol

RSNCODE=(r2-r12)

(Required) - Specifies a 4-byte field to receive the reason code on output. RM reason codes are defined in CSLRRR. SCI reason codes are defined in CSLSRR. Possible reason codes are described in the following table.

SCITOKEN=symbol

SCITOKEN=(r2-r12)

(Required) - Specifies a 16-byte field containing the SCI token. This token uniquely identifies this connection to SCI. The SCI token was returned by a successful CSLSCREG FUNC=REGISTER request.

CSLRMQRY return and reason codes

The following table lists the return and reason codes that can be returned on a CSLRMQRY request. Also included is the meaning of a reason code (that is, what possibly caused it).