Add Cluster Monitor (QcstAddClusterMonitor) APIAdd Cluster Monitor (QcstAddClusterMonitor) API| 1 | Request handle | Output | Char(16) |
| 2 | Cluster name | Input | Char(10) |
| 3 | Monitor information | Input | Char(*) |
| 4 | Format name | Input | Char(8) |
| 5 | Results information | Input | Char(30) |
| 6 | Error code | I/O | Char(*) |
The Add Cluster Monitor (QcstAddClusterMonitor) API is used to add a cluster node monitor to the cluster. The monitor runs on some node within the cluster and waits for messages from a server. The server sends a message when it detects a failure for a system it is monitoring.
In the absence of a cluster monitor, a failure such as a system crash due to a processor or memory failure is not detected by Cluster Resource Services as a node failure. Rather, Cluster Resource Services detects a failure in heartbeat communications and cannot determine if it is due to a node failure or a communications path failure. In this case, the cluster enters a partition state and failover does not occur. Refer to Managing failover outage events for information on failures that cause cluster partitions.
The following server types are supported:
| CIM server in a VIOS management partition | Some IBM i systems such as a blade server or an entry level system may not be managed by an HMC but instead make use of the Integrated Virtualization Manager (IVM) in a Virtual I/O Server (VIOS) management partition. Since the VIOS is software running on the same IBM i system as a cluster node, some failures such as a hardware failure which takes down the whole IBM i system cannot be detected with a cluster monitor. |
| CIM server on HMC | For IBM i systems that can be managed with a Hardware Management Console (HMC), the CIM server runs on the HMC. The HMC affords the most complete node failure detection since it is not part of the IBM i system and thus can continue to operate when a system has completely failed. Note: Support for the CIM server was removed in version 860 (V8R8.6.0) of the HMC. |
| Representational State Transfer (REST) server on HMC | For IBM i systems that can be managed with a Hardware Management Console (HMC), a REST server runs on the HMC. The HMC affords the most complete node failure detection since it is not part of the IBM i system and thus can continue to operate when a system has completely failed. Note: Support for the REST server was added in version 850 (V8R8.5.0) of the HMC. |
With the use of an HMC or VIOS and a cluster monitor, cluster partitions can be prevented for more situations. For example, suppose there are two cluster nodes: Node A and Node B. Each node is on a separate system. An HMC is attached to the system which contains Node A and the HMC is on a network which can communicate to Node B. A cluster node monitor is configured to run on Node B. Should Node A crash, the HMC sends a message to Node B and thus Cluster Resource Services has additional information to know that this was really a node failure and not a heartbeat communication failure.
When a cluster node is started and that node has had monitors added to it, Cluster Resource Services will attempt to contact the server defined in each monitor. The node will be started even if some error occurs contacting the server.
When an active cluster node is removed from the cluster and that node has had monitors added to it, Cluster Resource Services will attempt to contact the server defined in each monitor. The node will be removed even if some error occurs contacting the server.
The user id and password will be validated by connecting to the server host.
However, no validation is performed to determine if the server host is managing a system that has cluster nodes on it. For example, suppose a monitor was added on Node B to use an HMC, named HMC5. Cluster Resource Services will connect to HMC5 from Node B and validate the communication path is operational from Node B and that the user id and password are valid. But Cluster Resource Services does not attempt to validate that HMC5 is connected to and managing a system which has cluster nodes on it.
The following conditions apply to this API:
To add cluster monitors for Representational State Transfer (REST) servers operating system option 3 (Extended Base Directory Support) must be installed on the node to which the monitor is being added.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 to which the monitor is being added. It must be a valid simple name.
This parameter contains the information about the monitor and the server.
The content and format of the information supplied for the monitor information. The possible format names are:
| ADDM0100 | CIM cluster monitor information |
| ADDM0200 |
Representational State Transfer (REST) cluster monitor 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 | ||
| 0 | 0 | BINARY(4) | Length of data provided |
| 4 | 4 | CHAR(8) | Node id where monitor is to run |
| 12 | C | BINARY(4) | CCSID of CIM server host name, user id and password |
| 16 | 10 | CHAR(256) | CIM server host name |
| 272 | 110 | CHAR(33) | CIM server user id |
| 305 | 131 | CHAR(33) | CIM server password |
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Length of data provided |
| 4 | 4 | CHAR(8) | Node id where monitor is to run |
| 12 | C | BINARY(4) | CCSID of Representational State Transfer (REST) server host name, user id and password |
| 16 | 10 | CHAR(256) | Representational State Transfer (REST) server host name |
| 272 | 110 | CHAR(33) | Representational State Transfer (REST) server user id |
| 305 | 131 | CHAR(33) | Representational State Transfer (REST) server password |
CCSID of CIM server host name, user id and password. The Coded Character Set Identifier for the CIM server host name, user id and password. When authenticating with the CIM server, the user id and password are converted to CCSID 819 which corresponds to the Latin 1 characters in the ISO-8859-1 character encoding standard. Refer to CIM server host documentation on the characters that can be used for a user id and password.
| 0 | The CIM server host name, user id and password text is assumed in the CCSID of the job running this API. |
| CCSID | Specify a valid CCSID that your CIM server host name, user id and password are in. Valid values are between 1 and 65534. This API will validate the CCSID. |
CCSID of Representational State Transfer (REST) server host name, user id and password. The Coded Character Set Identifier for the REST server host name, user id and password. When authenticating with the REST server, the user id and password are converted to CCSID 1208 which corresponds to the UTF-8 standard. Refer to REST server host documentation on the characters that can be used for a user id and password.
| 0 | The REST server host name, user id and password text is assumed in the CCSID of the job running this API. |
| CCSID | Specify a valid CCSID that your Representational State Transfer (REST) server host name, user id and password are in. Valid values are between 1 and 65534. This API will validate the CCSID. |
CIM server host name. The name of the CIM server host (HMC or VIOS partition) that will send information about the system and logical partitions it is managing. This is a null terminated character string. The name must follow the rules for an Internet Domain Name. Lowercase characters a-z will be folded to uppercase characters A-Z by the API. Refer to the help for the HOSTNAME keyword on the ADDTCPHTE (Add TCP/IP Host Table Entry) CL command for additional information.
CIM server password. The password for the CIM server user id used to authenticate the cluster monitor's connection to the CIM server. This is a null terminated character string.
CIM server user id. The user id for the CIM server used to authenticate the cluster monitor's connection to the CIM server. This is a null terminated character string.
Length of data provided. This is the total length of data provided (including this field) for the cluster monitor entry information
Node id. A valid simple name that uniquely identifies the node.
Representational State Transfer (REST) server host name. The name of the REST server host (HMC partition) that will send information about the system and logical partitions it is managing. This is a null terminated character string. The name must follow the rules for an Internet Domain Name. Lowercase characters a-z will be changed to uppercase characters A-Z by the API. Refer to the help for the HOSTNAME keyword on the ADDTCPHTE (Add TCP/IP Host Table Entry) CL command for additional information.
Representational State Transfer (REST) server password. The password for the REST server user id used to authenticate the cluster monitor's connection to the REST server. This is a null terminated character string.
Representational State Transfer (REST) server user id. The user id for the REST server used to authenticate the cluster monitor's connection to the REST server. This is a null terminated character string.
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. |
| CPF2204 D | User profile &1 not found. |
| CPF3CF2 D | Error(s) occurred during running of &1 API. |
| CPFBB17 D | &1 API cannot be processed in cluster &2. |
| CPFBB24 D | Node &1 not participating in &2 API protocol. |
| CPFBB2D D | Timeout detected while waiting for a response. |
| CPFBB46 D | Cluster Resource Services internal error. |
| CPFBBC9 D | Product &1 option &2 not found on node &3. |
| CPFBBCB D | Cluster monitor error on node &3. |
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 | Message Text |
|---|---|
| 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. |
| CPFBB02 E | Cluster &1 does not exist. |
| CPFBB0A E | Cluster node &1 in cluster &2 not active. |
| CPFBB17 E | &1 API cannot be processed in cluster &2. |
| CPFBB26 E | Cluster Resource Services not active or not responding. |
| 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. |
| CPFBB5F E | Field value within structure is not valid. |
[ Back to top | Cluster APIs | APIs by category ]