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.

Command Description
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