End Cluster Node (QcstEndClusterNode) API

The End Cluster Node (QcstEndClusterNode) API is used to end Cluster Resource Services on one or all the nodes in the membership list of an existing cluster. The status of each node that is ended is set to Inactive. In order to restart Cluster Resource Services on nodes that have been ended, the Start Cluster Node (QcstStartClusterNode) API is used.

When a node in the cluster is ended, it is not removed from the cluster membership list.

If all the nodes in the cluster are being ended, cluster resource group exit programs will not be called with an indication to failover.

The following conditions apply to this API:

• The node being ended must be ACTIVE.
• This API can be called from a program running on the node which is to be ended, or it can be called from a program running on any node in the cluster which has a status of Active.
• The cluster resource group exit program on the node being ended will be called with an action code of End Node (16). The exit program on all other nodes in the recovery domain will be called with an action code of Failover (9).
• If this API is called when the cluster is partitioned, only nodes in the partition running the API will process the request.
• The recovery domain of cluster resource groups on the node that had ended will indicate a node status of Active even though the node is Inactive. For all the other nodes in the recovery domain, the status of the node will be Inactive. If the node being ended is the primary node for an active device cluster resource group, ownership of the hardware associated with the cluster resource group will be moved to a backup node. If the cluster resource group is not active, there are no backup nodes, or all backup nodes are either inactive or in a different cluster partition, the ownership of the hardware is left with the node being ended.

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 that contains the node or nodes being ended.

Node entry

INPUT; CHAR(*)

This parameter contains the node id being ended. It is ignored if the special value *ALL is specified as the node id.

Option

INPUT; BINARY(4)

The method used to end the node:

0	Immediate. The request to end replication for all CRGs on the node will be processed immediately.
1	Controlled. Pending CRG actions will complete before the request to end replication is processed.

Format name

INPUT; CHAR(8)

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

ENDN0100

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.

ENDN0100 Format

Field Descriptions

A valid simple name that uniquely identifies a node. A special value of *ALL can be specified to end all nodes in a cluster. The special value must be left-justified.

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.