List PowerHA Information (QhaListHAInfo) 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: QHASM/QHAAPI
Default Public Authority: *USE
Threadsafe: Yes
The List PowerHA Information (QhaListHAInfo) API retrieves PowerHA information about the High Availability clustered environment managed by the PowerHA licensed program product. It must be called from a program running on one of the nodes in the cluster which has the PowerHA licensed program product installed. 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.
Authorities and Locks
None.
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:
LHAI0100 Returns PowerHA information about all nodes or one node in the high availability environment. - Node ID
- INPUT; CHAR(8)
A valid simple name that uniquely identifies a node. *ALL special value can be used to return PowerHA information about all known nodes in the high availability environment. 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 PowerHA information list consists of:
- A user space
- A generic header
- A header section
- An input parameter section
- A list data section
- LHAI0100
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 high availability environment.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(1) | Information status |
| 1 | 1 | CHAR(10) | Current PowerHA version |
| 11 | B | CHAR(1) | Reserved |
| 12 | C | BINARY(4) | Current PowerHA version for programmer use |
| 16 | 10 | BINARY(4) | Current PowerHA modification for programmer use |
| 20 | 14 | BINARY(4) | Current cluster version |
| 24 | 18 | BINARY(4) | Current cluster version modification level |
LHAI0100 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) | PowerHA node status | ||
| CHAR(10) | Potential PowerHA version | ||
| CHAR(2) | Reserved | ||
| BINARY(4) | Current PowerHA fix level | ||
| BINARY(4) | Potential node version | ||
| BINARY(4) | Potential node version modification level | ||
| CHAR(10) | PowerHA licensed program product release | ||
| CHAR(2) | Reserved | ||
Field Descriptions
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.
Current PowerHA fix level. The current PowerHA PTF level of the node.
Current PowerHA version. The version at which the nodes in the cluster which are known by the PowerHA product are actively communicating with each other. Nodes are known by the PowerHA product if the PowerHA product is installed on the node in the same cluster and the potential PowerHA version of the node is compatible with the current PowerHA version. This value also indicates what function is supported by the known PowerHA nodes. The value is set when a cluster is created, or is assumed to be the lowest supported PowerHA version if a cluster already exists when the PowerHA product is installed. This field should be used for printed output only. The current PowerHA version can be changed with the Change Cluster Version (CHGCLUVER) command.
Current PowerHA version for programmer use. The integer representation of the current PowerHA version. This field should be used for verifying code compatibility between the PowerHA product version and an application using the PowerHA functionality provided in the version.
Current PowerHA modification for programmer use. The integer representation of the current PowerHA modification. This field should be used for verifying code compatibility between PowerHA modification levels and applications using the PowerHA functionality provided in the modification.
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 node entry. The length of the node entry.
Node entry array. Array of cluster nodes for which information is being returned.
Node ID. A valid simple name that uniquely identifies a node.
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.
Potential PowerHA version. The version at which the PowerHA product installed on the node in the cluster is capable of communicating with other known PowerHA nodes. A node is known to the PowerHA product if the PowerHA product is installed on a node in the same cluster and the potential PowerHA version of the node is compatible with the current PowerHA version.
PowerHA licensed program product release. The version, release, and modification level of the PowerHA licensed program product that is installed on the node. The format of this field is VxRyMz, where x is any numeric character 0 through 9, y is any numeric character 0 through 9, and z is any numeric character 0 through 9 or uppercase letter A through Z. The value is left justified and space padded.
PowerHA node status. The status of the node which is known to the PowerHA product. This value indicates whether or not the PowerHA protocol job is active. The possible statuses are:
| 1 | The node is new to the PowerHA product. The status of the PowerHA protocol job on the new node has not yet been determined. |
| 2 | The PowerHA protocol job is active on the node. |
| 3 | The PowerHA protocol job is not active on the node. |
| 4 | The PowerHA licensed program product license has expired on the node. No PowerHA product function can be run on the node until the license is renewed. The PowerHA protocol job is not active on the node. |
| 5 | The node is partitioned from the local node. |
Reserved. The field will contain hexadecimal zeroes.
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.
| 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. |
| CPFBB38 E | Library name &1 not allowed for this request. |
| HAE0047 E | No valid license for IBM PowerHA for i found. |
API introduced: IBM® i 7.1
[ Back to top | Cluster APIs | APIs by category ]