Start Cluster Resource Group (QcstStartClusterResourceGroup) API

The Start Cluster Resource Group (QcstStartClusterResourceGroup) API will enable resiliency for the specified cluster resource group. The Start Cluster Resource Group API can be used to change cluster resource group from a status of Indoubt (30) or Inactive (20) to Active (10).

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

1. Set the cluster resource group status to Start Cluster Resource Group Pending (560).
2. For primary-backup model cluster resource groups, if the current recovery domain 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. If the inactive backup nodes are already ordered after active backup nodes or if there are no inactive backup nodes, Start will not change the recovery domain.
3. Call the exit program on all active nodes in the recovery domain with an action code of Start (2), if an exit program is specified for the cluster resource group.
4. Set the cluster resource group status to Active (10) if the exit program is successful on all active nodes in the recovery domain.
5. Perform the following on all nodes if the exit program is unsuccessful on any active node in the recovery domain:
   • Set the status of the cluster resource group to Indoubt (30).

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

1. Verify the takeover IP address has been configured on all nodes in the recovery domain except replicates.
2. Start the takeover IP address on the primary node.
3. If the exit program returns a failure, on the primary node:
   • Cancel the exit program job with an option of *IMMED.
   • End the takeover IP address on the primary node.

This API will do the following for peer cluster resource groups:

1. All nodes that are designated with a peer role will be an active access point upon successful completion of this API.

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

1. Cluster Resource Services active on the node running the API.
2. For primary-backup model cluster resource groups, the membership status of the node currently assigned the role of primary must be active.
3. For peer model cluster resource groups:
   • At least one node must be designated as peer or the cluster resource group cannot be started.
   • At least one peer node must have a membership status of Active.
4. A cluster resource group status of Inactive (20) or Indoubt(30).

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

1. The cluster resource group must have at least one configuration object entry.
2. The configuration objects specified for the cluster resource group must exist on all active nodes in the recovery domain and the resource name specified in a configuration object must be the same on all active nodes in the recovery domain.
3. If a data base name has been specified for a configuration object, it must be the same on all active nodes in the recovery domain.
4. If a server takeover IP address is specified, it must exist on all nodes in the recovery domain.
5. The primary node must be the current owner of all IOPs or high-speed link I/O bridges for the devices in the cluster resource group.
6. Hardware configuration must be complete so that the physical hardware has been associated with the configuration object. In particular for auxiliary storage pools, the disk units must have been assigned.
7. The IOP or high-speed link I/O bridge controlling the devices specified in the cluster resource group must be accessible by all active nodes in the cluster resource group's recovery domain or by all nodes within the same site (for cross-site mirroring).
8. Starting the cluster resource group will not vary on the configuration objects or start the server takeover IP address.
9. All members of an auxiliary storage pool group must be configured in the cluster resource group.
10. A value of 2 for the device's 'configuration object online' attribute can be specified only for a secondary auxiliary storage pool.
11. If data port IP addresses are specified, it must exist on the node in the recovery domain.

This API requires the following for application cluster resource groups:

1. For an application cluster resource group, the exit program is not expected to complete on the primary node. The status of the cluster resource group will be set to Active (10) when the exit program job has been started on the primary and the exit program has completed successfully on all other nodes in the recovery domain.

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

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

Authorities and Locks

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

Cluster Resource Group Authority

*CHANGE

Cluster Resource Group Library Authority

*EXECUTE

Cluster Resource Group Lock

*EXCL

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

*EXECUTE

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

*EXECUTE

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

*USE

Request Information User Queue Authority

*OBJOPR, *ADD

Request Information User Queue Library Authority

*EXECUTE

Request Information User Queue Lock

*EXCLRD

Configuration Object Authority

*USE and *OBJMGT

Configuration Object Lock

*EXCLRD

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 containing the cluster resource group.

Cluster resource group name

INPUT; CHAR(10)

The name of the cluster resource group which will be started.

Exit program data

INPUT; CHAR(256)

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 before the exit program is called. If blanks are specified, then the exit program data stored with the cluster resource group will be cleared. This parameter must be set to *SAME if no exit program is specified. The following special value can be used:

*SAME

The exit program data stored with the cluster resource group specified will be passed to the exit program. 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.

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.