Description

The IOSADMF macro provides an interface for the movement of large amounts of data between main and expanded storage.

Environment

The requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	Supervisor state or program key mask (PKM) allowing keys 0-7.
Dispatchable unit mode:	Task or SRB mode for AREAD, AWRITE, and AQUERY requests. Task mode only for APURGE requests.
Cross memory mode:	PASN=HASN=SASN
AMODE:	31-bit
ASC mode:	Primary
Interrupt status:	Enabled for I/O and external interrupts
Locks:	No locks held
Control parameters:	Control parameters must be in the primary address space.

Programming requirements

The caller's parameter list and range list must be in the primary address space.

Restrictions

For IOSADMF APURGE requests, the caller may not have an EUT FRR established.

Input register information

Before issuing the IOSADMF macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.

Output register information

When control returns to the caller, the GPRs contain:

Register: Contents
0: Reason code
1: Used as a work register by the system.
2-14: Unchanged
15: Return code

When control returns to the caller, the access registers (ARs) contain:

Register: Contents
0-1: Used as work registers by the system.
2-13: Unchanged
14-15: Used as work registers by the system.

Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.

Performance implications

Using IOSADMF to move large amounts of data between central and expanded storage is more efficient than synchronous methods of moving data.

Syntax

The standard form of the IOSADMF macro is written as follows:

Syntax	Description

`name`	`name`: symbol. Begin `name` in column 1.

␢	One or more blanks must precede IOSADMF.

IOSADMF

␢	One or more blanks must follow IOSADMF.

APURGE
AREAD
AWRITE
AQUERY

,ALET=`alet-addr`	`alet-addr`: RX-type address or register (2) - (12).

,NUMRANGE=`n`	`n`: Number from 1 to 125.
,NUMRANGE=`num-addr`	`num-addr`: RX-type address or register (2) - (12). Default: NUMRANGE=1.

,RANGLIST=`list-addr`	`list-addr`: RX-type address or register (2) - (12).

,FAILBLKP=`fail-addr`	`fail-addr`: RX-type address or register (2) - (12).

,CROSSOVER=`cross-addr`	`cross-addr`: RX-type address or register (2) - (12).

,RETCODE=`ret-addr`	`ret-addr`: RX-type address or register (2) - (12).

,RSNCODE=`rsn-addr`	`rsn-addr`: RX-type address or register (2) - (12).

,MF=S

Table 1. Parameters Valid with IOSADMF Requests
Parameters	APURGE	AREAD	AWRITE	AQUERY
ALET	required	required	required	not valid
NUMRANGE	not valid	optional	optional	not valid
RANGLIST	not valid	required	required	not valid
FAILBLKP	not valid	optional	optional	not valid
CROSSOVER	not valid	not valid	not valid	optional
RETCODE	optional	optional	optional	optional
RSNCODE	optional	optional	optional	optional
MF	optional	optional	optional	optional

Parameters

The parameters are explained as follows:

APURGE

AREAD

AWRITE

AQUERY

Specifies the type of request, as follows: APURGE requests that the system purge any active AREAD or AWRITE operation for the hiperspace represented by the ALET.

AREAD requests that the system transfer data from a hiperspace to an address space.

AWRITE requests that the system transfer data from an address space to a hiperspace.

AQUERY requests that the system check to determine whether ADMF (asynchronous data mover facility) is installed. If ADMF is installed, the system returns a return code of 0. If ADMF is not installed, the system returns a return code of 8 with a corresponding reason code.

,ALET=alet-addr

Specifies either the address of a fullword or a register that contains the ALET associated with the hiperspace that is the target of an APURGE, AREAD, or AWRITE request.

,NUMRANGE=n

,NUMRANGE=num-addr

Specifies the number of entries in the range list in one of the following formats:

A decimal digit from 1 through 125
A fullword that contains the number of entries
A register that contains the address of a fullword that contains the number of entries.

The default is NUMRANGE=1.

,RANGLIST=list-addr

Specifies a fullword that contains the address of a list of ranges (up to 125), or specifies a register that contains the address of the fullword pointer to the range list. The list of ranges specifies one or more virtual storage ranges that are to be moved. The range list consists of a number of entries (specified by NUMRANGE), where each entry consists of three words:

First word: The starting virtual address in the address space into which the data is to be read or from which data is to be written.
Second word: The starting virtual address in the hiperspace from which the system is to read or into which the system is to read.
Third word: The number of blocks the system is to read from the hiperspace or write from the address space.

For example, if your register and storage are set up as in Figure 1, you can code the RANGLIST parameter and NUMRANGE parameter as follows:

Figure 1. RANGLIST and NUMRANGE Parameters

The range list must be in the caller's primary address space.

,FAILBLKP=fail-addr

Specifies a fullword that contains the address of a range list entry, or specifies a register that contains the address of the fullword pointer to a range list entry, for which a failure occurred. The system returns this value only when you code FAILBLKP and when the system can identify the failing range list entry.

When the system returns a return code 8 and fail-addr contains a non-zero value, the entry identified by fail-addr is either partially processed, or not processed and any subsequent range list entries are not processed. However, any prior range list entries processed successfully.

fail-addr contains a non-zero value only when the failing range list is known. The reason codes indicate when fail-addr is set.

,CROSSOVER=cross-addr

Specifies a fullword or register in which the system is to place the system-implemented crossover value. If the number of pages requested to be moved is greater than the CROSSOVER value, the system moves the data asynchronously with the ADMF. If you invoke IOSADMF when the number of pages is less than the crossover value, the system uses the move page facility to move the data.

You can request this value to determine whether using the ADMF is warranted for particular data movement.

,RETCODE=ret-addr

Specifies the location where the system is to store the return code. The return code is also in GPR 15.

,RSNCODE=rsn-addr

Specifies the location where the system is to store the return code. The reason code is also in GPR 0.

,MF=S

Specifies the standard form of the macro. This form generates code to place the parameters into an inline parameter list and invoke the macro service.

ABEND codes

None.

Return and reason codes

When the IOSADMF macro returns control to the caller, GPR 15 (and ret-addr, if you coded RETCODE) contains a return code and GPR 0 (and rsn-addr, if you coded RSNCODE) contains a reason code.

The reason code consists of four bytes; the third byte contains a value that indicates where the error occurred. The third byte contains X'01' when the error occurred in an address space; it contains X'02' when the error occurred in a hiperspace.

Table 2. Return and Reason Codes for the IOSADMF Macro
Hexadecimal Return Code	Hexadecimal Reason Code	Meaning and Action
00	—	Meaning: The IOSADMF operation completed successfully. For an AQUERY request, return code 0 indicates that the ADMF is installed. Action: None.
04	xx0101xx	Meaning: System error. The IOSADMF operation failed because of a communication error. The request was started, but the system stopped the request because of an error condition. The failure occurred in the storage area whose address is in the first word of the input range list entry. FAILBLKP contains the address of the range list entry for which the failure occurred. Action: Either retry the operation using IOSADMF or use the HSPSERV macro. If you still get the same error, record the return and reason codes; contact hardware support.
04	xx0202xx	Meaning: System error. The IOSADMF operation failed because of a communication error. The request was started, but the system stopped the request because of an error condition. The failure occurred in the storage whose address is in the second word of the input range list entry. FAILBLKP contains the address of the range list entry for which the failure occurred. Action: Either retry the operation using IOSADMF or use the HSPSERV macro. If you still get the same error, record the return and reason codes; contact hardware support.
04	xx0301xx	Meaning: Program error. A specified address identified an area in an address space for which the caller is not authorized. A protection exception was encountered. The failure occurred in the storage area whose address is in the first word of the input range list entry. FAILBLKP contains the address range list entry for which the failure occurred. Action: Either specify the address of an address space that the user has the authority to access, or obtain adequate authority to use the specified address. Retry the operation using IOSADMF or use the HSPSERV macro.
04	xx0501xx	Meaning: Program error. An error occurred during address translation. The request cannot be completed at the current time because an address space page was not valid. Either the address in the first word of the input range list entry was not correct or identified an area that was not backed. The failure occurred in the storage area whose address is in the first word of the input range list entry. FAILBLKP contains the range list entry for which the failure occurred. Action: Either retry the operation using IOSADMF or use the HSPSERV macro. Ensure that all the pages that are to be used are page fixed.
04	xx0502xx	Meaning: Program error. An error occurred during address translation. The request cannot be completed at the current time because a hiperspace page was not valid. Either the hiperspace in the second word of the input range list entry was not correct or identified an area that was reclaimed by the system. The failure occurred in the storage area whose address is in the second word of the input range list entry. FAILBLKP contains the address of a range list entry for which the failure occurred. Action: Use the HSPSERV macro to restore the hiperspace page.
04	xx0601xx	Meaning: System error. An uncorrectable storage error occurred at either the source or destination of the data move. The failure occurred in the storage area whose address is in the first word of the input range list entry. FAILBLKP contains the range list entry for which the failure occurred. Action: Either retry the operation using IOSADMF or use the HSPSERV macro. If you still get the same error, record the return and reason codes; contact hardware support.
04	xx0702xx	Meaning: System error. An uncorrectable storage error occurred at either the source or destination of the data move. The failure occurred in the storage area whose address is in the second word of the input range list entry. FAILBLKP contains the range list entry for which the failure occurred. Action: Either retry the operation using IOSADMF or use the HSPSERV macro. If you still get the same error, record the return and reason codes; contact hardware support.
04	xx0Cxxxx	Meaning: System error. An uncorrectable storage error occurred at either the source or destination of the data move. The system could not determine whether the error occurred in the address space storage or the hiperspace storage. FAILBLKP contains the range list entry for which the failure occurred. Action: Either retry the operation using IOSADMF or use the HSPSERV macro. If you still get the same error, record the return and reason codes; contact hardware support.
08	xx31xxxx	Meaning: Environmental error. The ADMF is not installed on the current system. The ADMF cannot be used until both hardware and software are installed and the operating system is IPLed. Action: Retry the operation using the HSPSERV macro instead of the IOSADMF macro.
08	xx32xxxx	Meaning: System error. The asynchronous data mover facility is not available. The system detected an unrecoverable error. Action: Use the HSPSERV macro instead of IOSADMF and rerun the program. Record the return and reason codes; contact hardware support.
08	xx34xxxx	Meaning: Program error. The calling program does not meet one or more of the environmental requirements for using IOSADMF. Action: Ensure that the IOSADMF macro is issued in the required environment. See in Environment.
08	xx35xxx	Meaning: Program error. Either no option (AWRITE, AREAD, APURGE, or AQUERY) was specified on the IOSADMF macro, or more than one option was specified. This error can occur if the parameter list is overlaid. Action: Make sure the IOSADMF macro invocation specifies one option and rerun the program.
08	xx36xxxx	Meaning: Program error. The specified ALET is incorrect. The ALET did not designate a hiperspace, or the ALET is not on the caller's access list. Action: Make sure the ALET is valid and rerun the program.
08	xx37xxxx	Meaning: Program error. The range count is not valid. The NUMRANGE value specified is either less than 1 or greater than 125. Action: Specify a NUMRANGE value from 1 through 125 and rerun the program.
08	xx38xxxx	Meaning: Program error. An input parameter list could not be addressed, or an error occurred during a reference to a range list entry. The RANGLIST parameter may be specified incorrectly. Action: Ensure RANGLIST is specified correctly, and NUMRANGE is a valid value, and rerun the program.
08	xx39xxxx	Meaning: Program error. An error occurred during the processing of a RANGLIST entry address. FAILBLKP contains the address of the failing entry. Action: Ensure the following: The RANGLIST parameter is correctly specified The address on the RANGLIST parameter is correct The NUMRANGE value reflects the actual number of NUMRANGE entries. The NUMRANGE value is from 1 though 125. Rerun the program.
08	xx3Axxxx	Meaning: System error. This return and reason code combination is for IBM® diagnostic purposes only. Action: Record the return and reason codes and supply them to the IBM Support Center.
08	xx3Bxxxx	Meaning: Program error. The calling program does not meet one or more of the environmental requirements for using IOSADMF. Action: Ensure IOSADMF is issued in the required environment. See in Environment.
08	xx3Cxxxx	Meaning: Program error. An incorrect version of the ADMF was specified. The current version is 1. This error can occur if the parameter list is overlaid. Action: Contact your software support.
08	xx3Exxxx	Meaning: Program error. The reserved fields in XFLAGS, XRESERVED1, or XRESERVED2 are not zero. These fields must be set to zero before the IOSADMF macro can be invoked. Action: See the IOSADMF macro expansion. Correct the parameter list and rerun the program.
08	xx40xxxx	Meaning: Program error. The caller attempted to access a hiperspace using the IOSADMF macro, but the hiperspace is in the process of being deleted. The access request is rejected. Action: Specify the ALET of another hiperspace and reissue the IOSADMF request.
08	xx41xxxx	Meaning: System error. This return and reason code combination is for IBM diagnostic purposes only. Action: Record the return and reason codes and supply them to the IBM Support Center.
0C	xx51xxxx	Meaning: System error. This return and reason code combination is for IBM diagnostic purposes only. Action: Record the return and reason codes and supply them to the IBM Support Center.
0C	xx52xxxx	Meaning: System error. This return and reason code combination is for IBM diagnostic purposes only. Action: Record the return and reason codes and supply them to the IBM Support Center.
0C	xx53xxxx	Meaning: System error. This return and reason code combination is for IBM diagnostic purposes only. Action: Record the return and reason codes and supply them to the IBM Support Center.