Remove Node From Recovery Domain (QcstRemoveNodeFromRcvyDomain) API
Required Parameter Group:
| 1 | Request handle | Output | Char(16) |
| 2 | Cluster name | Input | Char(10) |
| 3 | Cluster resource group name | Input | Char(10) |
| 4 | Node id | Input | Char(8) |
| 5 | Results information | Input | Char(30) |
| 6 | Error code | I/O | Char(*) |
Service Program: QCSTCRG1
Default Public Authority: *EXCLUDE
Threadsafe: Yes
The Remove Node From Recovery Domain (QcstRemoveNodeFromRcvyDomain) API is used to remove a node from the recovery domain of a cluster resource group. The node being removed does not need to be active in the cluster to be removed from the recovery domain. For primary-backup model, if the cluster resource group has no backup nodes in either the current recovery domain or the preferred recovery domain, the primary node cannot be removed.
This API will do the following for all cluster resource group types:
- Set the cluster resource group status to Remove Node Pending (550).
- Call the exit program on all active nodes in the recovery domain with an action code of Remove Node (12), if an exit program is specified for the cluster resource group.
- Reset the cluster resource group status to the value at the time the API was called, if the exit program completes successfully on all nodes.
- Set the cluster resource group status to Indoubt (30) if the exit program fails on any node and the original state of the cluster resource group cannot be recovered.
- Delete the cluster resource group object from the node removed.
This API will do the following for resilient application cluster resource groups:
- If Cluster Resource Services configured the takeover IP address, it will be removed.
This API will do the following for resilient device cluster resource groups:
- If the node being removed is the current primary node, ownership of the devices specified in the cluster resource group are switched from the current primary to the new primary, if none of the configuration objects are varied on on the current primary. For cross-site mirroring, the devices are switched to the new primary node (if the new primary node is at the same site as the current primary node) or to the active backup node at the same site as the current primary node. If any configuration objects are varied on, an error message is returned. In addition, the new primary node must be active.
- All members of an auxiliary storage pool group must be configured in the cluster resource group before ownership can be changed.
- Devices are not varied on after the ownership is switched. The node which is to become the new primary must be active in the cluster.
- If there are one or more external storage devices, and the current primary node is being removed, and the CRG production and mirror sites are to be changed with the new primary, then the storage source and target sites are only changed if the current production and mirror sites are the same as the current source and target sites.
This API requires:
- Cluster Resource Services started on the node running the API.
- For primary-backup model cluster
resource groups:
- A cluster resource group status other than Active (10) in order to remove the node that is currently the primary.
- At least one backup node in the recovery domain of the cluster resource group, if the primary node is removed.
- For peer model cluster resource groups:
- The last node designated as peer cannot be removed if the cluster resource group is Active (10).
- At least one active node in the recovery domain of the cluster resource group after the successful completion of the remove operation.
This API operates in an asynchronous mode. See Behavior of Cluster Resource Services APIs for more information.
Restriction: This API cannot be called from a cluster
resource group exit program.
Authorities and Locks
The program that calls this API must be running under a user profile with *IOSYSCFG special authority.
- Cluster Resource Group Authority
- *CHANGE, *OBJEXIST
- Cluster Resource Group Library Authority
- *EXECUTE
- Cluster Resource Group Lock
- *EXCL
- Exit Program Authority (applies to user profile calling the API and user profile to run the exit program)
- *EXECUTE
- Exit Program Library Authority (applies to user profile calling the API and user profile to run the exit program)
- *EXECUTE
- User Profile Authority (applies to user profile to run the exit program)
- *USE
- Request Information User Queue Authority
- *OBJOPR, *ADD
- Request Information User Queue Library Authority
- *EXECUTE
- Request Information User Queue Lock
- *EXCLRD
- Configuration Object Authority
- *USE and *OBJMGT
Required Parameter Group
- Request handle
- OUTPUT; CHAR(16)
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.
- Cluster name
- INPUT; CHAR(10)
The name of the cluster containing the cluster resource group.
- Cluster resource group name
- INPUT; CHAR(10)
The name of the cluster resource group from which the node will be removed.
- Node id
- INPUT; CHAR(8)
A unique string of characters that identifies the node that is to be removed from the recovery domain of the cluster resource group.
- Results information
- INPUT; CHAR(30)
This parameter identifies a qualified user queue field and is followed by a reserved field.
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.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
Usage Notes
Results Information User Queue
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. |
| CPF18BA D | Error occurred with subsystem. |
| CPF2113 E | Cannot allocate library &1. |
| 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. |
| CPFBB09 D | Cluster node Id &1 does not exist in Cluster &2. |
| CPFBB0A D | Cluster node &1 not active in cluster &2. |
| CPFBB0B D | Request using takeover IP address &1 failed. |
| CPFBB0F D | Cluster resource group &1 does not exist in cluster &2. |
| CPFBB17 D | &1 API cannot be processed in cluster &2. |
| CPFBB18 D | Request &1 not allowed for cluster resource group &2. |
| CPFBB1B D | Cluster node &1 does not exist in the recovery domain for cluster resource group &2. |
| CPFBB2C D | Attributes of exit program &1 in library &2 are not valid. |
| CPFBB2D D | Timeout detected while waiting for a response. |
| CPFBB2E D | Job submission failed for cluster resource group &1 in cluster &2. |
| CPFBB32 D | Attributes of user queue &1 in library &2 are not valid. |
| CPFBB38 D | Library name &1 not allowed for this request. |
| CPFBB39 D | Current user does not have IOSYSCFG special authority. |
| CPFBB46 D | Cluster resource service internal error. |
| CPFBB50 D | Cluster node &1 not removed from cluster resource group &2. |
| CPFBB5B D | Resource name &1 incorrect for configuration object &2 on node &3. |
| CPFBB66 D | Request failed for device cluster resource group &3. |
| CPFBB67 D | Node &1 cannot take ownership of configuration object &2. |
| CPFBB69 D | Primary node &1 not current owner of hardware resource &2. |
| CPFBB6C D | Hardware configuration is not complete for configuration objects in cluster resource group &1. |
| CPFBB70 D | API request &1 not compatible with current cluster version. |
| CPFBB7B D | Device type not correct for configuration object &1 on node &2. |
| CPFBB80 D | Request failed for device cluster resource group &3. |
| CPFBB81 D | New primary node &1 not active. |
| CPFBB90 D | Request failed for device cluster resource group &3. |
| CPFBB92 D | Hardware resource &1 not owned by node &3 or node &4. |
| CPFBB98 D | Hardware resource &1 not switchable. |
| CPFBB99 D | Request failed for device cluster resource group &3. |
| CPFBB9B D | Auxiliary storage pool group member &1 not specified. |
| CPIBB10 D | Cluster resource group exit program &1 in library &2 on node &3 failed. |
Error Messages
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. |
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3C1E E | Required parameter &1 omitted. |
| CPF3C39 E | Value for reserved field 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. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
| CPFBB02 E | Cluster &1 does not exist. |
| CPFBB09 E | Cluster node &1 does not exist in Cluster &2. |
| CPFBB0A E | Cluster node &1 not active in cluster &2. |
| CPFBB0F E | Cluster resource group &1 does not exist in cluster &2. |
| CPFBB1B E | Cluster node &1 does not exist in the recovery domain for cluster resource group &2. |
| CPFBB26 E | Cluster Resource Services not active or not responding. |
| CPFBB2C E | Attributes of exit program &1 in library &2 are not valid. |
| CPFBB32 E | Attributes of user queue &1 in library &2 are not valid. |
| CPFBB39 E | Current user does not have IOSYSCFG special authority. |
| CPFBB42 E | &1 API cannot be used within a cluster resource group exit program. |
| CPFBB50 E | Cluster node &1 not removed from cluster resource group &2. |
API introduced: V4R4
[ Back to top | Cluster APIs | APIs by category ]