Add Cluster Resource Group Device Entry (QcstAddClusterResourceGroupDev) API

The Add Cluster Resource Group Device Entry (QcstAddClusterResourceGroupDev) API adds one or more configuration objects representing hardware devices to a device cluster resource group. All devices being added must be able to be switched from one cluster node to another, unless for cross-site mirroring where a site only has one node.

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 at once. Additional members can be added later. If the auxiliary storage pool group has previously been created and clustering can determine which members are in the group, a warning message is sent if some members of the group were not added.

If an exit program is specified for the cluster resource group, the cluster resource group exit program is called with an action code of Add Device Entry (17) on all active nodes in the recovery domain. The cluster resource group status is set to Add Device Entry Pending (590). 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).

This API requires:

1. Only auxiliary storage pool devices are supported.
2. Cluster Resource Services must be active on the node processing the request.
3. The number of configuration objects being added plus the number of configuration objects already in the cluster resource group cannot exceed 256.
4. The configuration object for the devices being added must exist on all nodes in the recovery domain of the cluster resource group.
5. The resource name specified in the configuration object must be the same on all nodes in the recovery domain.
6. If a data base name is specified in the configuration object, it must be the same on all nodes in the recovery domain.
7. If a new auxiliary storage pool group is added to an active cluster resource group, all members of the group must be specified.
8. If a server takeover IP address is specified, it must exist on all nodes in the recovery domain if the cluster resource group is active. The server takeover IP address must be unique. It can only be associated with a primary auxiliary storage pool.
9. The configuration objects being added cannot be specified in another cluster resource group.
10. 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.
11. 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.
12. 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.
13. If the primary node does not currently own the specified devices, the API fails with an error message.
14. If an exit program is specified, the exit program must exist on all nodes in the recovery domain.
15. All nodes in the recovery domain must be active.

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

Configuration object entry information

INPUT; CHAR(*)

Detailed information about the configuration objects to be added to the cluster resource group. For more information, see Device Resiliency (RGDA0100 Format).

Format name

INPUT; CHAR(8)

The content and format of the device information. The possible format names are:

RGDA0100

This format describes the resilient device.

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.

Device Resiliency (RGDA0100 Format)

Field Descriptions

This array identifies the resilient devices.

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:

Length of additional fields. The length in bytes of additional fields. This must be set to hexadecimal zero. It will be used in a future release if more fields are needed in the RGDA0100 format.

Length of configuration object array entry. This specifies the length of an entry in the configuration object array. Is values must be set to the length of an array entry.

Number of entries in configuration object array. The number of entries in the configuration object array. This must be greater than zero and the number of these entries plus the number of entries already in the cluster resource group cannot be greater than 256.

Offset to additional fields. The byte offset from the beginning of this parameter to additional fields. This must be set to hexadecimal zero. It will be used in a future release if more fields are needed in the RGDA0100 format.

Offset to configuration object array. The byte offset from the beginning of this parameter to the configuration object array field.

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:

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.