| 1 | Request handle | Output | Char(16) |
| 2 | Cluster name | Input | Char(10) |
| 3 | Cluster membership information | Input | Char(*) |
| 4 | Number of cluster membership entries | Input | Binary(4) |
| 5 | Start indicator | Input | Binary(4) |
| 6 | Format name | Input | Char(8) |
| 7 | Results information | Input | Char(30) |
| 8 | Error code | I/O | Char(*) |
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.
The following conditions apply to this API:
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.
The program that calls this API must be running under a user profile with *IOSYSCFG special authority.
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.
The name of the cluster which is being created. This must be a valid simple name.
This parameter contains information about the cluster and the list of nodes which will be placed in the cluster membership list.
The number of nodes in the cluster membership array. Must be greater than or equal to 1 and less than or equal to 128.
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. |
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 |
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.
The structure in which to return error information. For the format of the structure, see Error Code parameter.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| BINARY(4) | Length of node entry | ||
| CHAR(8) | Node id | ||
| BINARY(4) | Offset to first cluster interface entry | ||
| BINARY(4) | Number of cluster interfaces | ||
| This field is repeated for each cluster interface. | CHAR(16) | Cluster interface address | |
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Target cluster version |
| 4 | 4 | BINARY(4) | Offset to first node entry |
| 8 | 8 | BINARY(4) | Offset to additional fields |
| 12 | C | BINARY(4) | Length of additional fields |
| Note: These fields are repeated for each node entry. | |||
| BINARY(4) | Length of node entry | ||
| CHAR(8) | Node id | ||
| BINARY(4) | Offset to first cluster interface entry | ||
| BINARY(4) | Number of cluster interfaces | ||
| This field is repeated for each cluster interface. | CHAR(16) | Cluster interface address | |
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 IP interfaces configured for an iSeries. See TCP/IP for instructions for configuring IP interfaces 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 (QcstChangeClusterNodeEntry) API should be used to make the corresponding change to the cluster interface address. A mismatch will cause cluster errors to occur.
Length of additional fields. The length of the additional fields. This must be set to hexadecimal zeros. It will be used in a future release.
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. This must be set to hexadecimal zeros. It will be used in a future release.
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.
| 0 | The cluster will communicate at the requesting node's potential node version. In addition, nodes with a potential node version less than the requesting node will not be allowed to join the cluster. |
| -1 | The cluster will communicate at the requesting node's potential node version minus 1. This allows nodes at a previous potential node version to join the cluster. However, no new cluster function on the node which has a newer version of the system software will be allowed to be used. |
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. |
| CPF3CF2 D | Error(s) occurred during running of &1 API. |
| CPFBB05 D | Cluster node &1 cannot be started. |
| CPFBB10 D | Specified cluster interface not defined on this system. |
| CPFBB12 D | Cluster node &1 in cluster &2 could not be started. |
| CPFBB2D D | Timeout detected while waiting for a response. |
| CPFBB46 D | Cluster Resource Services internal error. |
| CPIBB01 I | Cluster &1 created. |
| CPIBB03 I | Cluster node &1 added to cluster &2. |
| CPIBB05 I | Cluster node &1 started in cluster &2. |
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. |
| 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 &1 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. |
| TCP1901 E | Internet address &1 not valid. |
| Top | Cluster APIs | APIs by category |