List Cluster Resource Groups (QcstListClusterResourceGroups) API

The List Cluster Resource Groups (QcstListClusterResourceGroups) API generates a list of and descriptive information about the cluster resource groups in the cluster specified by the cluster name parameter. The generated list is placed in the specified user space and replaces any existing list. Information will be returned for all cluster resource groups in the cluster, even if they do not exist on the node running the API. All the cluster resource groups will be returned in the generated list regardless of the authority of the user calling the API. The List Objects (QUSLOBJ) API can be used to provide a list of cluster resource group objects on this node only. Since the request for information is not distributed to other nodes in the cluster, the information about a cluster resource group that is returned shows the values obtained from the node running the API. Several conditions (for example, Cluster Resource Services not active on the node running the API) may produce inconsistent information about a cluster resource group in the cluster.

This API can be called from a cluster resource group exit program.

Authorities and Locks

User Space Authority

*CHANGE

User Space Library Authority

*EXECUTE

User Space Lock

*EXCLRD

Required Parameter Group

Qualified user space name

INPUT; CHAR(20)

The name of the *USRSPC object that is to receive the generated list. The first 10 characters contain the user space object name, and the second 10 characters contain the name of the library where the user space is located. No special values are supported for library name, for example, QTEMP, *CURLIB, or *LIBL.

The user space cannot be in an independent auxiliary storage pool.

Format Name

INPUT; CHAR(8)

The format of the information returned for each cluster resource group object. Possible values are:

CRGL0100

Cluster resource group object names

Cluster name

INPUT; CHAR(10)

The name of the cluster for which the list of cluster resource group objects is retrieved.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error Code Parameter.

Format of the Generated Lists

The cluster resource group list consists of:

• A user space
• A generic header
• An input parameter section
• A header section
• A list data section:
  • CRGL0100 format

For details about the user area and generic header, see User Space Format for List APIs. For detailed descriptions of the fields in the list returned, see Field Descriptions.

The completion code in the generic header should be checked to determine if the API completed successfully. When you retrieve list entry information from a user space, you must use the entry size returned in the generic header. The size of each entry may be padded at the end. If you do not use the entry size, the result may not be valid.

Input Parameter Section

An exact copy of the parameters coded in the call to the API.

Header Section

Global information about the cluster resource groups.

CRGL0100 Format

General information about the cluster resource groups in the cluster. Detailed information about a single cluster resource group can be obtained by using the List Cluster Resource Group Information (QcstListClusterResourceGroupIn) API.

Offset		Type	Field
Dec	Hex
0	0	CHAR(10)	Cluster resource group name
10	A	BINARY(2)	Cluster resource group type
12	C	BINARY(4)	Cluster resource group status
16	10	CHAR(8)	Primary node id
24	18	CHAR(20)	Application id

Field Descriptions

Application id. This is a string to identify the application supplying the peer cluster resource group. The recommended format is 'vendor-id.name' where vendor-id is an identifier for the vendor creating the cluster resource group and name is the application name. For example, QIBM.ExamplePeer, indicates it is supplied by IBM for the ExamplePeer application. It is not recommended to use QIBM for vendor id name unless the cluster resource group is supplied by IBM.

Cluster name. The name of the cluster for which the list of cluster resource groups is to be retrieved.

Cluster resource group name. The name of the cluster resource group.

Cluster resource group status. The status of the cluster resource group when this information was gathered. See Summary of Cluster Resource Group Status for the possible values and definitions of the status.

Cluster resource group type. The type of the cluster resource group. The possible values are:

1	Data resiliency.
2	Application resiliency.
3	Device resiliency.
4	Peer resiliency.

Format name. The content and format of the information returned for each cluster resource group object entry. The value must be set to CRGL0100.

Information status. Indicates the consistency of the retrieved information.

Primary node id. A unique string of characters that identifies the node that has a current node role of primary for the cluster resource group object.

*NONE

Valid only for peer cluster resource group. There is no primary node for a peer cluster resource group.

User space library name. The name of the library that contains the user space.

User space name. The name of the user space that receives the list.

Error Messages

Messages that are delivered through the error code parameter are listed here.