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.
This API operates in an asynchronous mode. See Behavior of Cluster Resource Services APIs for more information.
For primary-backup model cluster resource groups:
- 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:
IFCA0100 Add cluster node interface IFCA0101 Add cluster node interface with IPv6 support IFCR0100 Remove cluster node interface IFCR0101 Remove cluster node interface with IPv6 support IFCC0100 Replace cluster node interface IFCC0101 Replace cluster node interface with IPv6 support STSC0100 Change cluster node status
- Node entry information
- INPUT; CHAR(*)
Detailed information about the node entry.
- Length of node entry information
- INPUT; BINARY(4)
The length of the node entry 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.
IFCA0100 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(16) | Cluster interface address |
IFCA0101 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(1) | Cluster interface address type |
| 1 | 1 | CHAR(45) | Cluster interface address |
IFCR0100 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(16) | Cluster interface address |
IFCR0101 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(1) | Cluster interface address type |
| 1 | 1 | CHAR(45) | Cluster interface address |
IFCC0100 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(16) | Old cluster interface address |
| 16 | 10 | CHAR(16) | New cluster interface address |
IFCC0101 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(1) | Old cluster interface address type |
| 1 | 1 | CHAR(45) | Old cluster interface address |
| 46 | 2E | CHAR(1) | New cluster interface address type |
| 47 | 2F | CHAR(45) | New cluster interface address |
STSC0100 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | New node status |
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 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. |
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. 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. |
| 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 ]