Change Cluster Resource Group (QcstChangeClusterResourceGroup) 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 | Cluster resource group description information | Input | Char(*) |
| 5 | Format name | Input | Char(8) |
| 6 | Text description | Input | Char(50) |
| 7 | Results information | Input | Char(30) |
| 8 | Error code | I/O | Char(*) |
Service Program: QCSTCRG1
Default Public Authority: *EXCLUDE
Threadsafe: Yes
The Change Cluster Resource Group (QcstChangeClusterResourceGroup) API changes some of the attributes of a cluster resource group.
The following fields may be changed without causing the cluster resource group exit program to be called:
- Text description
- Exit program data
- User profile
- Takeover IP address
- Job name
- Allow application restart
- Number of restarts
- The cluster resource group exit program
- Failover message queue
- Failover wait time
- Failover default action
- Cluster resource group exit program format name
- Application id
To add a node to the recovery domain use, the Add Node To Recovery Domain (QcstAddNodeToRcvyDomain) API.
To remove a node from the recovery domain, use the Remove Node From Recovery Domain (QcstRemoveNodeFromRcvyDomain) API.
To add a device to a resilient device cluster resource group, use the Add Cluster Resource Group Device Entry (QcstAddClusterResourceGroupDev) API.
To remove a device from a resilient device cluster resource group, use the Remove Cluster Resource Group Device Entry (QcstRmvClusterResourceGroupDev) API.
To change a device entry in a resilient device cluster resource group, use the Change Cluster Resource Group Device Entry (QcstChgClusterResourceGroupDev) API.
To change a cluster administrative domain, use the Change Cluster Administrative Domain (QcstChangeClusterAdminDomain) API.
This API will do the following for all cluster resource group types:
- Call the cluster resource group exit program with an action code of Change (13) on all active nodes in the recovery domain when either the preferred or current role is changed,or when a site name and/or data port IP addresses are changed, if an exit program is specified for the cluster resource group. The cluster resource group status is set to Change Pending (520). If the exit program completes successfully, the cluster resource group status is reset to its value at the time the API was called. If the exit program fails and the cluster resource group cannot be restored to its original condition, the cluster resource group status is set to Indoubt (30).
- Change the cluster resource group without calling the exit program if neither node role, site name nor data port IP addresses are changed.
- Change the name to be used for batch jobs submitted by cluster resource group. If the cluster resource group status is Active (10), batch jobs already submitted will not be changed. Any jobs submitted after the change will use the new name. This is true for other attributes associated with a submitted exit program such as the user profile, the restart count and so on. Changes to the cluster resource group will not affect an exit program that was previously submitted and is either on a job queue or is running.
- For a primary-backup model cluster resource group, if the current node role in the recovery domain is changed and the cluster resource group is active and 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.
This API will do the following for resilient application cluster resource groups:
- If the Cluster Resource Services configures the takeover IP address, it will remove the current address and add the new address when the takeover IP address is changed. If either the add or remove address function fails, the API will fail.
- If the cluster resource group is active and the role of a node is being changed from replica to backup, verify the takeover IP address exists and is not active on the node being changed. If the takeover IP address does not exist or is active on the node being changed, the API will fail.
This API will do the following for resilient device cluster resource groups:
- If the role of the current primary node is being changed, ownership of the devices specified in the cluster resource group is switched from the current primary to the new primary if the current primary has none of the devices varied on. If any devices 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.
- If the site name and/or data port IP addresses for a recovery domain node is changed but the node role is not changed, you can specify only the node that is changed, no need to specify all nodes in the recovery domain.
- A site name can be changed only if all configuration objects in the cluster resource group are for auxiliary storage pool devices. If there are any configuration objects that are not auxiliary storage pools, then a site name must be *NONE.
- For cross site mirroring, dataport addresses are required only for geo mirroring. Cross site mirroring that is not geo mirror can not specify dataport addresses.
- If a recovery domain node role is changed (a value other than -2 is specified), then the rest of the nodes in the recovery domain must also be specified and they must have value other than -2.
- In cross-site mirroring, a switchover on a mirror site can be done by changing the mirror site node roles, by assigning a different active node to be the highest node role ranking at a mirror site.
This API requires for all cluster resource group types:
- Cluster Resource Services must be active on the node processing the request.
- A cluster resource group must have a status of Inactive (20) or Indoubt (30) to designate a new primary node.
- The new exit program, if one specified, must exist on all nodes in the recovery domain when the cluster resource group exit program is changed.
- At least one active node in the recovery domain.
- If defined, the failover message queue must exist on all nodes in the recovery domain when the cluster resource group is changed.
This API requires for all primary-backup model cluster resource group types:
- Changing the node role to primary or changing the takeover IP address can only be done when the cluster resource group is Inactive (20) or Indoubt (30). If the cluster resource group is Active, the Initiate Switchover API can be used to assign the primary role to the first backup node. For information about the Initiate Switchover API, see Initiate Switchover (QcstInitiateSwitchOver) API.
- IP addresses created by IPv6 stateless address auto-configuration are not valid to be used as a takeover IP address.
This API requires for all peer model cluster resource group types:
- The recovery domain role can be changed from peer to replicate or replicate to peer by specifying one or more recovery domain nodes. The full recovery domain does not need to be specified.
- If the cluster resource group is Active (10) and:
- The role is changed from peer to replicate, the node becomes an inactive access point.
- The role is changed from replicate to peer, the node becomes an active access point.
- There must be at least one node designated as peer if the cluster resource group is Active (10).
- A cluster administrative domain CRG is not allowed to be changed with this API.
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
- 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
- Failover Message Queue Authority
- *OBJOPR, *ADD
- Failover Message 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 to which the cluster resource group belongs.
- Cluster resource group name
- INPUT; CHAR(10)
The name of the cluster resource group which is to be changed.
- Cluster resource group description information
- INPUT; CHAR(*)
Detailed information about the cluster resource group. For more information, see Data Resiliency (RGDC0100 Format), Data Resiliency (RGDC0110 Format), Application Resiliency (RGDC0200 Format), Application Resiliency (RGDC0201 Format), Device Resiliency (RGDC0300 Format), Device Resiliency (RGDC0301 Format), and Peer Resiliency (RGDC0400 Format).
- Format name
- INPUT; CHAR(8)
The content and format of the cluster resource group information. The possible format names are:
RGDC0100 This format describes the data cluster resource group. RGDC0110 This format also describes the data cluster resource group, with some additional fields added. RGDC0200 This format describes the application cluster resource group. RGDC0201 This format describes the application cluster resource group with IPv6 support. RGDC0300 This format describes the device cluster resource group. RGDC0301 This format describes the device cluster resource group with IPv6 support. RGDC0400 This format describes the peer cluster resource group.
- Text description
- INPUT; CHAR(50)
This text briefly describes the cluster resource group. This must be left justified. The following special value can be used:
*SAME The current text description is not changed. This must be left justified.
- 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.
Data Resiliency (RGDC0100 Format)
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Cluster resource group exit program name |
| 10 | A | CHAR(10) | Cluster resource group exit program library name |
| 20 | 14 | CHAR(8) | Cluster resource group exit program format name |
| 28 | 1C | CHAR(10) | User profile |
| 38 | 26 | CHAR(10) | Action for recovery domain array |
| 48 | 30 | CHAR(256) | Exit program data |
| 304 | 130 | BINARY(4) | Offset to recovery domain array |
| 308 | 134 | BINARY(4) | Number of nodes in recovery domain |
| * | * | Array (*) of CHAR(*) | Recovery domain array |
| These fields repeat, in the order listed, for each node in the recovery domain. | CHAR(8) | Node id | |
| BINARY(4) | Node role | ||
Data Resiliency (RGDC0110 Format)
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Cluster resource group exit program name |
| 10 | A | CHAR(10) | Cluster resource group exit program library name |
| 20 | 14 | CHAR(8) | Cluster resource group exit program format name |
| 28 | 1C | CHAR(10) | User profile |
| 38 | 26 | CHAR(10) | Action for recovery domain array |
| 48 | 30 | CHAR(256) | Exit program data |
| 304 | 130 | BINARY(4) | Offset to recovery domain array |
| 308 | 134 | BINARY(4) | Number of nodes in recovery domain |
| 312 | 138 | BINARY(4) | Failover wait time |
| 316 | 13C | BINARY(4) | Failover default action |
| 320 | 140 | CHAR(10) | Failover message queue name |
| 330 | 14A | CHAR(10) | Failover message queue library name |
| 340 | 154 | BINARY(4) | Offset to additional fields |
| 344 | 158 | BINARY(4) | Length of additional fields |
| * | * | Array (*) of CHAR(*) | Recovery domain array |
| These fields repeat, in the order listed, for each node in the recovery domain. | CHAR(8) | Node id | |
| BINARY(4) | Node role | ||
| * | * | CHAR(*) | Additional fields |
| These fields are part of the additional fields structure. | CHAR(10) | Job name | |
Application Resiliency (RGDC0200 Format)
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Cluster resource group exit program name |
| 10 | A | CHAR(10) | Cluster resource group exit program library name |
| 20 | 14 | CHAR(8) | Cluster resource group exit program format name |
| 28 | 1C | CHAR(10) | User profile |
| 38 | 26 | CHAR(10) | Action for recovery domain array |
| 48 | 30 | CHAR(256) | Exit program data |
| 304 | 130 | BINARY(4) | Offset to recovery domain array |
| 308 | 134 | BINARY(4) | Number of nodes in recovery domain |
| 312 | 138 | CHAR(16) | Application takeover IP address |
| 328 | 148 | CHAR(10) | Job name |
| 338 | 152 | CHAR(1) | Additional fields used |
| 339 | 153 | CHAR(1) | Reserved |
| 340 | 154 | BINARY(4) | Allow application restart |
| 344 | 158 | BINARY(4) | Number of restarts |
| 348 | 15C | BINARY(4) | Offset to additional fields |
| 352 | 160 | BINARY(4) | Length of additional fields |
| * | * | Array (*) of CHAR(*) | Recovery domain array |
| These fields repeat, in the order listed, for each node in the recovery domain. | CHAR(8) | Node id | |
| BINARY(4) | Node role | ||
| * | * | CHAR(*) | Additional fields |
| These fields are part of the additional fields structure. | BINARY(4) | Failover wait time | |
| BINARY(4) | Failover default action | ||
| CHAR(10) | Failover message queue name | ||
| CHAR(10) | Failover message queue library name | ||
Application Resiliency (RGDC0201 Format)
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Length of fixed fields |
| 4 | 4 | CHAR(10) | Cluster resource group exit program name |
| 14 | E | CHAR(10) | Cluster resource group exit program library name |
| 24 | 18 | CHAR(8) | Cluster resource group exit program format name |
| 32 | 20 | CHAR(10) | User profile |
| 42 | 2A | CHAR(10) | Action for recovery domain array |
| 52 | 34 | CHAR(256) | Exit program data |
| 308 | 134 | BINARY(4) | Offset to recovery domain array |
| 312 | 138 | BINARY(4) | Number of nodes in recovery domain |
| 316 | 13C | BINARY(4) | Length of recovery domain entry |
| 320 | 140 | CHAR(1) | Application takeover IP address type |
| 321 | 141 | CHAR(45) | Application takeover IP address |
| 366 | 16E | CHAR(10) | Job name |
| 376 | 178 | BINARY(4) | Allow application restart |
| 380 | 17C | BINARY(4) | Number of restarts |
| 384 | 180 | BINARY(4) | Failover wait time |
| 388 | 184 | BINARY(4) | Failover default action |
| 392 | 188 | CHAR(10) | Failover message queue name |
| 402 | 192 | CHAR(10) | Failover message queue library name |
| * | * | Array (*) of CHAR(*) | Recovery domain array |
| These fields repeat, in the order listed, for each node in the recovery domain. | CHAR(8) | Node id | |
| BINARY(4) | Node role | ||
Device Resiliency (RGDC0300 Format)
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Cluster resource group exit program name |
| 10 | A | CHAR(10) | Cluster resource group exit program library name |
| 20 | 14 | CHAR(8) | Cluster resource group exit program format name |
| 28 | 1C | CHAR(10) | User profile |
| 38 | 26 | CHAR(10) | Action for recovery domain array |
| 48 | 30 | CHAR(256) | Exit program data |
| 304 | 130 | BINARY(4) | Offset to recovery domain array |
| 308 | 134 | BINARY(4) | Number of nodes in recovery domain |
| 312 | 138 | BINARY(4) | Length of recovery domain array entry |
| 316 | 13C | BINARY(4) | Offset to additional fields |
| 320 | 140 | BINARY(4) | Length of additional fields |
| * | * | Array (*) of CHAR(*) | Recovery domain array if Length of recovery domain array entry field is set to non-zero |
| These fields repeat, in the order listed, for each node in the recovery domain. | CHAR(8) | Node id | |
| BINARY(4) | Node role | ||
| * | * | Array (*) of CHAR(*) | Recovery domain array if Length of recovery domain array entry field is set to zero |
| These fields repeat, in the order listed, for each node in the recovery domain. | BINARY(4) | Length of entry in the recovery domain | |
| CHAR(8) | Node id | ||
| BINARY(4) | Node role | ||
| CHAR(8) | Site name | ||
| BINARY(4) | Offset to data port IP address array | ||
| BINARY(4) | Number of data port IP addresses | ||
| BINARY(4) | Data port IP address action | ||
| Array(*) of CHAR(16) | Data port IP address | ||
| * | * | Additional fields | |
| These fields are part of the additional fields structure. | BINARY(4) | Failover wait time | |
| BINARY(4) | Failover default action | ||
| CHAR(10) | Failover message queue name | ||
| CHAR(10) | Failover message queue library name | ||
| CHAR(10) | Job name | ||
Device Resiliency (RGDC0301 Format)
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Length of fixed fields |
| 4 | 4 | CHAR(10) | Cluster resource group exit program name |
| 14 | E | CHAR(10) | Cluster resource group exit program library name |
| 24 | 18 | CHAR(8) | Cluster resource group exit program format name |
| 32 | 20 | CHAR(10) | User profile |
| 42 | 2A | CHAR(10) | Action for recovery domain array |
| 52 | 34 | CHAR(256) | Exit program data |
| 308 | 134 | BINARY(4) | Offset to recovery domain array |
| 312 | 138 | BINARY(4) | Number of nodes in recovery domain |
| 316 | 13C | BINARY(4) | Failover wait time |
| 320 | 140 | BINARY(4) | Failover default action |
| 324 | 144 | CHAR(10) | Failover message queue name |
| 334 | 14E | CHAR(10) | Failover message queue library name |
| 344 | 158 | CHAR(10) | Job name |
| * | * | Array (*) of CHAR(*) | Recovery domain array |
| These fields repeat, in the order listed, for each node in the recovery domain. | BINARY(4) | Length of entry in the recovery domain | |
| BINARY(4) | Length of fixed recovery domain fields | ||
| CHAR(8) | Node id | ||
| BINARY(4) | Node role | ||
| CHAR(8) | Site name | ||
| BINARY(4) | Offset to data port IP address array | ||
| BINARY(4) | Number of data port IP addresses | ||
| BINARY(4) | Length of data port IP address array entry | ||
| BINARY(4) | Data port IP address action | ||
| * | * | Array (*) of CHAR(*) | Data port IP address array |
| These fields repeat, in the order listed, for each data port IP address. | BINARY(2) | Reserved | |
| CHAR(1) | Data port IP address type | ||
| CHAR(45) | Data port IP address | ||
 CHAR(8) |
Data port site name |
||
Peer Resiliency (RGDC0400 Format)
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Length of fixed fields |
| 4 | 4 | BINARY(4) | Offset to recovery domain array |
| 8 | 8 | BINARY(4) | Number of nodes in recovery domain |
| 12 | C | BINARY(4) | Length of recovery domain array entry |
| 16 | 10 | CHAR(10) | Action for recovery domain array |
| 26 | 1A | CHAR(10) | Cluster resource group exit program name |
| 36 | 24 | CHAR(10) | Cluster resource group exit program library name |
| 46 | 2E | CHAR(8) | Cluster resource group exit program format name |
| 54 | 36 | CHAR(10) | User profile |
| 64 | 40 | CHAR(256) | Exit program data |
| 320 | 140 | CHAR(20) | Application id |
| 340 | 154 | CHAR(10) | Job name |
| * | * | Array (*) of CHAR(*) | Recovery domain array |
| These fields repeat, in the order listed, for each node in the recovery domain. | CHAR(8) | Node id | |
| BINARY(4) | Node role | ||
Field Descriptions
Action for recovery domain array. Indicates which node role in the recovery domain is being changed. The special values used are:
| *SAME | Neither node role is changed. |
| *CHGPREFER | The PREFERED node role in the recovery domain will change. |
| *CHGCURREN | The CURRENT node role in the recovery domain can be changed. For a device cluster resource group, site name and data port IP addresses also can be changed. |
Additional fields. A structure containing optional additional fields.
Additional fields used. A flag to signify whether the additional fields in format RGDC0200 are being used. If the cluster version is less than 3, this field must be set to hexadecimal zero. Possible values are:
| 0x00 | The additional fields are not being used. |
| 0x01 | The additional fields are being used. |
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). |
| -1 | Allow application restart is not changed. |
Application id. This is a string to identify the application that supplied the 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.
| *SAME | The application id is not changed. This must be left justified. |
Application takeover IP address. This is the floating IP address that is to be associated with an application. When the format name is RGDI0300, the specified IPv4 address must be in dotted decimal format and a null-terminated string. When the format name is RGDI0301, either an IPv4 or IPv6 address is supported. When the Application takeover IP address type field is 0, the specified address must be an IPv4 address in dotted decimal format and padded on the right with hex zeros. When the Application takeover IP address type field is 1, the specified address must be an IPv6 address and padded on the right with hex zeros.
An IPv6 address must be a unicast address and must not contain an imbedded IPv4 address (compatibility or mapped). An IPv6 address is specified in the form x:x:x:x:x:x:x:x, where x is a hexadecimal number ranging from 0 through X'FFFF'. The "::" may be used once in the IPv6 address to indicate one or more groups of 16 bits of zeros. The "::" may be used to compress leading, imbedded, or trailing zeros in the address. The coded character set identifier (CCSID) of the IP address specified must match the CCSID of the job calling the API. The following special value can be used:
| *SAME | The takeover IP address is not changed. This must be left justified. |
If the value is not *SAME and the Cluster Resource Services configured the takeover IP address, this API will remove the current takeover IP address and add this takeover IP address to the node. If either the add or remove address function fails, the API will fail. The cluster resource group must be Inactive (20) to change this field.
Application takeover IP address type. Type of IP address that follows in the Application takeover IP address field. The possible values are:
| 0 | Application takeover interface address is IPv4. |
| 1 | Application takeover interface address is IPv6. Only allowed if current cluster version is 7 or higher. |
Cluster resource group exit program format name. The contents and format of the cluster resource group exit program information. This field must be set to hexadecimal zeroes if no exit program is specified. If the exit program name is *SAME and was previously *NONE, this field is ignored. The format name supported is:
| EXTP0100 | Exit program information. This value is allowed for primary-backup model cluster resource group and peer model cluster resource group. |
| EXTP0101 | Exit program information with IPv6 support. This value is allowed for primary-backup model cluster resource group and peer model cluster resource group. This is only valid if current cluster version is 7 or higher. |
| EXTP0200 | Exit program information, with additional information in the recovery domain array which contains site name and data port IP addresses on each node. This value is allowed for primary-backup model cluster resource group. |
| EXTP0201 | Exit program information, with IPv6 support and additional information in the recovery domain array which contains site name and data port IP addresses on each node. This value is allowed for primary-backup model cluster resource group. This is only valid if current cluster version is 7 or higher. |
| *SAME | Exit program format name is not changed. |
Cluster resource group exit program library name. The name of the library where the exit program exists. The special value *CURLIB or *LIBL may not be used for the library name. QTEMP is not a valid library name.
If the cluster resource group exit program name is *NONE or *SAME, the exit program library name is ignored.
Cluster resource group exit program name. The name of exit program that is used to handle action codes that are passed to it. The exit program cannot be in an independent auxiliary storage pool.
If the exit program is changed for an active application cluster resource group, the job currently running which was submitted to handle the Start (2) action code continues running the prior exit program.
The following special value can be used:
| *SAME | The current exit program is not changed. This must be left justified. |
| *NONE | The cluster resource group does not have an exit program.This is valid only for a device. This must be left justified. |
Data port IP address. The IP address associated with the recovery domain node. When adding a data port IP address, it must already exist on the specified node if the CRG is active. User is responsible for starting/ending data port IP address. When the format name is RGDC0300, the specified IPv4 address must be in dotted decimal format and a null-terminated string. When the format name is RGDC0301, either an IPv4 or IPv6 address is supported. When the Data port IP address type field is 0, the specified address must be an IPv4 address in dotted decimal format and padded on the right with hex zeros. When the Data port IP address type field is 1, the specified address must be an IPv6 address and padded on the right with hex zeros.
An IPv6 address must be a unicast address and must not contain an imbedded IPv4 address (compatibility or mapped). An IPv6 address is specified in the form x:x:x:x:x:x:x:x, where x is a hexadecimal number ranging from 0 through X'FFFF'. The "::" may be used once in the IPv6 address to indicate one or more groups of 16 bits of zeros. The "::" may be used to compress leading, imbedded, or trailing zeros in the address. The coded character set identifier (CCSID) of the IP address specified must match the CCSID of the job calling the API.
Data port IP address action. Indicates whether to add or remove the data port IP address associated with the recovery domain node. The possible values are:
| -1 | The data port IP addresses are not changed. |
| 0 | Remove the data port IP addresses from the recovery domain node. |
| 1 | Add the data port IP addresses to the recovery domain node. |
Data port IP address array. This array identifies the data port IP addresses used by the recovery domain node.
Data port IP address type. Type of IP address that follows in the Data port IP address field. The possible values are:
| 0 | Data port IP address is IPv4. |
| 1 | Data port IP address is IPv6. Only allowed if current cluster version is 7 or higher. |
Data port site name. The site name that
the data port address is to be used with. Only allowed if current cluster version is 8 or higher.
Exit program data. 256 bytes of data that is passed to the cluster resource group exit program when it is called. This parameter may contain any scalar data except pointers. For example, it can be used to provide state information. This data will be stored with the specified cluster resource group and copied to all nodes in the recovery domain. Pointers in this area will not resolve correctly on all nodes and should not be placed in the data. See Cluster Resource Group Exit Program for information about the cluster resource group exit program. The data specified will replace the existing exit program data stored with the cluster resource group, if the API completes successfully. This field must be set to hexadecimal zeroes if no exit program is specified. If the exit program name is *SAME and was previously *NONE, this field is ignored.
The following special value can be used:
| *SAME | The exit program data is not changed. This must be left justified. |
Failover default action. Indicates what clustering should do pertaining to the failover request when a response to the failover message queue was not be received in the failover wait time limit. If the failover message queue is *NONE, this field must be set to 0. If the failover message queue is *SAME and was previously *NONE, this field must be set to -1 or 0.
| -1 | Failover default action is not changed. This is the default value. |
| 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. The library name cannot be *CURLIB, QTEMP, or *LIBL.
If the failover message queue name is *NONE or *SAME, the failover message queue library name is ignored. Version 2 or lower cluster resource groups will default to *NONE for the message queue library name when the cluster version is changed to 3.
Failover message queue name. The name of the message queue to receive messages dealing with failover. The queue cannot be in an independent auxiliary storage pool.
The following special values can be used:
| *SAME | The current failover message queue is not changed. This is the default value. This must be left justified. |
| *NONE | No messages will be sent when a failover occurs through this cluster resource group. This must be left justified. |
Failover wait time. Number of minutes to wait for a reply to the failover message that was enqueued on the failover message queue. If the failover message queue is *NONE, this field must be set to 0. If the failover message queue is *SAME and was previously *NONE, this field must be set to -2 or 0. If a failover message queue is specified, this field cannot be set to 0. Valid values are:
| -2 | Failover wait time is not changed. This is the default value. |
| -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. |
Job name. The name given the batch job that is submitted by the cluster resource group. This job will call the cluster resource group exit program with the action code generated by the API being used. If the cluster resource group exit program name field is *NONE, this field must be set to hex zeros if it is provided. Otherwise, one of the special values of *JOBD or *SAME must be used if the cluster resource group is not an application cluster resource group and the current cluster version is not 7 or higher. For formats RGDC0110 or RGDC0400, if the job name field is not provided, the behavior will be as if *SAME was specified. For format RGDC0300, if the job name field is not provided, the behavior will be as if *JOBD was specified. Valid special values are:
| *SAME | The job name is not changed. This must be left justified. |
| *JOBD | The job name in the job description for the specified user profile will be used. This must be left justified. |
Length of additional fields. The length in bytes of additional fields. In format RGDC0200, this field is ignored if the additional fields used flag is not set to 1. If the additional fields used flag is 1 in format RGDC0200, the value of this field must be less than or equal to 28. In format RGDC0300, the value of this field must be less than or equal to 28 or equal to 38. In format RGDC0110, the value of this field must be set to 0 or 10.
Length of data port IP address array entry. The length of the dataport IP address array entry. For RGDC0301, this must be set to 48 bytes or
56 bytes if a dataport site name is specified.
Length of entry in the recovery domain. The length of an entry in the recovery domain array. This field is used if each entry may have a different length.
Length of fixed fields. The length of the fixed fields in the format description. For RGDC0400 this value must be 340 or 350. For RGDC0201, this value must be 412. For RGDC0301, this value must be 354.
Length of fixed recovery domain fields. The length of the fixed fields for the recovery domain array entry. This value must be set to 44.
Length of recovery domain array entry. The length of an entry in the recovery domain array. For formats other than RGDC0300, this field must be set to 12. For format RGDC0300, this field can be set to either 12 or zero. If zero, then the length of entry in the recovery domain field is used.
Node id. A unique string of characters that identifies a node that is participating in the recovery domain of the specified cluster resource group. The node specified must be active in the cluster, and it must be unique in the recovery domain of the specified cluster resource group.
Node role. The role the node has in the recovery domain. A role must be defined for each node 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 its role is changed 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 its role is changed from replicate to peer.
The following table 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. The values need not be consecutive. No two backup nodes can have the same value. At the completion of the API, Cluster Resource Services will sequence the backups using consecutive numbers starting with 1. |
| -1 | Replicate node. All replicates have this value. |
| -2 | The node role is not changed. |
| -4 | Peer node. All peers have this value. |
Number of data port IP addresses. The number of data port IP addresses to be added to or removed from the recovery domain node. If the current cluster version is 3 and the length of recovery domain array specified includes this field, it must be set to zero. This field must also be set to zero if no change is made to the data port IP addresses.
Number of nodes in the recovery domain. The number of nodes in the recovery domain array. This field is ignored if the Action for recovery domain array field contains *SAME. For primary-backup model cluster resource groups, this should equal the number of backup nodes plus the number of replicate nodes plus one (for the primary node). This must be greater than or equal to one and equal the number of nodes in the recovery domain. For peer model cluster resource groups all recovery domain nodes do not need to be specified to change the role. Only specify those nodes that are changing. If roles are changing this must be equal to the number of nodes being changed and cannot exceed the number of nodes currently defined in the recovery domain.
Number of restarts. Number of times a cluster resource group exit program can be called on a same node before failure occurs. Maximum number of restarts is 3. -1 means the maximum number of restarts does not change. If the cluster resource group is currently active, any change does not take affect until failover occurs or the cluster resource group exit program job ends.
Offset to additional fields. The byte offset from the beginning of this parameter to additional fields. In format RGDC0200, this field will be ignored unless the additional fields used field is set to 1. In format RGDC0110, this must be set to 0 if the additional fields are not used.
Offset to data port IP address array. The byte offset from the beginning of this parameter to the first data port IP address. If the current cluster version is 3 and the length of recovery domain array specified includes this field, it must be set to zero. This field is ignored if the number of data port IP addresses field is set to zero.
Offset to recovery domain array. The byte offset from the beginning of this table to the array of node information. This field is ignored if the Action for recovery domain array field contains *SAME.
Recovery domain array. Array of recovery domain information. A role must be defined for each node specified. Nodes in the recovery domain must be unique. See Node role for more information about the node roles associated with the specific cluster resource group type. For primary-backup model cluster resource groups this array identifies the nodes that compose the recovery domain. The complete recovery domain must be specified. For peer model cluster resource groups, this array identifies the recovery domain nodes that are changing. Only those nodes that are being changed need to be specified.
An example of a primary-backup model cluster resource group: A cluster resource group has four nodes: NodeA, NodeB, NodeC and NodeD. NodeA is the primary. There are two backup nodes: NodeB and NodeD. NodeD is the first backup and NodeB is the second backup. There is one replicate: NodeC.
Node Role
----- ----
NodeA 0 <-- primary
NodeD 1 <-- backup #1
NodeB 2 <-- backup #2
NodeC -1 <-- replicate
The nodes do not have to be arranged in any particular order in the array. They could be in the array as listed below and have the same result.
Node Role
----- ----
NodeB 2 <-- backup #2
NodeA 0 <-- primary
NodeC -1 <-- replicate
NodeD 1 <-- backup #1
Reserved. Must contain hexadecimal zeroes.
Site name. The name of the site associated with the recovery domain node. A site name can be changed only if all configuration objects in the cluster resource group are for auxiliary storage pool devices. The site name can be changed from *NONE to a name, or from a name to *NONE. Changing a name to a different name is not allowed. If the current cluster version is 3 and the length of recovery domain array specified includes this field, it must be set to hexadecimal zeroes. Valid special values for this field are:
| *NONE | The node in the recovery domain is not associated with a site name. This must be left justified. |
| *SAME | The site name it not changed. This must be left justified. |
User profile. The name of the user profile under which the exit program should process. The user profile must exist on all nodes in the recovery domain. This field must be set to hexadecimal zeroes if no exit program is specified. If the exit program name is *SAME and was previously *NONE, this field is ignored.
The following user profiles are not valid:
- QDBSHR
- QDOC
- QDTFOWN
- QRJE
- QLPAUTO
- QLPINSTALL
- QSECOFR
- QSPL
- QSYS
- QTSTRQS
The following special value can be used:
| *SAME | The current user profile is not changed. This must be left justified. |
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. |
| 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 is not allowed for cluster resource group &2. |
| CPFBB1A D | At least one node in the recovery domain of cluster resource group &1 must be active. |
| 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 is not allowed for this request. |
| CPFBB39 D | The current user does not have IOSYSCFG special authority. |
| CPFBB46 D | Cluster Resource Services internal error. |
| CPFBB51 D | IP address &4 already in use by the cluster &3. |
| CPFBB5E E | User profile to run exit program not specified. |
| 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. |
| 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. |
| CPFBBA2 D | Value &1 specified for failover wait time is not valid. |
| CPFBBA3 D | Value &1 specified for failover default action is not valid. |
| CPFBBA4 D | Field value within additional fields structure is not valid. |
| CPFBBA7 D | Site name and data port IP address not match. |
| CPFBBA8 D | Site name &1 specified for node &2 not allowed. |
| CPFBBA9 D | Data port IP address &5 specified for node &2 not allowed. |
| CPFBBB0 D | Exit program format name 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. |
| CPF2204 E | User profile &1 not found. |
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3C1E E | Required parameter &1 omitted. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C29 E | Object name &1 is not valid. |
| 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 Id &1 is not a member of Cluster &2. |
| CPFBB0A E | Cluster node &1 in cluster &2 not active. |
| CPFBB0F E | Cluster resource group &1 does not exist in cluster &2. |
| CPFBB25 E | Value &1 specified for recovery domain array action is not valid. |
| CPFBB26 E | Cluster Resource Services not active or not responding. |
| CPFBB27 E | A primary node was not specified for the recovery domain. |
| CPFBB28 E | Cluster node &1 and cluster node &2 have the same node role value &3. |
| CPFBB29 E | Node role value &1 not valid. |
| CPFBB2C E | Attributes of exit program &1 in library &2 are not valid. |
| CPFBB30 E | Takeover IP address &2 not part of the TCP/IP subnetwork. |
| CPFBB31 E | Value &1 specified for number of restarts not valid. |
| CPFBB32 E | Attributes of user queue &1 in library &2 not valid. |
| CPFBB33 E | Cluster node &1 already exists in recovery domain for cluster resource group &4. |
| CPFBB35 E | The user profile name &1 is not valid for this request. |
| CPFBB36 E | The number of cluster nodes specified for the recovery domain is not valid. |
| CPFBB37 E | The offset to the recovery domain array is not valid. |
| CPFBB38 E | Library name &1 is 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 | Invalid format name &1 for cluster resource group type &2. |
| CPFBB44 E | &1 API cannot be called from a cluster resource group exit program. |
| CPFBB51 E | IP address &4 already in use by the cluster &3. |
| CPFBB5E E | User profile to run exit program not specified. |
| CPFBB5F E | Field value within structure is not valid. |
| CPFBB62 E | Exit program name *NONE not valid. |
| CPFBB70 E | API request &1 not compatible with current cluster version. |
| CPFBBA2 E | Value &1 specified for failover wait time is not valid. |
| CPFBBA3 E | Value &1 specified for failover default action is not valid. |
| CPFBBA7 E | Site name and data port IP address not match. |
| CPFBBA8 E | Site name &1 specified for node &2 not allowed. |
| CPFBBA9 E | Data port IP address &5 specified for node &2 not allowed. |
| CPFBBAC E | The offset to the data port IP address array for node &1 is not valid. |
| CPFBBAD E | The number of data port IP addresses specified for node &1 is not valid. |
| CPFBBAE E | The data port IP address action for node &1 is not valid. |
| CPFBBAF E | Recovery domain node role is not valid. |
| CPFBBB0 E | Exit program format name not specified. |
| CPFBBC0 E | Cluster resource group &1 not allowed to be changed. |
| CPFBBCA E | IP address type not valid. |
| TCP1901 E | Internet address &2 not valid. |
API introduced: V4R4
[ Back to top | Cluster APIs | APIs by category ]