The ATTACHX macro creates a subtask for callers in AR mode or primary
mode. It indicates the entry point in the program to be given control
when the subtask becomes active.
The format of the PARAM parameter list for callers in AR mode differs
from the format for callers in primary mode.
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.
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 ATTACH or ATTACHX. |
| |
|
| ATTACHX |
|
| |
|
| ␢ |
One or more blanks must follow ATTACH or 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 STAI. |
| ,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 SYNCH only if you specify
ESTAI. |
| ,ASYNCH=YES |
Default for ESTAI: ASYNCH=YES |
| |
|
| ,TERM=NO |
Note: TERM may be specified only if ESTAI
is specified. |
| ,TERM=YES |
Default: TERM=NO |
| |
|
| ,JSTCB=NO |
Default: JSTCB=NO |
| ,JSTCB=YES |
|
| |
|
| ,SM=PROB |
Default: SM=PROB |
| ,SM=SUPV |
|
| |
|
| ,SVAREA=YES |
Default: SVAREA=YES |
| ,SVAREA=NO |
|
| |
|
| ,KEY=PROP |
Default: KEY=PROP |
| ,KEY=ZERO |
|
| ,KEY=NINE |
|
| |
|
| ,PKM=SYSTEM_RULES |
Default: PKM=SYSTEM_RULES |
| ,PKM=REPLACE |
|
| |
|
| ,DISP=YES |
Default: DISP=YES |
| ,DISP=NO |
|
| ,DISP=RESET,TCB=tcb addr |
tcb addr: RX-type address or
address in register (2) - (12) |
| |
|
| ,TID=task id |
task id: Decimal digits 0-255,
or register (2) - (12). |
| |
Default: TID=0 |
| |
Note: IBM® recommends
that you specify a value less than 200. |
| |
|
| ,NSHSPV=subpool nmbr |
subpool nmbr: Symbol, decimal
digit, or register (2) - (12). |
| ,NSHSPL=subpool list addr |
subpool list addr: A-type address,
or register (2) - (12). |
| |
|
| ,RSAPF=NO |
Default: RSAPF=NO |
| ,RSAPF=YES |
|
| |
|
| ,ALCOPY=YES |
Default: ALCOPY=NO |
| ,ALCOPY=NO |
|
| |
|
| ,RELATED=value |
value: Any valid macro keyword
specification. |
| |
|
,ADDRENV=SAME
,ADDRENV=SUBSP
|
Default: ADDRENV=SAME |
| |
|
Parameters
The parameters are as explained under ATTACH, with the following
exception:
- ,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.
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=ZERO
- ,KEY=NINE
- ZERO specifies that the protection key of the newly created task
should be zero. 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, 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 1
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
Example 2
Attach a nondispatchable subtask called SUBTASK1, then reset SUBTASK1
to be dispatchable. PRINT NOGEN
NODISP CSECT
NODISP AMODE ANY
NODISP RMODE ANY
*********************************************************************
* The following code performs these functions: *
* 1. Creates a nondispatchable subtask by issuing the *
* ATTACHX macro with the DISP=NO parameter. *
* 2. Restarts the task by making it dispatchable with the *
ATTACHX macro and the DISP=RESET parameter. *
* *
*********************************************************************
SPACE 3
***************************************
* Entry linkage *
***************************************
STM R14,R12,12(R13)
BALR R12,0
USING BEGN,R12
BEGN DS 0H
LA R12,0(,R12) CLEAN HI-BYTE OF ENTRY REGISTERS
LA R13,0(,R13)
SPACE 3
ST R13,SAVE+4
LA R15,SAVE
ST R15,8(0,R13)
LR R13,R15
EJECT
***********************************************************************
* Attach a subtask. The subtask is in problem state and is *
* nondispatchable. *
***********************************************************************
SPACE 3
ATTACHX EP=SUBTASK1, X
ECB=AMYECB, X
DISP=NO
SPACE 3
ST R1,TCBADDR SAVE SUBTASK TCB ADDRESS
EJECT
. PROCESSING CONTINUES
.
.
********************************************************
* *
* Start the subtask by resetting it to be dispatchable.*
* *
********************************************************
SPACE 3
L 2,TCBADDR GET TARGET TCB ADDRESS
SPACE 3
RESET ATTACHX DISP=RESET,TCB=(2)
SPACE 3
EJECT
*****************************************************
* Wait until subtask completes, then detach subtask.*
*****************************************************
SPACE 3
WAIT 1,ECB=AMYECB
SPACE 3
DETACH TCBADDR DETACH SUBTASK
EJECT
***************************************
* End of program *
***************************************
SPACE 3
FINI DS 0H
L R13,SAVE+4
DROP R12
LM R14,R12,12(R13)
XR R15,R15
BR R14
EJECT
***********************************
* Define constants *
***********************************
SAVE DC 18F'0'
*
TCBADDR DC F'0' ADDRESS OF SUBTASK TCB
AMYECB DC F'0' END-OF-SUBTASK ECB
SPACE 3
EJECT
***********************************************
* Register equates *
***********************************************
SPACE 3
R12 EQU 12
R13 EQU 13
R14 EQU 14
R15 EQU 15
END
|
z/OS MVS Programming: Authorized Assembler Services Reference ALE-DYN
Copyright IBM Corporation 1990, 2014