AT APPEARANCE command

Gives z/OS® Debugger control when the specified compile unit is found in storage. This is usually the result of a new load module being loaded. However, for modules with the main compile unit in COBOL, the breakpoint does not occur until the compile unit is first entered after being loaded.

*: Sets a breakpoint at every APPEARANCE of any compile unit.
command: A valid z/OS Debugger command.

Usage notes

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.
If the compile unit is qualified with a load module name, the AT APPEARANCE breakpoint will only be recognized for the compile unit that is contained in the specified load module. For example, if a compile unit cux that is in load module loady appears, the breakpoint AT APPEARANCE loadx::>cux will not be triggered.
If the compile unit is not qualified with a load module name, the current load module qualification is not used.
z/OS Debugger gains control when the specified compile unit is first recognized by z/OS Debugger. This can occur when a program is reached that contains a reference to that compile unit. This occurs late enough that the program can be operated on (setting breakpoints, for example), but early enough that the program has not yet been executed. In addition, for C, static variables can also be referenced.
The AT APPEARANCE command cannot be used while you replay recorded statements by using the PLAYBACK commands.
AT APPEARANCE is helpful when setting breakpoints in unknown compile units. You can set breakpoints at locations currently unknown to z/OS Debugger by using the proper qualification and embedding the breakpoints in the command list associated with an APPEARANCE breakpoint. However, there can be only one APPEARANCE breakpoint set at any time for a given compile unit and you must include all breakpoints for that unknown compile unit in a single APPEARANCE breakpoint.
For a non-CICS® application, the AT APPEARANCE breakpoint is cleared at the end of a process.
Before you enter the AT APPEARANCE command while you debug an assembler or disassembled program, enter the SET ASSEMBLER ON or SET DISASSEMBLY ON command.
For C, C++, and Enterprise COBOL for z/OS Version 5 only: AT APPEARANCE is not triggered for compile units that reside in a loaded module because the compile units are known at the time of the load.
For C, C++, Enterprise COBOL for z/OS Version 5, and PL/I only: An APPEARANCE breakpoint is triggered when z/OS Debugger finds the specified compile unit in storage. To be triggered, however, the APPEARANCE breakpoint must be set before the compile unit is loaded.
For Enterprise COBOL for z/OS Version 4 or earlier: An APPEARANCE breakpoint is triggered when z/OS Debugger finds the specified compile unit in storage. To be triggered, however, the APPEARANCE breakpoint must be set before the compile unit is called.
At the time the APPEARANCE breakpoint is triggered, the compile unit you are monitoring has not become the currently-running compile unit. The compile unit that is current when the new compile unit appears in storage, triggering the APPEARANCE breakpoint, remains the current compile unit until execution passes to the new compile unit.
For CICS only: The AT APPEARANCE breakpoint is cleared at the end of the last process in the application.

Examples

Establish an entry breakpoint when compile unit cu is found in storage. The current programming language setting is C.
```
AT APPEARANCE cu {
  AT ENTRY a;
  GO;
}
```
Defer the AT EXIT and AT LABEL breakpoints until compile unit cuy is first entered after being loaded into storage. The current programming language setting is COBOL.
```
AT APPEARANCE cuy PERFORM
  AT EXIT cuy:>blocky LIST ('Exiting blocky.');
  AT LABEL cuy:>lab1 QUERY LOCATION;
END-PERFORM;
```
If cuy is later deleted from storage, the breakpoints that are dependent on cuy are automatically cleared. However, if cuy is then loaded again, the APPEARANCE breakpoint for cuy is triggered and the AT EXIT and AT LABEL breakpoints are redefined.

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