Start Cluster Node (QcstStartClusterNode) API

The Start Cluster Node (QcstStartClusterNode) API is used to start Cluster Resource Services on a node in the cluster. If Cluster Resource Services is successfully started on the node specified, the status of the node will be set to Active. Beginning with cluster version 3, a node can start itself and will be able to rejoin the current active cluster, provided it can find an active node in the cluster.

When a node starts itself, instead of assuming itself as the only active member in the cluster, it will first attempt to find a sponsor node from its cluster membership list. Any active member in the cluster can be a sponsor node. If the joiner finds a sponsor node, the start request will be forwarded to the sponsor node. The joiner then will be started by the cluster (the sponsor node), as if the start request was originated from the sponsor node initially. The sponsor, along with other actives members in the cluster, will process the start-joiner request. The joiner eventually rejoins the cluster.

During the activation of Cluster Resource Services, the allow add to cluster (ALWADDCLU) network attribute is checked to see whether the node being started should be part of the cluster and whether to validate the cluster request through the use of X.509 digital certificates. If validation is required, the requesting node and the node being added must have the software required for SSL installed on the systems.

The following conditions apply to this API:

• The node being started must exist in the cluster membership list.
• If all nodes have a status of New, this API must be called from a program running on the node on which the cluster was originally created.
• The node to be started must be IP reachable (TCP/IP is active and the INETD server is started).
• The first time a node is started, this API must be called from a program running on a node that is ACTIVE.
• If all nodes in the cluster are not ACTIVE, this API can be called from a program running on any node that had been previously ACTIVE.
• For cluster version 2 or lower, if any node that had been previously but not currently ACTIVE starts itself, it will be started as a singleton cluster. Starting in cluster version 3, a node which starts itself will be able to rejoin the current active cluster if it can find another active node in the cluster, otherwise it will become a singleton cluster.
• If the cluster is partitioned, this API may be used to start nodes in the partition running the API.
• The potential node version of the node being started must be equal to the current cluster version or up to one level higher than the current cluster version. The potential node version and the current cluster version can be retrieved for all nodes in the cluster by using the List Cluster Information (QcstListClusterInfo) API. The potential node version for the local node can also be retrieved by using the Retrieve Cluster Information(QcstRetrieveClusterInfo) or the List Cluster Information API.

If the node being started is in a device domain, this API requires that i5/OS option 41, HA Switchable Resources, is installed and a valid license key exists on that node.

This API operates in an asynchronous mode. See Behavior of Cluster Resource Services APIs for more information.

Restriction: This API cannot be used in 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 to which the node belongs.

Node entry

INPUT; CHAR(*)

The node id to be started.

Format name

INPUT; CHAR(8)

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

STRN0100

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.

STRN0100 Format

Field Descriptions

Node id. A unique string of characters that identifies the node to be started.

Usage Notes

Results Information User Queue

Asynchronous results are returned to a user queue specified by the Results Information parameter of the API. See Using Results Information and Cluster APIs Use of User Queues 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.