Open List of ASPs (QYASPOL) API

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

• Identification of all ASPs configured to a system
• Attributes of an ASP
• Unassigned disk units or disk units assigned to an ASP
• Hardware problems during varyon of an independent ASP.
• Current varyon activity.
• Jobs using an independent ASP.
• Geographic mirroring topology of an independent ASP.

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:

• Get List Entries (QGYGTLE)
• Close List (QGYCLST)

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:

-1	All records are built synchronously in the list by the main job.
0	All records are built asynchronously in the list by a server job.
records-to-return	If a positive number of records is specified, at least that many records are built synchronously (in order to return those records immediately to the caller of this API) and the remainder are built asynchronously by a server job.

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:

YASP0100	Identification of the ASPs configured to a system. This includes the system ASP and all user ASPs. The list is sorted by ASP number. For more information about the YASP0100 format, see YASP0100 Format.
YASP0200	The basic attributes of the ASP. For more information about the YASP0200 format, see YASP0200 Format.
YASP0300	The disk units assigned to the ASP. Records of this format are returned only if the disk units are owned by the system. Disk units that have been switched to another system are not owned and will not have YASP0300 format records returned. For more information about the YASP0300 format, see YASP0300 Format.
YASP0400	The hardware error information related to use of an ASP. Records of this format are returned only if the ASP is an independent ASP and if any errors were detected. For more information about the YASP0400 format, see YASP0400 Format.
YASP0500	The progress status related to use of an ASP. A record of this format is returned only if the ASP is an independent ASP. For more information about the YASP0500 format, see YASP0500 Format.
YASP0600	Identification of the jobs and their threads currently using an ASP. Records of this format are returned only if the ASP is an independent ASP. An entry will be returned for each thread in the job that is using the ASP. For more information about the YASP0600 format, see YASP0600 Format.
YASP0700	The geographic mirroring topology of an IASP. One record will be returned for each geographically mirrored IASP. Each record may have one connection entry record to identify the geographic mirroring source for the given IASP, and up to three connection entry records to identify geographic mirroring targets for the given IASP. For more information about the YASP0700 format, see YASP0700 Format.

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

Offset		Type	Field
Dec	Hex
0	0	BINARY(4)	ASP number
4	4	CHAR(10)	Resource name
14	E	CHAR(10)	Device description name
24	18	BINARY(4)	Version
28	1C	BINARY(4)	ASP usage
32	20	BINARY(4)	ASP status
36	24	CHAR(18)	Database name
54	36	CHAR(10)	Primary ASP resource name

YASP0200 Format

Offset		Type	Field
Dec	Hex
0	0	BINARY(4)	ASP number
4	4	BINARY(4)	Number of disk units
8	8	BINARY(4)	ASP capacity - total
12	C	BINARY(4)	ASP capacity available - total
16	10	BINARY(4)	ASP capacity - protected
20	14	BINARY(4)	ASP capacity available - protected
24	18	BINARY(4)	ASP capacity - unprotected
28	1C	BINARY(4)	ASP capacity available - unprotected
32	20	BINARY(4)	ASP system storage
36	24	BINARY(4)	Overflow storage
40	28	BINARY(4)	Space allocated to the error log
44	2C	BINARY(4)	Space allocated to the machine log
48	30	BINARY(4)	Space allocated to the machine trace
52	34	BINARY(4)	Space allocated for main storage dump
56	38	BINARY(4)	Space allocated to the microcode
60	3C	BINARY(4)	Storage threshold percentage
64	40	CHAR(2)	ASP type
66	42	CHAR(1)	Overflow recovery result
67	43	CHAR(1)	End immediate control
68	44	CHAR(1)	Compression recovery policy
69	45	CHAR(1)	Compressed disk units in ASP
70	46	CHAR(1)	Balance status
71	47	CHAR(1)	Balance type
72	48	CHAR(13)	Balance date and time
85	55	CHAR(3)	Reserved
88	58	BINARY(4)	Balance data moved
92	5C	BINARY(4)	Balance data remaining
96	60	BINARY(4)	Trace duration
100	64	CHAR(1)	Trace status
101	65	CHAR(13)	Trace date and time
114	72	CHAR(1)	Changes written to disk
115	73	CHAR(1)	Reserved
116	74	BINARY(4)	Number of multiple connection disk units
120	78	BINARY(4)	Geographic mirroring role
124	7C	BINARY(4)	Geographic mirroring copy state
128	80	BINARY(4)	Geographic mirroring copy data state
132	84	BINARY(4)	Geographic mirroring performance mode
136	88	BINARY(4)	Geographic mirroring resume priority
140	8C	BINARY(4)	Geographic mirroring suspend timeout
144	90	BINARY(4)	Disk unit presence
148	94	CHAR(1)	Encrypted ASP
149	95	CHAR(1)	Geographic mirroring transmission compression
150	96	BINARY(4)	Geographic mirroring transmission delivery

YASP0300 Format

Offset		Type	Field
Dec	Hex
0	0	BINARY(4)	ASP number
4	4	CHAR(4)	Disk type
8	8	CHAR(4)	Disk model
12	C	CHAR(10)	Disk serial number
22	16	CHAR(10)	Resource name
32	20	BINARY(4)	Disk unit number
36	24	BINARY(4)	Disk capacity
40	28	BINARY(4)	Disk storage available
44	2C	BINARY(4)	Disk storage reserved for system
48	30	CHAR(1)	Mirrored unit protected
49	31	CHAR(1)	Mirrored unit reported
50	32	CHAR(1)	Mirrored unit status
51	33	CHAR(1)	RAID type
52	34	BINARY(4)	Unit control
56	38	BINARY(4)	Blocks transferred to main storage
60	3C	BINARY(4)	Blocks transferred from main storage
64	40	BINARY(4)	Requests for data transfer to main storage
68	44	BINARY(4)	Requests for data transfer from main storage
72	48	BINARY(4)	Permanent blocks transferred from main storage
76	4C	BINARY(4)	Requests for permanent data transfer from main storage
80	50	BINARY(4)	Sample count
84	54	BINARY(4)	Not busy count
88	58	CHAR(1)	Compression status
89	59	CHAR(1)	Disk protection type
90	5A	CHAR(1)	Compressed unit
91	5B	CHAR(1)	Storage allocation restricted unit
92	5C	CHAR(1)	Availability parity set unit
93	5D	CHAR(1)	Multiple connection unit
94	5E	CHAR(1)	Encrypted unit
95	5F	CHAR(1)	Path status
96	60	CHAR(15)	Serial number expanded
111	6F	CHAR(1)	Lifetime remaining supported
112	70	BINARY(4)	Lifetime remaining
116	74	BINARY(4)	Block size
120	78	CHAR(1)	SSD
121	79	CHAR(1)	NVMe
122	7A	CHAR(1)	HyperSwap
123	7B	CHAR(1)	Thin provision

YASP0400 Format

Offset		Type	Field
Dec	Hex
0	0	BINARY(4)	ASP number
4	4	CHAR(4)	Error code
8	8	BINARY(4)	Disk unit number
12	C	CHAR(1)	Mirrored unit identifier

YASP0500 Format

Offset		Type	Field
Dec	Hex
0	0	BINARY(4)	ASP number
4	4	CHAR(2)	Transition target
6	6	CHAR(2)	Reserved
8	8	CHAR(16)	Function
24	18	BINARY(4)	Current count
28	1C	BINARY(4)	Total count
32	20	BINARY(4)	Current item count
36	24	BINARY(4)	Total item count
40	28	CHAR(6)	Elapsed time

YASP0600 Format

Offset		Type	Field
Dec	Hex
0	0	BINARY(4)	ASP number
4	4	BINARY(4)	Use identification
8	8	CHAR(10)	Job name
18	12	CHAR(10)	Job user name
28	1C	CHAR(6)	Job number
34	22	CHAR(2)	Reserved
36	24	CHAR(8)	Thread identifier
44	2C	UNSIGNED BINARY(4)	Thread handle
48	30	CHAR(4)	Thread status

YASP0700 Format

Offset		Type	Field
Dec	Hex
0	0	BINARY(4)	ASP number
4	4	CHAR(10)	Device description name
14	E	CHAR(2)	Reserved
16	10	CHAR(10)	Job user name
26	1A	CHAR(8)	Node name
34	22	CHAR(2)	Reserved
36	24	CHAR(10)	Cluster resource group name
46	2E	CHAR(8)	Cluster resource group site
54	36	BINARY(4)	Geographic mirroring role
58	3A	CHAR(1)	ASP exists
59	3B	CHAR(1)	All units enlisted
60	3C	CHAR(1)	Geographically mirrored
61	3D	CHAR(3)	Reserved
64	40	UNSIGNED BINARY(8)	Geographic mirroring tracking space in use
72	48	UNSIGNED BINARY(8)	Geographic mirroring tracking space allocated
80	50	CHAR(8)	Oldest tracked operation node
88	58	UNSIGNED BINARY(8)	Oldest tracked operation ID
96	60	CHAR(8)	Oldest tracked operation timestamp
104	68	CHAR(8)	Last received operation node
112	70	UNSIGNED BINARY(8)	Last received operation ID
120	78	UNSIGNED BINARY(4)	Size of a connection entry
124	7C	UNSIGNED BINARY(4)	Number of source connection entries
128	80	UNSIGNED BINARY(4)	Number of target connection entries
132	84	UNSIGNED BINARY(4)	Offset to source connection entry
136	88	UNSIGNED BINARY(4)	Offset to first target connection entry
*	*	*	Source connection entry
*	*	*	Target connection entries

YASP0700 Connection Entry Format

Offset		Type	Field
Dec	Hex
0	0	CHAR(1)	Target ASP detached
1	1	CHAR(1)	Target ASP auto resume
2	2	CHAR(2)	Reserved
4	4	CHAR(8)	Geographic mirroring source copy node
12	C	CHAR(8)	Geographic mirroring target copy node
20	14	BINARY(4)	Geographic mirroring performance mode
24	18	BINARY(4)	Geographic mirroring copy data state
28	1C	BINARY(4)	Geographic mirroring copy state
32	20	BINARY(4)	Geographic mirroring resume priority
36	24	BINARY(4)	Geographic mirroring transmission delivery
40	28	BINARY(4)	Geographic mirroring transmission compression
44	2C	BINARY(4)	Geographic mirroring synchronization percent complete
48	30	BINARY(4)	Geographic mirroring suspend timeout
52	34	BINARY(8)	Geographic mirroring data in transit
60	3C	BINARY(8)	Geographic mirroring target data out of synchronization
68	44	BINARY(8)	Geographic mirroring total time to transmit
76	4C	BINARY(8)	Geographic mirroring number of operations in transit
84	54	CHAR(12)	Reserved

Field Descriptions

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

All units enlisted. A flag that indicates if all units in the ASP have enlisted. The possible values are:

0	Indicates that not all units for this ASP have enlisted.
1	Indicates that all units for this ASP have enlisted.

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 exists. A flag that indicates if ASP specified by Input ASP number exists. The possible values are:

0	Indicates that the ASP does not exist.
1	Indicates that the ASP does exist on this system and its lodestone is reported in.

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 values are:

0	There is no status. This value is used for the system ASP and any basic user ASPs.
1	The status of the ASP is varyoff.
2	The status of the ASP is varyon.
3	The status of the ASP is active.
4	The status of the ASP is available.

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 types are:

00	The ASP is the system ASP.
10	The ASP is a user ASP that does not contain libraries.
11	The ASP is a user ASP that does contain libraries.

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

0	The usage attribute does not apply or is not known. This value is used for the system ASP, any basic user ASPs and any independent ASPs whose use cannot be determined (eg, one whose disk drives are not powered on).
1	The ASP is a user-defined file system ASP.
2	The ASP is a primary ASP.
3	The ASP is a secondary ASP.

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

0	The disk unit is not in an availability parity set.
1	The 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:

1	Century, where 0 indicates years 19xx and 1 indicates years 20xx.
2-7	The date, in YYMMDD (year, month, day) format.
8-13	The time of day, in HHMMSS (hours, minutes, seconds) format.

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:

0	No balance activity has occurred for this ASP.
1	The ASP balance function is currently running for this ASP.
2	The ASP balance function is currently in the process of ending. Either the time limit has run out or the End ASP Balance (ENDASPBAL) command was issued for this ASP.
3	The ASP balance function has run, but was ended before the ASP was completely balanced. The Start ASP Balance (STRASPBAL) command can be used to restart the balance function.
4	The ASP balance function has completed running. The ASP is completely balanced.

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 are:

0	No ASP balance activity was requested for the ASP.
1	Capacity balancing. Capacity balancing redistributes data so that the percentage of disk space used is the same on all disk units within the ASP.
2	Usage balancing. Usage balancing redistributes data so that the percentage of disk activity is the same on all disk units within the ASP. High-use and low-use data is identified by running the Trace ASP Balance (TRCASPBAL) command. Usage balancing moves data among the disk units, guided by the trace results, in an attempt to equalize the utilizations.
3	Hierarchical Storage Management (HSM) balancing. HSM balancing can be run only on an ASP that contains a mixture of high-performance and low-performance disk units. An example of low-performance disk units is compressed disk units. The HSM balance function moves high-use data to high-performance units and moves low-use data to low-performance units. The high-use and low-use data is identified by running the Trace ASP Balance (TRCASPBAL) command.
4	Clear collection data. Clear collection data removes the trace data created by running the Trace ASP Balance (TRCASPBAL) command.
5	Move data. Move data is used to reduce the down time associated with removing a disk unit. The Check ASP Balance (CHKASPBAL) command can be used to determine which units are currently marked to no longer receive new allocations and to have their existing allocations moved to other disk units.
6	Media Preference (MP) balancing. MP balancing can be run only on an ASP that contains a mixture of Solid State Disk (SSD) units and Hard Disk Drive (HDD) units. The goal of the MP balance function is to have high-use data on SSD units and low-use data on HDD units. The high-use and low-use data is identified by running the Trace ASP Balance (TRCASPBAL) command.

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

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.

0	Not all changes were written.
1	All changes were written.

Cluster resource group name. is the name of the cluster resource group that controls the replication of the geographically mirrored IASP.

Cluster resource group site. The name of the cluster resource group site that contains the cluster node that owns the copy of the geographically mirrored IASP.

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

0	No compressed disk units in this ASP.
1	Compressed and uncompressed disk units in this ASP.
2	All disk units in this ASP are compressed.

Compressed unit. The compression attribute of the disk unit.

0	Data on the disk unit is not compressed.
1	Data on the disk unit is compressed.

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:

1	When the system detects that the ASP capacity is about to be exceeded, the system posts system reference code (SRC) A6xx 0277 in the system control panel and waits for a limited time for space to become available. If space becomes available before the limited time ends, the SRC is removed from the system control panel and normal operations resume. If space does not become available before the limited time ends, data overflows into the system ASP.
2	When the system detects that the ASP capacity is about to be exceeded, the data immediately overflows into the system ASP.
3	When the system detects that the ASP capacity is about to be exceeded, the system posts SRC A6xx 0277 in the system control panel and waits indefinitely for space to become available. The user must take action before normal operation resumes. Possible actions include deleting objects from the ASP or changing the compression recovery policy to a value that allows the ASP to overflow.

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

0	Compression for this disk unit is not active.
1	Compression for this disk unit is active.

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:

0	No storage protection has been set up for this disk unit.
1	This disk unit has been set up with mirrored protection.
2	This disk unit is part of a parity protection array.

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.

0	No disk units were found.
1	The disk unit that is used to provide the identity of the ASP was found but some other disk units were not found.
2	All disk units were found.

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.

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

0	The data in the ASP is not encrypted.
1	The data in the ASP is encrypted.

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

0	The data in the unit is not encrypted.
1	The data in the unit is encrypted.

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

0	If a request for space in the system ASP cannot be satisfied because there is not enough storage, the system will be allowed to continue running.
1	If a request for space in the system ASP cannot be satisfied because there is not enough storage, the system will be ended immediately.

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:

C9FF204000000000	Waiting for devices - none are present
C9FF208000000000	Waiting for devices - not all are present
C600450A00000000	DASD checker running
C600420402000000	Storage management recovery
C600420503000000	Synchronization of mirrored data
C600420400000000	Synchronization of mirrored data - 2
C600426006010000	Scanning DASD pages
C600426006020000	Directory recovery - permanent directory
C600405500000000	Authority recovery
C600405300000000	Context rebuild
C600405600000000	Journal recovery
C600405700000000	Database recovery
C600405800000000	Journal synchronization
C600405900000000	Commit recovery
C600406000000000	Database initialization
C600406100000000	Journal cleanup
C600406200000000	Commit initialization
C9FF408000000000	User profile creation
C9FF608000000000	UID/GID mismatch correction
C900297000000000	Library validation
C900297300000000	Database recovery - 1
C900297600000000	Journal recovery - 1
C9002AA500000000	POSIX directory recovery - 1
C9002AA100000000	Commit recovery
C9002AA200000000	Journal recovery - 2
C9002AA300000000	Database recovery - 2
C9FF808000000000	POSIX directory recovery - 2
C9002AB000000000	Database access path recovery
C9FFB08000000000	Database cross-reference - 1
C9FFC08000000000	Database cross-reference - 2
C90029B000000000	SPOOL initialization
C9FFF08000000000	File system mount
C9FFA08000000000	Command analyzer recovery
C9FFC00000000000	Database cross-reference - 3
C9FFD08000000000	Ending jobs using the ASP
C9FFD0C000000000	Waiting for jobs to end
C9FFE00000000000	File system unmount
C9FFE08000000000	Image catalog synchronization
C9FFE0C000000000	Writing changes to disk
0000000000000000	Unidentified activity

Geographically mirrored. The geographic mirroring configuration status for this ASP copy.

0	Geographic mirroring is not configured.
1	Geographic mirroring is configured.

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

0	Geographic mirroring is not configured.
1	The geographic mirroring target copy is absolutely in sync with its geographic mirroring source copy.
2	The geographic mirroring target copy contains usable data. A detached mirror copy always has a usable data state.
3	There is an incoherent data state on the mirror copy and the data cannot be used.

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

0	Geographic mirroring is not configured.
1	Active. Geographic mirroring is actively replicating.
2	Resume pending. The system attempts to perform geographic mirroring when the IASP is online.
3	Resuming. The system is resuming and the IASP is online and performing synchronization.
4	The geographic mirroring mirror copy is suspended and geographic mirroring is not being performed.

Geographic mirroring data in transit. The amount of data that has been queued up to send to the mirroring copy node, but has not yet been received by the mirror copy node. This is a value in bytes. This parameter is only valid for asynchronous transmission delivery mode.

Geographic mirroring number of operations in transit. The number of operations that has been queued up to send to the mirror copy node, but has not yet been received by the mirror copy node. This parameter is only valid for asynchronous transmission delivery mode.

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

-1	The performance mode is unknown.
0	There is no performance mode.
1	The performance mode is synchronous.
2	The performance mode is asynchronous.

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

-1	The priority is unknown.
0	There is no priority.
1	The priority is low.
2	The priority is medium.
3	The priority is high.

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

0	Geographic mirroring is not configured.
1	System does not own a physical IASP copy.
2	Geographic mirroring role is unknown.
196	System owns a detached mirror copy.
212	System owns the mirror copy.
215	System owns the production copy.

Geographic mirroring source copy node. The cluster node that owns the source copy of the geographically mirrored ASP. There can be 0 or 1 source copies for any geographic mirroring connection. The combination of source and target copy nodes can be used to describe the current geographic mirroring topology.

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

Geographic mirroring synchronization percent complete. The percent of synchronization complete to the mirror copy. A value of 100 indicates the mirror copy is completely synchronized.

Geographic mirroring target copy node. The cluster node that owns the geographic mirroring copy of the ASP. There may be between 0 and 3 target copies. If there is no target copy, then this node must be a mirror copy and will have one source copy. The combination of source and target copy nodes can be used to describe the current geographic mirroring topology.

Geographic mirroring target data out of synchronization. The number of bytes of auxiliary storage that are not synchronized in a geographic mirroring environment.

Geographic mirroring total time to transmit. Indicates the time in microseconds it takes to send a message to the mirror copy target node and receive a response.

Geographic mirroring tracking space allocated. The number of bytes of auxiliary storage that are reserved for tracking changes in a geographic mirroring environment. This tracking space is only relevant to the current or immediate target.

Geographic mirroring tracking space in use. The number of bytes of auxiliary storage that is currently being used to track changes in a geographic mirroring environment for the copy on this node only. The tracking space used is not affected by the number of target copies.

Geographic mirroring transmission compression. The compression method for geographic mirroring.

FE	Data is not compressed.
FF	Data compression is unknown.
00	Geographic mirroring is not configured.
01	Geographic mirroring synchronization data is being compressed.

Geographic mirroring transmission delivery. The delivery method for geographic mirroring.

-1	The transmission delivery is unknown.
0	Geographic mirroring is not configured.
1	Synchronous delivery.
2	Asynchronous delivery.

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

0	The disk unit is not in a Metro Mirror relationship with HyperSwap failover capability.
1	The disk unit is either the primary or secondary unit in a Metro Mirror relationship with HyperSwap failover capability.

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.

Last received operation identifier. Indicates the operation identifier for the last received operation.

Last received operation node. Indicates the operation node that is associated with the last received operation.

Lifetime 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 hex 01.

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

0	The unit does not support the lifetime remaining attribute.
1	The unit does support the lifetime remaining attribute.

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

0	The disk unit is not mirrored or the error does not relate to a specific disk unit.
1	The first half of a mirrored pair.
2	The second half of a mirrored pair.

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

0	One mirrored unit of a mirrored pair is not active.
1	Both mirrored units of a mirrored pair are active.

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

0	The mirrored unit is missing. Information concerning the unit may not be current.
1	The mirrored unit reported at the time this information was gathered. The information is current to that point in time.

Mirrored unit status. The mirrored status of the unit.

1	This mirrored unit of a mirrored pair is active (that is, online with current data).
2	This mirrored unit is being synchronized.
3	This mirrored unit is suspended.

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.

0	The disk unit has only one connection.
1	The disk unit has more than one connection.

Node name. The name of the cluster node that owns the geographically mirrored IASP.

Non-volatile memory express (NVMe). This field indicates whether or not this is an NVMe device.

0	It is not an NVMe device.
1	It is an NVMe device.

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.

Number of source connection entries. The number of source connection entries returned. There can be from 0 to 1 source entries in a geographic mirroring environment.

Number of target connection entries. The number of target connection entries returned. There can be from 0 to 3 target entries in a geographic mirroring environment.

Offset to first target connection entry. The offset in bytes from the beginning of the YASP0700 format to the first target connection entry.

Offset to source connection entry. The offset in bytes from the beginning of the YASP0700 format to the source connection entry. There may be 0 or 1 source connections in a multitarget geographic mirroring environment.

Oldest tracked operation identifier. Indicates the operation identifier for the oldest tracked operation. A value of 0 means that either no changes have been tracked or the tracking space allocated for the ASP is 0.

Oldest tracked operation node. Indicates the node that the oldest tracked operation is associated with. A value of "*NONE" means that either no changes have been tracked or the tracking space allocated for the ASP is 0.

Oldest tracked operation timestamp. Indicates the timestamp of the oldest tracked operation. This timestamp is useful to know how far back in time that changes are being tracked. A value of hex 0's indicates that either no changes have been tracked or the tracking space allocated for the ASP is 0.

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.

0	All overflowed storage was successfully moved.
1	ASP overflow recovery failed due to insufficient space in the user ASP.
2	ASP overflow recovery was cancelled prior to completion.

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.

Path status. The status of the path to a disk unit.

0	Unknown/Non-multipath unit.
1	Active path. The path is connected to the disk unit and is used when reading and writing to the associated disk unit.
2	Passive path. The path is connected to the disk unit but is not used when reading or writing to the associated disk unit. This path is a backup in case an active path fails.

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:

0	No storage protection has been set up for this disk unit.
5	This disk unit has been set up with RAID 5 protection.
6	This disk unit has been set up with RAID 6 protection.

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. This field must be set to hexadecimal or binary zero.

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.

Serial 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.

Size of a connection entry. The size of a connection entry. This is a value in bytes.

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

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.

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

Solid-state drive (SSD). Indicates whether or not this is a SSD.

0	It is not a SSD.
1	It is a SSD.

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

0	The disk unit does not allow new storage allocations.
1	The disk unit allows new storage allocations.

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.

Target ASP auto resume. Indicates if the target geographically mirrored ASP indicated by the target copy node field will be automatically resumed by the operating system.

Target ASP detached. Indicates if the target geographically mirrored ASP indicated by the target copy node field has a current role of detached.

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

0	The unit is not thinly provisioned.
1	The unit is part of an external storage box and has more storage assigned to it than it has physically available.

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:

1	Century, where 0 indicates years 19xx and 1 indicates years 20xx.
2-7	The date, in YYMMDD (year, month, day) format.
8-13	The time of day, in HHMMSS (hours, minutes, seconds) format.

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:

0	There is no current trace data for this ASP.
1	The trace function is currently running for this ASP.
2	The trace function is currently in the process of ending. Either the time limit has run out or the trace was stopped through use of the Trace ASP Balance (TRCASPBAL) command.
3	The trace function has completed running. The statistics for the ASP have been gathered and are ready for the balance function to start.
4	The trace data for this ASP is being cleared.
5	The trace function has completed and the statistics for the ASP have been gathered. The ASP is ready for further collection or for the balance function to start.

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:

00	The ASP is not in a state transition.
01	The ASP is in the process of making an upward transition to the varyon state.
02	The ASP is in the process of making an upward transition to the active state.
03	The ASP is in the process of making an upward transition to the available state.
04	The ASP is in the process of making a downward transition to the active state.
05	The ASP is in the process of making a downward transition to the varyoff state.

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

0	There is no unit control value.
1	The disk unit is active.
2	The disk unit has failed.
3	Some other disk unit in the disk subsystem has failed.
4	There is a hardware failure within the disk subsystem that affects performance, but does not affect the function of the disk unit.
5	There is a hardware failure within the disk subsystem that does not affect the function or performance of the disk unit.
6	The disk unit's parity protection is being rebuilt.
7	The disk unit is not ready.
8	The disk unit is write protected.
9	The disk unit is busy.
10	The disk unit is not operational.
11	The disk unit has returned a status that is not recognizable by the system.
12	The disk unit cannot be accessed.
13	The disk unit is read/write protected.

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

0	Objects in the ASP are being used through library-based access, through the Integrated File System or both.

Version. The version of objects in an independent ASP.

0	Objects are usable by a system at release level V5R1M0.
1	Objects are usable by a system at release level V5R2M0.
2	Objects are usable by a system at release level V5R3M0.
3	Objects are usable by a system at release level V5R4M0.
4	Objects are usable by a system at release level V6R1M0.
5	Objects are usable by a system at release level V7R1M0.
6	Objects are usable by a system at release level V7R2M0.
7	Objects are usable by a system at release level V7R3M0.
8	Objects are usable by a system at release level V7R4M0.
9	Objects are usable by a system at release level V7R5M0.

Format of Filter Information

Offset		Type	Field
Dec	Hex
0	0	BINARY(4)	Size of filter entry
4	4	BINARY(4)	Filter key
8	8	BINARY(4)	Size of filter data
12	C	CHAR(*)	Filter data

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:

0	No ASPs are selected. If the requested format is YASP0300, disk unit records are returned for those disk units that are not assigned to an ASP. For all other formats, no records are returned.
-1	All ASPs are selected.
-2	All user ASPs are selected.
-3	All independent ASPs are selected.

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:

Entry size	Key	Data size	Filter data
16	1	BINARY(4)	ASP number
24	2	CHAR(10)	Resource name
24	3	CHAR(10)	Device description name
32	4	CHAR(18)	Database name

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

Format of Sort Information

Offset		Type	Field
Dec	Hex
0	0	BINARY(4)	Number of keys to sort on
Offsets vary. These fields repeat for each sort key field.		BINARY(4)	Sort key field starting position
		BINARY(4)	Sort key field length
		BINARY(2)	Sort key field data type
		CHAR(1)	Sort order
		CHAR(1)	Reserved

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.

-1	The list of jobs threads are order by ASP number, job name, job user name, job number, thread identifier and use identification. This parameter is only used with format YASP0600.

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.

1	Sort in ascending order.
2	Sort in descending order.

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.
GUI0002 E	&1 is not valid for length of receiver variable.
GUI0027 E	&1 is not valid for number of records to return.
GUI0141 E	Filter specification is not valid.
GUI0149 E	&1 is not valid for number of keys to sort on.

---

API introduced: V4R4

---

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