Change Cluster Resource Group (QcstChangeClusterResourceGroup) API

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:

1. Cluster Resource Services must be active on the node processing the request.
2. A cluster resource group must have a status of Inactive (20) or Indoubt (30) to designate a new primary node.
3. 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.
4. At least one active node in the recovery domain.
5. 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:

1. 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.
2. 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:

1. 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.
2. 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.
3. There must be at least one node designated as peer if the cluster resource group is Active (10).
4. 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)

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)

Application Resiliency (RGDC0201 Format)

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
*	*	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
		CHAR(10)	Job name

Device Resiliency (RGDC0301 Format)

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:

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:

Allow application restart. Attempt to restart an application if the cluster resource group exit program fails. Possible values are:

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.

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:

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:

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:

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.

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:

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.

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:

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:

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:

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.

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:

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:

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:

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.

[ Back to top | Cluster APIs | APIs by category ]