Change Cluster Node Entry (QcstChangeClusterNodeEntry) API
Required Parameter Group:
1
Request handle
Output
Char(16)
2
Cluster name
Input
Char(10)
3
Node id
Input
Char(8)
4
Format name
Input
Char(8)
5
Node entry information
Input
Char(*)
6
Length of node entry information
Input
Binary(4)
7
Results information
Input
Char(30)
8
Error code
I/O
Char(*)
Service Program: QCSTCTL
Default Public Authority: *EXCLUDE
Threadsafe: Yes
The Change Cluster Node Entry (QcstChangeClusterNodeEntry) API is used to
change the fields in the cluster node entry. The fields that can be changed are
the cluster interface addresses defined for the node and status of the node.
The node entry which is being changed may or may not have Cluster Resource
Services started.
The following conditions apply to this API:
This API must be called from a program running on a cluster node with a
status of Active.
If the cluster is in a partitioned state, this operation can only be
performed within the partition running the API.
Only one cluster interface address can be changed at a time. If the cluster
is in partitioned state, the change cluster interface address is only allowed
for a node within the same partition.
To change the cluster node status, only a node that has a status of
Partition or Failed can be changed and it can only be changed to Failed
status.
When the status of a node is changed to Failed, the role of nodes in the
recovery domain for each cluster resource group in the partition may be
reordered by assigning the specified node as the last backup. If multiple nodes
have failed and their status needs to be changed, the order in which the nodes
are changed will affect the final order of the recovery domain's backup nodes
in the cluster resource group.
If the failed node was the primary node for a cluster resource group, the
first active backup will be reassigned as the new primary node. When this
occurs for a device cluster resource group, ownership of the hardware will be
moved to the new primary node.
For a device CRG that has
one or more external storage devices, the storage source and target sites will only be changed if
they are the same as the CRG's production and mirror sites before the node status is
changed to Failed.
For peer model cluster resource groups, the membership status is changed to
inactive.
If an exit program is specified for the cluster resource group, it will be
called with an action code of Change Node Status (20).
If a problem is detected and the API does not complete successfully, the API
can be run again once the problem is corrected. Any cluster resource group that
had already had the status of a node changed from Partition to Failed and the
recovery domain order changed will not be affected by running this API
again.
When changing the node status to
failed, the exit program for any cluster resource group which has the changing
node in its recovery domain will be called with an action code of 20 (change node
status). Since this is not a failover, no message is sent
to the failover message queue. The cluster resource group status will remain at its
current status value.
Warning: Using this API to change the status of a node to failed provides a way to
tell Cluster Resource Services that a node has really failed. There are certain
failure conditions that Cluster Resource Services cannot detect as a node
failure. Rather, the problem appears to be a communication problem and the
cluster looks like it has become partitioned. By telling Cluster Resource
Services that a node has failed, it makes recovery from the partition state
simpler for primary-backup
model cluster resource groups since a backup node from the remaining active cluster nodes can then be
assigned as the primary node. Changing the node status to Failed when, in fact,
the node is still active and a true partition has occurred should not be done.
Doing so allows a node in each partition to become the primary node for a
cluster resource group. When two nodes think they are the primary node, data
such as files or data bases could become corrupted if two different nodes are
each making independent changes to copies of their files. In addition, from the cluster resource group
perspective the two partitions
cannot be merged back together when a node in each partition has been assigned
the primary role.
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.
Node id
INPUT; CHAR(8)
A valid simple name that uniquely identifies the node.
Format name
INPUT; CHAR(8)
The content and format of the node entry information. 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.
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 IFCA0100 or IFCR0100, the IPv4 address must be in dotted decimal format and a null-terminated string. When the format name is IFCA0101 or IFCR0101, 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 interface
addresses configured for a System i® platform. See TCP/IP setup for instructions for configuring interface
addresses 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 API
should be used to make the corresponding change to the cluster interface
address. A mismatch will cause cluster errors to occur. An interface address should not be used
as a takeover IP address.
Cluster interface address type. Type of IP address provided in 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.
New cluster interface address. The cluster interface
address which replaces the old cluster interface address. When the format name is IFCC0100, the IPv4 address must be in dotted decimal format and a null-terminated string. When the format name is IFCC0101, either an IPv4 or IPv6 address is supported. When New 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 New 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 interface
addresses configured for a System i® platform. See TCP/IP setup for instructions for configuring interface
addresses 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 API
should be used to make the corresponding change to the cluster interface
address. A mismatch will cause cluster errors to occur. An interface address should not be used
as a takeover IP address.
New cluster interface address type. Type of IP address provided in the New interface address field. The possible values are:
0
New cluster interface address is IPv4.
1
New cluster interface address is IPv6. This value is only allowed if current cluster version is 7 or higher.
New node status. The new status of the node. The valid
value for new node status is:
7
The node has failed.
Old cluster interface address. The cluster interface
address which is being replaced. When the format name is IFCC0100, the IPv4 address must be in dotted decimal format and a null-terminated string. When the format name is IFCC0101, either an IPv4 or IPv6 address is supported. When the Old 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 Old 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.
Old cluster interface address type. Type of IP address provided in the Old interface address field. The possible values are:
0
Old cluster interface address is IPv4.
1
Old cluster interface address is IPv6. This value is only allowed if current cluster version is 7 or higher.
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.
completed.
CPF3CF2 D
Error(s) occurred during running of &1
API.
CPFBB09 D
Cluster node &1 does not exist in cluster
&2.
CPFBB13 D
Cluster interface address &4 already assigned
to cluster node &2.
CPFBB14 D
Cluster interface address &5 cannot be added
for cluster node &2.
CPFBB15 D
Cluster interface address &5 cannot be
removed.
CPFBB16 D
Cluster interface address &6 cannot be
changed to &7.
CPFBB17 D
&1 API cannot be processed in cluster
&2.
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.
CPFBB47 D
Cluster Resource Services ended abnormally.
CPFBB89 D
The current status of cluster node &1 cannot
be changed.
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
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.
CPFBB13 E
Cluster interface address &4 already assigned
to cluster node &2.
CPFBB14 E
Cluster interface address &5 cannot be added
for cluster node &2.
CPFBB15 E
Cluster interface address &5 cannot be
removed.
CPFBB16 E
Cluster interface address &6 cannot be
changed to &7.
CPFBB17 E
&1 API cannot be processed in cluster
&2.
CPFBB32 E
Attributes of user queue &1 in library &2
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.
CPFBB56 E
Length of node entry not valid.
CPFBB5F E
Field value within structure is not valid.
CPFBB70 E
API request &1 not compatible with current
cluster version.
CPFBB89 E
The current status of cluster node &1 cannot
be changed.
IFCA0101