Reserved
453473| 1 | Request handle | Output | Char(16) |
| 2 | Qualified user space name | Input | Char(20) |
| 3 | Format name | Input | Char(8) |
| 4 | Cluster name | Input | Char(10) |
| 5 | Cluster resource group name | Input | Char(10) |
| 6 | Results information | Input | Char(30) |
| 7 | Error code | I/O | Char(*) |
The List Cluster Resource Group Information (QcstListClusterResourceGroupIn) API returns the contents of a cluster resource group object.
This API can be called from a cluster resource group exit program. However if the status of the cluster resource group specified on the list request is Initialize Pending (540); this API will fail. The cluster resource group exit program will not be called when this API is run.
If Cluster Resource Services has not been started:
If Cluster Resource Services has been started, this API will return information about the cluster resource group even if it does not exist on the node from which the API is called. For information retrieved from another node, the API will always indicate success. To determine if data was actually returned, wait for the API completion message which is sent to the results information queue and then check the length returned in the generic header portion of the user space.
If format LRGI0200 information about a device cluster resource group is requested and no configuration object entries have yet been added to the cluster resource group, the list entry size will be 0.
A unique string or handle that identifies this API call. It is used to associate this call to any responses placed on the user queue specified in the Results information parameter. If the cluster resource group exists on this node, then the Request handle field will be blank.
The user space that is to receive the created list. The first 10 characters contain the user space name, and the second 10 characters contain the name of the library where the user space is located. No special values can used for the library name, for example, QTEMP, *CURLIB, or *LIBL.
The user space cannot be in an independent auxiliary storage pool.
The format of the information to be returned. The format names supported are:
| LRGI0100 | Recovery Domain Entries |
| LRGI0200 | Configuration Object Entries |
| LRGI0300 | Recovery Domain Entries with additional information on site name and data port IP addresses. |
The name of the cluster containing the cluster resource group.
The name of the cluster resource group for which information is retrieved.
This parameter identifies a qualified user queue field and is followed by a reserved field. This parameter is ignored if the cluster resource group exists on the node initiating the API request.
Qualified user queue: Completion information is returned to this user queue, which exists on the node from which the API was called, after the function has completed. See the Usage Notes section of this API for a description of the data that is placed on this queue. This is a 20-character field. The first 10 characters contain the user queue name, and the second 10 characters contain the user queue library name. No special values are supported. QTEMP, *LIBL, *CURLIB are not valid library names. The attributes of this user queue must be keyed.
Reserved: The last 10 characters of the 30-character results information are reserved. Each character in this field must be set to hexadecimal zero.
The structure in which to return error information. For the format of the structure, see Error Code Parameter.
The cluster resource group list consists of:
For details about the user area and generic header, see User Space Format for List APIs. For details about the remaining items, see the following sections. For detailed descriptions of the fields in the list returned, see Field Descriptions.
When you retrieve list entry information from a user space, you must use the
entry size returned in the generic header for the LRGI0100 or LRGI0200
formats. 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. For examples of how to process lists, see Examples.
A copy of most parameters coded in the call to the API.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | User space name |
| 10 | A | CHAR(10) | User space library name |
| 20 | 14 | CHAR(8) | Format name |
| 28 | 1C | CHAR(10) | Cluster name |
| 38 | 26 | CHAR(10) | Cluster resource group name |
| 48 | 30 | CHAR(16) | Request handle |
| 64 | 40 | CHAR(30) | Results information |
| Note: The Results information field is comprised of the following 3 fields. | |||
| 64 | 40 | CHAR(10) | Results information user queue name |
| 74 | 4A | CHAR(10) | Results information user queue library name |
| 84 | 54 | CHAR(10) | Reserved |
Global information about the cluster resource group.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(1) | Information status |
| 1 | 1 | CHAR(3) | Reserved |
| 4 | 4 | BINARY(4) | Cluster resource group type |
| 8 | 8 | BINARY(4) | Current cluster resource group status |
| 12 | C | CHAR(10) | Cluster resource group exit program name |
| 22 | 16 | CHAR(10) | Cluster resource group exit program library name |
| 32 | 20 | CHAR(8) | Cluster resource group exit program format name |
| 40 | 28 | CHAR(10) | User profile |
| 50 | 32 | CHAR(256) | Exit program data |
| 306 | 132 | CHAR(16) | Takeover IP address |
| 322 | 142 | CHAR(10) | Job name |
| 332 | 14C | BINARY(4) | Allow application restart |
| 336 | 150 | BINARY(4) | Number of restarts |
| 340 | 154 | BINARY(4) | Previous cluster resource group status |
| 344 | 158 | CHAR(8) | Reporting node |
| 352 | 160 | CHAR(50) | Text description |
| 402 | 192 | CHAR(10) | Distribute information user queue name |
| 412 | 19C | CHAR(10) | Distribute information user queue library name |
| 422 | 1A6 | CHAR(1) | Configure takeover IP address |
| 423 | 1A7 | CHAR(1) | Clustered hash table cluster resource group |
| 424 | 1A8 | BINARY(4) | Failover wait time |
| 428 | 1AC | BINARY(4) | Failover default action |
| 432 | 1B0 | CHAR(10) | Failover message queue name |
| 442 | 1BA | CHAR(10) | Failover message queue library name |
| 452 | 1C4 | CHAR(1) | Reserved |
| 453 |
1C5 | CHAR(20) | Application id |
| 473 |
1D9 | CHAR(1) | Allow active takeover IP address |
The cluster resource group recovery domain information is returned when LRGI0100 is specified as the format type. Each recovery domain entry returned will contain both the current and the preferred node role. For detailed descriptions of the fields in the table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(8) | Node id |
| 8 | 8 | BINARY(4) | Current node role |
| 12 | C | BINARY(4) | Membership status |
| 16 | 10 | BINARY(4) | Preferred node role |
The cluster resource group resilient device information is returned when LRGI0200 is specified as the format type. For detailed descriptions of the fields in the table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Configuration object name |
| 10 | A | CHAR(2) | Reserved |
| 12 | C | BINARY(4) | Configuration object type |
| 16 | 10 | BINARY(4) | Device type |
| 20 | 14 | BINARY(4) | Configuration object online |
| 24 | 18 | BINARY(4) | Device subtype |
| 28 | 1C | CHAR(16) | Server takeover IP address |
The cluster resource group recovery domain information is returned when LRGI0300 is specified as the format type. Each recovery domain entry returned will contain both the current and the preferred node role. For detailed descriptions of the fields in the table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BIN(4) | Length of recovery domain entry |
| 4 | 4 | CHAR(8) | Node id |
| 12 | C | BINARY(4) | Current node role |
| 16 | 10 | BINARY(4) | Membership status |
| 20 | 14 | BINARY(4) | Preferred node role |
| 24 | 18 | CHAR(8) | Site name |
| 32 | 20 | BINARY(4) | Offset to data port IP address array |
| 36 | 24 | BINARY(4) | Number of data port IP addresses |
| * | * | Array(*) of CHAR(16) | Data Port IP address |
Allow application restart. Attempt to restart an application if the cluster resource group exit program fails. Possible values are:
| 0 | Do not attempt to restart the application. The cluster resource group exit program is called with an action code of Failover (9). |
| 1 | Attempt to restart the application on the same node. The cluster resource group exit program will be called with an action code of Restart (3). If the application cannot be restarted in the specified maximum number of attempts, the cluster resource group exit program will be called with an action code of Failover (9). |
Allow active takeover IP address. Allows a takeover IP address to already be active when it is assigned to an application cluster resource group. This field is only valid when configure takeover IP address field is 0x01. Possible values are:
| 0 | The takeover IP address must not already be active when starting the cluster resource group. This is the default value if the field is not specified. |
| 1 | The takeover IP address is allowed to be active prior to starting the cluster resource group but only on the primary node. |
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.
Clustered hash table (CHT) cluster resource group. Indicates if this cluster resource group is associated with the clustered hash table server.
| 0 | Cluster resource group not associated with CHT server. |
| 1 | Cluster resource group associated with CHT server. |
Cluster name. The name of the cluster containing the cluster resource group.
Cluster resource group exit program format name. Indicates which format should be used for the Information Given To User parameter on the cluster resource group exit program when it is called. See Cluster Resource Group Exit Program for details. This field will contain hexadecimal zeroes if no exit program is specified for the cluster resource group.
Cluster resource group exit program library name. The name of the library that contains the exit program for the cluster resource group. This field will contain hexadecimal zeroes if no exit program is specified for the cluster resource group.
Cluster resource group exit program name. The name of the user provided exit program. This field will contain *NONE left justified and padded with blanks if no exit program is specified for the cluster resource group.
Cluster resource group name. The name of the cluster resource group.
Cluster resource group type. The type of resilient resource information contained within the cluster resource group object.
| 1 | Data resiliency |
| 2 | Application resiliency |
| 3 | Device resiliency |
| 4 |
Peer resiliency |
Configuration object name. The configuration object name for a device entry. For example, the auxiliary storage pool device description name.
Configuration object online.Vary the configuration object on and start the server takeover IP address or leave the configuration object varied off and the server takeover IP address inactive when a device is switched from one node to another with the Initiate Switchover (QcstInitiateSwitchOver) API or when it is failed over to a backup node. This attribute does not vary the device on or off and does not start or end the server takeover IP address when the cluster resource group is started or ended and when adding a new device entry to the cluster resource group. For secondary auxiliary storage pools, only a value of 2 is valid. If cluster resources cannot determine if this value is correct for a device entry because the auxiliary storage pool is not yet created, any errors will be detected when the cluster resource group is started. A value of 2 cannot be specified for any other device type. Possible values are:
| 0 | Do not vary the configuration object on and do not start the server takeover IP address. |
| 1 | Vary the configuration object on and start the server takeover IP address. |
| 2 | Perform the same action for a secondary auxiliary storage pool as is specified for the primary. |
Configuration object type. This specifies the type of configuration object specified with configuration object name. Possible values are:
| 1 | Device description |
Configure takeover IP address. This field identifies who is responsible for configuring (adding and removing) the takeover IP address. This does not affect the starting and ending of the takeover IP address, Cluster Resource Services will perform this function. The following values are valid:
| 0x00 | Cluster Resource Services is responsible for configuring the takeover IP address. |
| 0x01 | User is responsible for configuring the takeover IP address. |
Current cluster resource group status. The current 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.
Current node role. The curent role the node has in the current
recovery domain. For primary-backup model cluster resource groups
a node can have one
of three roles: primary, backup, or replicate. Only one node can be designated
as the primary. Backup nodes are assigned a backup order. One indicates the
first backup, two the second backup, and so on. Replicates are not ordered and
cannot become a primary or backup node unless the Change Cluster Resource Group (QcstChangeClusterResourceGroup)
API is used to change its role from replicate to either a backup or
primary.
For peer model cluster
resource groups a node can have one
of two roles: peer or replicate. Any number of nodes can be designated
as the peer or replicate. Peer nodes are not ordered and can be an active access point
for the cluster resources. Replicates are not ordered and
cannot become an active access point for the cluster resource unless the Change Cluster Resource Group (QcstChangeClusterResourceGroup)
API is used to change its role from replicate to peer.
The following summarizes the valid values for this field:
| 0 | Primary node. Only one node can have this value. |
| >=1 | Backup node. The backup order is designated by increasing value. |
| -1 | Replicate node. All replicates have this value. |
-4 |
Peer node. All peers have this value. |
Data port IP address. The IP address associated with the recovery domain node.
Device subtype. The subtype of the device. This information is only as current as the last time the cluster resource group object could be updated. If configuration changes have been made on the node which owns the hardware and those changes have not yet been distributed to all nodes in the cluster, this information may be inaccurate. The data cannot be distributed if the configuration was changed on a node which does not have cluster resource services running.
| -1 | The subtype cannot be determined because hardware configuration is not complete. |
| 0 | This device type does not have a subtype. |
| 1 | UDFS independent auxiliary storage pool. |
| 2 | Secondary independent auxiliary storage pool. |
| 3 | Primary independent auxiliary storage pool. |
Device type. The type of device description.
| 1 | Auxiliary storage pool |
Distribute information user queue library name. The name of the library that contains the user queue to receive distributed information. This field will contain hexadecimal zeroes if no user queue is specified for the cluster resource group.
Distribute information user queue name. The name of the user queue to receive distributed information from the Distribute Information (QcstDistributeInformation) API. This field will contain *NONE left justified and padded with blanks if no user queue is specified for the cluster resource group.
Exit program data. 256 bytes of data which is passed to the cluster resource group exit program when it is called. This field will contain hexadecimal zeroes if no exit program is specified for the cluster resource group.
Failover default action. Should a response to the failover message queue not be received in the failover wait time limit, then this field tells clustering what it should do pertaining to the failover request.
| 0 | Proceed with failover. |
| 1 | Do NOT attempt failover. |
Failover message queue library name. The name of the library that contains the user queue to receive failover messages. This field will contain hexadecimal zeroes if if no message queue is specified for the cluster resource group.
Failover message queue name. The name of the message queue to receive messages dealing with failover. This field will contain *NONE left justified and padded with blanks if no message queue is specified for the cluster resource group.
Failover wait time. Number of minutes to wait for a reply to the failover message that was enqueued on the failover message queue. Possible values are:
| -1 | Wait forever until a response is given to the failover inquiry message. |
| 0 | Failover proceeds without user intervention. Acts the same as V5R1M0 and prior. |
| >=1 | Number of minutes to wait for a response to the failover inquiry message. If no response is received in the specified number of minutes, the failover default action field will be looked at to decide how to proceed. |
Format name. The content and format of the information returned in the user space.
Job name. The name given the batch job that is submitted to call the cluster resource group exit program. This field will contain hexadecimal zeroes if no exit program is specified for the cluster resource group. Valid special values for this field are:
| *JOBD | The job name is determined from the job description specified in the user profile for the cluster resource group exit program. |
Information status. Indicates the consistency of the retrieved information.
| 0 | The information is consistent for all active nodes in the cluster. |
| 1 | The information retrieved from the node running
the API may not be consistent with all active nodes in the cluster. In order to
obtain consistent information:
|
Length of recovery domain entry. The length in bytes of the entry for LRGI0300 format in the list data section. Use this field to access the next entry in the list.
Membership status. The cluster resource group membership status for the node.
| 0 | Active | The node is an active member of the cluster resource group membership. |
| 1 | Inactive | The node is not an active member of the cluster resource group membership. The Cluster Resource Services may not be active on the node or the cluster resource group job could be ended on the node. |
| 2 | Partition | The node is partitioned from the other members of the cluster resource group membership. |
| 3 | Ineligible | The node is an active member of the cluster resource group membership but not eligible to become the cluster resource group primary node. |
Node id. A unique string of characters that identifies a node that is in the recovery domain of the cluster resource group.
Number of data port IP addresses. The number of data port IP addresses associated with the recovery domain node.
Number of restarts. Number of times the cluster resource group exit program can be restarted on the same node before a failover occurs. Maximum number of restarts is 3. This field is valid only for an application cluster resource group. It will always contain hexadecimal zero for a data or device cluster resource group.
Offset to data port IP address array. The byte offset from the beginning of the user space to the first data port IP address.
Preferred node role. The preferred role the node has in
the recovery domain. For primary-backup model cluster resource groups
a node can have one
of three roles: primary, backup, or replicate. Only one node can be designated
as the primary. Backup nodes are assigned a backup order. One indicates the
first backup, two the second backup, and so on. Replicates are not ordered and
cannot become a primary or backup node unless the Change Cluster Resource Group (QcstChangeClusterResourceGroup)
API is used to change its role from replicate to either a backup or
primary.
For peer model cluster
resource groups a node can have one
of two roles: peer or replicate. Any number of nodes can be designated
as the peer or replicate. Peer nodes are not ordered and can be an active access point
for the cluster resources. Replicates are not ordered and
cannot become an active access point for the cluster resource unless the Change Cluster Resource Group (QcstChangeClusterResourceGroup)
API is used to change its role from replicate to peer.
Valid values are:
| 0 | Primary node. Only one node can have this value. |
| >=1 | Backup node. The backup order is designated by increasing value. |
| -1 | Replicate node. All replicates have this value. |
| -4 |
Peer node. All peers have this
value. |
Previous cluster resource group status. Indicates the status of this cluster resource group before the current request was executed.
Reporting node. The cluster node which returned the list information for the cluster resource group Valid special values are:
| *LOCAL | The information was retrieved from a cluster resource group on the local system and the local system did not have a cluster node associated with it. |
Request handle. Identifies this API call. It is used to associate this call to a response on the user queue specified in the Results Information parameter.
Reserved. The field will contain hexadecimal zeroes.
Results information. This field identifies a qualified user queue name and is followed by a reserved field.
Results information user queue library name. This field identifies the library where the results information user queue resides.
Results information user queue name. This field identifies the name of the user queue to which messages are sent when this API operates asynchronously.
Server takeover IP address. This is a takeover IP address for servers associated with the relational database name in the device description for an auxiliary storage pool. The address will be represented in dotted decimal format and returned as a null-terminated string. If not specified, or for a secondary and UDFS auxiliary storage pool, this field will contain *NONE left justified and padded with blanks. If the current cluster version is 2, this field is set to hexadecimal zeroes.
Site name. The name of the site associated with the recovery domain node. If the current cluster version is 3, this field is set to hexadecimal zeroes.
Takeover IP address. The floating IP address that is to be associated with the application. This field is only meaningful for an application cluster resource group. It is set to hexadecimal zeroes for a data or device cluster resource group. This field will be represented in dotted decimal format and returned as a null-terminated string.
Text description. The text description associated with the cluster resource group object.
User profile. The name of the user profile under which the cluster resource group exit program is run. This field will contain hexadecimal zeroes if no exit program is specified for the cluster resource group.
User space library name. The name of the library containing the user space.
User space name. The name of the user space which will
contain the information retrieved from the cluster resource group.
Asynchronous results are returned to a user queue specified by the Results Information parameter of the API. See Cluster APIs Use of User Queues and Using Results Information for details on how to create the results information user queue, the format of the entries, and how to use the data placed on the queue. The data is sent to the user queue in the form of a message identifier and the substitution data for the message (if any exists). The following identifies the data sent to the user queue (excluding the message text).
| Message ID | Message Text |
|---|---|
| CPCBB01 C | Cluster Resource Services API &1 completed. |
| CPF2204 D | User profile &1 not found. |
| CPF3CF2 D | Error(s) occurred during running of &1 API. |
| CPF9801 D | Object &2 in library &3 not found. |
| CPF9802 D | Not authorized to object &2 in &3. |
| CPF9803 D | Cannot allocate object &2 in library &3. |
| CPF9804 D | Object &2 in library &3 damaged.. |
| CPF9810 D | Library &1 not found. |
| CPFBB24 D | Node &1 not participating in &2 API protocol. |
| CPFBB32 D | Attributes of user queue &1 in library &2 are not valid. |
| CPFBB38 D | Library name &1 not allowed for this request. |
Messages that are delivered through the error code parameter are listed here. The data (messages) sent to the results information user queue are listed in the Usage Notes above.
| Message ID | Error Message Text |
|---|---|
| CPF2113 E | Cannot allocate library &1. |
| CPF3C1E E | Required parameter &1 omitted. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C3C E | Value for parameter &1 not valid. |
| CPF3C39 E | Value for reserved field not valid. |
| CPF3C3C E | Value for parameter &1 not valid. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
| CPF9801 E | Object &2 in library &3 not found. |
| CPF9802 E | Not authorized to object &2 in &3. |
| CPF9803 E | Cannot allocate object &2 in library &3. |
| CPF9804 E | Object &2 in library &3 damaged. |
| CPF980C E | Object &1 in library &2 cannot be in an independent auxiliary storage pool. |
| CPF9810 E | Library &1 not found. |
| CPF9820 E | Not authorized to use library &1. |
| CPFBB02 E | Cluster &1 does not exist. |
| CPFBB0F E | Cluster resource group &1 does not exist in cluster &2. |
| CPFBB26 E | Cluster Resource Services not active or not responding. |
| CPFBB32 E | Attributes of user queue &1 in library &2 are not valid. |
| CPFBB38 E | Library name &1 not allowed for this request. |
| CPFBB39 E | Current user does not have IOSYSCFG special authority. |
| CPFBB40 E | The value &1 specified for the allow application restarts parameter is not valid |
| CPFBB43 E | Format name &1 not valid for cluster resource group type &2. |
| CPFBB46 E | Cluster Resource Services internal error. |
| CPFBB70 E | API request &1 not compatible with current cluster version. |
| Top | Cluster APIs | APIs by category |