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. Cluster version 5 only allows configuration objects for auxiliary storage pool devices. Cluster versions 6 and greater allows additional configuration object types that are listed below. All devices being added must be able to be switched from one cluster node to another within the same site. If the cluster resource group does not define any site, then the devices must be able to be switched to any other node in the recovery domain. A cluster resource group with sites defined can only have auxiliary storage pool devices.

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. Cluster Resource Services must be active on the node processing the request.
2. The number of configuration objects being added plus the number of configuration objects already in the cluster resource group cannot exceed 256.
3. The configuration object for the devices being added must exist on all nodes in the recovery domain of the cluster resource group.
4. The resource name specified in the configuration object must be the same on all nodes in the recovery domain.
5. If a data base name is specified in the configuration object, it must be the same on all nodes in the recovery domain.
6. If a new auxiliary storage pool group is added to an active cluster resource group, all members of the group must be specified.
7. 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.
8. IP addresses created by IPv6 stateless address auto-configuration are not valid to be used as a server takeover IP address.
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 (QcstStartClusterResourceGroup) 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.
16. A cluster resource group with sites defined can only have auxiliary storage pool devices.
17. For cluster version 5, only auxiliary storage pool devices are allowed. Cluster versions 6 and greater allow additional configuration object types that are listed below.

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 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) or Device Resiliency (RGDA0101 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.
RGDA0101	This format describes the resilient device and includes IPv6 support.

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)

Device Resiliency (RGDA0101 Format)

Field Descriptions

This array identifies the resilient devices.

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:

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. This value must be set to the length of an array entry.

Length of fixed record. Length of fixed portion of the record. Must be set to 16.

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. 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 RGDA0100, a specified IPv4 address must be in dotted decimal format and a null-terminated string. When the format name is RGDA0101, 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:

0	Server takeover IP address is IPv4.
1	Server takeover IP address is IPv6. Only valid if current cluster version is 7 or higher.

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.

Message ID	Error Message Text
CPF2113 E	Cannot allocate library &1.
CPF2204 E	User profile &1 not found.
CPF24B4 E	Severe error while addressing parameter list.
CPF3C1E E	Required parameter &1 omitted.
CPF3C21 E	Format name &1 is not valid.
CPF3C29 E	Object name &1 is not valid.
CPF3CF1 E	Error code parameter not valid.
CPF3CF2 E	Error(s) occurred during running of &1 API.
CPF9801 E	Object &2 in library &3 not found.
CPF9802 E	Not authorized to object &2 in &3.
CPF9803 E	Cannot allocate object &2 in library &3.
CPF9804 E	Object &2 in library &3 damaged.
CPF980C E	Object &1 in library &2 cannot be in an independent auxiliary storage pool.
CPF9810 E	Library &1 not found.
CPF9820 E	Not authorized to use library &1.
CPF9872 E	Program or service program &1 in library &2 ended. Reason code &3.
CPFBB02 E	Cluster &1 does not exist.
CPFBB0F E	Cluster resource group &1 does not exist in cluster &2.
CPFBB26 E	Cluster Resource Services not active or not responding.
CPFBB2C E	Attributes of exit program &1 in library &2 are not valid.
CPFBB32 E	Attributes of user queue &1 in library &2 not valid.
CPFBB35 E	The user profile name &1 is not valid for this request.
CPFBB38 E	Library name &1 is not allowed for this request.
CPFBB39 E	Current user does not have IOSYSCFG special authority.
CPFBB44 E	&1 API cannot be called from a cluster resource group exit program.
CPFBB5F E	Number of configuration object entries not valid.
CPFBB60 E	Offset to configuration object array is not valid.
CPFBB61 E	Configuration object &1 specified more than once in configuration object array.
CPFBB63 E	The value specified for the field at offset &1 of configuration object array entry &2 is not valid.
CPFBB64 E	Configuration object &1 not valid device type.
CPFBB6B E	Request not valid for type &1 cluster resource group.
CPFBB70 E	API request &1 not compatible with current cluster version.
CPFBB7A E	Primary node &1 in cluster resource group &2 not current owner of specified devices.
CPFBBA5 E	Server takeover IP address &2 specified more than once in the configuration object array.
CPFBBCA E	IP address type not valid.
TCP1901 E	Internet address &2 not valid.

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