The requirements for the caller of ATTACH or ATTACHX are:

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.

• 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 ECB must be in storage addressable by both the caller of ATTACH and the system.
• Only job step tasks can issue ATTACH with JSTCB=YES. A task cannot issue a series of ATTACH macros that would cause its subtasks to be a mix of job step and nonjob step tasks.
• The caller cannot have an EUT FRR established.
• The parameter list specified for an ESTAI exit must be addressable using a 31-bit address.

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 system returns.

None.

The standard form of the ATTACH macro is written as follows:

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 entry name list. The entry name is constructed using the BLDL macro. When EPLOC is coded, entry name addr points to an eight-byte field. When the name is less than eight characters, left-justify the name and pad with blanks on the right to make up the eight characters.

Note:

1. ATTACH processing can attach a load module in 24-bit or 31-bit addressing mode physically resident above or below 16 megabytes virtual. The AMODE and RMODE, load module attributes located in the directory entry for the load module, provide this information. The RMODE indicates the place of the module; the AMODE indicates the addressing mode of the module. When the AMODE of the entry point is ANY, it is attached with the same addressing mode as the caller.
2. When you use the DE parameter with the ATTACH macro, DE specifies the address of a list 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.
3. See z/OS DFSMS Macro Instructions for Data Sets and z/OS DFSMS Using Data Sets for a description of the BLDL macro.

The contents of the GPRs on entry to the subtask are:

Register

Contents

0

Does not contain any information for use by the routine.

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

Do not contain any information for use by the routine.

13

Address of a 144-byte save area if SVAREA=YES was specified; Otherwise, zero.

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

Does not contain any information for use by the routine.

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

Do not contain any information for use by the routine.

13-15

Zeroes

,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 executed. The DCB must reside in storage below 16 megabytes.

,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 subtask, 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 subtask.

,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 subtask, with a higher number representing a higher dispatching priority. If, however, the resulting number is higher than the limit priority of the subtask, 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 subtask'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 for the subtask. The system uses this to indicate the termination of the subtask. This enables the issuer of the attach to wait on it, using the WAIT macro, and enables the system to post it on behalf of the terminating task. The return code, (when the task terminates normally), or the completion code, (when the task terminates abnormally), is placed in the event control block. When this parameter is coded, a DETACH macro must be issued 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. It is given control after the subtask normally or abnormally terminates. The exit routine is given control when the originating task becomes active after the subtask terminates. It must be in virtual storage. When this parameter is coded, a DETACH macro must be issued 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.

When the exit routine is given control, the contents of the GPRs are:

Register

Contents

0

Does not contain any information for use by the routine.

1

Address of the task control block for terminated task

2-12

Do not contain any information for use by the routine.

13

Address of a 72-byte save area provided by the system

14

Return address

15

Address of the exit routine

When the exit routine receives control, the contents of ARs are:

Register

Contents

0

Does not contain any information for use by the routine.

1

Zero

2-12

Do not contain any information for use by the routine.

13-15

Zeroes

The exit routine is responsible for saving and restoring the registers.

,GSPV=subpool nmbr

,GSPL=subpool list addr

Specifies a virtual storage subpool number, or address of a list of virtual storage subpool numbers, each less than 128. Ownership of each of the specified subpools is assigned to the subtask. Subpool zero is an exception. It can be specified but it cannot be transferred. When a task transfers ownership of a subpool, it can no longer obtain or release the associated virtual storage areas. When GSPL 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.

,SHSPV=subpool nmbr

,SHSPL=subpool list addr

Specifies a virtual storage subpool number or the address of a list of virtual storage subpool numbers, each less than 128. Programs of the originating task and the subtask can use the associated virtual storage areas. When 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 (YES) or not to be shared (NO) with the subtask.

,TASKLIB=dcb addr

Specifies the address of the DCB for the library to be used as the attached subtask's library. Otherwise, the subtask 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 subtask with a completion code of X'806' if the requested module is not in the subtask 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 for the attached task; any STAI or ESTAI recovery routines defined for the attached task are automatically propagated to its subtasks.

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 the action to be taken with regard to I/O operations when the subtask encounters an error. NONE indicates that no action is specified. HALT indicates halting of I/O operations. QUIESCE indicates quiescing of I/O operations.

,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 scheduled in these 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 nonjob step task issued the ABEND macro with the STEP parameter.
• z/OS UNIX is canceled and the user's task is in a wait in the z/OS UNIX kernel.

,JSTCB=NO

,JSTCB=YES

Specifies whether the attached task is to be a job step task. YES specifies that the attached task is to be a job step task.

NO specifies that the attached task is to be a nonjob step task and that the job step task of the issuer of ATTACH will be propagated to the newly attached task.

Note:

1. JSTCB=YES causes a new job pack area to be established for the attached task. Modules within the job pack area of the task issuing the ATTACH are not available to the newly attached task. See information about program management in z/OS MVS Programming: Authorized Assembler Services Guide for details.
2. The use of JSTCB=YES affects the ownership of those virtual storage subpools that are owned by job step tasks. See information about virtual storage management in z/OS MVS Programming: Authorized Assembler Services Guide for details.
3. Do not specify JSTCB=YES unless you know that the design of your application requires the special attributes of a job step task.

,SM=PROB

,SM=SUPV

PROB specifies that the attached task is to run in problem state. SUPV specifies that the attached subtask is to run in supervisor state.

,SVAREA=YES

,SVAREA=NO

Specifies whether a save area is needed for the attached task. YES specifies that the ATTACH routine obtains a 144-byte save area. When the attaching and attached task share subpool zero, the save area is obtained there. Otherwise, it is obtained from a new 4KB block. NO specifies that no save area is needed.

,KEY=PROP

,KEY=ZERO

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.

,DISP=YES

,DISP=NO

,DISP=RESET,TCB=tcb addr

YES specifies that the attached subtask is dispatchable. NO specifies that the subtask is nondispatchable; the system places the address of the TCB for the task in GPR 1, but ATTACH processing for the task does not complete.

When you specify DISP=NO, you must issue ATTACH again with the DISP=RESET,TCB=tcb addr parameter so that ATTACH processing completes for the subtask. When you issue ATTACH with DISP=RESET,TCB=tcb addr, you cannot specify any other parameters on the ATTACH macro. ATTACH DISP=RESET,TCB=tcb addr resets to dispatchable the subtask specified by tcb addr and all subtasks of the attaching program that were attached using the DISP=NO parameter.

,TID=task id

Specifies the task identifier to be placed in the TCB field of the attached subtask. IBM recommends that you specify a value less than 200 for task id.

,NSHSPV=subpool nmbr

,NSHSPL=subpool list addr

Specifies the virtual storage subpool number 236 or 237, or the address of a list of virtual storage subpool numbers 236 and 237. The subpools specified are not shared with the subtask.

When NSHSPL is specified, the first byte of the list contains the number of bytes remaining in the list. Each of the subsequent bytes contains a virtual storage subpool number.

,RSAPF=YES

,RSAPF=NO

Specifies that the attached subtask comes from an unauthorized library. When it comes from an APF-authorized library or the link pack area and is link-edited with the APF-authorized attribute, the step begins execution with APF authorization.

RSAPF=YES when these conditions are met:

• The caller is running in supervisor state, system key (0-7), or both
• The caller is running non-APF authorized
• The subtask is attached in the problem program state and with a nonsystem key.

Specify RSAPF=NO when the APF authorization of the step is to remain unchanged.

,ALCOPY=NO

,ALCOPY=YES

Specifies the EAX value for the subtask and determines the contents of its access list. ALCOPY=NO gives the subtask an EAX of zero and a null access list. ALCOPY=YES gives the subtask:

• The same EAX as the caller
• A copy of the caller's DU-AL. For details about how the system copies a DU-AL, see the topic on access lists in z/OS MVS Extended Addressability Guide.

The default is ALCOPY=NO.

,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. They can be any valid coding values.

The caller of ATTACH or ATTACHX might receive one of the following hexadecimal ABEND codes:

See z/OS MVS System Codes for explanations and responses for these codes.

When control is returned, register 15 contains one of the return codes in the following table.