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 the queue used by the Distribute Information API exists if the cluster resource group being created indicates 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. .

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

1. Only auxiliary storage pool devices are supported.
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. The same configuration object cannot be specified for more than one cluster resource group.
7. 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.
8. 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.
9. 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.
10. If configuration objects are specified and the primary node does not currently own the devices, the API fails with an error message.
11. A cluster resource group may be created with no device entries. Device entries must be added using the Add Cluster Resource Group Device Entry (QcstAddClusterResourceGroupDev) API before the cluster resource group can be started.
12. 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.
13. 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.
14. 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) , Device Resiliency (RGDI0300 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).
RGDI0300	This format describes the cluster resource group type 3 (device resiliency)
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)

Application Resiliency (RGDI0200 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	CHAR(16)	Takeover IP address
320	140	CHAR(10)	Job name
330	14A	CHAR(1)	Configure takeover IP address
331	14B	CHAR(1)	Reserved
332	14C	BINARY(4)	Allow application restart
336	150	BINARY(4)	Number of restarts
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(49)	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(1)	Allow active takeover IP address

Device Resiliency (RGDI0300 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
*	*	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.
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.

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 auxiliary storage pool device description object which can be switched between the nodes in the recovery domain. An auxiliary storage pool device description 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 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. This field must be represented in dotted decimal format and be a null-terminated string.

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. 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 formats RGDI0100 and 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 or 28.

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 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 RGDI0400 this value must be 350.

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 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.
-4	Peer node. All peers have this value.

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 on 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. This field is optional and can only be specified for a primary auxiliary storage pool. If specified, the address must be represented in dotted decimal format and be a null-terminated string. 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:

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. This field must be represented in dotted decimal format and be a null-terminated string. 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.

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

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.