Retrieve ASP Copy Information (QYASRTVINF) API
Required Parameter Group:
| 1 | Receiver variable | Output | Char(*) |
| 2 | Length of receiver variable | Input | BINARY(4) |
| 3 | Format name | Input | Char(8) |
| 4 | Number of filters | Input | BINARY(4) |
| 5 | Filter information | Input | Char(*) |
| 6 | Error Code | I/O | Char(*) |
Default Public Authority: *USE
Threadsafe: No
The Retrieve ASP Copy Information (QYASRTVINF) API retrieves information about ASP copy descriptions or ASP sessions.
Authorities and Locks
To use this API, *USE authority is required to each ASP device description referenced by an ASP copy description.
Required Parameter Group
- Receiver variable
- 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 the area can hold.
- Length of receiver variable
- INPUT; BINARY(4)
The length of the receiver variable provided. The length of the 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.
- Format name
- INPUT; CHAR(8)
The format of the information being returned. You must specify one of the following:
YASH0100 ASP copy description names. For more information about the YASH0100 format, see YASH0100 Format. YASH0200 ASP session names. For more information about the YASH0200 format, see YASH0200 Format. YASH0300 ASP copy description values. For more information about the YASH0300 format, see YASH0300 Format. YASH0400 ASP session values. For more information about the YASH0400 format, see YASH0400 Format.
- Number of filters
- INPUT; BINARY(4)
The number of filters provided in the filter information.
- Filter information
- INPUT; CHAR(*)
The information in this parameter is used to determine what to include in the returned format. See Format of Filter Information for a description of the layout of this parameter.
- 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 Receiver Variable
The following tables describe the order and format of the data that is returned in the receiver variable.
YASH0100 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Number of names returned |
| 12 | C | BINARY(4) | Number of available names |
| NOTE: The following fields repeat the number of times specified in the number of names returned field. | |||
| CHAR(10) | ASP copy description name | ||
Field Descriptions
ASP copy description name. The name of an ASP copy description.
Bytes available. The number of bytes of data available to be returned.
Bytes returned. The number of bytes of data that were returned.
Number of available names. The number of ASP copy description names that match the filter criteria.
Number of names returned. The number of ASP copy
description names that match the filter criteria and that fit within the
receiver variable.
YASH0200 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Number of names returned |
| 12 | C | BINARY(4) | Number of available names |
| NOTE: The following fields repeat the number of times specified in the number of names returned field. | |||
| CHAR(10) | ASP session name | ||
Field Descriptions
ASP session name. The name assigned to an ASP session.
Bytes available. The number of bytes of data available to be returned.
Bytes returned. The number of bytes of data that were returned.
Number of available names. The number of ASP session names that match the filter criteria.
Number of names returned. The number of ASP session
names that match the filter criteria and that fit within the receiver
variable.
YASH0300 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Offset to ASP copy descriptions |
| 12 | C | BINARY(4) | Number of ASP copy descriptions |
| NOTE: The following fields repeat the number of times specified in the number of ASP copy descriptions field. | |||
| CHAR(10) | ASP copy description name | ||
| 10 | A | CHAR(10) | ASP device description name |
| 20 | 14 | CHAR(10) | Cluster resource group name |
| 30 | 1E | CHAR(8) | Cluster resource group site name |
| 38 | 26 | CHAR(8) | Node location Name |
| 46 | 2E | CHAR(10) | Reserved |
| 56 | 38 | BINARY(4) | Offset to recovery domain descriptions |
| 60 | 3C | BINARY(4) | Number of recovery domain descriptions |
| 64 | 40 | BINARY(4) | Offset to storage hosts |
| 68 | 44 | BINARY(4) | Number of storage hosts |
| 72 | 48 | BINARY(4) | Offset to TotalStorage® devices |
| 76 | 4C | BINARY(4) | Number of TotalStorage® devices |
| NOTE: The following fields repeat the number of times specified in the number of storage hosts field. | |||
| CHAR(16) | User name | ||
| 16 | 10 | BINARY(4) | Offset to internet addresses |
| 20 | 14 | BINARY(4) | Number of internet addresses |
| NOTE: The following fields repeat the number of times specified in the number of internet addresses field. | |||
| CHAR(45) | Internet address | ||
| 45 | 2D | CHAR(1) | Internet address type |
| 46 | 2E | CHAR(2) | Reserved |
| NOTE: The following fields repeat the number of times specified in the number of TotalStorage® devices field. | |||
| CHAR(16) | TotalStorage® device name | ||
| 16 | 10 | BINARY(4) | Offset to LUN ranges |
| 20 | 14 | BINARY(4) | Number of LUN ranges |
| 24 | 18 | BINARY(4) | Offset to consistency group ranges |
| 28 | 1C | BINARY(4) | Number of consistency group ranges |
| NOTE: The following fields repeat the number of times specified in the number of LUN ranges field. | |||
| CHAR(4) | Start of LUN range | ||
| 4 | 4 | CHAR(4) | End of LUN range |
| NOTE: The following fields repeat the number of times specified in the number of consistency group ranges field. | |||
| CHAR(4) | Start of consistency group LUN range | ||
| 4 | 4 | CHAR(4) | End of consistency group LUN range |
| NOTE:The following fields repeat the number of times specified in the number of recovery domain descriptions field. | |||
| CHAR(10) | Cluster node name | ||
| 10 | A | CHAR(6) | Reserved |
| 16 | 10 | BINARY(4) | Offset to TotalStorage host definitions |
| 20 | 14 | BINARY(4) | Number to TotalStorage host definitions |
| 24 | 18 | CHAR(8) | Reserved |
| NOTE:The following fields repeat the number of times specified in the number of TotalStorage host definitions field. | |||
| CHAR(4) | Host identifier | ||
| 4 | 4 | CHAR(5) | Volume group identifier |
| >9 | 9 | BINARY(4) | Storage host number |
| 13 | D | CHAR(3) | >Reserved |
Field Descriptions
ASP copy description name. The name assigned to an ASP copy description.
ASP device description name. The name of an ASP device description.
Bytes available. The number of bytes of data available to be returned.
Bytes returned. The number of bytes of data that were returned.
Cluster resource group name. The name of the cluster resource group (CRG) that manages the ASP copy.
Cluster resource group site name. The name of the cluster resource group (CRG) site that has the ASP copy.
Cluster node name. The name of the cluster node in the CRG recovery domain.
End of consistency group LUN range. The LUN number of the last LUN in a range that consists of consecutive LUN numbers to be used for the consistency group.
End of LUN range. The LUN number of the last LUN in a range that consists of consecutive LUN numbers.
Host identifier. The identifier for the host connection in the TotalStorage system.
Internet address. The internet address that is used to communicate with a storage host.
Internet address type. An indicator of the format of data returned within the Internet address field.
| '1' | IPv4 format. |
| '2' | IPv6 format. |
Node Location Name. The name of the node that owns the ASP copy. The name can be that of a cluster node or, if access to the ASP is managed by a CRG or CRG site, it can be *DEFAULT. If the copy defines the target of a flashcopy that will never be varied on, the Node Location Name will be *NONE.
Number of ASP copy descriptions. The number of ASP copy descriptions that were returned.
Number of consistency group ranges. The number of LUN ranges that identify LUNs used for global mirror consistency groups.
Number of internet addresses. The number of internet addresses that can be used to communicate with a storage host.
Number of LUN ranges. The number of LUN ranges that identify the LUNs that form a copy of an ASP.
Number of recovery domain descriptions. The number of CRG recovery domain descriptions for the ASP copy description.
Number of storage hosts. The number of storage hosts for an ASP copy.
Number of TotalStorage devices. The number of TotalStorage devices that contain the logical units (LUNs) for the ASP.
Number of TotalStorage host definitions. The number of total storage host definitions.
Offset to ASP copy descriptions. The offset from the beginning of the receiver variable to the ASP copy descriptions.
Offset to consistency group ranges. The offset from the beginning of the receiver variable to the LUN ranges that identify the LUNs used for global mirror consistency groups.
Offset to internet addresses. The offset from the beginning of the receiver variable to the internet addresses that can be used to communicate with a storage host.
Offset to LUN ranges. The offset from the beginning of the receiver variable to the LUN ranges that identify the LUNs that form a copy of an ASP.
>Offset to recovery domain descriptions. The offset from the beginning of the receiver variable to the descriptions that identify the CRG recovery domain nodes.
Offset to storage hosts. The offset from the beginning of the receiver variable to the storage host information.
Offset to TotalStorage devices. The offset from the beginning of the receiver variable to the TotalStorage device information.
Offset to TotalStorage host definitions. The offset from the beginning of the receiver variable to the total storage host definition information.
Reserved. Reserved field. This field is set to binary zero.
Resource name. The name of an IOA is used to perform disk read and write operations.
Start of consistency group LUN range. The LUN number of the first LUN in a range that consists of consecutive LUN numbers to be used for the consistency group.
Start of LUN range. The LUN number of the first LUN in a range that consists of consecutive LUN numbers.
Storage host number. Which storage
host the recovery domain client entry belongs to with zero being the first host and one being the second
storage host.
TotalStorage device name. The name of the TotalStorage device that contiains the LUNs that form an ASP.
User name. The user name that is used when authenticating user access to the storage host.
Volume group identifier The identifier for a volume group definition in a TotalStorage system.
YASH0400 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | CHAR(10) | Session name |
| 18 | 12 | CHAR(2) | Reserved |
| 20 | 14 | BINARY(4) | Session type |
| 24 | 18 | BINARY(4) | Reserved |
| 28 | 1C | BINARY(4) | Session mode |
| 32 | 20 | BINARY(4) | Suspend timeout |
| 36 | 24 | BINARY(4) | Persistent |
| 40 | 28 | BINARY(4) | Synchronization priority |
| 44 | 2C | BINARY(4) | Tracking space |
| 48 | 30 | BINARY(4) | Track option |
| 52 | 34 | BINARY(4) | FlashCopy® type |
| 56 | 38 | BINARY(4) | Number sectors copied |
| 60 | 3C | BINARY(4) | Number sectors still to copy |
| 64 | 40 | BINARY(4) | Offset to ASP copy roles |
| 68 | 44 | BINARY(4) | Number of ASP copy roles |
| 72 | 48 | BINARY(4) | Length of an ASP copy role |
| NOTE: The following fields repeat the number of time specified in the number of ASP copy roles field. | |||
| BINARY(4) | ASP copy role | ||
| 4 | 4 | BINARY(4) | Number of ASP copy entries |
| 8 | 8 | BINARY(4) | Length of an ASP copy entry |
| NOTE: The following fields repeat the number of time specified in the number of ASP copy entries field. | |||
| CHAR(10) | ASP copy description name | ||
| CHAR(2) | Reserved | ||
| CHAR(8) | Node | ||
| BINARY(4) | Local node role | ||
| BINARY(4) | State | ||
| BINARY(4) | Data state | ||
| |
CHAR(10) | Device description name | |
| CHAR(2) | Reserved | ||
| CHAR(1) | Copy progress | ||
| CHAR(3) | Reserved | ||
| CHAR(8) | Tracking space allocated | ||
| CHAR(8) | Tracking space used | ||
| CHAR(8) | Data out of sync | ||
| CHAR(8) | Data in transit |
||
Field Descriptions
ASP copy description name. The name assigned to an ASP copy description.
ASP copy role. The role of the ASP copy. Possible values are:
| 0 | The ASP copy role currently is that of a source or production copy. |
| 1 | The ASP copy role is currently that of a target or mirror copy. |
| 2 | The ASP copy role is that of a FlashCopy target in support of the current Global Mirror source copy. |
| 3 | The ASP copy role is that of a FlashCopy target in support of the current Global Mirror target copy. |
Bytes available. The number of bytes of data available to be returned.
Bytes returned. The number of bytes of data that were returned.
Copy progress. The
percent of synchronization complete between source and target.
Data out of sync. The amount of data
that is currently being tracked (in megabytes).
Data in transit. The amount of data that
has been queued up to send to the mirror copy but has not yet been received by the mirror copy node. This
indicates how far "back level" the mirror copy node is. This value is in megabytes.
Data state. The data state of the ASP copy.
| -1 | The data state could not be determined. |
| 0 | The ASP copy is in-synch. |
| 1 | The ASP copy is usable. |
| 2 | The ASP copy is unusable. |
Device description name. The
name of the device description.
FlashCopy type. The type of FlashCopy. Possible values are:
| -1 | The type could not be determined. |
| 0 | The FlashCopy type is 'no copy'. |
| 1 | The FlashCopy type is 'copy'. |
Length of an ASP copy entry. The length of each ASP copy entry for the ASP copy role.
Length of an ASP copy role. The length of each ASP copy role. This length includes that of the ASP copy entries for the ASP copy role.
Local node role. The node's copy role. Possible values are:
| -1 | The node has no role or its role could not be determined. |
| 0 | Owns the production or source copy. |
| 1 | Owns the mirror or target copy. |
| 2 | Owns the detached copy. |
Node. The name of the node that has affinity with the ASP copy. A node name of *CRG indicates that the copy is in the recovery domain of a CRG and has affinity to all the nodes in the recovery domain.
Number of ASP copy entries. The number of ASP copy entries for any ASP copy role is equal to the number of ASP devices assigned to the session.
Number of ASP copy roles. The number of ASP copy roles in the ASP session. All session types have two roles except for Global Mirror which has four roles.
Number of sectors copied. The number of sectors that have been copied.
Number of sectors still to copy. The number of sectors that are yet to be copied.
Offset to ASP copy roles. The offset from the beginning of the receiver variable to the first ASP copy role.
Persistent. The persistence of the relationship between the ASP copies.
| -1 | The persistence is unknown. |
| 0 | The relationship is not persistent. |
| 1 | The relationship is persistent. |
Reserved. The field is not used and is set to binary zeroes.
Session mode. The mode of the session.
| -1 | The mode could not be determined. |
| 0 | The mode attribute does not apply. A FlashCopy session has this mode value. |
| 1 | The mode of the session is synchronous. |
| 2 | The mode of the session is asynchronous. |
Session name. The name assigned to the session.
Session type. The type of session. Possible values are:
| -1 | The type could not be determined. |
| 0 | Geographic mirroring. |
| 1 | Metro mirror. |
| 2 | Global mirror. |
| 3 | FlashCopy. |
State. The state of the copy. Possible values are:
| -1 | The state could not be determined. |
| 0 | The configuration state of the ASP is varyoff. |
| 1 | The configuration state of the ASP is varyon pending. |
| 2 | The configuration state of the ASP is varyon. |
| 3 | The configuration state of the ASP is active. |
| 4 | The configuration state of the ASP is available. |
| 10 | The ASP copy state is resume pending. The configuration state of the production copy of the ASP is varyoff but the production copy has changes that the mirror copy does not. Until a vary on is initiated, the mirror copy state is resume pending. |
| 11 | The ASP copy is resuming. The mirror copy of the ASP is not synchronized with its production copy but synchronization is currently in-progress. |
| 12 | The ASP copy is suspended. |
Suspend timeout. The number of seconds to wait for a communications response before suspending the ASP sesson.
Synchronization priority. The priority to be used during geographic mirroring synchronization. Possible values are:
| -1 | The priority could not be determined. |
| 0 | The priority attribute does not apply. The session type is not geographic mirroring. |
| 1 | The priority is 'low'. |
| 2 | The priority is 'medium'. |
| 3 | The priority is 'high'. |
Track option. The geographic mirroring tracking option.
| -1 | The track option is unknown. |
| 0 | The track option has been set to not track when mirroring is suspended or the copy is detached. |
| 1 | The track option has been set to track when mirroring is suspended or the copy is detached. |
Tracking space. The percent of the total potentially usable tracking space to actually reserve for tracking.
Tracking space allocated. Indicates
the percent of the maximum assignable tracking space that has been reserved for tracking changes. The
maximum assignable tracking space is one percent of the total space within an independent ASP. The
allocated tracking space is used to track information about the changed data, not the changed data itself.
A large amount of data can be tracked without requiring a large amount of tracking
space.
Tracking space used. The percentage of the reserved tracking space
that has been used for tracking changes. When 100% of the reserved tracking space has been used, changes to the data stop being
tracked and a full synchronization will be required.
Format of Filter Information
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Entry size |
| 4 | 4 | BINARY(4) | Key |
| 8 | 8 | BINARY(4) | Data size |
| 12 | C | CHAR(*) | Data |
Field Descriptions
Data. If there is no filter data because the number of filters is zero, all ASP copy description names are returned for format YASH0100 and all ASP session names are returned for format YASH0200. All other retrieves require the specification of a filter.
The filter data for the different filter keys have meanings as follow:
| 1 | The filter data is a device description name. This filter key is only valid with formats YASH0100 and YASH0200. If the format name is YASH0100, the names of all ASP copy descriptions for the device description are placed in the receiver variable. If the format name is YASH0200, the names of all ASP sessions for the device description are placed in the receiver variable. |
| 2 | The filter data is an ASP copy description name. This filter key is only valid with formats YASH0200 and YASH0300. If the format name is YASH0200, the names of all ASP sessions for the copy description are placed in the receiver variable. If the format name is YASH0300, the values for the copy description are placed in the receiver variable. |
| 3 | The filter data is an ASP session name. This filter key is only valid with formats YASH0100 and YASH0400. If the format name is YASH0100, the names of the ASP copy descriptions for the session are placed in the receiver variable. If the format name is YASH0400, the values for the ASP session are placed in the receiver variable. |
| 4 | The filter data is a cluster resource group name. This filter key is only valid with formats YASH0100 and YASH0200. If the format name is YASH0100, the names of all ASP copy descriptions for the cluster resource group are placed in the receiver variable. If the format name is YASH0200, the names of the ASP session for the cluster resource group is placed in the receiver variable. |
| 5 | The filter data is a session type. This filter key is only valid with format YASH0200. If the format name is YASH0200, the names of all the ASP sessions of the type are placed in the receiver variable. |
Data size. The size of the filter data. The size must be exactly the size specified in the key table.
Entry size. The combined size of all fields in the filter entry (key, entry size, data size, and data). The size must be exactly the size specified in the key table.
Key. The field to use to filter the list information. The filter key and its corresponding filter data length and filter data is:
| Key | Entry size | Data size | Data |
|---|---|---|---|
| 1 | 24 | CHAR(10) | Device description name. |
| 2 | 24 | CHAR(10) | Copy description name. |
| 3 | 24 | CHAR(10) | ASP session name. |
| 4 | 24 | CHAR(10) | Cluster resource group name. |
| 5 | 16 | BINARY(4) | Session type. |
Session type. The type of session. Possible values are:
| 1 | Geographic mirroring. |
| 2 | Metro mirror. |
| 3 | Global mirror. |
| 4 | FlashCopy. |
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3C19 E | Error occurred with receiver variable specified. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
| HAE002A E | Filter specification is not valid. |
API introduced: V6R1