Add Node To Recovery Domain (QcstAddNodeToRcvyDomain) API

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:

1. Set the cluster resource group status to Add Node Pending(500).
2. For application cluster resource groups:
   1. If Cluster Resource Services configured the takeover IP address, add the interface. If the takeover IP address cannot be added, this request fails.
   2. 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.
3. For device cluster resource groups:
   1. 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.
4. 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.
5. 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.
6. Verify the failover message queue if one was specified when the cluster resource group was created.
7. Reset the cluster resource group status to the value at the time the API was called if the exit program is successful.
8. 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.
9. 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:

1. This API cannot be called from a cluster resource group exit program.
2. Cluster Resource Services must be active on the node processing the request.
3. At least one active node in the recovery domain.
4. The node being added must be active in the cluster.
5. 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.
6. The node being added must not already be a member of the cluster resource group recovery domain.
7. 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.
8. 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.
9. 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.
10. . 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.
11. For device cluster resource groups:
    1. 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.
    2. 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.
    3. 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.
    4. 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.
    5. 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.
    6. 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.

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.
-4	Peer 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).

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.