Remove Cluster Resource Group Device Entry (QcstRmvClusterResourceGroupDev) API
Required Parameter Group:
| 1 | Request handle | Output | Char(16) |
| 2 | Cluster name | Input | Char(10) |
| 3 | Cluster resource group name | Input | Char(10) |
| 4 | Configuration object entry information | Input | Char(*) |
| 5 | Format name | Input | Char(8) |
| 6 | Results information | Input | Char(30) |
| 7 | Error code | I/O | Char(*) |
Service Program: QCSTCRG1
Default Public Authority: *EXCLUDE
Threadsafe: Yes
The Remove Cluster Resource Group Device Entry (QcstRmvClusterResourceGroupDev) API removes one or more configuration objects from a device cluster resource group. All configuration object entries can be removed but at least one configuration object entry must exist before the Start Cluster Resource Group (QcstStartClusterResourceGroup) API can be called.
Ownership of the hardware associated with the configuration object being removed is not affected. The hardware is still owned by whatever node owned it before this API was called.
If an exit program is specified for the cluster resource group, the cluster resource group exit program is called with an action code of Remove Device Entry (18) on all active nodes in the recovery domain. The cluster resource group status is set to Remove Device Entry Pending (600). 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).
Removing a device from a cluster resource group does not vary the device off.
This API requires:
- Cluster Resource Services must be active on the node processing the request.
- If an exit program is specified, the exit program must exist on all nodes in the recovery domain.
- At least one node in the recovery domain must be active.
- If the cluster resource group is active, all members of an auxiliary storage pool group must be removed at the same time.
- If the cluster resource group is active, the last device entry cannot be removed. The cluster resource group must be ended first.
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
- *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 (RGDR0100 Format).
- Format name
- INPUT; CHAR(8)
The content and format of the configuration object information. The possible format names are:
RGDR0100 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 (RGDR0100 Format)
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Offset to configuration object array |
| 4 | 4 | BINARY(4) | Number of entries in configuration object array |
| 8 | 8 | BINARY(4) | Length of configuration object array entry |
| 12 | C | BINARY(4) | Offset to additional fields |
| 16 | 10 | BINARY(4) | Length of additional fields |
| * | * | Array (*) of CHAR(16) | Configuration object array |
| These fields repeat, in the order listed, for each device. | CHAR(10) | Configuration object name | |
| CHAR(2) | Reserved | ||
| BINARY(4) | Configuration object type | ||
Field Descriptions
Configuration object array. This array identifies the resilient devices.Configuration object name. The name of the configuration object which is to be removed from the cluster resource group.
Configuration object type. This specifies the type of configuration object specified with configuration object name. Possible values are:
| 1 | Device description |
| 2 | Controller description |
| 3 | Line description |
| 5 | Network server description |
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 RGDR0100 format.
Length of configuration object array entry. This specifies the length of an entry in the configuration object array.
Number of entries in configuration object array. The number of entries in the configuration object array. This must be greater than zero and less than or equal to 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 RGDR0100 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.
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).
| Message ID | Error Message Text |
|---|---|
| CPCBB01 C | Cluster Resource Services API &1 completed. |
| CPF18BA D | Error occurred with subsystem. |
| CPF2113 E | Cannot allocate library &1. |
| CPF2204 D | User profile &1 not found. |
| CPF3CF2 D | Error(s) occurred during running of &1 API. |
| CPF9801 D | Object &2 in library &3 not found. |
| CPF9802 D | Not authorized to object &2 in &3. |
| CPF9803 D | Cannot allocate object &2 in library &3. |
| CPF9804 D | Object &2 in library &3 damaged. |
| CPF9810 D | Library &1 not found. |
| CPFBB0F D | Cluster resource group &1 does not exist in cluster &2. |
| CPFBB17 D | &1 API cannot be processed in cluster &2. |
| CPFBB18 D | Request &1 is not allowed for cluster resource group &2. |
| CPFBB2C D | Attributes of exit program &1 in library &2 are not valid. |
| CPFBB2D D | Timeout detected while waiting for a response. |
| CPFBB2E D | Job submission failed for cluster resource group &1 in cluster &2. |
| CPFBB32 D | Attributes of user queue &1 in library &2 are not valid. |
| CPFBB35 D | The user profile name &1 is not valid for this request. |
| CPFBB38 D | Library name &1 is not allowed for this request. |
| CPFBB39 D | The current user does not have IOSYSCFG special authority. |
| CPFBB46 D | Cluster Resource Services internal error. |
| CPFBB5B D | Resource name &1 incorrect for configuration object &2 on node &3. |
| CPFBB7B D | Device type not correct for configuration object &1 on node &2. |
| CPFBB98 D | Hardware resource &1 not switchable. |
| CPFBB9C D | Not all auxiliary storage pool group members added or removed together. |
| CPIBB10 D | Cluster Resource Group exit program &1 in library &2 on node &3 failed. |
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. |
| CPFBB43 E | Invalid format name &1 for cluster resource group type &2. |
| 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. |
| CPFBB6B E | Request not valid for type &1 cluster resource group. |
| CPFBB6D E | Configuration object &1 not in cluster resource group &2. |
| CPFBB6F E | Last device entry cannot be removed from cluster resource group &1. |
| CPFBB70 E | API request &1 not compatible with current cluster version. |
API introduced: V5R1
[ Back to top | Cluster APIs | APIs by category ]