Change Cluster Monitor (QcstChgClusterMonitor) 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 Change Cluster Monitor (QcstChgClusterMonitor) API is used to change information about a cluster monitor. The monitor was previously added with the Add Cluster Monitor (QcstAddClusterMonitor) API. The name of the server host or the user id or password used to authenticate to the server can be changed.
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 changed 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.
When a cluster node is started which has cluster monitors configured, Cluster Resource Services will attempt to connect to each monitor's server. If some error occurs while trying to connect, the cluster node will still be started. Cluster Resource Services can be told to try to connect again by using the Change Cluster Monitor API and specifying *SAME for the new server host name, the server user id, and the server password. The node whose monitor is being changed must be active in the cluster.
The following conditions apply to this API:
- The node where the monitor is configured to run must be active within the cluster.
- The API will fail if any node in the cluster has a status of Partition and the server name, user id or password is being changed.
- This API can only be used with a cluster at cluster version 7 or greater.
- To change cluster monitors for CIM servers:
- The 5770-UME Licensed Product (IBM Universal Manageability Enablement for i) must be installed and configured on the node where the monitor is configured.
- To change CIM cluster monitors the 5733-SC1 Licensed Product (IBM Portable Utilities for i) and option 1 must be installed on the node where the monitor is configured.
- To change CIM cluster monitors operating system option 33 (Portable Application Solution Environment (PASE)) must be installed on the node where the monitor is configured.
To change cluster monitors for Representational State Transfer (REST) servers operating system option 3 (Extended Base Directory Support) must be installed on the node where the monitor is configured.
- The server host associated with this monitor must be running and able to communicate with the node where the monitor is configured.
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:
CHGM0100 CIM cluster monitor information CHGM0200Representational 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.
CHGM0100 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Length of data provided |
| 4 | 4 | CHAR(8) | Node id where monitor is configured to run |
| 12 | C | BINARY(4) | CCSID of CIM server host name, user id and password |
| 16 | 10 | CHAR(256) | Current CIM server host name |
| 272 | 110 | CHAR(256) | New CIM server host name |
| 528 | 210 | CHAR(33) | CIM server user id |
| 561 | 231 | CHAR(33) | CIM server password |
CHGM0200 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Length of data provided |
| 4 | 4 | CHAR(8) | Node id where monitor is configured to run |
| 12 | C | BINARY(4) | CCSID of Representational State Transfer (REST) server host name, user id and password |
| 16 | 10 | CHAR(256) | Current Representational State Transfer (REST) server host name |
| 272 | 110 | CHAR(256) | New Representational State Transfer (REST) server host name |
| 528 | 210 | CHAR(33) | Representational State Transfer (REST) server user id |
| 561 | 231 | CHAR(33) | Representational State Transfer (REST) server password |
Field Descriptions
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 character encoding 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 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 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.
The following special value can be used:
| *SAME | The current password is not changed. This must be left justified. |
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.
The following special value can be used:
| *SAME | The current user id is not changed. This must be left justified. |
Current 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.
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.
Current Representational State Transfer (REST) server host name. The name of the REST server host 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.
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.
Length of data provided. This is the total length of data provided (including this field) for the cluster monitor entry information.
New CIM server host name. The new name of the CIM 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 following special value can be used:
| *SAME | The current CIM server host name is not changed. This must be left justified. |
New Representational State Transfer (REST) server host name. The new 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 following special value can be used:
| *SAME | The current REST server host name is not changed. This must be left justified. |
Node id where the monitor is configured to run. A valid simple name that uniquely identifies the node.
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.
The following special value can be used:
| *SAME | The current password is not changed. This must be left justified. |
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.
The following special value can be used:
| *SAME | The current user id is not changed. This must be left justified. |
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. |
| 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. |
API introduced: IBM® i 7.1
[ Back to top | Cluster APIs | APIs by category ]