DETACH — Detach a subtask

Description

The DETACH macro removes from the system a subtask created using the ATTACH (or ATTACHX) macro with the ECB or ETXR parameters. Subtasks created using the ATTACH macro without specifying the ECB or ETXR parameters are automatically removed by the system when they terminate. If a task attaches a subtask with the ECB or ETXR parameters, the originating task must detach the subtask before terminating.

You can issue a DETACH macro only for subtasks created by the active task.

Environment

The requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	Problem state, and any PSW key.
Dispatchable unit mode:	Task
Cross memory mode:	PASN=HASN=SASN
AMODE:	24- or 31- or 64-bit
ASC mode:	Primary or AR
Interrupt status:	Enabled for I/O and external interrupts
Locks:	The caller may not hold any locks.
Control parameters:	Must be in the primary address space.

Programming requirements

If your program is in AR mode, issue the SYSSTATE ASCENV=AR macro before you issue DETACH.

Restrictions

Failure to remove subtasks created using the ATTACH macro with the ECB or ETXR parameters causes the originating task and all of its subtasks to terminate abnormally.
Detaching a terminated subtask that was created without the ECB or ETXR parameters will cause the originating task and all its subtasks to terminate abnormally.
Detaching a task that has not yet terminated will cause that task and all its subtasks (but not the originating task) to terminate abnormally.
The caller cannot have an EUT FRR established.

Input register information

Before issuing the DETACH 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-1: Used as work registers by the system
2-14: Unchanged
15: Return code

When control returns to the caller, the access registers (ARs) contain:

Register: Contents
0-1: Used as work registers by the system
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.

Performance implications

None.

Syntax

The DETACH macro is written as follows:

Syntax	Description

`name`	`name`: Symbol. Begin `name` in column 1.

␢	One or more blanks must precede DETACH.

DETACH

␢	One or more blanks must follow DETACH.

`tcb addr`	`tcb addr`: Symbol, RX-type address, or register (1) or (2) - (12).

,STAE=NO ,STAE=YES	Default: STAE=NO

,RELATED=`value`

Parameters

The parameters are explained as follows:

tcb addr

Specifies the address of a fullword on a fullword boundary containing the address of the task control block for the subtask to be removed from the system.

,STAE=NO

,STAE=YES

Specifies whether the ESTAE-type routine (STAI, ESTAI, STAE, ESTAE) established by the subtask is to receive control or whether previously established ESTAE-type routines existing for the subtasks are to receive control.

If you specify STAE=YES, any ESTAE-type routines associated with the detached task will receive control if the task is detached while active.

If you specify STAE=NO, only the ESTAE-type routines that were established through the ATTACH, ESTAE, or ESTAEX macros, with TERM=YES, will receive control in this event.

When an ESTAE-type routine gains control as a result of a DETACH, no retry is allowed even if one is requested in the routine. For more information about recovery processing, refer to z/OS MVS Programming: Assembler Services Guide.

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

ABEND codes

The caller of DETACH might receive one of the following ABEND codes:

ABEND Code	Associated Reason Code
X'13E'	None
X'23E'	0, 4, 8
X'33E'	None
X'43E'	None
X'53E'	None

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

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: Environmental error. An incomplete subtask was detached with STAE=YES specified; DETACH processing successfully completed. Action: None required. However, you might take some action based upon your application.

Example 1

Remove the subtask from the address space. The address of the TCB is in the fullword labeled SAVEWORD.

DETACH SAVEWORD

Example 2

In addition to removing the subtask from the address space, give control to the most recent STAE exit established by the subtask if the subtask has not yet been terminated.

DETACH (1),STAE=YES