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.
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:
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.
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.
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.
ADDN0101