ATTACH (Attach a Task) Macro

A subtask can be initiated by any other task of the partition with the ATTACH macro.

ATTACH supports the 31-bit environment as well as data spaces. ATTACH processing can attach a subtask in 24-bit or 31-bit addressing mode, physically resident above or below 16 MB. When ATTACH is issued in 24-bit addressing mode, all operands are treated as 24-bit addresses. When ATTACH is issued in 31-bit addressing mode, all operands are treated as 31-bit addresses.

The attached task will get control in the same addressing mode as the issuer of the ATTACH macro. If, for example, a main task issues an ATTACH macro in AMODE 31, the subtask will also receive control in AMODE 31.

The maximum number of subtasks that can be initiated in the system concurrently depends on the number of partitions that are defined by the IPL SYS NPARTS command and on the maximum number of tasks that are defined with the SYSDEF SYSTEM NTASKS command. This maximum number of subtasks calculates as follows:

Maximum number of subtasks = 
      SYSDEF SYSTEM NTASKS value - IPL SYS NPARTS value - 32 system tasks

Up to 31 subtasks can run concurrently within a partition, provided the overall limitation as calculated above is not exceeded.

If the maximum number of subtasks is already attached, any attempt to attach another subtask is unsuccessful. This is indicated to the attaching task by a 1 in high-order bit 0 in register 1. Register 1 then points to an unposted ECB in the supervisor or the shared area (24 bit), and this ECB contains the reason code in byte 3. If byte 3 is zero, the maximum number of subtasks in the system is already attached or no system resources are available. A nonzero value indicates that the maximum number of 31 subtasks is already running in the partition. The attaching task can use this ECB to enter a wait state. The ECB is posted by the system whenever a task is available for attaching.

If the ATTACH macro successfully initiates a subtask, the attached task is given the lowest subtask priority, however, a higher priority than the main task. Register 1 of the attached task contains the address of the attaching task 's save area; the other registers contain the same values as those of the attaching task at the time when the ATTACH was issued. The address in register 1 can be used as the second operand of a POST macro later in the job if task-to-task communication is wanted.

When SAVE is specified, register 0 of the attaching task contains the address of the byte immediately following the save area of the attached task, upon return from a successful ATTACH.

Note: If your program uses VSAM files, provide STXIT macros with AB and PC and issue a CLOSE or TCLOSE for the files before you cancel the subtask.

If register notation is used in any of the macro operands, register 0 and 1 should not be specified.

Format

Requirements for the caller

AMODE:: 24 or 31
RMODE:: 24 or ANY
ASC Mode:: Primary

Parameters

entrypoint | (S,entrypoint) | (r1)

The operand specifies the entrypoint of the subtask.

SAVE=savearea | (S,savearea) | (r2)

If specified, this operand must provide the address of the save area for the subtask. The save area is 120 bytes in length (=15 doublewords) and must be allocated below the 16 MB line (RMODE 24).

If this operand is omitted, the supervisor allocates a save area for the attached subtask and passes its address in register 1 of the attaching task.

If an interrupt occurs while the subtask is in control, the system saves data in this area as follows (for the format of the area, see Table 1):

The subtask 's interrupt status information
The contents of the general purpose registers
The contents of the floating-point registers

Note: The status of the access registers is saved in an internal save area.

Before issuing the ATTACH macro, move the subtask name in the first 8 bytes of the save area. This name is used to identify the subtask if an abnormal end occurs.

Alternatively, you can specify the name of the subtask in the NAME operand of this macro.

Table 1. Subtask-Save Area (120 Bytes)
Offset (In Hex)	Length (In Hex)	Length (In Dec)	Contents
0	8	8	Name of subtask.
8	8	8	Interrupt status.
10	40	64	Contents of registers 9 through 8 (one fullword per register).
50	8	8	Reserved.
58	20	32	Contents of floating-point registers.

ABSAVE=absavearea | (S,absavearea) | (r3)

Specify this operand only if the subtask is to use the attaching task 's abnormal termination routine (see the STXIT (Set Exit) Macro), that is, if it does not provide an abnormal termination routine of its own. The value that is specified in this operand must be the address of an AB exit save area for the subtask. If no AB exit is available, the specification is ignored.

If the ATTACH macro is issued in AMODE 31 or if the attaching task uses the extended save area layout (STXIT AMODE=ANY), the length of the AB exit save area must correspond to this layout. If the attaching task uses the extended 64-bit save area layout (STXIT AMODE=ANY64), the length of the AB exit save area must correspond to this extended 64-bit layout. Otherwise, the old STXIT save area is used. See the STXIT (Set Exit) Macro and the mapping MAPSAVAR (Map Save Area) Macro.

If an abnormal termination occurs, the supervisor saves the interrupt status and general registers 0 through 15 in this area before the exit is taken. In the extended save area, also the access registers are saved.

ECB=ecbname | (S,ecbname) | (r4)

Specify this operand if other tasks can be affected by this subtask 's termination or if the ENQ and DEQ macros are used within the subtask. The operand is the name of the subtask 's event control block (ECB). This block has a format as follows:

  Bytes               Meaning of Bits if 1
 
   0-1     Reserved
 
    2        0        Termination indicator
             1        Abnormal end indicator
            2-7       Reserved
 
    3      Reserved

When a subtask is attached, bits 0 and 1 of byte 2 are set to 0. When a subtask terminates, the supervisor sets byte 2, bit 0 of the ECB to 1. In addition, byte 2, bit 1 is set to 1 when the subtask ends abnormally; that is, if task termination is not caused by issuing one of the macros CANCEL, DETACH, DUMP, JDUMP, or EOJ.

NAME=name | (S,name) | (r5)

You can specify the subtask name here; however, only if you have omitted the SAVE operand (with the subtask name specification). It points to an 8-byte subtask name field.

If both the NAME and the SAVE operands are omitted, the supervisor allocates a save area for the subtask and provides a subtask name.

ALCOPY=YES | NO

This operand allows your program to transfer a copy of the attaching task's DU-AL to the subtask to be attached. Thereby the attaching program can share access to one or more data spaces with a program running under the subtask.

YES causes a copy of the caller's DU-AL to be given to the subtask. NO causes no access list to be given.

MFG=area | (S,area) | (r6)

The operand is required if the program which issues the ATTACH macro is to be reenterable. It specifies the address of a 64-byte storage area, that is, storage which your program can obtain through a GETVIS macro. This area is required for system use during execution of the macro.