Retrieve HA Status (QhaRetrieveStatus) API
Required Parameter Group:
| 1 | Receiver variable | Output | Char(*) |
| 2 | Length of receiver variable | Input | Binary(4) |
| 3 | Receiver variable format name | Input | Char(8) |
| 4 | Cluster name | Input | Char(10) |
| 5 | Selection format name | Input | Char(8) |
| 6 | Selection information | Input | Char(*) |
| 7 | Error Code | I/O | Char(*) |
Service Program: QHASM/QHAAPI
Default Public Authority: *USE
Threadsafe: Yes
The Retrieve High Availability (HA) Status (QhaRetrieveStatus) API is used to retrieve information about the current HA environment status.
Authorities and Locks
- None
Required Parameter Group
- Receiver variable here)
- OUTPUT; CHAR(*)
The receiver variable that receives the information requested. You can specify the size of the area to be smaller than the format requested as long as you specify the length parameter correctly. As a result, the API returns only the data that the area can hold.
- Length of receiver variable
- INPUT; BINARY(4)
The length of the receiver variable provided. The length of receiver variable parameter may be specified up to the size of the receiver variable specified in the user program. If the length of receiver variable parameter specified is larger than the allocated size of the receiver variable specified in the user program, the results are not predictable. The minimum length is 8 bytes.
- Receiver variable format name
- INPUT; CHAR(8)
The content and format of the HA status information that is returned. The possible format names are:
RHYS0100 HyperSwap status is returned. - Cluster name
- INPUT; CHAR(10)
The name of the cluster.
- Selection format name
- INPUT; CHAR(10)
The format name of the selection. The possible format names are:
IHAS0100 Specify the selection information about HA status information to be retrieved. - Selection information
- INPUT; CHAR(*)
The information in this parameter is used to determine what to include in the HA status information to be returned.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
RHYS0100 format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes provided |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Length of fixed fields |
| 12 | C | BINARY(4) | Number of HyperSwap ASP entries returned |
| 16 | 10 | BINARY(4) | Offset to HyperSwap ASP entries array |
| Array(*) of CHAR(*) | HyperSwap ASP entry | ||
RHYS0100 Field Descriptions
Bytes available. The number of bytes of data available to be returned.
Bytes provided. The number of bytes that the calling application has provided for the HA environment status data.
Length of fixed fields. The length of the fixed portion of the format.
Number of HyperSwap entries returned. The number of HyperSwap ASP entries that were returned.
Offset to HyperSwap entries array. The offset from the beginning of the receiver variable to the HyperSwap entries array.
RHYS0100 format - HyperSwap ASP entry
There is typically one HyperSwap ASP entry per cluster node and ASP. The following is the information for HyperSwap ASP entry:
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Length of HyperSwap ASP entry |
| 4 | 4 | BINARY(4) | Length of fixed fields |
| 8 | 8 | CHAR(8) | Cluster node name |
| 16 | 10 | CHAR(10) | ASP device description name |
| 26 | 1A | CHAR(2) | Reserved |
| 28 | 1C | BINARY(4) | HyperSwap copy status summary |
| 32 | 20 | CHAR(16) | Primary storage identifier |
| 48 | 30 | CHAR(16) | Second storage identifier |
| 64 | 40 | BINARY(4) | Number of HyperSwap disk unit entries returned |
| 68 | 44 | BINARY(4) | Offset to HyperSwap disk unit entries |
| Array(*) of CHAR(*) | HyperSwap disk unit entry | ||
RHYS0100 Field Descriptions - HyperSwap ASP entry
Length of HyperSwap ASP entry. The length of the HyperSwap ASP entry.
Length of fixed fields. The length of the fixed portion of the HyperSwap ASP entry.
Cluster node name. The cluster node name of the HyperSwap ASP entry.
ASP device description name. The ASP device description name of the HyperSwap ASP entry.
Reserved. Reserved field. This field is set to binary zero.
HyperSwap copy status summary. A summary of the overall HyperSwap copy relation status. Possible values are:
| 0 | HyperSwap Not configured. |
| 1 | HyperSwap Summary Unknown. This could happen if the individual disk units have a conflicting HyperSwap status. |
| 2 | One or more HyperSwap relationships are resuming. |
| 3 | All HyperSwap relationships are currently synchronized. This is the only state where a HyperSwap switchover or HyperSwap failover is allowed. |
| 4 | One or more HyperSwap relationships is currently suspended. |
| 5 | One or more HyperSwap relationships consists of two primary volumes. |
Primary storage identifier. The current primary storage device for the ASP. In the event that HyperSwap is not configured, this field will be blank.
Second storage identifier. The current second storage device for the ASP. In most cases this is the current secondary storage identifier, however in the event that both storage devices are primary, as identified by a HyperSwap copy status of 5, the second storage identifier will also be a primary storage device. In the event that HyperSwap is not configured this field will be blank.
Number of HyperSwap disk unit entries returned. The number of HyperSwap disk unit entries that were returned.
Offset to HyperSwap disk unit entries array. The offset from the beginning of the receiver variable to the HyperSwap disk unit entries array.
RHYS0100 - HyperSwap disk unit entry
There is typically one HyperSwap disk unit entry per disk unit in the ASP described by the HyperSwap ASP entry. The following is the information for HyperSwap ASP entry:
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Length of HyperSwap disk unit entry |
| 4 | 4 | BINARY(4) | Length of fixed fields |
| 8 | 8 | CHAR(10) | ASP device description name |
| 18 | 12 | CHAR(2) | Reserved |
| 20 | 14 | BINARY(4) | Disk unit number |
| 24 | 18 | CHAR(16) | Storage identifier 1 |
| 40 | 28 | CHAR(4) | Volume 1 |
| 44 | 2C | CHAR(2) | Volume flags 1 |
| 44 | 2C | BIT 0 | Primary volume |
| 44 | 2C | BIT 1 | Volume inaccessible |
| 44 | 2C | BITS 2-15 | Reserved |
| 46 | 2E | BINARY(4) | Copy status |
| 50 | 32 | CHAR(16) | Storage identifier 2 |
| 66 | 42 | CHAR(4) | Volume 2 |
| 70 | 46 | CHAR(2) | Volume flags 2 |
| 70 | 46 | BIT 0 | Primary volume |
| 70 | 46 | BIT 1 | Volume inaccessible |
| 70 | 46 | BITS 2-15 | Reserved |
| 74 | 4A | BINARY(4) | Synchronization progress |
RHYS0100 Field Descriptions - HyperSwap disk unit entry
Length of HyperSwap disk unit entry. The length of the HyperSwap disk unit entry.
Length of fixed fields. The length of the fixed portion of the HyperSwap disk unit entry.
ASP device description name. The ASP device description name of the HyperSwap disk unit entry.
Reserved. Reserved field. This field is set to binary zero.
Disk unit number. The system disk unit number which uniquely identifies the disk unit. The value of the unit number is assigned by the system when the unit is allocated to an auxiliary storage pool.
Storage identifier 1. The identifier for the storage subsystem that identifies the first volume in the HyperSwap relationship. The order of the first and second volume in the HyperSwap relationship is indeterminate. This field will be blank if HyperSwap is not configured.
Volume 1. The volume identifier as presented by the storage, that identifies the volume. This field will be blank if HyperSwap is not configured.
Volume flags 1. This field contains flags representing different features of the volume. Flags are:
| Bit 0 | Primary volume. A value of 1 indicates that the volume is currently a primary volume in the storage. A value of 0, indicates that the volume is currently a secondary volume. |
| Bit 1 | Volume inaccessible. A value of 1 indicates that the volume is currently not accessible by the host, and data may be outdated. |
| Bits 2-15 | Reserved. Reserved field. This field is set to binary zero. |
Copy status. The copy status field indicates the current status of the HyperSwap relationship between volume 1 and volume 2. Possible values are:
| 0 | HyperSwap is not configured for this disk unit. |
| 1 | HyperSwap configuration for this disk unit is currently unknown. |
| 2 | The HyperSwap status is currently resuming from volume 1 to volume 2. |
| 3 | The HyperSwap status is currently resuming from volume 2 to volume 1. |
| 4 | The HyperSwap status is currently suspended, and the replication direction is from volume 1 to volume 2. |
| 5 | The HyperSwap status is currently suspended, and the replication direction is from volume 2 to volume 1. |
| 6 | The HyperSwap relationship consists of two primary volumes. |
Storage identifier 2. The identifier for the storage subsystem that identifies the second volume in the HyperSwap relationship. The order of the first and second volume in the HyperSwap relationship is indeterminate. This field will be blank if HyperSwap is not configured.
Volume 2. The volume identifier as presented by the storage, that identifies the volume. This field will be blank if HyperSwap is not configured.
Volume flags 2. This field contains flags representing different features of the volume. Flags are:
| Bit 0 | Primary Volume.A value of 1 indicates that the volume is currently a primary volume in the storage. A value of 0, indicates that the volume is currently a secondary volume. |
| Bit 1 | Volume Inaccessible. A value of 1 indicates that the volume is currently not accessible by the host, and data may be outdated. |
| Bits 2-15 | Reserved. Reserved field. This field is set to binary zero. |
Synchronization progress. The value of this field depends upon the value of the Copy Status field. When the copy status field is resuming (2 or 3), this field will contain the synchronization progress in percent complete. When the copy status is anything else, this field will be set to binary 0.
IHAS0100 format
The following is the selection information for format IHAS0100:
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Number of selections |
| Array(*) of CHAR(*) | Selection information entry | ||
IHAS0100 Field Descriptions
Number of selections. The number of selections provided. Selections are used to filter out or select certain data to return. Selections with the same type will be treated as if a logical 'or' existed between them. Selections with different types will be treated as if a logical 'and' existed between them. For example, if you have two selections, the first of which specifies an ASP device description name of 'EXAMPLEDD' and the second which specifies a node name of 'EXAMPLENOD' then all ASP device descriptions with the specified name on the specified node will be returned. If you add another selection which specifies an ASP device description name of 'EXAMPLEDD2' then all entries on the specified node with either ASP device description name will be returned.
IHAS0100 format - selection information
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Length of selection information entry |
| 4 | 4 | BINARY(4) | Selection type |
| 8 | 8 | CHAR(*) | Selection data |
IHAS0100 Field Descriptions- Selection information
Length of selection information entry. The length of the selection information entry. The length is dependent upon the type of the selection information entry.
Selection type. The selection type indicates how to select and filter the data returned.
For receiver variable format name RHYS0100 the following selection types are supported:
Selection type 0 - ASP device description
Used to only receive HyperSwap status for the specified ASP device description. If multiple nodes own the ASP (as there is with Flash Copy), there may be multiple HyperSwap ASP entries that come back.
The selection information structure for a selection type 0, has the following format:
| Offset | Type | Field | Data | |
|---|---|---|---|---|
| Dec | Hex | |||
| 0 | 0 | BINARY(4) | Length | 18 |
| 4 | 4 | BINARY(4) | Selection type | 0 |
| 8 | 8 | CHAR(10) | Selection data | The selection data portion contains an ASP device description name, and must be 10 characters long and must be one of the following:
|
| 18 | 12 | CHAR(2) | Reserved | Binary zeroes |
Selection type 1 - Node Name
Used to only receive HyperSwap status from the specified node. The selection information structure for a selection type 1, has the following structure.
| Offset | Type | Field | Data | |
|---|---|---|---|---|
| Dec | Hex | |||
| 0 | 0 | BINARY(4) | Length | 16 |
| 4 | 4 | BINARY(4) | Selection type | 1 |
| 8 | 8 | CHAR(8) | Selection data | The selection data portion contains a cluster node name and must be 8 characters long and can be one of the following:
|
Error Messages
The following messages may be sent from this function:
| Message ID | Error Message Text |
|---|---|
| CPF3C1E E | Required parameter &1 omitted. |
| CPF3C19 E | Error occurred with receiver variable specified. |
| 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. |
| CPFBB02 E | Cluster &1 does not exist. |
API introduced: IBM® i 7.2 PTF
[ Back to top | Cluster APIs | APIs by category ]