 |
The ASCRE macro creates an address space. The caller of ASCRE can
establish cross memory linkages between the creating address space
and the created address space. In this macro description, the created
address space is called the “new” address space.
Use the INIT parameter to specify an address space initialization
routine that runs in the new address space. The initialization routine
performs such actions as loading modules into the new address space
and building control blocks there.
Use either the ASNAME or STPARM parameter to name the new address
space and specify the first program that will run after the initialization
routine completes. This first program has all system services available
to it.
Optionally, you can use the AXLIST, TKLIST, and LXLIST parameters
to set up cross memory linkages that allow programs in the new address
space to use the services of programs in the creator's address space. - AXLIST specifies the location of a list of authorization index
(AX) values that the caller obtained through AXRES.
- TKLIST specifies the location of the list of tokens that represents
the entry tables built by the creating address space.
- LXLIST specifies the location of a list of linkage index (LX)
values that the caller obtained through LXRES.
Environment
The requirements for the caller are:
| Environmental factor |
Requirement |
|---|
| Minimum authorization: |
Supervisor state |
| Dispatchable unit mode: |
Task |
| Cross memory mode: |
PASN=HASN or PASN¬=HASN |
| AMODE: |
Any |
| ASC mode: |
Primary or AR |
| Interrupt Status: |
Enabled for I/O and external interrupts |
| Locks: |
No locks held |
| Control parameters: |
For callers in primary mode, control parameters
must be in the primary address space. |
| |
For callers in AR address space control (ASC)
mode, the parameters can be in the primary address space (qualified
by an ALET of 0) or in any space addressable through public entries
in the caller's dispatchable unit access list (DU-AL). |
Programming requirements
The caller in AR ASC mode must have issued SYSSTATE ASCENV=AR to
tell ASCRE to generate code and addresses appropriate for callers
in AR mode.
Restrictions
The caller must not have an enabled unlocked task (EUT) functional
recovery routine (FRR) established.
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
- 1
- If the return code is 4, GPR 1 contains the address of the ASCB
for the new address space. Otherwise, GPR 1 is used as a work register
by the system.
- 2-13
- Unchanged
- 14
- Used as a work register by the system
- 15
- Return code
When control returns to the caller, the access registers (ARs)
contain: - Register
- Contents
- 0
- Used as a work register by the system
- 1
- Contains a 0 if the return code is 4; otherwise, used as a work
register by the system.
- 2-13
- Unchanged
- 14-15
- Used as work registers by the system
See z/OS MVS Programming: Extended Addressability Guide for
information on initializing address spaces. It also gives an example
of coding the ASCRE macro.
Other implications
A task started under JES2 using the default IEESYSAS proc will
have a jobname of IEESYSAS in the JES2 $DS(sss),
where sss is the started task number. The SDSF
panel DA will also show a jobname of IEESYSAS. The stepname, however,
will be that of the started task. The z/OS® command-
D A,L will show both a jobname and stepname of the started task.
Syntax
The standard form of the ASCRE macro is written as follows:
| Syntax |
Description |
|---|
| |
|
| name |
name: Symbol. Begin name in
column 1. |
| |
|
| ␢ |
One or more blanks must precede ASCRE. |
| |
|
| ASCRE |
|
| |
|
| ␢ |
One or more blanks must follow ASCRE. |
| |
|
| ASNAME=as name |
as name: One to eight characters,
enclosed in apostrophes. |
| STPARM=start parm addr |
start parm addr: RX-type address
or register (2) - (12). |
| |
|
| ,INIT=init rtn name |
init rtn name: One to eight
characters, enclosed in apostrophes. |
| ,INIT=init rtn name addr |
init rtn name addr: RX-type
address or register (2) - (12). |
| |
|
| ,ODA=output data addr |
output data addr: RX-type address
or register (2) - (12). |
| |
|
| ,TRMEXIT=term rtn addr |
term rtn addr: RX-type address
or register (2) - (12). |
| |
|
| ,UTOKEN=user token addr |
user token addr: RX-type address
or register (2) - (12). |
| |
Note: Specify UTOKEN only if you specify
TRMEXIT. |
| |
|
| ,ASPARM=parm area addr |
parm area addr: RX-type address
or register (2) - (12). |
| |
|
| ,ATTR=attribute list |
attribute list: List of attributes,
separated by commas. |
| |
|
| ,AXLIST=ax list addr |
ax list addr: RX-type address
or register (2) - (12). |
| |
|
| ,TKLIST=token list addr |
token list addr: RX-type address
or register (2) - (12). |
| |
Note: When you specify TKLIST, specify
LXLIST also. |
| |
|
| ,LXLIST=lx list addr |
lx list addr: RX-type address
or register (2) - (12). |
| ,ELXLIST=lx list addr |
elx list addr: RX-type address
or register (2) - (12). |
| |
Note: Specify LXLIST only if you specify
TKLIST. |
| |
|
| ,RELATED=value |
value: Any valid macro parameter
specification. |
| |
|
Parameters
The parameters are explained as follows:
- ASNAME=as name
- STPARM=start parm addr
- Specifies either the name of the new address space or the address
of a parameter string that is input to an internal START command.
You must specify either STPARM or ASNAME. Use ASNAME if you are adding
a procedure to SYS1.PROCLIB and you are not passing parameters to
JCL.
ASNAME specifies the address space name (the same as
the name of the procedure in SYS1.PROCLIB that specifies the first
program to execute in the new address space.) The operator uses this
name to issue certain commands, such as the DISPLAY command that displays
information about the address space. The name must consist of 1 to
8 characters, enclosed by apostrophes. The first character must be
alphabetic or national (#, $, or @); other characters can be alphabetic,
national, or numeric.
STPARM specifies the address of
a parameter string that is input to an internal START command that
the system uses to start the address space. The string consists of
a two-byte length field, followed by up to 124 bytes of parameter
data. The length field identifies the length of the parameter data
(not including the length field itself). The parameter data consists
of START command parameters, for example “GTF,,,JES2”. Data must
begin with the address space name, which corresponds to the procedure
in SYS1.PROCLIB that specifies the first program that is to execute
in the new address space.
If you do not need special DD definitions
for data sets, specify the common system address space procedure IEESYSAS.
In the parameter data, specify the system-defined procedure IEESYSAS
in the following format: IEESYSAS.x,PROG=y
where: - x is name of the address space.
- y is the name of the first program to execute
in the new address space.
- ,INIT=init rtn name
- ,INIT=init rtn name addr
- Specifies the name of the address space initialization routine
or the address of the name. The name is a string of up to eight alphanumeric
characters; if you specify init rtn name, you must
enclose the name in apostrophes. The first character of the name must
be alphabetic or national; other characters can be alphabetic, national,
or numeric. If the name is less than eight characters, left-justify
the name and pad with blanks on the right to make up the eight characters.
The
routine, which performs functions such as loading modules, must reside
in either the LPA (PLPA, MLPA, fixed LPA) or in a library in the LNKLST
concatenation. If the routine uses the two ECBs (EAERIMWT and EAEASWT)
that the system provides for communication between the creating address
space and the initialization routine, the routine must be in 31-bit
addressing mode.
INIT is a required parameter. If you do not
need an initialization routine, you can specify the dummy module IEFBR14
on the INIT parameter.
- ,ODA=output data addr
- Specifies the address of a 24-byte area that contains output information
from the ASCRE macro. The output information, mapped by the macro
IHAASEO, consists of:
- Eight bytes for the STOKEN of the new address space
If you
use the ASDES macro to terminate the new address space, you can obtain
the STOKEN from this field.
- Four bytes for the address of the ASCB of the new address space
- Four bytes for the address of the two contiguous ECBs (EAERIMWT
and EAEASWT).
The creator of the address space and the new address
space can use these two ECBs for communicating and synchronizing.
They are mapped by IEZEAECB. A program must be in 31-bit addressing
mode when it references them.
- Eight bytes (not part of the programming interface)
ODA is required.
- ,TRMEXIT=term rtn addr
- Specifies the address of the termination routine that gets control
when the new address space terminates. The routine receives control
in 31-bit addressing mode as an asynchronous exit in the creator's
address space under the creator's TCB. If you specify UTOKEN, on
entry to the routine, register 1 contains the address of a copy of
the token specified by the UTOKEN parameter.
On entry to the routine: - GPR 1 contains the address of a copy of the 64-bit token that
the UTOKEN parameter supplies.
- GPR 13 contains the address of a standard 18-word save area.
- GPR 14 contains the return address.
- GPR 15 contains the entry point address.
If you specify TRMEXIT, you can also specify UTOKEN.
- ,UTOKEN=user token addr
- Specifies the address of a 64-bit token of your choice that the
termination routine can use to identify the new address space. Do
not specify UTOKEN unless you specify TRMEXIT. If you specify TRMEXIT
without specifying UTOKEN, the termination routine does not have the
user data.
- ,ASPARM=parm area addr
- Specifies the address of a parameter string that the new address
space can obtain through the ASEXT macro. The parameter string consists
of a halfword length field, followed by up to 254 bytes of parameter
data. The length field contains the length of the parameter data
(not including the length field itself).
- ,ATTR=attr
- Specifies some attributes of the new address space. Attributes
specified on the execute form of the ASCRE macro are added to the
options specified on the list form.
Options for the ATTR parameter
are as follows:
- JOBSPACE
- The address space is to be marked as a "job" (started task) address
space, instead of as a "system" address space.
- NONURG
- Specifies that the address space will be used by nonurgent services.
Specify either NONURG or HIPRI. NONURG is the default.
- HIPRI
- Indicates that the address space is for a high-priority service.
Specify either NONURG or HIPRI. NONURG is the default.
- PERM
- Specifies that the system does not terminate the new address space
when the TCB that represents the creating program terminates. If
you do not specify PERM, the system terminates the new address space
when it terminates the TCB.
- ,NOMT
- The address space may not be memtermed unless a DAT error occurs.
If a DAT error does occur then the recovery action is controlled by
the NOMD option. If an unrecoverable error occurs for an address
space created with NOMT the entire system is placed into a wait state.
This
specification does not prevent the ASDES service from forcing the
termination of the address space.
- ,NOMD
- The address space may not be memtermed on a DAT error.
This
option is honored only if NOMT is also specified. If a DAT error
occurs for an address space created with NOMD the entire system is
placed into a wait state.
- ,1LPU
- The address space must have all private area long-term fixed pages
assigned to preferred (nonreconfigurable and non-V=R) storage frames.
This
option is the same as specifying LPREF for a program on a PPT definition.
- ,2LPU
- The address space must have all private area short-term fixed
pages assigned to preferred (nonreconfigurable and non-V=R) storage
frames.
This option is the same as specifying SPREF for a program
on a PPT definition.
- ,N2LP
- The address space does not need to have all private area short-term
fixed pages assigned to preferred storage frames. That is, the program's
short-term fixes are in fact short-term fixes and can be allowed in
reconfigurable storage.
This option is the same as specifying NOPREF
for a program on a PPT definition.
- ,PRIV
- The address space is privileged.
A task marked PRIV is put in
the SYSSTC service class if it is not explicitly classified in the
WLM classification rules.
- ,NOSWAP
- The address space is non-swappable.
- ,CANCEL
- The address space jobstep can be canceled after the ASCRE initialization
routine is completed.
- ,REUSASID
- The address space is assigned to a reusable ASID, if REUSASID(YES)
was specified in parmlib member DIAGxx. For more information about
reusing ASIDs, see z/OS MVS Programming: Extended Addressability Guide.
- ,AXLIST=ax list addr
- Specifies the address of a list of halfwords containing the AX
values for the new address space. These values determine the PT and
SSAR authority for programs. (This list was obtained through the AXRES
macro.) The first entry in the list describes the number of AX values
in the list (from 1 to 32).
Using this parameter has the same effect
as a program in the new address space issuing the ATSET macro once
for each AX value in the list.
- ,TKLIST=token list addr
- Specifies the address of a list of fullword tokens that represent
the entry tables that the system is to connect to the linkage table
of the new address space. The first entry in the list describes the
number of token values that follow (from 1 to 32). The ETCRE macro
returned these tokens in register 0. Using this parameter has the
same effect as a program in the new address space issuing the TKLIST
parameter on the ETCON macro.
When you specify TKLIST, you must
also specify LXLIST.
- ,LXLIST=lx list addr
- ,ELXLIST=elx list addr
- lx list addr specifies the address of
a list of values that represent indexes into the linkage table. Each
linkage index (LX) value represents an entry in the linkage table.
The system connects the entry tables specified by the TKLIST parameter
to the LX values specified in this list. The first entry in the list
must be the number of LX values that follow (from 1 to 32). The number
of LX values must be the same as the number of entry table tokens.
Using this parameter has the same effect as a program in the new
address space issuing the LXLIST parameter on the ETCON macro.
elx
list addr specifies the address of an area that contains
extended linkage index (LX) values returned by the ELXLIST parameter
of LXRES. The first word in the area must be the number of extended
LX values that follow (from 1 to 32). Each subsequent eight bytes
contains an extended LX value, which consists of a 4-byte sequence
number followed by an LX value. Each extended linkage index value
represents an entry in the linkage table. The system connects the
entry tables specified by the TKLIST parameter to the extended LX
values specified in this list. The number of extended LX values must
be the same as the number of entry table tokens. Using this parameter
has the same effect as a program in the new address space issuing
the ELXLIST parameter on the ETCON macro.
When you specify
TKLIST, you must also specify either LXLIST or ELXLIST.
- ,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
The following table gives the return codes from register 15 and
the associated reason codes from register 0.
Table 1. Return and Reason
Codes for the ASCRE Macro| Decimal Return Code |
Decimal Reason Code |
Meaning |
|---|
| 00 |
00 |
Meaning: The address space has been created.
Data has been returned in the output data area. |
| 00 |
04 |
Meaning: The address space creation has
been scheduled. Data has been returned in the output data area. |
| 04 |
04 |
Meaning: The address space has been created;
there was an error accessing the ODA. |
| 04 |
08 |
Meaning: The address space creation has
been scheduled; there was an error accessing ODA. |
| 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 has an invalid function
code on input. |
| 08 |
24 |
Meaning: ASCRE could not establish recovery. |
| 12 |
04 |
ASCRE cannot reference the parameter list. |
| 12 |
08 |
Meaning: The version number in the parameter
list is not valid. |
| 12 |
12 |
Meaning: The reserved field in the parameter
list is not 0. |
| 16 |
04 |
Meaning: ASCRE cannot reference the INIT
parameter. |
| 16 |
08 |
Meaning: The initialization routine is
not specified or is specified incorrectly. |
| 20 |
04 |
Meaning: ASCRE cannot reference the STPARM
or ASNAME parameter. |
| 20 |
08 |
Meaning: Neither STPARM or ASNAME was specified. |
| 20 |
12 |
Meaning: The STPARM length is not 1-124. |
| 24 |
04 |
Meaning: The reserved attribute bit is
set. |
| 24 |
08 |
Meaning: Both HIPRI and NONURG are specified. |
| 28 |
04 |
Meaning: ASCRE cannot reference the UTOKEN. |
| 28 |
08 |
Meaning: UTOKEN is specified without TRMEXIT. |
| 32 |
04 |
Meaning: ASCRE cannot reference the ASPARM
parameter. |
| 32 |
08 |
Meaning: The ASPARM length is not 0-254. |
| 36 |
04 |
Meaning: ASCRE cannot reference AXLIST. |
| 36 |
08 |
Meaning: The AXLIST length is not 1-32
elements. |
| 40 |
04 |
Meaning: ASCRE cannot reference LXLIST. |
| 40 |
08 |
Meaning: The LXLIST length is not 1-32
elements. |
| 44 |
04 |
Meaning: ASCRE cannot reference the TKLIST
parameter. |
| 44 |
08 |
Meaning: The TKLIST length is not same
as LXLIST length. |
| 48 |
08 |
Meaning: The ASCRE invocation specified
one of the following: - ASNAME, but the address space name is not valid.
- STPARM for a procedure other than IEESYSAS, but the address space
name is not valid.
- STPARM for procedure IEESYSAS, but did not correctly provide the
required format of IEESYSAS.x, where x is the name of
the address space.
|
| 52 |
04 |
Meaning: A storage shortage prevented the
creation of an address space. Resubmit the failed job because the
shortage might have been caused by a temporary strain on workload.
If the problem persists, you might have to reevaluate your installation
defined storage thresholds. |
| 52 |
08 |
Meaning: Either the maximum number of address
spaces was exceeded or the system could not obtain storage for the
ASCB or ASSB. The system programmer can change the value specified
on the MAXUSER parameter in the IEASYSxx parmlib member (to increase
the number of address spaces that are available). |
| 52 |
12, 16 |
Meaning: Record the return and reason codes
and inform your technical support personnel. |
| 56 |
16 |
Meaning: The caller specified an address
space attribute that is not valid. |
| 60, 64, 68, 72 |
Any |
Meaning: Record the return and reason codes
and inform your technical support personnel. |
Example
Create an address space named ASPACE1. Note the USING statements
that establish addressability for different segments of code. ASCRETST CSECT
ASCRETST AMODE 31
ASCRETST RMODE ANY
BALR 10,0 ESTABLISH ...
USING *,10 ... ADDRESSABILITY
.
.
* ISSUE ASCRE SPECIFYING A TERMINATION ROUTINE NAME IN STORAGE
ASCRE ASNAME='ADSPACE1',INIT=INITNAME,TRMEXIT=TERMEXIT,ODA=ODAAREA
.
.
* TERMINATION EXIT
TERMEXIT DS 0H
USING *,15 REGISTER 15 CONTAINS ENTRY ADDRESS
SAVE (14,12),,* SAVE REGISTERS
.
* PERFORM ADDRESS SPACE TERMINATION PROCESSING
.
.
RETURN (14,12) RESTORE REGISTERS; RETURN TO SYSTEM
.
.
* DATA AREAS
INITNAME DC CL8'INITMOD'
ODAAREA DS CL24
END
|
z/OS MVS Programming: Authorized Assembler Services Reference ALE-DYN
Copyright IBM Corporation 1990, 2014