ASEXT — Extract address space parameters

Description

The ASEXT macro returns to the caller the address of a copy of a parameter string that the creating program made available at the time it created the primary address space. Use this macro only if the primary address space was created through the ASCRE macro and you specified the ASPARM parameter on the ASCRE macro.

Environment

The requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	Supervisor state
Dispatchable unit mode:	Task or SRB
Cross memory mode:	PASN=HASN or PASN¬=HASN
AMODE:	24-bit or 31-bit. To reference the copy of the parameter string, the user must be in 31-bit addressing mode.
ASC mode:	Primary or AR
Interrupt status:	Enabled for I/O and external interrupts
Locks:	No locks held
Control parameters:	Must be in the primary address space

Programming requirements

The caller must not have an enabled unlocked task (EUT) functional recovery routine (FRR) established.

Restrictions

None.

Register information

After the caller issues the macro, the system might use some registers as work registers or might change the contents of some registers. When the system returns control to the caller, the contents of these registers are not the same as they were before the macro was issued. Therefore, if the caller depends on these registers containing the same value before and after issuing the macro, the caller must save these registers before issuing the macro and restore them after the system returns control.

When control returns to the caller, the general purpose registers (GPRs) contain:

Register: Contents
0: Reason code, described in Return and reason codes.
1: Address of the extracted parameter string if the return code is 0; otherwise, contains a 0.
2-13: Unchanged
14: Used as a work register by the system
15: Return code, described in Return and reason codes

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

Register: Contents
0: Used as a work register by the system.
1: AR 1 contains a 0, which indicates that the parameter string copy is addressable in the primary address space.
2-13: Unchanged
14-15: Used as work registers by the system

Performance implications

None.

Syntax

The syntax of the ASEXT macro is as follows:

Syntax	Description

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

␢	One or more blanks must precede ASEXT.

ASEXT

␢	One or more blanks must follow ASEXT.

ASPARM

,RELATED=`value`	`value`: Any valid macro parameter specification.

Parameters

The parameters are explained as follows:

ASPARM: Requests the address of a copy of the parameter string (including the halfword length field) that the creator of the address space specified on the ASPARM parameter on the ASCRE macro. ASPARM is required.
,RELATED=value: Specifies information used to self-document macros by “relating” functions or services to corresponding functions or services. The format and contents of the information specified are at the discretion of the user, and may be any valid coding values.

Return and reason codes

When ASEXT macro returns control to your program, GPR 15 contains a return code and GPR 0 contains a reason code.

Table 1. Return and Reason Codes for the ASEXT Macro
Decimal Return Code	Decimal Reason Code	Meaning
00	00	Meaning: The ASEXT service has completed successfully.
08	04	Meaning: The caller is not in supervisor state.
08	08	Meaning: The caller is not enabled.
08	12	Meaning: The caller is not in task mode.
08	16	Meaning: The caller is not unlocked.
08	20	Meaning: GPR 0 on input has an invalid function code.
08	24	Meaning: ASEXT is unable to establish recovery.
12	04	Meaning: GPR 1 has an invalid extract code on input.
16	04	Meaning: An unexpected error occurred while ASEXT was in progress.