List Cluster Information (QcstListClusterInfo) API
Required Parameter Group:
| 1 | Qualified user space name | Input | Char(20) |
| 2 | Cluster name | Input | Char(10) |
| 3 | Format name | Input | Char(8) |
| 4 | Node ID | Input | Char(8) |
| 5 | Error code | I/O | Char(*) |
Service Program: QCSTCTL1
Default Public Authority: *USE
Threadsafe: Yes
The List Cluster Information (QcstListClusterInfo) API is used to retrieve
information about a cluster. It must be called from a program running on one of
the nodes in the cluster. The information returned may not be current if this
API is called from a program running on a node that has a status of Inactive or
Failed. This API may be called from a cluster resource group exit program.
Authorities and Locks
- User Space Authority
- *CHANGE
- User Space Library Authority
- *EXECUTE
- User Queue Lock
- *EXCLRD
Required Parameter Group
- Qualified user space name
- OUTPUT; CHAR(20)
The user space that receives the information and the library in which it is located. The first 10 characters contain the user space name, and the second 10 characters contain the library name. No special values (QTEMP, *CURLIB, or *LIBL) can used for the library name.
- Cluster name
- INPUT; CHAR(10)
The name of the cluster for which information is retrieved.
- Format name
- INPUT; CHAR(8)
The format of the information to be returned. Supported format names are:
LCTI0100 Returns information about a specific node or all nodes in the cluster and additional information about the cluster. LCTI0101 Returns information about a specific node or all nodes in the cluster and additional information about the cluster with IPv6 support. LCTI0200 Returns information about the cluster monitors for a specific node or the cluster monitors for all nodes. This format can only be used with a cluster at cluster version 7 or greater. - Node ID
- INPUT; CHAR(8)
A valid simple name that uniquely identifies a node. *ALL special value can be used to return information about all nodes in the cluster. The *ALL special value must be left-justified.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
Format of Generated Lists
The cluster information list consists of:
- A user space
- A generic header
- A header section
- An input parameter section
- A list data section
- LCTI0100 or
- LCTI0101 or
- LCTI0200
For details about the user area and generic header, see User spaces. For detailed descriptions of the fields in the list returned, see Field Descriptions.
When you retrieve list entry information from a user space, you must not use
the entry size returned in the generic header. Each entry may have a different
size. The size of each entry may be padded at the end.
Input Parameter Section
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | User space name |
| 10 | A | CHAR(10) | User space library name |
| 20 | 14 | CHAR(10) | Cluster name |
| 30 | 1E | CHAR(8) | Format name |
| 38 | 26 | CHAR(8) | Node ID |
Header Section
Global information about the cluster.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(1) | Information status |
| 1 | 1 | CHAR(3) | Reserved |
| 4 | 4 | BINARY(4) | Current cluster version |
| 8 | 8 | BINARY(4) | Current cluster version modification level |
| 12 | C | CHAR(10) | Cluster message queue name |
| 22 | 16 | CHAR(10) | Cluster message queue library name |
| 32 | 20 | BINARY(4) | Failover wait time |
| 36 | 24 | BINARY(4) | Failover default action |
LCTI0100 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| These fields are repeated for each node entry returned. | Array(*) of CHAR(*) | Node entry array | |
| BINARY(4) | Length of node entry | ||
| CHAR(8) | Node ID | ||
| BINARY(4) | Node status | ||
| BINARY(4) | Offset to cluster interface array | ||
| BINARY(4) | Number of cluster interface array entries | ||
| BINARY(4) | Potential node version | ||
| BINARY(4) | Potential node version modification level | ||
| CHAR(10) | Device domain name | ||
| Array(*) of CHAR(16) | Cluster interface array | ||
| These fields are repeated for each cluster interface entry returned. | CHAR(16) | Cluster interface address - IPv4 | |
LCTI0101 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| These fields are repeated for each node entry returned. | Array(*) of CHAR(*) | Node entry array | |
| BINARY(4) | Length of node entry | ||
| CHAR(8) | Node ID | ||
| BINARY(4) | Node status | ||
| BINARY(4) | Offset to cluster interface array | ||
| BINARY(4) | Number of cluster interface array entries | ||
| BINARY(4) | Length of cluster interface array entry | ||
| BINARY(4) | Potential node version | ||
| BINARY(4) | Potential node version modification level | ||
| CHAR(10) | Device domain name | ||
| Array(*) of CHAR(*) | Cluster interface array | ||
| These fields are repeated for each cluster interface entry returned. | CHAR(1) | Cluster interface address type | |
| CHAR(45) | Cluster interface address - IPv4 or IPv6 | ||
LCTI0200 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Number of cluster monitor entries |
| 4 | 4 | BINARY(4) | Offset to cluster monitor array |
| 8 | 8 | Array(*) of CHAR(*) | Cluster monitor array |
| These fields are repeated for each monitor entry returned. | |||
| BINARY(4) | Length of cluster monitor entry | ||
| BINARY(4) | Cluster monitor entry type | ||
| CHAR(8) | Node ID where cluster monitor runs | ||
| CHAR(*) |  Type specific data |
||
Type specific data for CIM and Representational State Transfer (REST) cluster monitor entries
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(256) | Server host name |
| 256 | 256 | CHAR(33) | Server user id |
Field Descriptions
Cluster interface address - IPv4. The cluster interface address is an IP address which is used by Cluster Resource Services to communicate with other nodes in the cluster. Each IPv4 address is returned as a null-terminated string and represented in dotted decimal format. If the cluster interface address is not actually an IPv4 address, the special value *IPV6 padded on the right with hex zeros is returned.
Cluster interface address - IPv4 or IPv6. The cluster interface address is an IP address which is used by Cluster Resource Services to communicate with other nodes in the cluster. Either an IPv4 or IPv6 address is supported. When Cluster interface address type field is 0, the returned address is an IPv4 address in dotted decimal format and padded on the right with hex zeros. When Cluster interface address type field is 1, the returned address is an IPv6 address and padded on the right with hex zeros. The coded character set identifier (CCSID) of the IP address returned will match the CCSID of the job calling the API.
Cluster interface entry array. Array of cluster interface addresses in use by each node in the node entry array.
Cluster interface address type. Type of IP address that follows in the Cluster interface address - IPv4 or IPv6 field. The possible values are:
| 0 | Cluster interface address is IPv4. |
| 1 | Cluster interface address is IPv6. |
Cluster message queue library name. The name of the library that contains the message queue to receive cluster messages. This field will contain hexadecimal zeroes if no cluster message queue is specified.
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. This field will contain *NONE left justified and padded with blanks if no cluster message queue is specified.
Cluster monitor array. Array of cluster monitors which have been configured with the Add Cluster Monitor (QcstAddCluster Monitor) API.
Cluster monitor entry type. The type of cluster monitor entry.
| 1 | CIM server monitor. |
| 2 |
Representational State Transfer (REST) server monitor. |
Cluster name. The name of the cluster for which information is retrieved.
Current cluster version. The version at which the nodes in the cluster are actively communicating with each other. This value in conjunction with the potential node version determines what nodes can join in the cluster. This value also determines the cluster's ability to use new functions supported by the node's potential node version. It is set when the cluster is created and can be changed by the Adjust Cluster Version (QcstAdjustClusterVersion) API.
Current cluster version modification level. The modification level of the current cluster version. The modification level further identifies the version at which the nodes in the cluster communicate. It is updated when code changes that impact the version are applied to the system.
Device domain name. The name of the device domain that this node belongs to. This field will contain hexadecimal zeros if the node does not belong to a device domain.
Failover default action. Indicates what clustering should do when a response to the failover message on the cluster message queue was not received in the failover wait time limit. Valid values are:
| 0 | Proceed with failover. |
| 1 | Do NOT attempt failover. |
Failover wait time. Number of minutes to wait for a reply to the failover message that was enqueued on the cluster message queue. Valid values are:
| -1 | Wait forever until a response is given to the failover message. |
| 0 | Failover proceeds without user intervention. Acts the same as V5R4M0 and prior. |
| >=1 | Number of minutes to wait for a response to the failover message. If no response is received in the specified number of minutes, the failover default action field will be looked at to decide how to proceed. |
Format name. The content and format of the information returned in the user space.
Information status. Indicates the consistency of the retrieved information.
| 0 | The information is consistent for all active nodes in the cluster. |
| 1 | The information retrieved from the node running
the API may not be consistent with all active nodes in the cluster. In order to
obtain consistent information:
|
Length of cluster interface array entry. The length of an entry in the cluster interface array. This length should be used to navigate to the next cluster interface array entry.
Length of cluster monitor entry. The length of the cluster monitor entry.
Length of node entry. The length of the node entry, including the cluster interface array.
Node entry array. Array of cluster nodes for which information is being returned.
Node ID. A valid simple name that uniquely identifies a node.
Node ID where cluster monitor runs. The ID of the node where a cluster monitor runs and receives information from a server.
Node status. The status of the node in the cluster. See Cluster Node Status for the possible values and definitions of the status.
Number of cluster interface array entries. The number of IP interfaces used by the node for Cluster Resource Services.
Number of cluster monitor entries. The number of entries in the cluster monitor array. This can be zero if no monitors have been added to the cluster or no monitors have been added to the particular node whose information is being retrieved.
Offset to cluster interface array. The offset from the beginning of the node entry to the first entry in the cluster interface array.
Offset to cluster monitor array. The offset from the beginning of the user space to the first cluster monitor entry.
Potential node version. The version at which the node is capable of communicating with the other nodes in the cluster. This is the value associated with the cluster code installed on the node. It will be used to determine if the node can join a cluster. If communications have not yet been established with the node (status of New), then the potential node version will be reported as 0.
Potential node version modification level.The modification level of the potential node version. The modification level further identifies the version at which the node is capable of communicating with the other nodes in the cluster. It is updated when code changes that impact the version are applied to the system.
Reserved. The field will contain hexadecimal zeroes.
Server host name.The name of the server host being used to monitor the status of one or more cluster nodes. This is a null terminated character string. The data is returned in the job's default CCSID.
Server user ID.The user id on the server host used by Cluster Resource Services for authentication when information is requested from the server. This is a null terminated character string. The data is returned in the job's default CCSID.
User space name. The name of the user space.
User space library name. The name of the library in which
the user space resides. No special values are supported for library name.
Error Messages
Messages that are delivered through the error code parameter are listed here.
| 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. |
| 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. |
| 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. |
| CPFBB02 E | Cluster &1 does not exist. |
| CPFBB09 E | Cluster node &1 does not exist in cluster &2. |
| CPFBB38 E | Library name &1 not allowed for this request. |
| CPFBB70 E | Request &1 not compatible with current cluster version. |
API introduced: V4R4
[ Back to top | Cluster APIs | APIs by category ]