Create Cluster Resource Group (QcstCreateClusterResourceGroup) API

The Create Cluster Resource Group API creates a cluster resource group object. The cluster resource group object identifies a recovery domain. A recovery domain is a set of nodes in the cluster that will play a role in recovery. To change attributes of the cluster resource group, use the Change Cluster Resource Group (QcstChangeClusterResourceGroup) API.

This API will do the following for all cluster resource group types:

• Create the cluster resource group object on all nodes in the recovery domain. The cluster resource group may be accessed by a cluster resource group API running on any node in the cluster. The cluster resource group will be owned by the user profile calling this API.
• Provide users a single system image of the cluster resource group object. That is, any changes made to the cluster resource group will be made on all nodes in the recovery domain.
• Call the cluster resource group exit program with an action code of Initialize (1) after the cluster resource group has been created on each node in the recovery domain, if exit program is specified for the cluster resource group. The cluster resource group status will be set to Initialize Pending (540). If the exit program fails, the cluster resource group object is deleted from all nodes in the recovery domain.
• If the exit program is successful, the cluster resource group status is set to Inactive (20). To change the cluster resource group status to Active (10), use the Start Cluster Resource Group(QcstStartClusterResourceGroup) API.
• After the exit program is called, the API verifies that the queue used by the Distribute Information API exists if the cluster resource group being created indicates that the Distribute Information(QcstDistributeInformation) API will be used. The distributed information user queue does not allow pointers within the message content.
• After the exit program is called, the API verifies the failover message queue exists on all recovery domain nodes if one was specified.

This API requires the following for all cluster resource group types:

1. Cluster Resource Services must be active on the node processing the API request.
2. All nodes specified in the recovery domain must be active in the cluster.
3. The cluster resource group exit program must exist on all nodes in the recovery domain if an exit program is specified. It must have the same name and be in the same library on each node.
4. Each node is specified only once in the recovery domain.
5. The cluster resource group name cannot be used by an existing cluster resource group on any node in the cluster.

This API requires the following for resilient application cluster resource groups:

1. For the specified takeover IP address:
   • If Cluster Resource Services configures the takeover IP address, all nodes in the recovery domain must be in the same subnet (network address) and the subnet defined on all nodes in the recovery domain.
   • The takeover IP address must be unique. If Cluster Resource Services is responsible for configuring the takeover IP address, it will be added to each node in the recovery domain.
   • The takeover IP address must not be active on any node in the recovery domain when cluster resource services creates the application takeover IP address.
   • IP addresses created by IPv6 stateless address auto-configuration are not valid to be used as a takeover IP address.

This API requires the following for resilient device cluster resource groups:

1. Cluster version 5 only allows auxiliary storage pool devices. Cluster versions 6 and greater allows additional configuration object types that are listed below.
2. All nodes in the recovery domain must belong to the same device domain.
3. The configuration objects, such as device descriptions, for the devices specified for the cluster resource group must exist on all nodes in the recovery domain and the resource name specified in a configuration object must be the same on all nodes in the recovery domain.
4. If a data base name is specified in a configuration object, it must be the same on all nodes in the recovery domain.
5. The server takeover IP address must be unique. It can only be associated with a primary auxiliary storage pool.
6. IP addresses created by IPv6 stateless address auto-configuration are not valid to be used as a server takeover IP address.
7. The same configuration object cannot be specified for more than one cluster resource group.
8. Devices attached to the same IOP or high-speed link I/O bridge can be specified for only one cluster resource group. For cross-site mirroring which only has one node at a site, this requirement does not apply.
9. If devices attached to different IOPs or high-speed link I/O bridges are grouped such as for an auxiliary storage pool, all devices for the affected IOPs or high-speed link I/O bridges must be specified in the same cluster resource group. For cross-site mirroring which only has one node at a site, this requirement does not apply.
10. The IOP or high-speed link I/O bridge controlling the devices specified in a cluster resource group must be accessible by all nodes in the cluster resource group's recovery domain or by all nodes within the same site (for cross-site mirroring). This is verified if sufficient hardware configuration has been performed so that all nodes are aware of the new hardware. If hardware configuration is incomplete, this is verified when the Start Cluster Resource Group API is called.
11. If configuration objects are specified and the primary node does not currently own the devices, the API fails with an error message.
12. A cluster resource group may be created with no device entries. Device entries must be added by using the Add Cluster Resource Group Device Entry (QcstAddClusterResourceGroupDev) API before the cluster resource group can be started.
13. If the cluster resource group contains any members of an auxiliary storage pool group, it must contain all members before the cluster resource group can be started. All members do not have to be specifed when the cluster resource group is created. Additional members can be added with the Add Cluster Resource Group Device API. If the auxiliary storage pool group exists and clustering can determine the members of the group, a warning message is sent if any members were not specified.
14. If the configuration objects specified are for geographic mirroring, each node in the recovery domain must have a site name and up to 4 data port IP addresses. If a site name is specified, at least one data port IP address must be specified too. The reverse is also true. If one or more data port IP addresses are specified, a site name must be specified too.
15. A cluster resource group with sites defined can only have auxiliary storage pool devices.
16. If the configuration objects are specified, then the cluster version must be at the appropriate level for the information being specified.

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.
• The cluster resource group name cannot begin with QCST.

Note: For information about the recovery domain, see Cluster Resource Group APIs--Introduction.

Authorities and Locks

The program that calls this API must be running under a user profile with *IOSYSCFG special authority. This profile is named the calling user profile.

Cluster Resource Group Library Authority

*OBJOPR, *ADD, and *READ

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

Configuration Object Lock

*EXCLRD

Distribute Information User Queue Authority

*OBJOPR, *ADD

Distribute Information User Queue Library Authority

*EXECUTE

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 which will contain the cluster resource group.

Cluster resource group name

INPUT; CHAR(10)

The name of the cluster resource group which is to be created. The cluster resource group name cannot begin with QCST. The cluster resource group object will be created in the QUSRSYS library.

Cluster resource group type

INPUT; BINARY(4)

The type of cluster resource group being created. Valid cluster resource group types are:

1	Data resiliency
2	Application resiliency
3	Device resiliency
4	Peer resiliency

Cluster resource group description information

INPUT; CHAR(*)

Detailed information about the cluster resource group. For more information, see Data Resiliency (RGDI0100 Format) , Application Resiliency (RGDI0200 Format) , Application Resiliency (RGDI0201 Format) , Device Resiliency (RGDI0300 Format), Device Resiliency (RGDI0301 Format), and Peer Resiliency (RGDI0400 Format).

Format name

INPUT; CHAR(8)

The content and format of the cluster resource group information. The possible values for format name are:

RGDI0100	This format describes the cluster resource group type 1 (data resiliency).
RGDI0200	This format describes the cluster resource group type 2 (application resiliency).
RGDI0201	This format describes the cluster resource group type 2 (application resiliency) and includes IPv6 support.
RGDI0300	This format describes the cluster resource group type 3 (device resiliency).
RGDI0301	This format describes the cluster resource group type 3 (device resiliency) and includes IPv6 support.
RGDI0400	This format describes the cluster resource group type 4 (peer resiliency).

Text description

INPUT; CHAR(50)

This text briefly describes the cluster resource group.

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 (RGDI0100 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(1)	Additional fields used
39	27	CHAR(1)	Reserved
40	28	CHAR(256)	Exit program data
296	128	BINARY(4)	Offset to recovery domain array
300	12C	BINARY(4)	Number of nodes in recovery domain
304	130	BINARY(4)	Offset to additional fields
308	134	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)	Distribute information user queue name
		CHAR(10)	Distribute information user queue library name
		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

Application Resiliency (RGDI0200 Format)

Application Resiliency (RGDI0201 Format)

Device Resiliency (RGDI0300 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(2)	Reserved
40	28	CHAR(256)	Exit program data
296	128	BINARY(4)	Offset to recovery domain array
300	12C	BINARY(4)	Number of nodes in recovery domain
304	130	BINARY(4)	Length of recovery domain array entry
308	134	BINARY(4)	Offset to configuration object array
312	138	BINARY(4)	Number of configuration object array entries
316	13C	BINARY(4)	Length of configuration object array entry
320	140	BINARY(4)	Offset to additional fields
324	144	BINARY(4)	Length of additional fields
328	148	CHAR(10)	Distribute information user queue name
338	152	CHAR(10)	Distribute information user queue library name
*	*	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
		Array(*) of CHAR(16)	Data port IP address
*	*	Array (*) of CHAR(*)	Configuration object array
These fields repeat, in the order listed, for each device entry.		CHAR(10)	Configuration object name
		BINARY(2)	Reserved
		BINARY(4)	Configuration object type
		BINARY(4)	Configuration object online
		CHAR(16)	Server takeover 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 (RGDI0301 Format)

Peer Resiliency (RGDI0400 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)	Cluster resource group exit program name
26	1A	CHAR(10)	Cluster resource group exit program library name
36	24	CHAR(8)	Cluster resource group exit program format name
44	2C	CHAR(10)	User profile
54	36	CHAR(256)	Exit program data
310	136	CHAR(10)	Distribute information user queue name
320	140	CHAR(10)	Distribute information user queue library
330	14A	CHAR(20)	Application id
350	15E	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

Additional fields. A structure containing optional additional fields.

Additional fields used. A flag to signify whether the additional fields in formats RGDI0100, RGDI0200, and RGDI0300 are being used. Possible values are:

Allow active takeover IP address. Allows a takeover IP address to already be active when it is assigned to an application cluster resource group. This field is only valid when configure takeover IP address field is 0x01. 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 supplying the peer 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.

Cluster resource group exit program format name. Indicates which format should be used for the Information Given To User parameter on the cluster resource group exit program when it is called. This value must be set to hexadecimal zeroes if an exit program is not specified. Possible values if an exit program is specified are:

EXTP0100	Standard information. This value is allowed for primary-backup model cluster resource group and peer model cluster resource group.
EXTP0101	Standard 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	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	Additional information in the recovery domain array which contains site name and data port IP addresses on each node, and IPv6 support. This value is allowed for primary-backup model cluster resource group. This is only valid if current cluster version is 7 or higher.

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. This value must be set to hexadecimal zeroes if an exit program is not specified.

Cluster resource group exit program name. The name of the exit program that is used to handle action codes that are passed to it. The action codes are described in Cluster Resource Group Exit Program.

The cluster resource group exit program cannot be in an independent auxiliary storage pool. Valid special values for this field are:

Configuration object array. This array identifies the resilient devices that can be switched from one node to another.

Configuration object name. The name of the configuration object which can be switched between the nodes in the recovery domain. A configuration object can be specified in only one cluster resource group.

Configuration object online. Vary the configuration object on and start the server takeover IP address or leave the configuration object varied off and the server takeover IP address inactive when a device is switched from one node to another with the Initiate Switchover (QcstInitiateSwitchOver) API or when it is failed over to a backup node. This attribute does not vary the device on or off and does not start or end the server takeover IP address when the cluster resource group is started or ended and when adding a new device entry to the cluster resource group. For secondary auxiliary storage pools, only a value of 2 is valid. If cluster resources cannot determine if this value is correct for a device entry because the auxiliary storage pool is not yet created, any errors will be detected when the cluster resource group is started. A value of 2 cannot be specified for any other device type. Possible values are:

Configuration object type. This specifies the type of configuration object specified with configuration object name. Possible values and devices supported are:

Configure takeover IP address. This field identifies who is responsible for configuring (adding and removing) the takeover IP address. This does not affect the starting and ending of the takeover IP address, Cluster Resource Services will perform this function. The following values are valid:

Data port IP address. The IP address associated with the recovery domain node. User is responsible for configuring and starting/ending data port IP address. The data port IP address may or may not already exist on the specified node. When the format name is RGDI0300, the 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 Data port IP address type field is 0, the 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 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 array. This array identifies the data port IP addresses used by the recovery domain node.

Data port IP address type. Type of interface address in the Data port IP address field. The possible values are:

0	Data port interface address is IPv4.
1	Data port interface address is IPv6. Only valid if current cluster version is 7 or higher.

Distribute information user queue library name. The name of the library that contains the user queue to receive the distributed information. The library name cannot be *CURLIB, QTEMP, or *LIBL. If the user would like to distribute cluster-wide information through this cluster resource group using the Distribute Information(QcstDistributeInformation) API, then this field must be set. The only way to change the value of this field once the cluster resource group has been created is to delete and recreate the cluster resource group. This field must be set to hexadecimal zeroes if the distribute information user queue name is *NONE.

Distribute information user queue name. The name of the user queue to receive distributed information from the Distribute Information API. If the user would like to distribute cluster-wide information through this cluster resource group using the Distribute Information API, then this field must be set to a value other than *NONE. If this field is set, the specified user queue must exist on all nodes in the recovery domain after the exit program completes.

The queue cannot be in an independent auxiliary storage pool.

The only way to change the value of this field once the cluster resource group has been created is to delete and recreate the cluster resource group. Valid special values for this field are:

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. This value must be set to hexadecimal zeroes if an exit program is not specified.

Failover default action. Should a response to the failover message queue not be received in the failover wait time limit, then this field tells clustering what it should do pertaining to the failover request. This field must be set to 0 if the failover message queue name is *NONE. For format RGDI0100 or RGDI0200, if the current cluster version is 2 and the length of additional fields specified includes the failover default action, this field must be set to 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 user would like to receive failover message through this cluster resource group, then this field must be set. This field must be set to hexadecimal zeroes if the failover message queue name is *NONE. For format RGDI0100 or RGDI0200, if the current cluster version is 2 and the length of additional fields specified includes the failover message queue library name, this field must be set to hexadecimal zeroes.

Failover message queue name. The name of the message queue to receive messages dealing with failover. If the user would like to receive notice before a failover occurs, then this field must be set to a value other than *NONE. If this field is set, the specified message queue must exist on all nodes in the recovery domain. The queue cannot be in an independent auxiliary storage pool. For format RGDI0100 or RGDI0200, if the current cluster version is 2 and the length of additional fields specified includes the failover message queue name, this field must be set to hexadecimal zeroes. Valid special values for this field are:

Failover wait time. Number of minutes to wait for a reply to the failover message (CPFBBAB) that was enqueued on the failover message queue. This field must be set to 0 if the failover message queue name is *NONE. This field cannot be set to 0 if a failover message queue is specified. For format RGDI0100 or RGDI0200, if the current cluster version is 2 and the length of additional fields specified includes the failover wait time, this field must be set to 0. Valid values are:

Job name. The name given the batch job that is submitted. This is the job that calls the cluster resource group exit program. If the cluster resource group exit program name field is *NONE, this field must be set to hex zeros if it is provided. Otherwise, the special value of *JOBD 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 RGDI0100, RGDI0300, or RGDI0400, if the job name field is not provided, the behavior will be as if *JOBD was specified. Valid special values for this field are:

Length of additional fields. The length in bytes of additional fields. In formats RGDI0100 and RGDI0200, 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 RGDI0100, the value of this field must be equal to 20, 48 or 58. If the additional fields used flag is 1 in format RGDI0200, the value of this field must be equal to 20, 48 or 49. In format RGDI0300, if the cluster version is less than 3, the value of this field must be 0. If the cluster version is 3, the value of this field must be equal to 0, 28 or 38.

Length of configuration object array entry. The length of an entry in the configuration object array. This field must be set to 0 if the number of entries in the configuration object array field has a value of 0. If the number of entries has a value greater than 0, it must be set to the length of a single entry.

Length of data port IP address array entry. The length of the dataport IP address array entry. For format RGDI0301, this must be set to 48.

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 format RGDI0400, this value must be 350 or 360. For format RGDI0201, this value must be 424. For format RGDI0301, this value must be 378.

Length of fixed recovery domain fields. The length of the fixed fields for the recovery domain array entry. This value must be set to 40.

Length of recovery domain array entry. The length of an entry in the recovery domain array. For formats other than RGDI0300, this field must be set to 12. For format RGDI0300, 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. This node will become an active access point when the cluster resource group is started. Backup nodes are assigned a backup order. One indicates the first backup, two the second backup, and so on. Backup nodes are avaliable to become an active access point. Replicates are not ordered and cannot become an access point for the cluster resource 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 the peer or replicate. Peer nodes are not ordered and can become 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 table summarizes the valid values for this field:

Number of configuration object array entries. The number of entries in the configuration object array. This value can be 0 if no configuration object entries are to be added when the cluster resource group is initially created. At least one configuration object entry must be added before the Start Cluster Resource Group (QcstStartClusterResourceGroup) API is called. A cluster resource group can have a maximum of 256 configuration object entries. If no configuration objects specified this field must be hexadecimal zero.

Number of data port IP addresses. The number of data port IP addresses associated with the recovery domain node. A node can have up to 4 data port IP addresses. If the current cluster version is 3 and the length of recovery domain array specified includes this field, it must be set to zero.

Number of nodes in the recovery domain. The number of nodes in the recovery domain array. 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.

Number of restarts. Number of times an application can be restarted on the same node before a failover occurs. Maximum number of restarts is 3. Every time the cluster resource group exit program is run, the number of restarts is reset to 0 and works up to the maximum value specified.

Offset to additional fields. The byte offset from the beginning of this parameter to additional fields. In formats RGDI0100 and RGDI0200, this field will be ignored unless the additional fields used field is set to 1. In format RGDI0300, if the cluster version is less than 3, the value of this field must be 0.

Offset to configuration object array. The byte offset from the beginning of this parameter to the Configuration object array field. This field must be set to 0 if the number of entries in the configuration object array field has a value of 0.

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 parameter to the Recovery domain array field.

Recovery domain array. This array identifies the nodes that compose the recovery domain. A role must be defined for each node in the recovery domain. Nodes in the recovery domain must be unique. See the node role field for more information about primary, backup, replicate and peer.

An example for 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.

Server takeover IP address. This is a takeover IP address for servers associated with the relational database name in the device description for an auxiliary storage pool. For all other devices, this field must be *NONE. For auxiliary storage pools, this field is optional and can only be specified for a primary auxiliary storage pool. 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 Server 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 Server 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 specified address must exist on all nodes in the recovery domain if the cluster resource group is active. If not specified, or for a secondary and UDFS auxiliary storage pool, this field must be set to *NONE and be left justified. If the current cluster version is 2 and the length of configuration object array entry specified includes the server takeover IP address, this field must be set to hexadecimal zeroes. Valid special values for this field are:

Server takeover IP address type. Type of IP address that follows in the Server takeover IP address field. The possible values are:

0	Server takeover interface address is IPv4.
1	Server takeover interface address is IPv6. Only valid if current cluster version is 7 or higher.

Site name. The name of the site associated with the recovery domain node. If the current cluster version is 3 and the length of recovery domain array specified includes this field, this field must be set to hexadecimal zeroes. Valid special values for this field are:

Takeover IP address. This is the floating IP address that is to be associated with the application. When the format name is RGDI0200, the IPv4 address must be in dotted decimal format and a null-terminated string. When the format name is RGDI0201, either an IPv4 or IPv6 address is supported. When the 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 Takeover IP address type field is 1, the 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 Cluster Resource Services will create this IP address on every system in the recovery domain if the Configure takeover IP address is 0x00. If the IP address already exists, then this API will fail.

Takeover IP address type. Type of IP address that follows in the Takeover interface address field. The possible values are:

0	Takeover interface address is IPv4.
1	Takeover interface address is IPv6. Only valid if current cluster version is 7 or higher.

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 the cluster resource group does not have an exit program. The following user profiles are not valid:

• QDBSHR
• QDOC
• QDFTOWN
• QRJE
• QLPAUTO
• QLPINSTALL
• QSECOFR
• QSPL
• QSYS
• QTSTRQS

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.
CPF2204 D	User profile &1 not found.
CPF2108 D	Object not added to library.
CPF2112 D	Object &1 in &2 type *&3 already exists.
CPF2113 D	Cannot allocate library &1.
CPF2182 D	Not authorized to library &1.
CPF3C29 D	Object name &1 is not valid.
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 E	Cannot allocate object &2 in library &3.
CPF9804 D	Object &2 in library &3 damaged.
CPF9810 D	Library &1 not found.
CPF9820 D	Not authorized to use library &1.
CPF9830 D	Cannot assign library &1.
CPF9838 D	User profile storage limit exceeded.
CPF9870 D	Object &2 type *&5 already exists in library &3.
CPFBB02 D	Cluster &1 does not exist.
CPFBB0A D	Node &1 is not active in cluster &2.
CPFBB0B D	Request using takeover IP address &1 failed.
CPFBB17 D	&1 API cannot be processed in cluster &2.
CPFBB27 D	A primary node was not specified for the recovery domain.
CPFBB28 D	Cluster node &1 and cluster node &2 have the same node role value &3.
CPFBB29 D	Node role value &1 not valid.
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.
CPFBB30 D	Takeover IP address &2 is not part of the TCP/IP subnetwork.
CPFBB32 D	Attributes of user queue &1 in library &2 are not valid.
CPFBB34 D	Cluster resource group &1 already exists in cluster &2.
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	Current user does not have IOSYSCFG special authority.
CPFBB46 D	Cluster Resource Services internal error.
CPFBB47 D	Cluster Resource Services ended abnormally.
CPFBB48 D	Cluster Resource Services error detected.
CPFBB51 D	IP address &4 already in use by the cluster &3.
CPFBB5A D	All recovery domain nodes not in same device domain.
CPFBB5B D	Resource name &1 incorrect for configuration object &2 on node &3.
CPFBB5C D	Configuration object &1 already in cluster resource group &2.
CPFBB5D D	Other related devices already in cluster resource group &1.
CPFBB60 D	Cluster message not received from cluster node &3.
CPFBB64 D	Configuration object &1 not valid device type.
CPFBB66 D	Request failed for device cluster resource group &3.
CPFBB7A D	Primary node &1 in cluster resource group &2 not current owner of specified devices.
CPFBB7B D	Device type incorrect for configuration object &1 on node &2.
CPFBB7C D	Resource name &1 already used by configuration object &2 in cluster resource group &4.
CPFBB7D D	Configuration object &1 already in cluster resource group &2.
CPFBB7E D	Resource name &1 already in cluster resource group &2.
CPFBB7F D	Too many I/O processors or high-speed link I/O bridges specified for cluster resource group &1.
CPFBB80 D	Request failed for device cluster resource group &3.
CPFBB84 D	Device domain entry for node &1 being removed.
CPFBB90 D	Request failed for device cluster resource group &3.
CPFBB98 D	Hardware resource &1 not switchable.
CPFBB99 D	Request failed for device cluster resource group &3.
CPFBB9A D	Online value not valid for device &1.
CPFBB9B D	Auxiliary storage pool group member &1 not specified.
CPFBB9D D	Device &1 not compatible with current cluster version.
CPFBB9E D	Data base name &1 not correct for configuration object &2 on node &3.
CPFBBA6 D	Server takeover IP address cannot be associated with device subtype &1.
CPFBBA8 D	Site name &1 specified for node &2 not allowed.
CPFBBA9 D	Data port IP address &5 specified for node &2 not allowed.
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
CPF2112 E	Object &1 in &2 type *&3 already exist.
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.
CPF3C4B E	Value not valid for field &1.
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.
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.
CPF9838 E	User profile storage limit exceeded.
CPF9872 E	Program or service program &1 in library &2 ended. Reason code &3.
CPFBB02 E	Cluster &1 does not exist.
CPFBB09 E	Cluster node &1 does not exist in cluster &2.
CPFBB0A E	Cluster node &1 in cluster &2 is not active.
CPFBB0E E	Cluster resource group type &1 not valid.
CPFBB26 E	Cluster Resource Services not active or not responding.
CPFBB27 E	No primary node specified in recovery domain.
CPFBB28 E	Two or more backup nodes have the same node role value &1.
CPFBB29 E	Node role value &1 not valid.
CPFBB2C E	Attributes of exit program &1 in library &2 are not valid.
CPFBB31 E	Value &1 specified for number of restarts not valid.
CPFBB32 E	Attributes of user queue &1 in library &2 are not valid.
CPFBB33 E	Cluster node &1 already exists in the recovery domain for cluster resource group &4
CPFBB34 E	Cluster resource group &1 already exist in cluster &2.
CPFBB35 E	User profile name not valid for this request.
CPFBB36 E	Number of nodes in recovery domain is not valid.
CPFBB37 E	Offset to recovery domain is not valid.
CPFBB38 E	Library name &1 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 restart parameter is not valid.
CPFBB43 E	Format name &1 not valid 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.
CPFBB5A E	Device domain for recovery domain nodes not correct.
CPFBB5F E	Field value within structure is not valid.
CPFBB61 E	Configuration object &1 specified more than once in configuration object array.
CPFBB62 E	Exit program name *NONE not valid.
CPFBB63 E	Configuration object &1 not valid type.
CPFBB64 E	Configuration object &1 not valid device type.
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.
CPFBBA4 E	Field value within additional fields structure is not valid.
CPFBBA5 E	Server takeover IP address &2 specified more than once in the configuration object array.
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.
CPFBBCA E	IP address type not valid.
TCP1901 E	Internet address &2 not valid.

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