Create Cluster (QcstCreateCluster) API

The Create Cluster (QcstCreateCluster) API is used to create a new cluster of one or more nodes. Each node specified on the "Cluster membership information" parameter will be placed in the cluster membership list.

If the "Start indicator" parameter is set to 0, each node that is being added will have a status of New and Cluster Resource Services will not be started on any node. In order to start Cluster Resource Services, the Start Cluster Node (QcstStartClusterNode) API must be called from a program running on the node that ran the Create Cluster API. The Start Cluster Node API may be used to start nodes in the cluster membership list.

If the "Start indicator" parameter is set to 1, the cluster can contain only one node. Cluster Resource Services will be started on the node being defined. If Cluster Resource Services is successfully started, the status for the node will be set to Active. If Cluster Resource Services is not successfully started, the status of the node remains New. If a list of nodes is specified, the start indicator is ignored.

If the NODE0100 format is chosen, the current cluster version will be set equal to the requesting node's potential node version.

After Cluster Resource Services has been started on the original node, additional nodes can only be started by calling the Start Cluster Node API on the original node. If Cluster Resource Services is active on more than one node, additional nodes may be started by calling the Start Cluster Node API on any node that has a status of Active.

Once the cluster has been created, the Add Cluster Node Entry (QcstAddClusterNodeEntry) API can be used to add additional nodes to the cluster membership list. The Add Cluster Node Entry API can be called from a program running on any node in the cluster that has a status of Active or from the node on which the cluster was originally created.

Prior to cluster version 6, a failover message queue could be defined for a CRG. If the failover message queue was defined, a message was enqueued during the failover of the CRG, allowing the user to cancel or continue the failover. If a cluster node ended or failed and there were multiple CRGs with that node as a primary recovery domain node, the user would have needed to respond to a message for each CRG.

In cluster version 6 and above, the user has the option of receiving and responding to one message for all CRGs which are failing over to the same node when the primary node for the CRGs ends or fails. A cluster message queue, failover wait time, and failover default action may be specified on this API or it can also be specified on the Change Cluster Resource Services (QcstChgClusterResourceServices) API. If failure occurs on a node, that node is the primary recovery domain node for any active CRGs, and the cluster message queue is defined, then one message will be enqueued on the cluster message queue. This gives the user the option of continuing all CRG failovers to the new primary, or cancelling all CRG failovers. No message will be enqueued if the primary node is removed from the cluster. If a CRG is failing over individually, one message will be sent which will control the failover of that CRG. The message will be placed on the message queue on the new primary node before the CRGs call their exit programs. If the failovers are cancelled, the primary node of the CRGs will not be changed, and the cluster resource groups will become Inactive. The exit programs will be called with an action code of Failover Cancelled.

If the user wants to specify failover actions for a specific CRG, the failover message queue fields on the Create Cluster Resource Group API or Change Cluster Resource Group API should be used instead of the cluster message queue fields on the Create Cluster API or the Change Cluster Resource Services API. If the failover fields are set at a cluster level, they will override any CRG failover parameters. If the cluster message queue is set to *NONE, then the failover of each individual CRG will be controlled via the CRG failover parameters.

The following conditions apply to this API:

• A node can be a member of only one cluster.
• At least one node must be specified in the cluster membership list. A cluster cannot be created with an empty membership list.
• If a cluster message queue is specified, it must exist on each node in the cluster. This will be verified on the requesting node as part of the Create Cluster API and will be verified on each additional cluster node when that node is started.

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 which is being created. This must be a valid simple name.

Cluster membership information

INPUT; CHAR(*)

This parameter contains information about the cluster and the list of nodes which will be placed in the cluster membership list.

Number of cluster membership entries

INPUT; BINARY(4)

The number of nodes in the cluster membership array. Must be greater than or equal to 1 and less than or equal to 128.

Start indicator

INPUT; BINARY(4)

An indicator which specifies whether or not Cluster Resource Services is to be started on the node being defined.

0	Cluster Resource Services will not be started on any node.
1	Cluster Resource Services will be started on the node.

Format name

INPUT; CHAR(8)

The content and format of the information supplied in the cluster membership information parameter. The possible format names are:

NODE0100	Cluster membership information
NODE0200	Cluster membership information plus additional information
NODE0201	Cluster membership information plus additional 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.

NODE0100 Format

NODE0200 Format

NODE0201 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. When the format name is NODE0100 or NODE0200, the IPv4 address must be in dotted decimal format and a null-terminated string. When the format name is NODE0201, 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:

Cluster message queue library name. The name of the library that contains the user queue to receive cluster messages. The library name cannot be *CURLIB, QTEMP, *LIBL, *USRLIBL, *ALL, or *ALLUSR. This field must be set to hexadecimal zeroes if the cluster message queue name is *NONE.

Cluster message queue name. The name of the message queue to receive messages relating to cluster or node level events. For cluster version 6, messages relating to failover will be sent to this queue. For node level failovers, one message will be sent which will control the failover of all CRGs with the same new primary node. If a CRG is failing over individually, one message will be sent which will control the failover of that CRG. The message will be sent on the new primary node. If this field is set, the individual CRG failover message queue fields will not be used. If this field is set, the specified message queue must exist on each node in the cluster. This will be verified on the requesting node as part of the Create Cluster API and will be verified on each additional cluster node when that node is started. The queue cannot be in an independent auxiliary storage pool. If the offset to additional fields and length of additional fields are 0, the cluster message queue defaults to *NONE. Valid special values for this field are:

Failover default action. Indicates what clustering should do when a response to the failover message on the cluster message queue is not received in the failover wait time limit. If the cluster message queue is *NONE, this field must be set to 0. Valid values are:

Failover wait time. Number of minutes to wait for a reply to the failover message that was enqueued on the cluster message queue. If the cluster message queue is *NONE, this field must be set to 0. This field cannot be set to 0 if a cluster message queue is specified. Valid values are:

Length of additional fields. The length of the additional fields. If the cluster version is less than 6, the value of this field must be 0. If the cluster version is 6, the value of this field must be equal to 0 or 28.

Length of cluster interface entry. Length of cluster interface entry. This must be set to 46.

Length of fixed node record. Length of fixed portion of the node entry. This must be set to 28.

Length of fixed record. Length of fixed portion of the record. This must be set to 40.

Length of node entry. The length of the node entry.

Node id. A simple valid name that uniquely identifies a node.

Number of cluster interfaces. The number of IP interfaces that are to be used by Cluster Resource Services. It is limited to 1 or 2 entries only.

Offset to additional fields. The offset from the beginning of the structure to the additional fields. If the cluster version is less than 6, the value of this field must be 0.

Offset to first cluster interface entry. The offset from the beginning of the structure to the first cluster interface entry.

Offset to first node entry. The offset from the beginning of the structure to the first node entry.

Target cluster version. The version the cluster will use in conversation with the other nodes in the cluster. This also determines the potential node version of the nodes allowed to join the cluster. The following possible values are based on the node originating the request.

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.

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.
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.
CPF9803 E	Cannot allocate object &2 in library &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.
CPFBB01 E	Cluster already exists.
CPFBB03 E	Number of cluster node entries not valid.
CPFBB04 E	Number of cluster interface addresses not valid.
CPFBB0C E	Cluster node ID &1 specified more than once.
CPFBB0D E	Cluster interface address &2 specified more than once.
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.
CPFBB55 E	Value &1 specified for start indicator not valid.
CPFBB56 E	Length of node entry not valid.
CPFBB57 E	Offset to cluster interface entry not valid.
CPFBB5F E	Field value within structure is not valid.
CPFBB70 E	Request &1 not compatible with current cluster version.
CPFBBA2 E	Value &1 specified for failover wait time is not valid.
CPFBBA3 E	Value &1 specified for failover default action is not valid.
CPFBBA4 E	Field value within additional fields structure is not valid.
CPFBBCA E	IP address type not valid.
TCP1901 E	Internet address &2 not valid.

[ Back to top | Cluster APIs | APIs by category ]