Change Cluster Resource Group (QcstChangeClusterResourceGroup) API

The Change Cluster Resource Group (QcstChangeClusterResourceGroup) API changes some of the attributes of a cluster resource group.

The following fields may be changed without causing the cluster resource group exit program to be called:

• Text description
• Exit program data
• User profile
• Takeover IP address
• Job name
• Allow application restart
• Number of restarts
• The cluster resource group exit program
• Failover message queue
• Failover wait time
• Failover default action
• Cluster resource group exit program format name
• Application id

To add a node to the recovery domain use, the Add Node To Recovery Domain (QcstAddNodeToRcvyDomain) API.

To remove a node from the recovery domain, use the Remove Node From Recovery Domain (QcstRemoveNodeFromRcvyDomain) API.

To add a device to a resilient device cluster resource group, use the Add Cluster Resource Group Device Entry (QcstAddClusterResourceGroupDev) API.

To remove a device from a resilient device cluster resource group, use the Remove Cluster Resource Group Device Entry (QcstRmvClusterResourceGroupDev) API.

To change a device entry in a resilient device cluster resource group, use the Change Cluster Resource Group Device Entry (QcstChgClusterResourceGroupDev) API.

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

• Call the cluster resource group exit program with an action code of Change (13) on all active nodes in the recovery domain when either the preferred or current role is changed,or when a site name and/or data port IP addresses are changed, if an exit program is specified for the cluster resource group. The cluster resource group status is set to Change Pending (520). If the exit program completes successfully, the cluster resource group status is reset to its value at the time the API was called. If the exit program fails and the cluster resource group cannot be restored to its original condition, the cluster resource group status is set to Indoubt (30).
• Change the cluster resource group without calling the exit program if neither node role, site name nor data port IP addresses are changed.
• Change the name to be used for batch jobs submitted by cluster resource group. If the cluster resource group status is Active (10), batch jobs already submitted will not be changed. Any jobs submitted after the change will use the new name. This is true for other attributes associated with a submitted exit program such as the user profile, the restart count and so on. Changes to the cluster resource group will not affect an exit program that was previously submitted and is either on a job queue or is running.
• For a primary-backup model cluster resource group, if the current node role in the recovery domain is changed and the cluster resource group is active and it has more than one backup node and some backup nodes are not active, the recovery domain may be reordered so that all active backup nodes are ordered before inactive backup nodes.

This API will do the following for resilient application cluster resource groups:

• If the Cluster Resource Services configures the takeover IP address, it will remove the current address and add the new address when the takeover IP address is changed. If either the add or remove address function fails, the API will fail.
• If the cluster resource group is active and the role of a node is being changed from replica to backup, verify the takeover IP address exists and is not active on the node being changed. If the takeover IP address does not exist or is active on the node being changed, the API will fail.

This API will do the following for resilient device cluster resource groups:

• If the role of the current primary node is being changed, ownership of the devices specified in the cluster resource group is switched from the current primary to the new primary if the current primary has none of the devices varied on. If any devices are varied on, an error message is returned. In addition, the new primary node must be active. All members of an auxiliary storage pool group must be configured in the cluster resource group before ownership can be changed. Devices are not varied on after the ownership is switched.
• If the site name and/or data port IP addresses for a recovery domain node is changed but the node role is not changed, you can specify only the node that is changed, no need to specify all nodes in the recovery domain.
• If a recovery domain node role is changed (a value other than -2 is specified), then the rest of the nodes in the recovery domain must also be specified and they must have value other than -2.
• In cross-site mirroring, a switchover on a mirror site can be done by changing the mirror site node roles, by assigning a different active node to be the highest node role ranking at a mirror site.

This API requires for all cluster resource group types:

1. Cluster Resource Services must be active on the node processing the request.
2. A cluster resource group must have a status of Inactive (20) or Indoubt (30) to designate a new primary node.
3. The new exit program, if one specified, must exist on all nodes in the recovery domain when the cluster resource group exit program is changed.
4. At least one active node in the recovery domain.
5. If defined, the failover message queue must exist on all nodes in the recovery domain when the cluster resource group is changed.

This API requires for all primary-backup model cluster resource group types:

1. Changing the node role to primary or changing the takeover IP address can only be done when the cluster resource group is Inactive (20) or Indoubt (30). If the cluster resource group is Active, the Initiate Switchover API can be used to assign the primary role to the first backup node. For information about the Initiate Switchover API, see Initiate Switchover (QcstInitiateSwitchOver) API.

This API requires for all peer model cluster resource group types:

1. The recovery domain role can be changed from peer to replicate or replicate to peer by specifying one or more recovery domain nodes. The full recovery domain does not need to be specified.
2. If the cluster resource group is Active (10) and:
   • The role is changed from peer to replicate, the node becomes an inactive access point.
   • The role is changed from replicate to peer, the node becomes an active access point.
3. There must be at least one node designated as peer if the cluster resource group is Active (10).

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

Restriction: This API cannot be called from a cluster resource group exit program.

Authorities and Locks

The program that calls this API must be running under a user profile with *IOSYSCFG special authority.

Cluster Resource Group Authority

*CHANGE

Cluster Resource Group Library Authority

*EXECUTE

Cluster Resource Group Group Lock

*EXCL

Exit Program Authority (applies to user profile calling the API and user profile to run the exit program)

*EXECUTE

Exit Program Library Authority (applies to user profile calling the API and user profile to run the exit program)

*EXECUTE

User Profile Authority (applies to user profile to run the exit program)

*USE

Request Information User Queue Authority

*OBJOPR, *ADD

Request Information User Queue Library Authority

*EXECUTE

Request Information User Queue Lock

*EXCLRD

Configuration Object Authority

*USE and *OBJMGT

Failover Message Queue Authority

*OBJOPR, *ADD

Failover Message Queue Library Authority

*EXECUTE

Required Parameter Group

Request handle

OUTPUT; CHAR(16)

A unique string or handle that identifies this API call. It is used to associate this call to any responses placed on the user queue specified in the results information parameter.

Cluster name

INPUT; CHAR(10)

The name of the cluster to which the cluster resource group belongs.

Cluster resource group name

INPUT; CHAR(10)

The name of the cluster resource group which is to be changed.

Cluster resource group description information

INPUT; CHAR(*)

Detailed information about the cluster resource group. For more information, see Data Resiliency (RGDC0100 Format), Data Resiliency (RGDC0110 Format), Application Resiliency (RGDC0200 Format), Device Resiliency (RGDC0300 Format) and Peer Resiliency (RGDC0400 Format).

Format name

INPUT; CHAR(8)

The content and format of the cluster resource group information. The possible format names are:

RGDC0100	This format describes the data cluster resource group.
RGDC0110	This format also describes the data cluster resource group, with some additional fields added.
RGDC0200	This format describes the application cluster resource group.
RGDC0300	This format describes the device cluster resource group.
RGDC0400	This format describes the peer cluster resource group.

Text description

INPUT; CHAR(50)

This text briefly describes the cluster resource group. This must be left justified. The following special value can be used:

*SAME

The current text description is not changed. This must be left justified.

Results information

INPUT; CHAR(30)

This parameter identifies a qualified user queue field and is followed by a reserved field.

Qualified user queue: Completion information is returned to this user queue, which exists on the node from which the API was called, after the function has completed. See the Usage Notes section of this API for a description of the data that is placed on this queue. This is a 20-character field. The first 10 characters contain the user queue name, and the second 10 characters contain the user queue library name. No special values are supported. QTEMP, *LIBL, *CURLIB are not valid library names. The attributes of this user queue must be keyed.

Reserved: The last 10 characters of the 30-character results information are reserved. Each character in this field must be set to hexadecimal zero.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error Code Parameter.

Data Resiliency (RGDC0100 Format)

Data Resiliency (RGDC0110 Format)

Application Resiliency (RGDC0200 Format)

Device Resiliency (RGDC0300 Format)

Peer Resiliency (RGDC0400 Format)

Offset		Type	Field
Dec	Hex
0	0	BINARY(4)	Length of fixed fields
4	4	BINARY(4)	Offset to recovery domain array
8	8	BINARY(4)	Number of nodes in recovery domain
12	C	BINARY(4)	Length of recovery domain array entry
16	10	CHAR(10)	Action for recovery domain array
26	1A	CHAR(10)	Cluster resource group exit program name
36	24	CHAR(10)	Cluster resource group exit program library name
46	2E	CHAR(8)	Cluster resource group exit program format name
54	36	CHAR(10)	User profile
64	40	CHAR(256)	Exit program data
320	140	CHAR(20)	Application id
*	*	Array (*) of CHAR(*)	Recovery domain array
These fields repeat, in the order listed, for each node in the recovery domain.		CHAR(8)	Node id
		BINARY(4)	Node role

Field Descriptions

Action for recovery domain array. Indicates which node role in the recovery domain is being changed. The special values used are:

Additional fields. A structure containing optional additional fields.

Additional fields used. A flag to signify whether the additional fields in format RGDC0200 are being used. If the cluster version is less than 3, this field must be set to hexadecimal zero. Possible values are:

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

Application id. This is a string to identify the application that supplied the cluster resource group. The recommended format is 'vendor-id.name' where vendor-id is an identifier for the vendor creating the cluster resource group and name is the application name. For example, QIBM.ExamplePeer, indicates it is supplied by IBM for the ExamplePeer application. It is not recommended to use QIBM for vendor id name unless the cluster resource group is supplied by IBM.

Application takeover IP address. This is the floating IP address that is to be associated with an application. This field must be represented in dotted decimal format and be a null-terminated string. The following special value can be used:

If the value is not *SAME and the Cluster Resource Services configured the takeover IP address, this API will remove the current takeover IP address and add this takeover IP address to the node. If either the add or remove address function fails, the API will fail. The cluster resource group must be Inactive (20) to change this field.

Cluster resource group exit program format name. The contents and format of the cluster resource group exit program information. This field must be set to hexadecimal zeroes if no exit program is specified. If the exit program name is *SAME and was previously *NONE, this field is ignored. The format name supported is:

EXTP0100	Exit program information. This value is allowed for primary-backup model cluster resource group and peer model cluster resource group.
EXTP0200	Exit program information, with additional information in the recovery domain array which contains site name and data port IP addresses on each node.This value is allowed for primary-backup model cluster resource group.
*SAME	Exit program format name is not changed.

Cluster resource group exit program library name. The name of the library where the exit program exists. The special value *CURLIB or *LIBL may not be used for the library name. QTEMP is not a valid library name.

If the cluster resource group exit program name is *NONE or *SAME, the exit program library name is ignored.

Cluster resource group exit program name. The name of exit program that is used to handle action codes that are passed to it. The exit program cannot be in an independent auxiliary storage pool.

If the exit program is changed for an active application cluster resource group, the job currently running which was submitted to handle the Start (2) action code continues running the prior exit program.

The following special value can be used:

Data port IP address. The IP address associated with the recovery domain node. When adding a data port IP address, it must already exist on the specified node if the CRG is active. User is responsible for starting/ending data port IP address. This field must be represented in dotted decimal format and be a null-terminated string.

Data port IP address action. Indicates whether to add or remove the data port IP address associated with the recovery domain node. The possible values are:

Exit program data. 256 bytes of data that is passed to the cluster resource group exit program when it is called. This parameter may contain any scalar data except pointers. For example, it can be used to provide state information. This data will be stored with the specified cluster resource group and copied to all nodes in the recovery domain. Pointers in this area will not resolve correctly on all nodes and should not be placed in the data. See Cluster resource group exit program for information about the cluster resource group exit program. The data specified will replace the existing exit program data stored with the cluster resource group, if the API completes successfully. This field must be set to hexadecimal zeroes if no exit program is specified. If the exit program name is *SAME and was previously *NONE, this field is ignored.

The following special value can be used:

Failover default action. Indicates what clustering should do pertaining to the failover request when a response to the failover message queue was not be received in the failover wait time limit. If the failover message queue is *NONE, this field must be set to 0. If the failover message queue is *SAME and was previously *NONE, this field must be set to -1 or 0.

Failover message queue library name. The name of the library that contains the user queue to receive failover messages. The library name cannot be *CURLIB, QTEMP, or *LIBL.

If the failover message queue name is *NONE or *SAME, the failover message queue library name is ignored. Version 2 or lower cluster resource groups will default to *NONE for the message queue library name when the cluster version is changed to 3.

Failover message queue name. The name of the message queue to receive messages dealing with failover. The queue cannot be in an independent auxiliary storage pool.

The following special values can be used:

Failover wait time. Number of minutes to wait for a reply to the failover message that was enqueued on the failover message queue. If the failover message queue is *NONE, this field must be set to 0. If the failover message queue is *SAME and was previously *NONE, this field must be set to -2 or 0. If a failover message queue is specified, this field cannot be set to 0. Valid values are:

Job name. The name given the batch job that is submitted by the cluster resource group. This job will call the cluster resource group exit program with the action code generated by the API being used. If this field is blank, the job name will be the value of the job description found in the user profile. Valid special values are:

Length of additional fields. The length in bytes of additional fields. In format RGDC0200, this field is ignored if the additional fields used flag is not set to 1. If the additional fields used flag is 1 in format RGDC0200, the value of this field must be less than or equal to 28. In format RGDC0300, the value of this field must be less than or equal to 28. In format RGDC0110 this field must be set to hexadecimal zero. It will be used in a future release if more fields are needed.

Length of entry in the recovery domain. The length of an entry in the recovery domain array. This field is used if each entry may have a different length.

Length of fixed fields. The length of the fixed fields in the format description. For RGDC0400 this value must be 340.

Length of recovery domain array entry. The length of an entry in the recovery domain array. For formats other than RGDC0300, this field must be set to 12. For format RGDC0300, this field can be set to either 12 or zero. If zero, then the length of entry in the recovery domain field is used.

Node id. A unique string of characters that identifies a node that is participating in the recovery domain of the specified cluster resource group. The node specified must be active in the cluster, and it must be unique in the recovery domain of the specified cluster resource group.

Node role. The role the node has in the recovery domain. A role must be defined for each node in the recovery domain. For primary-backup model cluster resource groups a node can have one of three roles: primary, backup, or replicate. Only one node can be designated as the primary. Backup nodes are assigned a backup order. One indicates the first backup, two the second backup, and so on. Replicates are not ordered and cannot become a primary or backup node unless its role is changed from replicate to either a backup or primary.
For peer model cluster resource groups a node can have one of two roles: peer or replicate. Any number of nodes can be designated as the peer or replicate. Peer nodes are not ordered and can be an active access point for the cluster resources. Replicates are not ordered and cannot become an active access point for the cluster resource unless its role is changed from replicate to peer.
The following summarizes the valid values for this field:

0	Primary node. Only one node can have this value.
>=1	Backup node. The backup order is designated by increasing value. The values need not be consecutive. No two backup nodes can have the same value. At the completion of the API, Cluster Resource Services will sequence the backups using consecutive numbers starting with 1.
-1	Replicate node. All replicates have this value.
-2	The node role is not changed.
-4	Peer node. All peers have this value.

Number of data port IP addresses. The number of data port IP addresses to be added to or removed from the recovery domain node. If the current cluster version is 3 and the length of recovery domain array specified includes this field, it must be set to zero. This field must also be set to zero if no change is made to the data port IP addresses.

Number of nodes in the recovery domain. The number of nodes in the recovery domain array. This field is ignored if the Action for recovery domain array field contains *SAME. For primary-backup model cluster resource groups this should equal the number of backup nodes plus the number of replicate nodes plus one (for the primary node). This must be greater than or equal to one and equal the number of nodes in the recovery domain. For peer model cluster resource groups all recovery domain nodes do not need to be specified to change the role. Only specify those nodes that are changing. If roles are changing this must be equal to the number of nodes being changed and cannot exceed the number of nodes currently defined in the recovery domain.

Number of restarts. Number of times a cluster resource group exit program can be called on a same node before failure occurs. Maximum number of restarts is 3. -1 means the maximum number of restarts does not change. If the cluster resource group is currently active, any change does not take affect until failover occurs or the cluster resource group exit program job ends.

Offset to additional fields. The byte offset from the beginning of this parameter to additional fields. In format RGDC0200, this field will be ignored unless the additional fields used field is set to 1. In format RGDC0110, this must be set to hexadecimal zero.

Offset to data port IP address array. The byte offset from the beginning of this parameter to the first data port IP address. If the current cluster version is 3 and the length of recovery domain array specified includes this field, it must be set to zero. This field is ignored if the number of data port IP addresses field is set to zero.

Offset to recovery domain array. The byte offset from the beginning of this table to the array of node information. This field is ignored if the Action for recovery domain array field contains *SAME.

Recovery domain array. Array of recovery domain information. A role must be defined for each node specified. Nodes in the recovery domain must be unique. See node role for more information on the node roles associated with the specific cluster resource group type. For primary-backup model cluster resource groups this array identifies the nodes that compose the recovery domain. The complete recovery domain must be specified. For peer model cluster resource groups, this array identifies the recovery domain nodes that are changing. Only those nodes that are being changed need to be specified.

An example of a primary-backup model cluster resource group: A cluster resource group has four nodes: NodeA, NodeB, NodeC and NodeD. NodeA is the primary. There are two backup nodes: NodeB and NodeD. NodeD is the first backup and NodeB is the second backup. There is one replicate: NodeC.

    Node   Role
    -----  ----
    NodeA   0   <-- primary
    NodeD   1   <-- backup #1
    NodeB   2   <-- backup #2
    NodeC   -1  <-- replicate

The nodes do not have to be arranged in any particular order in the array. They could be in the array as listed below and have the same result.

    Node   Role
    -----  ----
    NodeB   2   <-- backup #2
    NodeA   0   <-- primary
    NodeC   -1  <-- replicate
    NodeD   1   <-- backup #1

Reserved. Must contain hexadecimal zeroes.

Site name. The name of the site associated with the recovery domain node. The site name can be changed from *NONE to a name, or from a name to *NONE. Changing a name to a different name is not allowed. If the current cluster version is 3 and the length of recovery domain array specified includes this field, it must be set to hexadecimal zeroes. Valid special values for this field are:

User profile. The name of the user profile under which the exit program should process. The user profile must exist on all nodes in the recovery domain. This field must be set to hexadecimal zeroes if no exit program is specified. If the exit program name is *SAME and was previously *NONE, this field is ignored.

The following user profiles are not valid:

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

The following special value can be used:

Usage Notes

Results Information User Queue

Asynchronous results are returned to a user queue specified by the Results Information parameter of the API. See Cluster APIs Use of User Queues and Using Results Information for details on how to create the results information user queue, the format of the entries, and how to use the data placed on the queue. The data is sent to the user queue in the form of a message identifier and the substitution data for the message (if any exists). The following identifies the data sent to the user queue (excluding the message text).

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.