ABEND — Abnormally terminate a task

Description

The ABEND macro is used to initiate error processing for a task. ABEND can request a full or tailored dump of virtual storage areas and control blocks pertaining to the tasks being abnormally terminated, and can specify that the entire job step is to be abnormally terminated. If a user-written recovery routine was activated at the time the ABEND macro was issued, it will get control before the task is terminated. This routine may recover the task and allow it to retry. See z/OS MVS Programming: Assembler Services Guide for information on how to provide user-written recovery routines.

If the job step task is abnormally terminated or if ABEND specifies job step termination, the completion code is recorded on the system output device, and the remaining job steps in the job are either skipped or executed as specified in their job control statements.

If the job step is not to be terminated, the system takes the following actions:
  • It terminates the task that was active when ABEND was issued and all of the subtasks of that active task.
  • It posts the completion code as indicated in the completion code parameter description below.
  • It selects the end-of-task exit routine specified in the ATTACH macro to receive control. That end-of-task routine created the task that issued ABEND. The system gives the exit routine control when the originating task of the task for which ABEND was issued becomes active. It does not give control to any of the end-of-task exit routines specified for any subtasks of the task for which ABEND was issued.

Environment

The requirements for the caller are:

Environmental factor Requirement
Minimum authorization: Problem state and any PSW key
Dispatchable unit mode: Task or SRB
Cross memory mode: Any PASN, any HASN, any SASN
AMODE: 24- or 31- or 64-bit
ASC mode: Primary, secondary, or access register (AR)
Interrupt status: Enabled or disabled for I/O and external interrupts
Locks: No locks required
Control parameters: None.

Programming requirements

If your program is in AR mode, issue the SYSSTATE ASCENV=AR macro before you issue the ABEND macro. SYSSTATE ASCENV=AR tells the ABEND macro to generate code appropriate for AR mode.

Restrictions

None.

Input register information

Before issuing the ABEND 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

None, because control does not return to the caller.

Performance implications

None.

Syntax

The ABEND macro is written as follows:

Syntax Description
   
   name name: Symbol. Begin name in column 1.
   
␢ One or more blanks must precede ABEND.
   
ABEND  
   
␢ One or more blanks must follow ABEND.
   
comp code
comp code:  Symbol, decimal or hexadecimal digit, or
register (1) or (2) - (12).
Value range:  0 - 4095
   
   ,REASON=reason code reason code: Symbol, decimal or hexadecimal number, or register (2) - (12).
   
   ,DUMP  
   ,,STEP  
   ,,,code type code type: USER or SYSTEM. Default: code type = USER.
   ,DUMP,STEP  
   ,DUMP,,code type  
   ,,STEP,code type  
   ,DUMP,STEP,code type  
   ,DUMP,DUMPOPT=parm
   list addr
 parm list addr: RX-type address, or register (2) - (12).
   ,DUMP,DUMPOPX=parm
   list addr
  
   

Parameters

The parameters are explained as follows:

comp code
Specifies the completion code associated with the abnormal termination. If the job step is to be terminated, the decimal representation of the user completion code or the hexadecimal representation of the system completion code is recorded on the system output device. If the job step is not to be terminated, the completion code is placed in the TCB of the active task, and in the ECB specified in the ECB parameter of the ATTACH macro issued to create the active task. If you specify a hexadecimal digit, you must use X‘dd’ format to distinguish the hexadecimal from decimal.
,REASON=reason code
Specifies the reason code that the user wants to pass to subsequent recovery exits. The value range for the reason code is a 32-bit hexadecimal number or a 31-bit decimal number. This reason code supplements the completion code associated with an abnormal termination, allowing the user to uniquely identify the cause of the abnormal termination. The reason code is propagated to each recovery exit.
,DUMP
,,STEP
,,,code type
,DUMP,STEP
,DUMP,,code type
,,STEP,code type
,DUMP,STEP,code type
,DUMP,DUMPOPT=parm list addr
,DUMP,DUMPOPX=parm list addr
Specifies options available with the ABEND macro:

DUMP specifies that a dump is requested of virtual storage areas assigned to the task and control blocks pertaining to the task. A separate dump is provided for each of the tasks being terminated as a result of ABEND. If a //SYSABEND, //SYSMDUMP, or //SYSUDUMP DD statement is not provided, the DUMP parameter is ignored.

For z/OS UNIX System Services, the system writes a core dump, which is a SYSMDUMP to an HFS file, for errors following an exec or fork() function when the original address space had a SYSMDUMP DD statement. For more information, see AD/Cycle LE/370 Debugging and Run-Time Messages Guide.

STEP specifies that the entire job step of the active task is to be abnormally terminated.

Note: If the STEP parameter is coded in an ABEND macro under TSO, the TSO job will be terminated.

code type specifies that the completion code is to be treated as a USER or SYSTEM code.

DUMPOPT and DUMPOPX specify the address of a parameter list of options for a tailored dump. To create the parameter list, use the list form of either the SNAP or SNAPX macro, or code data constants in your program. DUMPOPT specifies the address of a parameter list that the SNAP macro created. DUMPOPX specifies the address of a parameter list that the SNAPX macro created.

The TCB, DCB, ID, and STRHDR options available on SNAP will be ignored if they appear in the parameter list; the TCB used will be that of the task being terminated, the DCB used will be provided by the ABDUMP routine. If a //SYSABEND, //SYSMDUMP, or //SYSUDUMP DD statement is not provided, this parameter is ignored.

If the dump options specified include ranges of storage areas to be dumped, only the storage areas in the first thirty ranges will be dumped. If SUBPLST is specified in the SNAP or SNAPX parameter list passed to the ABEND macro via DUMPOPT or DUMPOPX, the first seven subpools will be dumped.

The dump option parameter list, storage ranges, and subpools must be in the primary address space.

ABEND codes

None.

Return and reason codes

None.

Example 1

Terminate with a user completion code of 432. 
ABEND 432

Example 2

Terminate with the user completion code that is contained in register 5. The entire job step is to be terminated. 
ABEND (5),,STEP

Example 3

Terminate with a system completion code of X‘0C4’. 
ABEND X'0C4',,,SYSTEM