Open List of ASPs (QYASPOL) API


  Required Parameter Group:


  Optional Parameter:


  Default Public Authority: *USE

  Threadsafe: No

The Open List of ASPs (QYASPOL) API generates a list of ASPs or information about an ASP. This can be any of the following:

On successful completion of this API, a handle is returned in the list information parameter. You may use this handle on subsequent calls to the following APIs:

The QSYS2.ASP_INFO and QSYS2.ASP_JOB_INFO views can be used as an alternative to this API. See ASP_INFO view and ASP_JOB_INFO view for more information.


Authorities and Locks

None.


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.

List information
OUTPUT; CHAR(80)

The variable used to return status information about the list of opened ASPs. For a description of the layout of this parameter, see Open list information format.

Number of records to return
INPUT; BINARY(4)

The number of records in the list to put into the receiver variable after filtering has been done. The valid values for this field are as follows:

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 which ASPs to include in the list. See Format of Filter Information for a description of the layout of this parameter.

Format name
INPUT; CHAR(8)

The format of the ASP information being returned. You must specify one of the following:


Error code
I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error code parameter.


Optional Parameter

Sort information
INPUT; CHAR(*)

Information on which fields within the record of information to sort. See Format of Sort Information for a description of the layout of this parameter. If this parameter is omitted, no sorting is done.


Format of Receiver Variable

The following tables describe the order and format of the data that is returned in the receiver variable.


YASP0100 Format



YASP0200 Format



YASP0300 Format



YASP0400 Format



YASP0500 Format



YASP0600 Format



Field Descriptions

Note: Megabytes, as used in this topic, means millions of bytes.

ASP capacity - protected. The total number of used and unused megabytes in the ASP that are protected by mirroring or device parity. A special value of -2 is returned if the size of this field is exceeded.

ASP capacity available - protected. The number of unused megabytes in the ASP that are protected by mirroring or device parity. A special value of -2 is returned if the size of this field is exceeded.

ASP capacity - total. The total number of used and unused megabytes in the ASP. A special value of -2 is returned if the size of this field is exceeded.

ASP capacity available - total. The total number of unused megabytes in the ASP. A special value of -2 is returned if the size of this field is exceeded.

ASP capacity - unprotected. The total number of used and unused megabytes in the ASP that are not protected by mirroring or device parity. A special value of -2 is returned if the size of this field is exceeded.

ASP capacity available - unprotected. The number of unused megabytes in the ASP that are not protected by mirroring or device parity. A special value of -2 is returned if the size of this field is exceeded.

ASP number. A unique identifier for an auxiliary storage pool. Possible values are 1 through 255.

ASP status. The device configuration status of an auxiliary storage pool. The possible ASP status values are:

ASP system storage. The amount of storage in megabytes currently allocated in the ASP for system use.

ASP type. The type of ASP. The possible ASP types are:

ASP usage. The use that is assigned to the auxiliary storage pool. The possible ASP usage values are:

Availability parity set unit. An indicator of whether a disk unit is in an availability parity set.

Balance data moved. The number of megabytes that have been moved by the balance function. A special value of -2 is returned if the size of this field is exceeded. If the ASP status is neither ACTIVE nor AVAILABLE, 0 is returned.

Balance data remaining. The number of megabytes that remain to be moved by the balance function before the move is considered complete. A special value of -2 is returned if the size of this field is exceeded. If the ASP status is neither ACTIVE nor AVAILABLE, 0 is returned.

Balance date and time. The date and time of the last status change for the balance function. This field is valid for an IASP if its status is either ACTIVE or AVAILABLE, otherwise hexadecimal zeros are returned. The 13 characters are:

Balance status. The current status of the balance function for this ASP. This field is valid for an IASP if its status is either ACTIVE or AVAILABLE, otherwise hexadecimal zeros are returned. The following special values are returned:

Balance type. The type of balance activity that is currently running or was done last. This field is valid for an IASP if its status is either ACTIVE or AVAILABLE, otherwise hexadecimal zeros are returned. The possible types of ASP balancing are:

Start of changeBlock size. Indicates the size in bytes of a single page on the disk unit.

End of change

Blocks transferred from main storage. The number of 512-byte blocks transferred to the disk unit since the last IPL. This value wraps around to zero and continues counting in the case of an overflow of the field with no indication of the overflow having occurred.

Blocks transferred to main storage. The number of 512-byte blocks transferred from the disk unit since the last IPL. This value wraps around to zero and continues counting in the case of an overflow of the field with no indication of the overflow having occurred.

Changes written to disk. An indicator of whether all changes made the previous time the IASP was online were written to disk. Varyoff processing attempts to write changed IASP storage but, in some failures, it may not be successful.

Compressed disk units in ASP. Whether there are compressed disk units in the ASP. The following special values are returned:

Compressed unit. The compression attribute of the disk unit.

Compression recovery policy. The compression recovery policy for the ASP. If the ASP has compressed drives as part of its configuration, this value controls how overflow situations are handled for this ASP. The following policies allow the user to control what is done when the ASP appears full. For more information about the compression recovery policy, see the Recovering your system topic collection. The following values are returned:

Compression status. The current status of compression for this disk unit. The following values are returned:

Current count. The number of entities that have been processed by the function. The definition of an entity depends on the function; it may be an object, an address, a data structure, and so on.

Current item count. The number of items that have been processed by the function. The definition of an item depends on the function.

Database name. The name that is assigned to the database that this ASP defines. If the ASP is neither a primary or secondary ASP, this field consists of blanks.

Device description name. The name of the device description that most recently brought the independent ASP to varyon/active state. If the ASP is not an independent ASP, this field consists of blanks.

Disk capacity. The total size of the disk unit in megabytes.

Disk model. The model of the disk unit.

Disk protection type. The type of protection that has been assigned to this disk unit. The following values are returned:

Disk serial number. The serial number of the disk unit.

Disk storage available. The number of megabytes of space not currently assigned.

Disk storage reserved for system. The number of megabytes of auxiliary storage on the disk unit reserved for use by the system. This storage contains system data related to hardware configuration, hardware error processing, and so forth.

Disk type. The type of disk unit.

Disk unit number. A unique identifier for each non-mirrored unit or mirrored pair among the configured disk units. Both mirrored units of a mirrored pair have the same disk unit number. The value of the disk unit number is assigned by the system when the disk unit is assigned to the ASP.

Disk unit presence. Indicates whether disk units in the ASP were found on the system.

Elapsed time. The time that has elapsed since the start of the function. This value is in the format HHMMSS where HH is the hour, MM is the minute, and SS is the second.

Start of change Encrypted ASP. This field specifies whether or not the data contained in the ASP is encrypted.

Encrypted unit. This field specifies whether or not the data contained in the unit is encrypted.

End of change

End immediate control. This field has meaning in the system ASP (ASP 1) only.

Error code. An error code that identifies a hardware problem related to the use of an independent ASP (error codes are not available for other ASP types). An error code of less than 1000 is an error. An error code of 1000 or greater is a warning. The possible error code values and their descriptions and recovery actions can be found in message file QSYS/QCPFMSG in these messages: CPDB8E0, CPDB8E1, CPDB8E2 and CPDB8E3.

Function. The function that is currently running as part of a state transition for an ASP. The possible values are:

Start of changeGeographic mirror transmission compression. Indicates if Geographic mirror data is compressed when sent between systems.

End of change

Geographic mirror copy data state. The condition of the data on the target.

Geographic mirror copy state. The mirror state of the mirror copy.

Geographic mirror performance mode. The performance mode of the mirroring.


Geographic mirror role. The current role of a physical IASP.


Geographic mirror resume priority. The resume priority following a suspend.


Geographic mirror suspend timeout. The number of seconds the production node waits for a response from the mirror copy node before suspending geographic mirroring.

Start of changeHyperSwap. Indicates if the disk unit is in a Metro Mirror relationship with HyperSwap failover capability.

End of change

Job name. The simple job name of the job that is using an ASP.

Job number. The system-assigned job number of the job that is using an ASP.

Job user name. The user name under which the job that is using an ASP was started.

Start of changeLifetime remaining. Indicates the percentage of lifetime remaining for the device, in a range of 0 to 100. This field contains a valid lifetime remaining only if Lifetime remaining supported is binary 1.

Lifetime remaining supported. Indicates whether or not the disk unit supports the lifetime remaining attribute.

End of change

Mirrored unit identifier. One of a pair of mirrored units. The possible values are:

Mirrored unit protected. The mirrored status of the mirrored pair of which this unit is a member.

Mirrored unit reported. This mirrored unit reported present. Information concerning this unit may or may not be current.

Mirrored unit status. The mirrored status of the unit.

Multiple connection unit. A disk unit may have multiple resource names. Each resource name represents a unique connection to the disk unit. All active connections are used to communicate with the disk unit. This attribute indicates whether the disk unit has more than one connection.

Not busy count. The number of times the disk queue was empty during the same time period that the sample count was taken.

Number of disk units. The total number of disk units in the ASP. If mirroring is active for disk units within the ASP, the mirrored pair of units is counted as one.

Number of multiple connection units. The total number of disk units with multiple connections.

Start of changeNVMe. This field indicates whether or not this is a Non-Volatile Memory Express device (NVMe).

End of change

Overflow recovery result. An indicator of the result of the ASP overflow recovery operation, which is performed during IPL at the user's request. When this operation is requested, the machine attempts to recover the user ASP from an overflow condition by moving overflowed auxiliary storage from the system ASP back to the user ASP during the storage management recovery step of an IPL.

Overflow storage. The number of megabytes of storage that has overflowed from the user ASP into the system ASP. A special value of -2 is returned if the size of this field is exceeded.

Start of changePath status. The status of the path to a disk unit.

End of change

Permanent blocks transferred from main storage. The number of 512-byte blocks of permanent storage transferred to the disk unit since the last IPL. If the field overflows, this value wraps around to zero and continues counting, with no indication that the overflow condition occurred.

Primary ASP resource name. The resource name of the primary ASP for a secondary ASP. Only a secondary ASP contains this value.

RAID type. The type of RAID protection that has been assigned to this disk unit. The following values are returned:

Requests for data transfer from main storage. The number of output data transfer requests processed for the disk unit since the last IPL. If the field overflows, this value wraps around to zero and continues counting, with no indication that the overflow occurred. This value is not directly related to the number of blocks transferred for the disk unit because the number of blocks to be transferred for a given transfer request can vary greatly.

Requests for data transfer to main storage. The number of input data transfer requests processed for the disk unit since the last IPL. If the field overflows, this value wraps around to zero and continues counting, with no indication that the overflow occurred. This value is not directly related to the number of blocks transferred for the disk unit because the number of blocks to be transferred for a given transfer request can vary greatly.

Requests for permanent data transfer from main storage. The number of output permanent data transfer requests processed for the disk unit since the last IPL. If the field overflows, this value wraps around to zero and continues counting, with no indication that the overflow occurred. This value is not directly related to the permanent blocks transferred from main storage for the disk unit because the number of blocks transferred for a given transfer request can vary greatly.

Reserved. An ignored field.

Resource name. The unique system-assigned name of the disk unit.

Sample count. The number of times the disk queue was checked to determine whether or not the queue is empty.

Start of changeSerial number expanded. Specifies the 15 character extended serial number of the device containing the auxiliary storage unit. This field will contain one of two serial number formats. For auxiliary storage units that support it, this field will contain the 12 character, 11S format serial number padded to the right with blanks. For auxiliary storage units that do not support the 11S serial number, this field will contain the older 10 character serial number padded to the right with blanks.

End of change

Space allocated for main storage dump. The number of megabytes of auxiliary storage allocated to the main storage dump space.

Space allocated to the microcode. The number of megabytes of auxiliary storage allocated to the microcode and space used by the microcode.

Space allocated to the error log. The number of megabytes of auxiliary storage allocated to the error log.

Space allocated to the machine log. The number of megabytes of auxiliary storage allocated to the machine log.

Space allocated to the machine trace. The number of megabytes of auxiliary storage allocated to the machine trace.

Start of changeSSD. Indicates whether or not this is a solid-state device (SSD).

End of change

Storage allocation restricted unit. An indicator of whether new storage allocations are allowed on the disk unit.

Storage threshold percentage. When the storage in the ASP reaches this percentage, a warning message is sent to the QSYSOPR message queue. When this percentage is reached for the system ASP (ASP 1), message CPF0907 is sent. When this percentage is reached for one of the user ASPs, message CPI0953 is sent.

Start of changeThin provision. The unit is part of an external storage box and has more storage assigned to it than it has physically available.

End of change

Thread handle. A value that addresses a particular thread within a job. While the thread identifier uniquely identifies the thread within the job, the thread handle can improve performance when referencing the thread.

Thread identifier. A value that uniquely identifies a thread within a job.

Thread status. The current status of the thread. Refer to the description of Thread status in Work Management API Attribute Descriptions for the possible values that can be returned.

Total count. The total number of entities to be processed by the function. The definition of an entity depends on the function; it may be an object, an address, a data structure, and so forth.

Total item count. The total number of items that are to be processed by the function. An item is a part of an object, but has no precise definition; that is, items differ by object type if an object type has them at all.

Trace date and time. The date and time of the last status change for the trace function. The 13 characters are:

Trace duration. The number of minutes that the trace function has run collecting data for this ASP. The trace can be run multiple times for an ASP. If the ASP status is neither ACTIVE nor AVAILABLE, zero is returned.

Trace status. The current status of the trace function. The trace gathers statistics about the data on the disk units within the ASP. This data is used by the balance functions. This field is valid for an IASP if its status is either ACTIVE or AVAILABLE, otherwise hexadecimal zeros are returned. The following special values are returned:

Transition target. The state transition target of the ASP. This field is valid for an IASP if its status is either ACTIVE or AVAILABLE, otherwise hexadecimal zeros are returned. The possible values are:

Unit control. The disk status for the disk unit. The possible values for the field are:

Use identification. An identification of how an ASP is being used.

Version. The version of objects in an independent ASP.



Format of Filter Information



Field Descriptions

Filter data. When the filter key is 1 (an ASP number), the filter data contains the number of the ASP for which information is to be returned. A value larger than 0 is the number of the ASP. A zero or negative number has special meaning as follows:

When the filter key is 2, 3, or 4, the filter data contains respectively the resource name, device description name, or database name of the ASP for which information is to be returned.

Filter key. The field to use to filter the list information. The filter key and its corresponding filter data length and filter data is:

Size of filter entry. The combined size of all fields in the filter entry (size, key, and data).


Format of Sort Information



Field Descriptions

Number of keys to sort on. The number of fields within the record structure on which to sort. If 0 is specified, the list is not sorted.

The following special value is supported for format YASP0600 only.

Reserved. Reserved field. This field must be set to hexadecimal or binary zero.

Sort key field data type. Data type of field to sort. Refer to the Sort (QLGSORT) API for information on the list of data types available.

Sort key field length. The length of the field on which to sort.

Sort key field starting position. Within the record of information, the starting position of the field on which to sort.

Sort order. Whether the list should be sorted in ascending or descending order according to the key.



Error Messages



API introduced: V4R4

[ Back to top | Configuration APIs | APIs by category ]