Change Cluster Node Entry (QcstChangeClusterNodeEntry) API

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 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
IFCR0100	Remove cluster node interface
IFCC0100	Replace cluster node interface
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

IFCR0100 Format

IFCC0100 Format

STSC0100 Format

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. The address is in dotted decimal format and is a null-terminated string.

Note: Cluster Resource Services uses existing interface addresses configured for an iSeries. See TCP/IP for instructions for configuring interface addresses on the iSeries. 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. The cluster interface address which replaces the old cluster interface address. The address is in dotted decimal format and is a null-terminated string.

New node status. The new status of the node. The valid value for new node status is:

Old cluster interface address. The cluster interface address which is being replaced. The address is in dotted decimal format and is a null-terminated string.

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).

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.