Create Cluster Resource Group (QcstCreateClusterResourceGroup) API


  Required Parameter Group:


  Service Program: QCSTCRG1

  Default Public Authority: *EXCLUDE

  Threadsafe: Yes

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:

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.
Caution. Switchover and failover completion may be delayed if the device CRG online attribute has a value of *YES for devices that may take a long time to vary on.

This API operates in an asynchronous mode. See Behavior of Cluster Resource Services APIs for more information.

Restriction:

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:

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:


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)


Application Resiliency (RGDI0201 Format)



Device Resiliency (RGDI0300 Format)


Device Resiliency (RGDI0301 Format)



Peer Resiliency (RGDI0400 Format)



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:

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:

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:

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:

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:


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.


API introduced: V4R4

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