 |
Note: IBM® recommends that you use ATTACHX rather than
ATTACH.
The ATTACH macro causes the system to create a new task and indicates
the entry point in the program to be given control when the new task
becomes active. The entry point name that is specified must be a
member name or an alias in a directory of a partitioned data set,
or must have been specified in an IDENTIFY macro. If the system cannot
locate the specified entry point, it abnormally terminates the new
subtask.
For information about how to select an MVS/SP version
other than the current version, see Compatibility of MVS macros.
The descriptions of ATTACH and ATTACHX in this book are: - The standard form of the ATTACH macro, which includes general
information about the ATTACH and ATTACHX macros, with some specific
information about the ATTACH macro. The syntax of the ATTACH macro
is presented, and all ATTACH parameters are explained.
- The standard form of the ATTACHX macro, which includes information
specific to the ATTACHX macro and to callers in AR mode.
- The list form of the ATTACH and ATTACHX macros.
- The execute form of the ATTACH and ATTACHX macros.
The new task is a subtask of the originating task; the originating
task is the task that was active when you issued the ATTACH macro.
The limit and dispatching priorities of the new task are the same
as those of the originating task unless modified in the ATTACH macro.
The address space control mode (ASC) of the new task is the same as
the originating task.
The load module containing the program to be given control is brought
into virtual storage if a usable copy is not available in virtual
storage. The issuing program can provide an event control block in
which termination of the new task is posted and an exit routine to
be given control when the new task is terminated.
If you code the ECB or ETXR parameter, you must issue a DETACH
macro to remove the subtask from virtual storage before the program
that issued the ATTACH macro terminates. If you do not code the ECB
or ETXR parameter, the system automatically removes the subtask from
virtual storage upon completion of the subtask's processing. If you
specify the ECB parameter in the ATTACH macro, the ECB must be in
storage addressable by both the issuer of ATTACH and the system, so
that the issuer of ATTACH can wait on it (using the WAIT macro) and
the system can post it on behalf of the terminating task.
Environment
The requirements for the caller of ATTACH or ATTACHX are:
| Environmental factor |
Requirement |
|---|
| Minimum authorization: |
Problem state and any PSW key |
| Dispatchable unit mode: |
Task |
| Cross memory mode: |
PASN=HASN=SASN |
| AMODE: |
If you use the STAI parameter, 24-bit; otherwise,
24- or 31- or 64-bit. Note: AMODE 64 is valid only for the ATTACHX
macro.
|
| ASC mode: |
If you use the STAI parameter, primary; otherwise,
primary or access register (AR) |
| Interrupt status: |
Enabled for I/O and external interrupts |
| Locks: |
No locks held |
| Control parameters: |
For both primary ASC mode callers and AR ASC mode
callers, control parameters must be in the primary address space. |
Programming requirements
If your program is in AR mode, issue SYSSTATE ASCENV=AR so the
system can generate code that is appropriate for AR mode. If you
issue SYSSTATE ASCENV=AR and then issue ATTACH, the system substitutes
the ATTACHX macro and issues a message telling you that it made the
substitution.
Restrictions
- If the caller is running in 31-bit addressing mode, all input
parameters can have addresses greater than 16 megabytes, except for
the address of the DCB.
- The caller cannot have an EUT FRR established.
- The parameter list specified for an ESTAI exit must be addressable
using a 31-bit address.
Input register information
If you want to pass a parameter list to the new task without coding
the PARAM or MF=E parameter, general purpose register (GPR) 1 must
contain the address of the list on entry to ATTACH or ATTACHX. Otherwise,
before issuing the ATTACH or ATTACHX 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
- Used as a work register by the system
- 1
- If GPR 15 contains a return code other than X'00', zero;
otherwise, the address of the task control block for the new task
- 2-13
- Unchanged
- 14
- Used as a work register by the system
- 15
- Return code
When control returns to the caller, the ARs contain: - Register
- Contents
- 0
- Used as a work register by the system
- 1
- Zero (the ALET of the task control block address)
- 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.
Syntax
The standard form of the ATTACH macro is written as follows:
| Syntax |
Description |
|---|
| |
|
| name |
name: Symbol. Begin name in
column 1. |
| |
|
| ␢ |
One or more blanks must precede ATTACH. |
| |
|
| ATTACH |
|
| |
|
| ␢ |
One or more blanks must follow ATTACH. |
| |
|
| 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) |
| |
|
| ,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) |
|
| |
|
| ,PURGE=QUIESCE |
Note: PURGE may be specified only if STAI
or ESTAI is specified. |
| ,PURGE=NONE |
Default for STAI: PURGE=QUIESCE |
| ,PURGE=HALT |
Default for ESTAI: PURGE=NONE |
| |
|
| ,ASYNCH=NO |
Default for STAI: ASYNCH=NO |
| ,ASYNCH=YES |
Default for ESTAI: ASYNCH=YES |
| |
Note: ASYNCH may be specified only if
STAI or ESTAI is specified. |
| |
|
| ,TERM=NO |
Note: TERM may be specified only if ESTAI
is specified. |
| ,TERM=YES |
Default: TERM=NO |
| |
|
| ,ALCOPY=NO |
Default: ALCOPY=NO |
| ,ALCOPY=YES |
|
| |
|
| ,RELATED=value |
value: Any valid macro keyword
specification. |
| |
|
Parameters
The parameters are explained as follows:
- EP=entry name
- EPLOC=entry name addr
- DE=list entry addr
- Specifies the entry name, the address of the entry name, or the
address of the name field of a 62-byte list entry for the entry name
that was constructed using the BLDL macro. If EPLOC is coded, the
name must be padded to eight bytes, if necessary.
When you use
the DE parameter with the ATTACH macro, DE specifies the address of
a list that was created by a BLDL macro. You must issue the BLDL and
the ATTACH from the same task; otherwise, the system abnormally terminates
the program with a completion code of X'106'. Do not issue
an ATTACH or a DETACH between issuances of the BLDL and ATTACH.
The
system ignores the information you specify on the DE parameter if
the parameter does one of the following: - Specifies an entry in an authorized library (that is, defined
in IEAAPFxx member of SYS1.PARMLIB)
- Requests access to a program or library that is controlled by
the system authorization facility (SAF).
Instead, the system uses the BLDL macro to construct
a new list entry containing the DE information.
The contents
of the GPRs on entry to the subtask are: - Register
- Contents
- 0
- Used as a work register by the system.
- 1
- Address of the user parameter list if specified on either the
PARAM or MF=E parameters; otherwise, contains whatever GPR 1 contained
at the time the ATTACH macro was issued.
- 2-12
- Used as work registers by the system.
- 13
- Address of a 144-byte save area.
- 14
- Return address. Bit 0 is 0 if the subtask routine gets control
in 24-bit addressing mode; bit 0 is 1 if the subtask routine gets
control in 31-bit addressing mode.
- 15
- When the subtask routine is to run in 24-bit or 31-bit addressing
mode, the entry point address of the subtask routine.
When the
subtask routine is to run in 64-bit addressing mode, it is expected
to use relative branching and register 15 contains a value that can
be used to determine the addressing mode of the issuer of the ATTACH
or ATTACHX macro as follows: - Issuer AMODE 24: X'FFFFF000'
- Issuer AMODE 31: X'FFFFF002'
- Issuer AMODE 64: X'FFFFF004'
The contents of the ARs on entry to the subtask
are: - Register
- Contents
- 0
- Used as a work register by the system.
- 1
- Zero if you specified a user parameter list on either the PARAM
or MF=E parameters; otherwise, contains whatever AR 1 contained at
the time the ATTACH macro was issued.
- 2-12
- Used as work registers by the system.
- 13-15
- Zeros.
- ,DCB=dcb addr
- Specifies the address of the data control block for the partitioned
data set containing the entry name.
Note: The DCB must be opened before
the ATTACH macro is issued and must be the DCB used in the BLDL that
built the 62-byte DE list entry. The DCB must remain open until the
subtask becomes active, and it should not be closed immediately following
the ATTACH.
Note: DCB must reside in 24-bit addressable storage.
- ,LPMOD=limit prior nmbr
- Specifies the number (0 to 255) to be subtracted from the
current limit priority of the originating task. The resulting number
is the limit priority of the new task, with a higher number representing
a higher limit priority.
If you omit this parameter, the current
limit priority of the originating task is assigned as the limit priority
of the new task.
- ,DPMOD=disp prior nmbr
- Specifies the signed number (-255 to +255) to be algebraically
added to the current dispatching priority of the originating task.
The resulting number is assigned as the dispatching priority of the
new task, with a higher number representing a higher dispatching priority.
If, however, the resulting number is higher than the limit priority
of the new task, the limit priority is assigned as the dispatching
priority.
If a register is designated, a negative number must be
in two's complement form in the register. If you omit this parameter,
the dispatching priority assigned is the smaller of either the new
task's limit priority or the originating task's dispatching priority.
- ,PARAM=(addr)
- ,PARAM=(addr),VL=1
- Specifies an address or addresses to be passed to the attached
program. ATTACH expands each address inline to a fullword on a fullword
boundary, in the order designated, building a parameter list. When
the program receives control, register 1 contains the address of the
first word of the parameter list.
Specify VL=1 only if the called
program can be passed a variable number of parameters. VL=1 causes
the high-order bit of the last address to be set to 1; the bit can
be checked to find the end of the list.
- ,ECB=ecb addr
- Specifies the address of an event control block (ECB) for the
new task that the system will use to indicate when the new task terminates.
The ECB must be in storage so that the issuer of ATTACH can wait
on it (using the WAIT macro) and the system can post it on behalf
of the terminating task. The return code (if the task is terminated
normally) or the completion code (if the task is terminated abnormally)
is also placed in the event control block. If you code this parameter,
you must issue a DETACH macro to remove the subtask from virtual storage
after the subtask terminates. The system assumes that the ECB is in
the home address space.
- ,ETXR=exit rtn addr
- Specifies the address of the end-of-task exit routine to be given
control after the new task is normally or abnormally terminated. The
exit routine receives control when the originating task becomes active
after the subtask is terminated, and must be in virtual storage when
required. If you code this parameter, you must issue a DETACH macro
to remove the subtask from the system after the subtask terminates.
The
exit routine runs asynchronously under the originating task. The routine
receives control in the addressing mode of the issuer of the ATTACH
macro. The system abnormally ends a task with completion code X'72A' if
the task attempts to create two subtasks with the same exit routine
in different addressing modes. Upon entry, the routine has an empty
dispatchable unit access list (DU-AL). To establish addressability
to a data space created by the originating task and shared with the
terminating subtask, the routine can issue the ALESERV macro with
the ADD parameter, and specify the STOKEN of the data space.
The
exit routine receives control with the following environment:
| Environmental factor |
Requirement |
|---|
| Authorization: |
Problem state, PSW key is the same as TCB key
of the issuer of the ATTACH macro. |
| Dispatchable unit mode: |
Task |
| Cross memory mode: |
PASN=HASN=SASN |
| AMODE: |
24-bit when the issuer of the
ATTACH macro is AMODE 24; Otherwise, 31-bit. |
| ASC mode: |
Primary |
| Interrupt status: |
Enabled for I/O and external interrupts |
| Locks: |
No locks held |
| Control parameters: |
Not applicable. |
The contents of the GPRs when the exit routine receives
control are as follows: - Register
- Contents
- 0
- Used as a work register by the system.
- 1
- Address of the task control block for the task that was terminated.
- 2-12
- Used as work registers by the system.
- 13
- Address of a 72-byte area provided by the
system.
- 14
- Return address (to the system).
- 15
- Address of the exit routine.
The contents of the ARs when the exit routine
receives control are: - Register
- Contents
- 0
- Used as a work register by the system.
- 1
- Zero
- 2-12
- Used as work registers by the system.
- 13-15
- Zeros
The exit routine is responsible for saving
and restoring the registers.
- ,GSPV=subpool nmbr
- ,GSPL=subpool list addr
- Specifies a virtual storage subpool number less than 128 or the
address of a list of virtual storage subpool numbers each less than
128. Except for subpool zero, ownership of each of the specified
subpools is assigned to the new task. Although it can be specified,
subpool zero cannot be transferred. When ownership of a subpool is
transferred, programs of the originating task can no longer obtain
or release the associated virtual storage areas.
If GSPL is specified,
the first byte of the list contains the number of following bytes
in the list; each of the following bytes contains a virtual storage
subpool number.
- ,SHSPV=subpool nmbr
- ,SHSPL=subpool list addr
- Specifies a virtual storage subpool number less than 128 or the
address of a list of virtual storage subpool numbers each less than
128. Programs of both originating task and the new task can use the
associated virtual storage areas.
If SHSPL is specified, the first
byte of the list contains the number of remaining bytes in the list;
each of the following bytes contains a virtual storage subpool number.
- ,SZERO=YES
- ,SZERO=NO
- Specifies whether subpool 0 is to be shared with the subtask.
YES specifies that subpool 0 is to be shared; NO specifies that subpool
0 is not to be shared.
- ,TASKLIB=dcb addr
- Specifies the address of the DCB for the library to be used as
the attached task's library. Otherwise, the task library is propagated
from the originating task. (Note: The DCB must be opened before the
ATTACH macro is executed.) SYS1.LINKLIB is the last library searched.
If the DCB address specifies SYS1.LINKLIB, the search begins with
SYS1.LINKLIB, goes through other libraries, and ends with SYS1.LINKLIB.
The system abnormally terminates the attached task with a completion
code of X'806' if the requested module is not in the task
library and is not in the other libraries searched.
See "Location
of the Load Module" in z/OS MVS Programming: Assembler Services Guide for
additional information on using the TASKLIB parameter.
Note: DCB
must reside in 24-bit addressable storage.
- ,STAI=(exit addr)
- ,STAI=(exit addr,parm addr)
- ,ESTAI=(exit addr)
- ,ESTAI=(exit addr,parm addr)
- Specifies whether a STAI or ESTAI recovery routine is to be defined;
any recovery routines defined for the originating task are propagated
to the new task.
The exit addr specifies the
address of the STAI or ESTAI recovery routine that is to receive control
if the subtask encounters an error; the recovery routine must be in
virtual storage at the time of the error. The parm addr is
the address of a parameter list which may be used by the STAI or ESTAI
recovery routine. The address must be 24-bit for STAI and 31-bit for
ESTAI.
ATTACHX processing passes control to an ESTAI recovery
routine in the addressing mode of the issuer of the ATTACHX macro.
A STAI exit routine can run only in 24-bit addressing mode. If a
caller in the wrong addressing mode or AR mode specifies the STAI
parameter on the ATTACH macro, the caller ends abnormally with a completion
code of X'52A'.
- ,PURGE=QUIESCE
- ,PURGE=NONE
- ,PURGE=HALT
- Specifies what action is to be taken with regard to I/O operations
if the subtask encounters an error. No action may be specified (NONE),
a halting of I/O operations may be requested (HALT), or a quiescing
of I/O operations may be indicated (QUIESCE).
Note: You need to understand
PURGE processing before using this parameter. For information about
PURGE processing, see &idas300t;.
- ,ASYNCH=NO
- ,ASYNCH=YES
- Specifies whether asynchronous exits are to be allowed when a
subtask encounters an error.
ASYNCH=YES must be coded if: - Any supervisor services that require asynchronous interruptions
to complete their normal processing are going to be requested by the
recovery routine.
- PURGE=QUIESCE is specified for any access method that requires
asynchronous interruptions to complete normal input/output processing.
- PURGE=NONE is specified and the CHECK macro is issued in the recovery
routine for any access method that requires asynchronous interruptions
to complete normal input/output processing.
Note: If ASYNCH=YES is specified and the error was an error
in asynchronous exit handling, recursion will develop when an asynchronous
exit handling was the cause of the failure.
- ,TERM=NO
- ,TERM=YES
- Specifies whether the recovery routine associated with the ESTAI
request is also to be scheduled in the following situations:
- System-initiated logoff
- Job step timer expiration
- Wait time limit for job step exceeded
- DETACH macro without the STAE=YES parameter issued from a higher-level
task (possibly by the system if the higher-level task encountered
an error)
- Operator cancel
- Error on a higher-level task
- Error in the job step task when a non-job-step task issued the
ABEND macro with the STEP parameter
- z/OS UNIX System Services is
canceled and the user's task is in a wait in the z/OS UNIX System Services kernel.
- ,ALCOPY=NO
- ,ALCOPY=YES
- Determines the contents of the new task's access list and determines
the extended authorization index (EAX) value for the new task. ALCOPY=NO
gives the new task an EAX of zero and a null access list. ALCOPY=YES
gives the new task:
- The same extended authorization index (EAX) as the caller
- A copy of the caller's DU-AL.
The default is ALCOPY=NO.
- ,RELATED=value
- Specifies information used to self-document a macro 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.
ABEND codes
The caller of ATTACH or ATTACHX might receive one of the following
ABEND codes:
| ABEND Code |
Associated Reason Code |
|---|
| 12A |
0, 4 |
| 22A |
0 |
| 42A |
None |
| 52A |
0, 4, 8 |
| 72A |
0, 4, 8, C, 10, 14 |
| 82A |
None |
| 92A |
0, 4, 8, C, 10, 14, 18 |
Note: ABEND code 92A results from an error not directly caused by
the caller.
Return and reason codes
When control is returned, register 15 contains one of the following
return codes:
| Hexadecimal Return Code |
Meaning and Action |
|---|
| 00 |
Meaning: Successful completion. Action:
None.
|
| 04 |
Meaning: Program error. ATTACH was issued
in a STAE exit; processing not completed. Action: Change
your program so that the ATTACH is not issued by a STAE exit routine.
|
| 08 |
Meaning: Environmental error. Insufficient
storage available for control block for STAI/ESTAI request; processing
not completed. Action: Retry the request.
|
| 0C |
Meaning: Incorrect exit routine address
or incorrect parameter list address specified with STAI parameter;
processing not completed. Action: Ensure that the exit routine
and parameter list address are correct.
|
| 20 |
Meaning: Program error, due to one of
the following reasons:- The current task was not subspace active and the ATTACHX macro
specified ADDRENV=SUBSP.
- The current task is a subspace task that is not subspace active
and issued either ATTACH, or ATTACHX with ADDRENV=SAME specified or
defaulted.
Action:- If the current task was not subspace active and the ATTACHX macro
specified ADDRENV=SUBSP, update your program so that it issues ATTACHX
with ADDRENV=SUBSP only if it is subspace active.
- If the current task is a subspace task that is not subspace active
and ADDRENV=SAME was specified or defaulted, update your program so
that it issues ATTACH, or ATTACHX with ADDRENV=SAME specified or defaulted,
only if it is not a subspace task or is a subspace task that is not
subspace active.
|
| 24 |
Meaning: Program error. ADDRENV=SAME
was specified or defaulted and the issuer was a subspace task that
is subspace active, but the task was processing with a different active
subspace than that which was in effect when it was attached. Action: Update
your program if it is a subspace task and subspace active so that
it issues ATTACH or ATTACHX with ADDRENV=SAME only if the task was
processing with the same active subspace that was in effect when
it was attached.
|
Note: It is possible for the originating task to obtain return code
00, and still not have the subtask successfully created (for example,
if the entry name could not be found). In such cases, the new subtask
is abnormally terminated.
Example 1
Cause the program named in the list to be attached. Establish
RTN as an end-of-task exit routine. ATTACH DE=LISTNAME,ETXR=RTN
Example 2
Cause PROGRAM1 to be attached, share subpool 5, wait on WORD1 to
synchronize processing with that of the subtask, and establish EXIT1
as an ESTAI exit. ATTACH EP=PROGRAM1,SHSPV=5,ECB=WORD1,ESTAI=(EXIT1)
Example 3
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.
TESTCASE CSECT
.
ATTACH EP=PROGRAM1,SZERO=YES,ALCOPY=YES
.
END TESTCASE
Example 4
Usage of the SF and MF parameters. MVC ATTACH_EXEC,ATTACH_LIST Copy static plist to dynamic
*
ATTACHX
PARAM=(PARM1,PARM2,PARM3),
MF=(E,REMOTE_PLIST),
SF=(E,ATTACH_EXEC)
(in the module's static area)
* .
ATTACH_LIST ATTACHX EP=PROGRAM1,SZERO=YES,ALCOPY=YES,SF=L
*
(in the module's dynamic area)
REMOTE_PLIST DS 3F
PARM1 DS F
PARM2 DS F
PARM3 DS F
ATTACH_EXEC ATTACHX SF=L
|
z/OS MVS Programming: Assembler Services Reference ABE-HSP
Copyright IBM Corporation 1990, 2014