Add Cluster Node Entry (QcstAddClusterNodeEntry) API
Required Parameter Group:
| 1 | Request handle | Output | Char(16) |
| 2 | Cluster name | Input | Char(10) |
| 3 | Node entry | Input | Char(*) |
| 4 | Start indicator | Input | Binary(4) |
| 5 | Format name | Input | Char(8) |
| 6 | Results information | Input | Char(30) |
| 7 | Error code | I/O | Char(*) |
Service Program: QCSTCTL
Default Public Authority: *EXCLUDE
Threadsafe: Yes
The Add Cluster Node Entry (QcstAddClusterNodeEntry) API is used to add a node to the membership list of an existing cluster.
If the "Start Indicator" parameter is set to 0, the node that is being added will have a status of New and Cluster Resource Services will not be started on that node. The Start Cluster Node (QcstStartClusterNode) API can be called from a program running on one of the active nodes in the cluster to start Cluster Resource Services on a node that does not have a status of Active.
If the "Start Indicator" parameter on this API is set to 1, Cluster Resource Services will be started on the node that is being added. If Cluster Resource Services is successfully started, the status for the added node will be set to Active. If the Cluster Resource Services cannot be started, the status of the added node will be set to New.
During the activation of Cluster Resource Services, the allow add to cluster (ALWADDCLU) network attribute is checked to see whether the node being added 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 prerequisites installed on the systems.
The following conditions apply to this API:
- A node cannot add itself to a cluster. It must be added from a node in the cluster that has a status of Active. If Cluster Resource Services has not been started on any of the nodes in the cluster, this API must be called from a program running on the node where the cluster was originally created, and the start indicator must be set to 0.
- The node being added to the cluster must not already be a member of this or any other cluster. A node can be a member of only one cluster.
- If the start indicator is set to 1, the node must be IP reachable (TCP/IP active and the INETD server started).
- The API will fail if any node in the cluster has a status of Partition.
- If the start indicator is set to 1, the potential node version of the node being added 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 by using the List Cluster Information (QcstListClusterInfo) API. The potential node version can also be retrieved by using the Retrieve Cluster Information (QcstRetrieveClusterInfo) API.
- If the start indicator is set to 1 and the cluster message queue is defined for the cluster, the cluster message queue must exist on the node being added.
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
- Cluster Message Queue Authority
- *OBJOPR and *ADD
- Cluster Message Queue Library Authority
- *EXECUTE
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 is being added. It must be a valid simple name.
- Node entry
- INPUT; CHAR(*)
This parameter contains the information associated with the node which is being added to the cluster membership list.
- Start indicator
- INPUT; BINARY(4)
An indicator which specifies whether or not Cluster Resource Services is to be started on the node that is being added.
0 Cluster Resource Services will not be started on the node. 1 Cluster Resource Services will be started on the node.
- Format name
- INPUT; CHAR(8)
The content and format of the information supplied for the node entry. The possible format names are:
ADDN0100 Node entry information ADDN0101 Node entry information with IPv6 support
- 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.
ADDN0100 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(8) | Node id |
| 8 | 8 | BINARY(4) | Offset to first cluster interface entry |
| 12 | C | BINARY(4) | Number of cluster interfaces |
| This field repeats for each number of cluster interfaces. | CHAR(16) | Cluster interface address | |
ADDN0101 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Length of fixed record |
| 4 | 4 | CHAR(8) | Node id |
| 12 | C | BINARY(4) | Offset to first cluster interface entry |
| 16 | 10 | BINARY(4) | Number of cluster interfaces |
| 20 | 14 | BINARY(4) | Length of cluster interface entry |
| These fields repeat, in the order listed, for each cluster interface. | CHAR(1) | Cluster interface address type | |
| CHAR(45) | Cluster interface address | ||
Field Descriptions
Cluster interface address. The cluster interface address is an IP address that is used by Cluster Resource Services to communicate with other nodes in the cluster. When the format name is ADDN0100, the IPv4 address must be in dotted decimal format and a null-terminated string. When the format name is ADDN0101, either an IPv4 or IPv6 address is supported. When the Cluster interface address type field is 0, the address must be an IPv4 address in dotted decimal format and padded on the right with hex zeros. When the Cluster interface address type field is 1, the address must be an IPv6 address and padded on the right with hex zeros.
An IPv6 address must be a unicast address and must not contain an imbedded IPv4 address (compatibility or mapped). An IPv6 address is specified in the form x:x:x:x:x:x:x:x, where x is a hexadecimal number ranging from 0 through X'FFFF'. The "::" may be used once in the IPv6 address to indicate one or more groups of 16 bits of zeros. The "::" may be used to compress leading, imbedded, or trailing zeros in the address. The coded character set identifier (CCSID) of the IP address specified must match the CCSID of the job calling the API.
Note: Cluster Resource Services uses existing IP interfaces configured for a System i® platform. See TCP/IP setup for instructions for configuring IP interfaces on a System i platform. The IP addresses defined as cluster interface addresses can be used by other applications. If an IP address is reconfigured through the TCP/IP configuration functions, the Change Cluster Node Entry (QcstChangeClusterNodeEntry) API should be used to make the corresponding change to the cluster interface address. A mismatch will cause cluster errors to occur.
Cluster interface address type. Type of IP address that follows in the Cluster interface address field. The possible values are:
| 0 | Cluster interface address is IPv4. |
| 1 | Cluster interface address is IPv6. This value is only allowed if current cluster version is 7 or higher. |
Length of fixed record. Length of fixed portion of the record. Must be set to 24.
Length of cluster interface entry. Length of cluster interface entry. Must be set to 46.
Node id. A valid simple name that uniquely identifies the node.
Number of cluster interfaces. The number of IP interfaces associated with a cluster node. It is limited to 1 or 2 entries only.
Offset to first cluster interface entry. The offset from the beginning of the structure to the first cluster interface address entry.
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. |
| 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. |
| CPFBB07 D | Node &1 could not be added to cluster &2. |
| CPFBB11 D | Cluster node &1 already exists in cluster &2. |
| CPFBB12 D | Cluster node &1 in cluster &2 could not be started. |
| CPFBB13 D | Cluster interface address &4 already assigned to cluster node &2. |
| CPFBB17 D | &1 API cannot be processed in cluster &2. |
| CPFBB24 D | Node &1 not participating in &2 API 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. |
| CPFBB96 D | Internal device domain mismatch. |
| CPIBB03 I | Cluster node &1 added to cluster &2. |
| CPIBB05 I | Cluster node &1 started in 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 | Message Text |
|---|---|
| CPF2113 E | Cannot allocate library &1. |
| CPF3C1E E | Required parameter &1 omitted. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C29 E | Object 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. |
| CPFBB04 E | Number of cluster interface addresses not valid. |
| CPFBB07 E | Node &1 could not be added to cluster &2. |
| CPFBB0D E | Cluster interface address &2 specified more than once. |
| CPFBB11 E | Cluster node &1 already exists in cluster &2. |
| CPFBB13 E | Cluster interface address &4 already assigned to cluster node &2. |
| CPFBB17 E | &1 API cannot be processed 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 called from a cluster resource group exit program. |
| CPFBB46 E | Cluster Resource Services internal error. |
| CPFBB55 E | Value &1 specified for start indicator not valid. |
| CPFBB57 E | Offset to cluster interface entry not valid. |
| CPFBBCA E | IP address type not valid. |
| TCP1901 E | Internet address &2 not valid. |
API introduced: V4R4
[ Back to top | Cluster APIs | APIs by category ]