AT command

The AT command defines a breakpoint or a set of breakpoints. By defining breakpoints, you can temporarily suspend program execution and use z/OS® Debugger to perform other tasks. By specifying an AT-condition in the AT command, you instruct z/OS Debugger when to gain control. You can also specify in the AT command what action z/OS Debugger should take when the AT-condition occurs.

A breakpoint for the specified AT-condition remains established until either another AT command establishes a new action for the same AT-condition or a CLEAR command removes the established breakpoint. An informational message is issued when the first case occurs. Some breakpoints might become obsolete during a debug session and will be cleared automatically by z/OS Debugger.

For MVS batch, TSO, and CICS® programs, the SET SAVE and SET RESTORE commands can be used to automatically save and restore breakpoints between z/OS Debugger sessions. For all other programs, the SET SAVE and RESTORE commands can be used to automatically save and manually restore breakpoints between sessions.

For CICS only: If you do not use the SET SAVE and SET RESTORE commands to control the saving and restoring of breakpoints or monitor specifications and you use a DTCN profile to start a full-screen mode debugging session, z/OS Debugger preserves the following breakpoints for that session until the DTCN profile is deleted:

APPEARANCE breakpoints
CALL breakpoints
DELETE breakpoints
ENTRY breakpoints
EXIT breakpoints
GLOBAL APPEARANCE breakpoints
GLOBAL CALL breakpoints
GLOBAL DELETE breakpoints
GLOBAL ENTRY breakpoints
GLOBAL EXIT breakpoints
GLOBAL LABEL breakpoints
GLOBAL LOAD breakpoints
GLOBAL STATEMENT/LINE breakpoints
LABEL breakpoints
LOAD breakpoints
OCCURRENCE breakpoints
STATEMENT/LINE breakpoints
TERMINATION breakpoint

If a deferred AT ENTRY breakpoint has not been encountered, it is not saved nor restored.

For optimized COBOL programs: The order in which breakpoints are encountered in optimized programs is generally the same as in unoptimized programs. There might be differences due to the effects of optimization.

The following table summarizes the forms of the AT command.

`AT ALLOCATE (PL/I) command`	Gives z/OS Debugger control when storage for a named controlled variable or aggregate is dynamically allocated by PL/I.
`AT APPEARANCE command`	Gives z/OS Debugger control: For C and PL/I, when the specified compile unit is found in storage For COBOL, the first time the specified compile unit is called
`AT CALL command`	Gives z/OS Debugger control on an attempt to call the specified entry point.
`AT CHANGE command (full screen mode, line mode, batch mode)`	Gives z/OS Debugger control when either the specified variable value or storage location is changed.
`AT CHANGE command (remote debug mode)`	Gives z/OS Debugger control when the specified variable value is changed.
`AT CURSOR command (full-screen mode)`	Defines a statement breakpoint by cursor pointing.
`AT DATE command (COBOL)`	For COBOL, gives z/OS Debugger control for each date processing statement within the specified block.
`AT DELETE command`	Gives z/OS Debugger control when a load module is deleted.
`AT ENTRY command` or `AT ENTRY command (remote debug mode)`	Defines a breakpoint at the specified entry point.
`AT EXIT command`	Defines a breakpoint at the specified exit point.
`AT GLOBAL command`	Gives z/OS Debugger control for every instance of the specified `AT`-condition.
`AT LABEL command`	Gives z/OS Debugger control at the specified statement label.
`AT LINE command`	Gives z/OS Debugger control at the specified line.
`AT LOAD command` or `AT LOAD command (remote debug mode)`	Gives z/OS Debugger control when the specified load module is loaded.
`AT OCCURRENCE command`	Gives z/OS Debugger control on a language or Language Environment® condition or exception.
`AT OFFSET command (disassembly)`	Gives z/OS Debugger control at the specified offset in the disassembly view.
`AT PATH command`	Gives z/OS Debugger control at a path point.
`AT Prefix command (full-screen mode)`	Defines a statement breakpoint through the Source window prefix area.
`AT STATEMENT command` or `AT STATEMENT command (remote debug mode)`	Gives z/OS Debugger control at the specified statement.
`AT TERMINATION command`	Gives z/OS Debugger control when the application program is terminated.

Usage notes

To set breakpoints at specific locations in a program, z/OS Debugger depends on that program being loaded into storage. If you issue an AT command for a specific EXIT, LABEL, LINE, or STATEMENT breakpoint and the program is not known by z/OS Debugger, a warning message is issued and the breakpoint is not set. For ENTRY, the breakpoint becomes a deferred breakpoint.
To set a global breakpoint, you can specify an asterisk (*) with the AT command or you can specify an AT GLOBAL command. For example, if you want to set a global AT ENTRY breakpoint, specify:
```
AT ENTRY *;
or
AT GLOBAL ENTRY;
```
AT CHANGE, AT EXIT, AT LABEL, AT LINE, or AT STATEMENT breakpoints (when entered for a specific block, label, line, or statement) are automatically cleared when the containing compile unit is removed from storage. AT ENTRY breakpoints are converted to deferred AT ENTRY breakpoints.
AT CHANGE breakpoints are usually automatically cleared when the containing blocks are no longer active or if the relevant variables are in dynamic storage that is freed by a language construct in the program (for example, a C call to free()). However, such breakpoints are not cleared when storage in an assembler or disassembly program is freed via a STORAGE RELEASE macro.
Clearing of a breakpoint is independent of whether the breakpoint is enabled by using the ENABLE command or disable by using the DISABLE command.
When multiple AT conditions are raised at the same statement or line, z/OS Debugger processes them in the following order:
1. Any global breakpoints other than PATH.
2. Any PATH breakpoints.
3. Any statement breakpoints.
4. Any CHANGE breakpoints
If you want breakpoints to stop your program only under certain conditions, you can use a combination of the AT and IF command or the AT command with a WHEN condition to establish a conditional breakpoint.
The AT commands cannot be used while you replay recorded statements by using the PLAYBACK commands.

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

Related tasks
IBM® z/OS Debugger User's Guide

Related references
LIST command