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:

  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. 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.

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

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 ]