AT OCCURRENCE command

Gives z/OS® Debugger control on a language or Language Environment® condition or exception or an MVS or CICS® ABEND.


>>-AT--+--------------+--OCCURRENCE--+-condition-----------+---->
       '-every_clause-'              |    .-,---------.    |   
                                     |    V           |    |   
                                     '-(----condition-+--)-'   

>--command--;--------------------------------------------------><

condition

A valid condition or exception. This can be one of the following codes or conditions:

A Language Environment symbolic feedback code.
A language-oriented keyword or code, depending on the current programming language setting.
An MVS System or User ABEND code Sxxx or Uxxx, where xxx is three hexadecimal digits corresponding to the desired ABEND code. These codes are valid only when you are running without the Language Environment run time.
Any four-character string representing a CICS ABEND code. This code is valid only when you are running without the Language Environment run time.

Following are the C and C++ condition constants; they must be uppercase and not abbreviated:

SIGABND
SIGABRT
SIGFPE

SIGILL
SIGINT
SIGIOERR
SIGSEGV

SIGTERM
SIGUSR1
SIGUSR2
THROWOBJ

When a C++ user specifies AT CONDITION THROWOBJ, z/OS Debugger transfers control to the user at the point of the throw in C++ code.

PL/I condition constants can be used. For conditions associated with file handling, the file reference can be a wildcard.

There are no COBOL condition constants. Instead, an Language Environment symbolic feedback code must be used, for example, CEE347.

The TRAP(ON) run-time option must be used to stop on Language Environment conditions or MVS or CICS Abends.

command

A valid z/OS Debugger command.

Program conditions and condition handling vary from language to language. The methods the OCCURRENCE breakpoint uses to adapt to each language are described below.

For C and C++:

When a C and C++ or an Language Environment condition occurs during your session, the following series of events takes place:

z/OS Debugger is started before any C or C++ signal handler.
If you set an OCCURRENCE breakpoint for that condition, z/OS Debugger processes that breakpoint and executes any commands you have specified. If you did not set an OCCURRENCE breakpoint for that condition, and:
- If the current test-level setting is ALL, z/OS Debugger prompts you for commands or reads them from a commands file.
- If the current test-level setting is ERROR, and the condition has an error severity level (that is, anything but SIGUSR1, SIGUSR2, SIGINT, or SIGTERM), z/OS Debugger gets commands by prompting you or by reading from a commands file.
- If the current test-level setting is NONE, z/OS Debugger ignores the condition and returns control to the program.

You can set OCCURRENCE breakpoints for equivalent C and C++ signals and Language Environment conditions. For example, you can set AT OCCURRENCE CEE345 and AT OCCURRENCE SIGSEGV during the same debug session. Both indicate an addressing exception and, if you set both breakpoints, no error occurs. However, if you set OCCURRENCE breakpoints for a condition using both its C, C++, and Language Environment designations, the Language Environment breakpoint is the only breakpoint triggered. Any command list associated with the C condition is not executed.

You can use OCCURRENCE breakpoints to control your program's response to errors.

Usage notes

If the application program also has established an exception handler for the condition then that handler is entered when z/OS Debugger releases control, unless return is by use of GO BYPASS or GOTO or a specific statement.
OCCURRENCE breakpoints for COBOL IGZ conditions can only be set after a COBOL run-time module has been initialized.
For C, C++, and PL/I, certain Language Environment conditions map to C and C++ SIGxxx values and PL/I condition constants. It is possible to enter two AT OCCURRENCE breakpoints for the same condition. For example, one could be entered with the Language Environment condition name and the other could be entered with the C and C++ SIGxxx condition constant. In this case, the AT OCCURRENCE breakpoint for the Language Environment condition name is triggered and the AT OCCURRENCE breakpoint for the C or C++ condition constant is not. However, if an AT OCCURRENCE breakpoint for the Language Environment condition name is not defined, the corresponding mapped C, C++, or PL/I condition constant is triggered.
If this breakpoint is set in a parent enclave it can be triggered and operated on with breakpoint commands while the application is in a child enclave.
For a CICS application on z/OS Debugger, this breakpoint is cleared at the end of the last process in the application. For a non-CICS application on z/OS Debugger, it is cleared at the end of a process.
For COBOL and LangX COBOL, z/OS Debugger detects Language Environment conditions. If a Language Environment condition occurs during your session, the following series of events takes place:
1. z/OS Debugger is started before any condition handler.
2. If you set an OCCURRENCE breakpoint for that condition, z/OS Debugger processes that breakpoint and executes any commands you have specified. If you have not set an OCCURRENCE breakpoint for that condition, and:
  - If the current test-level setting is ALL, z/OS Debugger prompts you for commands or reads them from a commands file.
  - If the current test-level setting is ERROR, and the condition has a severity level of 2 or higher, z/OS Debugger gets commands by prompting you or by reading from a commands file.
  - If the current test-level setting is NONE, z/OS Debugger ignores the condition and returns control to the program.
You can use OCCURRENCE breakpoints to control your program's response to errors.
For PL/I, z/OS Debugger detects Language Environment and PL/I conditions. If a condition occurs, z/OS Debugger is started before any condition handler. If you have issued an ON command or set an OCCURRENCE breakpoint for the specified condition, z/OS Debugger runs the associated commands.
If there is no AT OCCURRENCE or ON set, then:
- If the current test-level setting is ALL, z/OS Debugger prompts you for commands or reads them from a commands file.
- If the current test-level setting is ERROR, and the condition has an error severity level of 2 or higher, z/OS Debugger gets commands by prompting you or by reading from a commands file.
- If the current test-level setting is NONE, z/OS Debugger ignores the condition and returns control to the program.
Once z/OS Debugger returns control to the program, any relevant PL/I ON-unit is run.
If you are debugging a program that uses SPIE or ESPIE, while SPIE or ESPIE is active, the program behaves as if TRAP(OFF) was specified for all program checks except for a program check that might arise from the use of the CALL command.
If you are debugging a program that uses ESTAE or ESTAEX, while ESTAE or ESTAEX is active, the program behaves as if TRAP(OFF) was specified for all abends except program checks. z/OS Debugger does not handle any conditions. The ESTAE or ESTAEX exit handles any abends except for program checks.
The AT OCCURRENCE command cannot be used while you replay recorded statements using the PLAYBACK commands.

Examples

When a data exception occurs, query the current location. The current programming language setting is either C or COBOL.
```
AT OCCURRENCE CEE347 QUERY LOCATION;
```
When you are running in MVS without the Language Environment run time, that is under EQANMDBG, when a System 0C1 ABEND occurs, list information about the current CUs with the following command:
```
AT OCCURRENCE S0C1 DESCRIBE CUS;
```
When the SIGSEGV condition is raised, set an error flag and call a user termination routine. The current programming language setting is C.
```
AT OCCURRENCE SIGSEGV {
  error = 1;
  terminate (error);
}
```
Suppose SIGFPE maps to CEE347 and the following breakpoints are defined. The current programming language setting is C.
```
AT OCCURRENCE SIGFPE LIST "SIGFPE condition";
AT OCCURRENCE CEE347 LIST "CEE347 condition";
```
If the Language Environment condition CEE347 is raised, the CEE347 breakpoint is triggered.

However, if a breakpoint had not been defined for CEE347 and the CEE347 condition is raised, the SIGFPE breakpoint is triggered (because it is mapped to CEE347).
Stop for every file where ENDFILE condition occurs. The current programming language is PL/I.
```
AT OCCURRENCE ENDFILE(*);
```

Refer to the following topics for more information related to the material discussed in this topic.

Related references
every_clause syntax
ON command (PL/I)
PLAYBACK commands
z/OS Language Environment Programming Guide
z/OS Language Environment Debugging Guide
PL/I for MVS and VM Language Reference