The ATTACHX macro creates a new task and indicates the entry point
in the program to be given control when the new task becomes active.
The ASC mode of the new task is the same as the ASC mode of the issuer
of ATTACHX.
At entry to the attached task, if the caller specifies a user parameter
list on the PARAM parameter or by issuing the execute form of the
macro with MF=E: - GPR 1 contains the address of the user parameter list.
- If the caller of the ATTACHX macro is in AR mode, AR 1 contains
an ALET of 0.
All parameters that are valid for ATTACH are also valid for ATTACHX.
Syntax
The standard form of the ATTACHX macro is written as follows:
| Syntax |
Description |
|---|
| |
|
| name |
name: Symbol. Begin name in
column 1. |
| |
|
| ␢ |
One or more blanks must precede ATTACHX. |
| |
|
| ATTACHX |
|
| |
|
| ␢ |
One or more blanks must follow ATTACHX. |
| |
|
| EP=entry name |
entry name: Symbol. |
| EPLOC=entry name addr |
entry name addr: A-type address,
or register (2) - (12). |
| DE=list entry addr |
list entry addr: A-type address,
or register (2) - (12). |
| |
|
| ,DCB=dcb addr |
dcb addr: A-type address,
or register (2) - (12). |
| |
|
| ,LPMOD=limit prior nmbr |
limit prior nmbr: Symbol,
decimal digit, or register (2) - (12). |
| |
|
| ,DPMOD=disp prior nmbr |
disp prior nmbr: Symbol, decimal
digit, or register (2) - (12). |
| |
|
| ,PARAM=(addr) |
addr: A-type address |
| ,PARAM=(addr),VL=1 |
Note: addr is one or
more addresses, separated by commas. For example, PARAM=(addr,addr,addr) |
| |
|
| ,PLIST4=YES |
Default: None. |
| ,PLIST4=NO |
|
| |
|
| ,PLIST8=YES |
Default: None. |
| ,PLIST8=NO |
|
| |
|
| ,PLIST8ARALETS=NO |
Default: PLIST8ARALETS=NO |
| ,PLIST8ARALETS=YES |
|
| |
|
| ,ECB=ecb addr |
ecb addr: A-type address,
or register (2) - (12). |
| |
|
| ,ETXR=exit rtn addr |
exit rtn addr: A-type address,
or register (2) - (12). |
| |
|
| ,GSPV=subpool nmbr |
subpool nmbr: Symbol, decimal
digit, or register (2) - (12). |
| ,GSPL=subpool list addr |
subpool list addr: A-type
address, or register (2) - (12). |
| |
|
| ,SHSPV=subpool nmbr |
subpool nmbr: Symbol, decimal
digit, or register (2) - (12). |
| ,SHSPL=subpool list addr |
subpool list addr: A-type
address, or register (2) - (12). |
| |
|
| ,SZERO=YES |
Default: SZERO=YES |
| ,SZERO=NO |
|
| |
|
| ,TASKLIB=dcb addr |
dcb addr: A-type address,
or register (2) - (12). |
| |
|
| ,STAI=(exit addr) |
exit addr: A-type address,
or register (2) - (12). |
| ,STAI=(exit addr,parm addr) |
parm addr: A-type address,
or register (2) - (12). |
| ,ESTAI=(exit addr) |
Note: AR mode callers and 31-bit callers
must not use STA. |
| ,ESTAI=(exit addr,parm addr) |
|
| ,SDWALOC31=NO |
Note: SDWALOC31 may be specified only when ESTAI is
specified. |
| ,SDWALOC31=YES |
Default: SDWALOC31=NO |
| |
|
| ,PURGE=QUIESCE |
Note: Specify PURGE only if you specify
ESTAI. |
| ,PURGE=NONE |
Default for ESTAI: PURGE=NONE |
| ,PURGE=HALT |
|
| |
|
| ,ASYNCH=NO |
Note: Specify ASYNCH only if you specify
ESTAI. |
| ,ASYNCH=YES |
Default for ESTAI: ASYNCH=YES |
| |
|
| ,TERM=NO |
Note: Specify TERM only if you specify
ESTAI. |
| ,TERM=YES |
Default: TERM=NO |
| |
|
| ,ALCOPY=NO |
Default: ALCOPY=NO |
| ,ALCOPY=YES |
|
| |
|
| ,RELATED=value |
value: Any valid macro keyword
specification. |
| |
|
| ,KEY=PROP |
Default: KEY=PROP |
| ,KEY=NINE |
|
| |
|
| ,PKM=SYSTEM_RULES |
Default: PKM=SYSTEM_RULES |
| ,PKM=REPLACE |
|
| |
|
,ADDRENV=SAME
,ADDRENV=SUBSP
|
Default: ADDRENV=SAME |
| |
|
Parameters
The parameters are as explained under ATTACH, with the following
exceptions:
- ,PARAM=(addr)
- ,PARAM=(addr),VL=1
- Specifies an address or addresses to be passed to the attached
task. ATTACHX expands each address inline to a fullword boundary and
builds a parameter list with the addresses in the order specified.
When the attached task receives control, register 1 contains the address
of the parameter list. When PARAM is not specified, ATTACHX passes
GPR1 and AR1 unchanged to the attached routine.
When an AR mode
caller uses either:- a parameter list with 4 bytes per entry; or
- a parameter list with 8 bytes per entry and specifies PLIST8ARALETS=YES,
the addresses passed to the subtask are in the first part
of the parameter list and their associated ALETs are in the second
part. For a non-AR mode caller, or for an AR mode caller using a parameter
list with 8 bytes per entry without PLIST8ARALETS=YES, ALETs are not
passed in the parameter list. When ALETs are passed in the parameter
list, the ALETs occupy consecutive 4-byte fields, whether the parameter
list is 4 or 8 bytes per entry. See the description of the PLIST4
and PLIST8 keywords below for more information about controlling the
bytes-per-entry in the parameter list. See the description of the
PLIST8ARALETS keyword below for more information about ALETs and 8-bytes-per-entry
parameter lists. See User parameters for an example
of passing a parameter list in AR mode.
When using a 4-bytes-per-entry
parameter list, specify VL=1 when you pass a variable number
of parameters. VL=1 results in setting the high-order bit
of the last address to 1. The 1 in the high-order bit identifies the
last address parameter (which is not the last word in the list
when the ALETs are also saved). When using an 8-bytes-per-entry parameter
list, VL=1 is not valid.Note: If you specify only one address
for PARAM= and you are not using register notation, you do not need
to enter the parentheses.
- ,PLIST4=YES
- ,PLIST4=NO
-
- ,PLIST8=YES
- ,PLIST8=NO
- Defines the size of the parameter list entries for a parameter
list to be built by ATTACHX based on the PARAM keyword.
PLIST4
and PLIST8 cannot be specified together. If neither is specified,
the default is: - If running AMODE 64, PLIST8=YES
- If not running AMODE 64, PLIST4=YES
If running AMODE 64 and PLIST4=YES is specified, the
system builds a 4-bytes-per-entry parameter list just as it would
if the program were running AMODE 24 or AMODE 31 and did not specify
PLIST4 or PLIST8.
If running AMODE 24 or AMODE 31 and PLIST8
is specified, the system builds an 8-bytes-per-entry parameter list
just as it would if the program were running AMODE 64 and did not
specify PLIST4 or PLIST8.
- ,PLIST8ARALETS=NO
- ,PLIST8ARALETS=YES
- If there is to be an 8-byte-per-entry parameter list and the invoker
is in AR mode, indicates if the parameter list is also to contain
the ALETs associated with the addresses. Otherwise, this parameter
is ignored.
- ,PLIST8ARALETS=NO
- Indicates that the 8-byte-per-entry parameter list is to consist
of just the 8-byte addresses.
- ,PLIST8ARALETS=YES
- Indicates that the 8-byte-per-entry parameter list is to consist
of the following two parts:
- All the 8-byte addresses,
- All the associated ALETs in consecutive 4-byte fields.
- ,SDWALOC31=NO
- ,SDWALOC31=YES
- Specifies the location of the ESTAI's SDWA.
If using ESTAI and
SDWALOC31=YES, then the SDWA is in 31–bit storage.
If using
ESTAI and SDWALOC31=NO, then the SDWA is in 24–bit storage.
- ,KEY=PROP
- ,KEY=NINE
- PROP specifies that the protection key of the newly created task
should be propagated from the task using ATTACH. NINE specifies that
the protection key of the newly created task should be nine.
You
can use KEY=NINE to help to prevent the attached task from inadvertently
modifying storage owned by the attaching task, since a program running
in with PSW key 9 cannot modify storage in any other PSW key. The
following parameters are not valid when KEY=NINE is specified: GSPL,
GSPV, SHSPL, and SHSPV. In addition, if you specify KEY=NINE, you
must specify SZERO=NO.
Within a task that was attached with
the KEY=NINE parameter: - the system-provided save area is above 16M (for a non-KEY=NINE
task, the save area is below 16M)
- the CEL anchor pointer is above 16M. For a task that
is not KEY=NINE, the CEL anchor pointer is below 16M.
- a re-entrant program, whether from an APF-authorized concatenation
or not, is placed into key 0 storage (for a non-KEY=NINE task, only
re-entrant programs from an APF-authorized concatenation are placed
into key 0 storage).
- ,PKM=SYSTEM_RULES
- ,PKM=REPLACE
- SYSTEM_RULES specifies that the system should determine
the appropriate PSW key mask using the following rules:
- If KEY=ZERO, the PSW key mask represents key 0 plus key 9.
- If KEY=PROP, but the mother task's initial key does not match
the mother task's current key, the PSW key mask represents the PSW
key of the daughter task plus key 9.
- If KEY=PROP and the mother task's initial key matches the mother
task's current key, or if KEY=NINE, the PSW key mask represents the
mother task's initial key plus the mother task's initial PSW key mask
plus the PSW key of the daughter task plus key 9.
REPLACE specifies that the PSW key mask is to be replaced with
a value representing the PSW key of the daughter task plus key 9.The
default is PKM=SYSTEM_RULES.
- ,ADDRENV=SAME
- ,ADDRENV=SUBSP
- Identifies processing related to the subspace environment for
the new task. In general, the program is responsible for keeping track
of whether it is a subspace task or whether it is subspace active.
A
subspace task is a task that was attached either by ATTACHX with ADDRENV=SUBSP
or by a task that itself was a subspace task that was subspace active
at the time of the ATTACH or ATTACHX.
Note: It is up to the program
that issues BSG to keep track of whether it is subspace active.
- ,ADDRENV=SAME
- If the current task is a subspace task and is active to the same
active subspace that was in effect when the current task was attached,
make the new task a subspace task that is active to that subspace.
If the current task is not a subspace task, take no action. Do not
use this option if the current task is a subspace task that either
is not subspace active or is subspace active but for a different subspace
than was in effect when the current task was attached.
- ,ADDRENV=SUBSP
- If the current task is a subspace task and is subspace active,
make the new task a subspace task and active to that subspace. Do
not specify this option if the current task is not subspace active.
Example
With the caller in AR ASC mode, cause PROGRAM1 to be attached and
share subpool zero. The subtask is to receive control: - With the same extended authorization index (EAX) as the caller.
- With a copy of the caller's DU-AL.
- Executing in AR ASC Mode.
TESTCASE CSECT
.
SYSSTATE ASCENV=AR
.
ATTACHX EP=PROGRAM1,SZERO=YES,ALCOPY=YES
.
END TESTCASE
|
z/OS MVS Programming: Assembler Services Reference ABE-HSP
Copyright IBM Corporation 1990, 2014