| 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(*) |
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:
If the node being started is in a device domain, this API requires that IBM® i option 41, HA Switchable Resources, is installed and a valid license key exists on that node.
If the node being started has had cluster monitors added to it, the CIM server for each monitor will be contacted. The CIM server then knows that it should be monitoring for system or logical partition failures and notifying the cluster monitor node. The cluster node will be started even if some error occurs while trying to contact the CIM server. If contact of the CIM server fails, one can use the QcstChgClusterMonitor API with values of *SAME for the new CIM server host name, user id, and password, to cause Cluster Resource Services to attempt the contact again.
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.
The program that calls this API must be running under a user profile with *IOSYSCFG special authority.
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.
The name of the cluster to which the node belongs.
The node id to be started.
The content and format of the information supplied in the node entry array. The possible format names are:
| STRN0100 | Node id information |
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.
The structure in which to return error information. For the format of the structure, see Error code parameter.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(8) | Node id |
Node id. A unique string of characters that identifies the
node to be started.
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).
| 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 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 can not be in an independent auxiliary storage pool. |
| CPF9810 E | Library &1 not found. |
| CPF9820 E | Not authorized to use library &1. |
| CPFBB01 D | Cluster already exists. |
| CPFBB05 D | Cluster node &1 cannot be started. |
| CPFBB09 D | Cluster node &1 does not exist in cluster &2. |
| CPFBB10 D | Specified cluster interface not defined on this system. |
| CPFBB12 D | Cluster node &1 in cluster &2 could not be started. |
| CPFBB19 D | Cluster node &1 in cluster &2 already started. |
| 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. |
| CPFBB54 D | Node &1 not be added to the cluster &2. |
| CPFBB71 D | Potential node version &1 of node &2 not compatible. |
| CPFBB79 D | Internal cluster resource services mismatch. |
| CPFBB93 D | Base operating system option 41 not installed or license key not valid. |
| CPFBB96 D | Internal device domain mismatch. |
| CPIBB05 I | Cluster node &1 started in cluster &2. |
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. |
| CPFBB19 E | Cluster node &1 in cluster &2 already started. |
| 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. |
| CPFBB98 E | Cluster node &1 cannot be started by cluster node &2. |
[ Back to top | Cluster APIs | APIs by category ]