Remove Cluster Node Entry (QcstRemoveClusterNodeEntry) API

Required Parameter Group:

1	Request handle	Output	Char(16)
2	Cluster name	Input	Char(10)
3	Node entry	Input	Char(*)
4	Format name	Input	Char(8)
5	Results information	Input	Char(30)
6	Error code	I/O	Char(*)

  Service Program: QCSTCTL

  Default Public Authority: *EXCLUDE

  Threadsafe: Yes

The Remove Cluster Node Entry (QcstRemoveClusterNodeEntry) API is used to remove a node from a cluster. The node specified will be removed from the cluster membership list and will no longer be considered a member of the cluster. The node will also be removed from the device domain it belongs to. The cluster resource group (CRG) objects on the node being removed are deleted only if the node has a status of Active or if the program that calls this API is running on the node that is being removed.

The following conditions apply to this API:

A node can be removed regardless of its status.
If this API is called from a program running on a node with a status of Active, any node in the cluster can be removed.
If this API is called from a program running on a node where cluster resource services is Inactive, only the node running the API can be removed.
If all of the nodes in the cluster have a status of New, this API can only be called from a program running on the node where the cluster was originally created.
To remove a node that is not Active, this API should be called from a program running on the node being removed and on a node in the cluster that is Active.
There must be more than one node in the membership list.
If the node being removed is Active, the cluster resource group exit program will be passed an action code of Remove Node (12). The exit program on all other nodes in the recovery domain of the cluster resource group will be passed an action code of Failover (9). If the node being removed is the primary node for a device cluster resource group, ownership of the hardware associated with the cluster resource group will be moved to a backup node. If there are no backup nodes or all the backup nodes are either inactive or in a different cluster partition, ownership of the hardware is left with the node being removed. If there are one or more external storage devices, and the current storage source and target sites are the same as the current CRG production and mirror sites, then the sites will be switched if needed for the new primary.
If the node being removed is Inactive, the cluster resource group exit program will be passed an action code of Remove Node (12) on all nodes in the recovery domain. Ownership of hardware associated with a device cluster resource group will not be changed but will remain with the node being removed.
If the node being removed is Inactive, the cluster resource group exit program will be called with an action code of Delete Command (14) on the node being removed if the API is run on the node being removed.
If the node being removed is a member of a device domain and it later will be added back to a cluster, the node most likely has to be IPLed before it can be added to any device domain. One example of this situation would be if a device description for an auxiliary storage pool has been varied on since the last IPL.

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.

User Queue Authority: *OBJOPR and *ADD
User Queue Library Authority: *EXECUTE
User Queue 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 from which the node will be removed.

Node entry

INPUT; CHAR(*)

This parameter contains the information associated with the node which is being removed from the cluster membership list. The size of this parameter is implied by the format name.

Format name

INPUT; CHAR(8)

The content and format of the information supplied in the node entry. The possible format names are:

RMVN0100

Node id information

Results information

INPUT; CHAR(30)

A library qualified user queue name followed by a reserved field.

Library qualified user queue: A user queue, which exists on the node from which the API was called, that receives results information after the function has completed on all active nodes in the cluster. 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, and *CURLIB are not valid for the library name. The attributes of this user queue must be keyed.

Reserved: The last 10 characters of results information are reserved and 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.

RMVN0100 Format

Offset		Type	Field
Dec	Hex	Type	Field
0	0	CHAR(8)	Node id

Field Descriptions

Node id. A unique string of characters that identifies a node.

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	Message Text
CPCBB01 C	Cluster Resource Services API &1 completed.
CPF18BA D	Errors occurred with subsystem.
CPF3CF2 D	Error(s) occurred during running of &1 API.
CPFBB09 D	Cluster node &1 does not exist in cluster &2.
CPFBB24 D	Node &1 not participating in &2 protocol.
CPFBB2D D	Timeout detected while waiting for a response.
CPFBB46 D	Cluster Resource Services internal error.
CPFBB58 D	Cluster node &1 cannot be removed from cluster &2.
CPIBB04 I	Cluster node &1 removed from cluster &2.

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.
CPF3C1E E	Required parameter &1 omitted.
CPF3C21 E	Format name &1 is not valid.
CPF3C39 E	Value for reserved field 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.
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.
CPFBB09 E	Cluster node &1 does not exist in cluster &2.
CPFBB26 E	Cluster Resource Services not active or not responding.
CPFBB32 E	Attributes of user queue &1 in library &1 are not valid.
CPFBB39 E	Current user does not have IOSYSCFG special authority.
CPFBB44 E	&1 API cannot be used within a cluster resource group exit program.
CPFBB46 E	Cluster Resource Services internal error.
CPFBB58 E	Cluster node &1 cannot be removed from cluster &2.

API introduced: V4R4

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