TASKEXIT

Standard Format

See also List Format, List Address Format and Execute Format.

Purpose

Use the TASKEXIT macro to declare a task termination exit routine for an entire virtual machine group.

A task termination exit routine, declared for an entire virtual machine group, gains control whenever a task running within the group terminates—either normally or abnormally.

There are several good reasons for declaring such an exit routine for a virtual machine group. For example, several subsystem applications may be running in various virtual machines within the group. Having a task termination exit routine declared might help the subsystem clean up after itself, monitor the various applications, and react to their progress.

The TASKEXIT macro is an authorized GCS function.

Parameters

SET

Indicates that you are declaring a task termination exit routine for your entire virtual machine group.

CLR

Indicates that the task termination exit routine you specify is to be canceled.

EP

Specifies the address of the task termination exit routine in question.

This exit routine must reside in a shared segment. That is, a routine whose entry point is defined in a shared segment directory that was created through the CONTENTS macro. See CONTENTS.

You can write this parameter as an assembler program label or as register (2) through (12).

UWORD

Specifies a fullword of data you want passed to the task termination exit routine if it ever gains control.

You can use this parameter to pass any information you please.

If you write this parameter as an assembler program label, then the address associated with that label is passed to the exit routine. If you write it as register (2) through (12), then the contents of the register are passed to the routine.

NAME

Specifies a name used in any TASKEXIT macro to refer to a certain task termination exit routine.

Do not confuse this name with the name of any entry point within the exit routine or with the name of the routine itself. This name is merely an identifier used by the TASKEXIT macro to distinguish one task termination exit routine from another. The name is meaningless outside the TASKEXIT macro environment.

This name can contain up to eight characters.

There are two ways of coding this name in the TASKEXIT macro:

• Write the actual name itself.
• Write a register number from (2) through (12). The register you specify must contain the address where the name can be found. If the name is less than eight characters long, then it must be padded on the right with blanks.

ERROR

Specifies the address of an error routine that is to receive control if an error is found in the TASKEXIT macro.

If you omit this parameter and an error occurs, then control will return to the instruction following the TASKEXIT macro, just as it would were there no error.

Usage

1. Only an authorized user can enter the TASKEXIT macro.
2. The exit routine that you define through the TASKEXIT macro must reside in a shared segment.
3. Remember that the identifier you specify in the NAME parameter is strictly for your benefit and the TASKEXIT macro. To specify the SET and NAME parameters together states the name that is associated with the exit routine in question.
4. The AMODE, which the exit will be run, is the AMODE from the correspondent entry in the CONTENTS macro. However if the AMODE parameter in the CONTENTS entry is DEFINED, then the address of the routine in the TASKEXIT macro will be considered a 32 bit address with the AMODE being the first bit. See CONTENTS.
5. You can declare more than one task termination exit routine for your virtual machine group. However, because the TASKEXIT macro can declare only one exit routine at a time, you will have to enter it more than once. Each exit routine that you declare will run when a task in your virtual machine group terminates. However, the order which they will run is unpredictable.
6. GCS associates the PSW key and the enable flags of the task that issues the TASKEXIT macro with those of the task termination exit routine.
7. A task termination exit routine always runs in supervisor state. Moreover, it is eligible for the same types of interrupts as the task that declared it.
8. Remember that besides the task termination exit routine declared for the entire group, an individual task may have its own exit routines declared. For example, you may have defined an exit routine through the ESTAE macro that will run if the task ends abnormally.

   Should this be the case, and the task ends, GCS sees to it that the task's exit routines are run first. Afterward the task termination exit routine is executed.

9. When the task that declared the task termination exit routine terminates, then the latter executes one last time. After that, it disappears.
10. When the task termination exit routine gains control, its registers contain the following:

    Register	Contents
    0	The high-order 2 bytes contain the virtual machine ID in which the terminated task was running. The low-order bytes contain the task ID.
    1	The UWORD.
    13	Address of the register save area.
    14	Return address within the GCS supervisor.
    15	The address of the task termination exit routine.

Return Codes and ABEND Codes

When this macro completes processing, it passes to the caller a return code in register 15.

List Format

Notes:

• ¹ The following parameters are optional and may be specified in any order. For any parameter not specified, the default value, if applicable, is used.

Purpose (List Format)

This format of the macro generates an in-line parameter list based on the parameter values that you specify. However, this format generates no executable code. Remember that you cannot specify any of the parameters using register notation. Only the preceding parameters listed are valid in the list format of this macro.

Added Parameter

MF=L

Specifies the list format of this macro.

List Address Format

Notes:

• ¹ The following parameters are optional and may be specified in any order. For any parameter not specified, the default value, if applicable, is used.

Purpose (List Address Format)

This format of the macro does not produce any executable code that starts the function. However, it does produce executable code that moves the parameter values that you specify into a certain parameter list. If you enter the macro using this format, then you must do so before any related invocation of the macro using the execute format. Only the preceding parameters listed are valid in the list address format of this macro.

Added Parameter (List Address Format)

MF=(L,address,label)

address specifies the address of the parameter list into which you want the parameter values you mention placed. This address can be within your program or somewhere in free storage.

label is optional and is a user-specified label, indicating that you want to determine the length of the parameter list. The macro expansion equates the label you specify with the length of the parameter list.

Execute Format

Notes:

• ¹ The following parameters are optional and may be specified in any order. For any parameter not specified, the default value, if applicable, is used.

Purpose (Execute Format)

This format of the macro generates code that executes the function using a parameter list whose address you specify. Only the preceding parameters listed are valid in the execute format of this macro.

Added Parameter (Execute Format)

MF=(E,address)

address specifies the address of the parameter list to be used by the macro.

You can add or modify values in this parameter list by specifying them in this macro.