Remove Cluster Monitor (QcstRmvClusterMonitor) API
Required Parameter Group:
| 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(*) |
Service Program: QCSTCTL2
Default Public Authority: *EXCLUDE
Threadsafe: Yes
The Remove Cluster Monitor (QcstRmvClusterMonitor) API is used to remove a monitor from the cluster. The monitor was previously added with the Add Cluster Monitor (QcstAddClusterMonitor) API. The monitor that was configured to run on a specific node is removed from that node.
In order to properly remove configuration information from the server host, there are several licensed programs or options as described below that must be installed. However if they are not installed or the license has expired, the monitor will still be removed from the cluster node it is configured on.
The following conditions apply to this API:
- The API will fail if any node in the cluster has a status of Partition.
- To remove cluster monitors for CIM servers:
- The 5770-UME Licensed Product (IBM Universal Manageability Enablement for i) must be installed and configured on the node from which the monitor is being removed.
- The 5733-SC1 Licensed Product (IBM Portable Utilities for i) and option 1 must be installed on the node from which the monitor is being removed.
- Operating system option 33 (Portable Application Solution Environment (PASE)) must be installed on the node from which the monitor is being removed.
To remove Representational State Transfer (REST) cluster monitors operating system option 3 (Extended Base Directory Support) must be installed on the node from which the monitor is being removed.
- This API can only be used with a cluster at cluster version 7 or greater.
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
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 on which the monitor is being changed. It must be a valid simple name.
- Monitor information
- INPUT; CHAR(*)
This parameter contains the information about the monitor and the server.
- Format name
- INPUT; CHAR(8)
The content and format of the information supplied for the monitor information. The possible format names are:
RMVM0100 CIM cluster monitor information RMVM0200Representational State Transfer (REST) cluster monitor 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.
RMVM0100 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Length of data provided |
| 4 | 4 | CHAR(8) | Node id where monitor was added |
| 12 | C | BINARY(4) | CCSID of CIM server host name |
| 16 | 10 | CHAR(256) | CIM server host name |
RMVM0200 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Length of data provided |
| 4 | 4 | CHAR(8) | Node id where monitor was added |
| 12 | C | BINARY(4) | CCSID of Representational State Transfer (REST) server host name |
| 16 | 10 | CHAR(256) | Representational State Transfer (REST) server host name |
Field Descriptions
CCSID of CIM server host name. The Coded Character Set Identifier for the CIM server host name.
| 0 | The CIM server host name 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. The Coded Character Set Identifier for the REST server host name.
| 0 | The REST server host name text is assumed in the CCSID of the job running this API. |
| CCSID | Specify a valid CCSID that your 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). 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.
The name must match the name that was used on the Add Cluster Monitor or a previous Change Cluster Monitor API. If the monitor was added with the complete domain name such as NYCHMC1.ABCCOMPANY.COM, that is what must be specified for the CIM server host name. If the monitor was added with a short name such as NYCHMC1, that is what must be specified for the CIM server host name.
Length of data provided. This is the total length of data provided (including this field) for the cluster monitor entry information.
Node id where monitor was added. The node where the monitor was previously added with the QcstAddClusterMonitor API.
Representational State Transfer (REST) server host name. The name of the REST server host. 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.
The name must match the name that was used on the Add Cluster Monitor or a previous Change Cluster Monitor API. If the monitor was added with the complete domain name such as NYCHMC1.ABCCOMPANY.COM, that is what must be specified for the REST server host name. If the monitor was added with a short name such as NYCHMC1, that is what must be specified for the REST server host name.
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. |
| 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. |
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 | 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. |
| 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. |
API introduced: IBM® i 7.1
[ Back to top | Cluster APIs | APIs by category ]