Add Node To Recovery Domain (QcstAddNodeToRcvyDomain) 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 | Node role | Input | Binary(4) |
| 6 | Results information | Input | Char(30) |
| 7 | Error code | I/O | Char(*) |
Service Program: QCSTCRG1
Default Public Authority: *EXCLUDE
Threadsafe: Yes
The Add Node To Recovery Domain API is used to add a new node to the recovery domain of an existing cluster resource group. This API causes the preferred and current roles of all nodes in the recovery domain to be updated.
This API will do the following:
- Set the cluster resource group status to Add Node Pending(500).
- For application cluster resource groups:
- If Cluster Resource Services configured the takeover IP address, add the interface. If the takeover IP address cannot be added, this request fails.
- If the cluster resource group is active and the node is being added as a backup, verify the takeover IP address exists and is not active on the node being added.
- For device cluster resource groups:
- If the node being added to a cluster resource group is to become the new 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 current primary devices are varied on and the cluster resource group is not active. If any devices are varied on, an error message is returned. Devices are not varied on after the ownership is switched.
- Call the cluster resource group exit program with the action code of Add Node (11) on all active nodes in the recovery domain, if an exit program is specified for the cluster resource group.
- Verify the queue used by the Distribute Information (QcstDistributeInformation) API if the cluster resource group has been created to indicate the Distribute Information API will be used.
- Verify the failover message queue if one was specified when the cluster resource group was created.
- Reset the cluster resource group status to the value at the time the API was called if the exit program is successful.
- Set the cluster resource group status to Indoubt(30) if the exit program fails and the original state of the cluster resource group cannot be recovered.
- Assign the added node the specified role. For primary-backup model cluster resource groups, if the cluster resource group is active, it has more than one backup node, and some backup nodes are not active, the recovery domain may be reordered so that all active backup nodes are ordered before inactive backup nodes.
To change the role of the added node, use the Change Cluster Resource Group (QcstChangeClusterResourceGroup) API.
To remove a node from the recovery domain use the Remove Node From Recovery Domain (QcstRemoveNodeFromRcvyDomain) API.
This API operates in an asynchronous mode. See Behavior of Cluster Resource Services APIs for more information.
Restrictions:
- This API cannot be called from a cluster resource group exit program.
- Cluster Resource Services must be active on the node processing the request.
- At least one active node in the recovery domain.
- The node being added must be active in the cluster.
- The cluster resource group exit program must exist on each node in the recovery domain, including the node being added. The exit program cannot be in an independent auxiliary storage pool.
- The node being added must not already be a member of the cluster resource group recovery domain.
- For primary-backup model cluster resource groups, a node can only be added as a primary node if the cluster resource group has a status of Inactive (20). The old primary becomes the last backup. If the cluster resource group has a status of Active(10), a node can be added as either a backup or a replicate.
- For peer model cluster resource groups, the node can be added as a peer or replicate. If the cluster resource group has a status of Active (10) and a peer node is added, the node will be added as an active access point.
- The queue used by the Distribute Information API must exist on each node in the recovery domain, including the node being added if it was specified on the Create Cluster Resource Group (QcstCreateClusterResourceGroup) API. This is verified after the exit program returns. The distributed information user queue does not allow pointers within the message content. The distributed information user queue cannot be in an independent auxiliary storage pool.
- If the failover message queue was defined on the cluster resource group, the failover message queue must exist on each node in the recovery domain, including the node being added. This is verified after the exit program returns. The queue cannot be in an independent auxiliary storage pool.
- For device cluster resource groups:
- A node can be added to a cluster resource group even if it has no device entries. Device entries must be added using the Add Cluster Resource Group Device Entry API before the cluster resource group can be started.
- If a node is being added to a cluster resource group, the node must be in the same device domain as the other nodes in the recovery domain.
- The configuration objects for the device resources in the cluster resource group must exist on the node being added and the resource names in the configuration objects must be the same as the resource names used by the configuration objects on the existing nodes in the recovery domain. The node being added must be able to access the hardware resources represented by the configuration objects in the cluster resource group.
- If a data base name is specified in the configuration objects in the cluster resource group, it must be the same on the node being added.
- If adding a new primary node and an auxiliary storage pool group already exists for the cluster resource group, all members of the auxiliary storage pool group must be configured in the cluster resource group before ownership can be changed.
- If a server takeover IP address is specified in the cluster resource group and the cluster resource group is active, the server takeover IP address must exist.
Authorities and Locks
The program that calls this API must be running under a user profile with *IOSYSCFG special authority. In addition if the the user profile is not the owner of the Cluster Resource Group object, the profile must have *ALLOBJ special authority on all nodes in the CRG's recovery domain and on the node being added to the recovery domain.
- Cluster Resource Group Authority
- *CHANGE
- 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
- Failover Message Queue Authority
- *OBJOPR, *ADD
- Failover Message Queue Library Authority
- *EXECUTE
- 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
- Distribute Information User Queue Authority
- *OBJOPR, *ADD
- Distribute Information User Queue Library Authority
- *EXECUTE
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 in which the cluster resource group exists.
- Cluster resource group name
- INPUT; CHAR(10)
The name of the cluster resource group that will have the new node added to its recovery domain.
- Node id
- INPUT; CHAR(8)
A unique string of characters that identifies the node being added to the recovery domain of the cluster resource group specified. The node specified must be in the cluster and must be unique in the recovery domain of the cluster resource group specified.
- Node role
- INPUT; BINARY(4)
The role the node will have 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 a 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. The new node is to be the primary node. The cluster resource group must have a status of Inactive (20). >=1 Backup node. The number indicates the backup order. If there is already a node with the same backup order, the new node is inserted in the position requested. At the completion of the request the nodes with backup roles will be sequentially renumbered from the first backup to the last. The first backup will always be 1. -1 Replicate node. All replicates have this value. Replicate nodes are not ordered. -2 Last Backup. The new node id will be added as the last backup.
-4Peer node. All peers have this value. Peer nodes are not ordered. - 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 | Error 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 &2 not found. |
| CPF222E D | &1 special authority is required. |
| 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 | Node Id &1 does not exist in cluster &2. |
| CPFBB0A D | Cluster node &1 in cluster&2 not active. |
| 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. |
| 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. |
| CPFBB35 D | The user profile name &1 is not valid for this request. |
| CPFBB38 D | Library name &1 not allowed on this request. |
| CPFBB39 D | Current user does not have IOSYSCFG special authority. |
| CPFBB46 D | Cluster Resource Service internal error. |
| CPFBB52 D | Cluster node &1 could not be added to cluster resource group &2. |
| CPFBB5B D | Resource name &1 incorrect for configuration object &2 on node &3. |
| CPFBB65 D | Cluster node &1 in different device domain. |
| CPFBB66 D | Request failed for device cluster resource group &3. |
| CPFBB67 D | Node &1 cannot take ownership of configuration object &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. |
| CPFBB9E D | Data base name &1 not correct for configuration object &2 on node &3. |
| 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 | Node &1 does not exist in cluster &2. |
| CPFBB0A E | Cluster node &1 in cluster&2 not active. |
| CPFBB0F E | Cluster resource group &1 does not exist in cluster &2. |
| CPFBB26 E | Cluster Resource Services not active or not responding. |
| CPFBB29 E | Node role value &1 not valid. |
| 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. |
| CPFBB44 E | &1 API cannot be called from a cluster resource group exit program. |
| CPFBB52 E | Cluster node &1 not added to cluster resource group &2. |
API introduced: V4R4
[ Back to top | Cluster APIs | APIs by category ]