AT

Purpose

Sets, modifies, removes, or reviews breakpoints in a program.

Syntax

ADD Format

►►─── AT debug-expression ────────────────────────────────────────────────────►

 ►─┬───────────────────────────────┬─┬──────────────────────────────┬─────────►
   └─ BEFore ─┬─ MAXimum ◄ ───────┬┘ └─ AFTer ─┬─ 0 ◄ ─────────────┬┘
              └─ execution-count ─┘            └─ execution-count ─┘

 ►─┬──────────────────────────────┬─┬──────────┬──────────────────────────────►◄
   └─ EVEry ─┬─ 1 ◄ ─────────────┬┘ ├─ ON ◄ ───┤
             └─ execution-count ─┘  └─ IGNore ─┘

INQUIRE Format

►►─── AT ─┬─ ALL ──────────────┬─┬─ INQuire ─┬────────────────────────────────►◄
          └─ debug-expression ─┘ ├─ ON ──────┤
                                 ├─ IGNore ──┤
                                 └─ OFF ─────┘

Parameters

debug-expression

Specifies a breakpoint location in a user program. Debug-expression can include multiple debug expressions, and it resolves to an address containing a valid instruction or a valid CME (CA ADS dialogs only). It is not valid to set a breakpoint at the target of an Assembler execute (EX) instruction.

Note: Debugger will not successfully resume if you set breakpoint at a "BALR RX,0" type instruction or a "BAL RX,..." instruction later used as a base register. An alternative is to set breakpoint at next instruction.

Note: For more information on the values used in a debug expression, see Expression Components in the "Command Considerations" chapter.

ALL

Specifies that the action should apply to all previously established breakpoints. Can be used only in INQUIRE format.

BEFore MAXimum

Causes the debugger to pause each time the breakpoint instruction is reached. MAXIMUM is the default.

BEFore execution-count

Specifies an execution pause every time the specified breakpoint instruction is encountered, up to but not including execution-count.

AFTer 0

Causes the debugger to pause each time the breakpoint instruction is reached. Zero is the default.

AFTer execution-count

Specifies an execution pause each time the same breakpoint instruction is encountered beyond execution-count.

EVEry 1

Causes the debugger to pause every time the breakpoint instruction is encountered. One is the default.

EVEry execution-count

Specifies an execution pause each time the counter for the specified breakpoint instruction reaches a multiple of execution-count.

ON

Sets a new breakpoint or resets the status of a breakpoint previously ignored. ON is the default in ADD format.

IGNore

Bypasses the specified breakpoint but increments the breakpoint counter.

OFF

Removes the breakpoint. Can be used only in INQUIRE format.

INQuire

Requests a listing of the breakpoint locations and characteristics. Can be used only in INQUIRE format.

Usage

Two formats

The AT command has two formats. The ADD format is used to set and modify breakpoints; the INQUIRE format is used to review breakpoint locations, if any have been set, as well as to modify the breakpoints.

Temporary processing halt

A breakpoint temporarily halts processing, allowing you to examine the results of execution up to the point of interruption. Processing is halted before the instruction at the breakpoint is executed. You can use the AT command in both the setup and the runtime phases of a debugger session.

Breakpoint count

In response to the INQUIRE format, the debugger displays all parameters in effect for the named breakpoints and indicates the breakpoint count. The breakpoint count (BKPT COUNT) shows how often the breakpoint has been encountered from the time the program received control via #LINK or #XCTL.

If you issue an AT INQUIRE command is issued during the setup phase, the breakpoint count documents the count from the most recently executed program. The breakpoint counter is reset to zero each time a #LINK or #XCTL is processed for the program.

Example 1

This command schedules program breaks on the second through ninth time the instruction at the address $ + 8 is encountered.

DEBUG >
at $ + 8 before 10 after 1

The debugger verifies the breakpoint with this message:

AT>  $ + 8 ADDED

Once the breakpoint in the example above has been set, the debugger displays the following message in response to an AT $ + 8 INQUIRE command:

AT>  AT $ + 8 BEFORE 10 AFTER 1 EVERY 1 BKPT COUNT 0 ON

In this example, the default value is indicated for the EVERY parameter. BKPT COUNT 0 indicates that this breakpoint has not yet been encountered in the current execution of the program.

Example 2

When a breakpoint is reached during the runtime phase, the debugger displays a message that names the address, identifies the program, and displays the debug expression that established the breakpoint. For example, the following message would appear for a breakpoint established with an AT $ + 8 command for program TESTPROG:

AT OFFSET @8 IN TESTPROG EXPRESSION $ + 8

Example 3

In CA ADS dialogs you can set breakpoints by specifying a line number:

DEBUG >
at #200

If line 200 is a valid address, the debugger responds to the above command as follows:

AT #200
AT> #200 ADDED

Example 4

When debugging a dialog, you can set a breakpoint in a process other than the current process without changing the currency. In the following example where MIS-MAIN1 is the current process, a breakpoint is set at line 100 in a second process (MIS-MAIN2); MIS-MAIN1 retains its currency. As usual, the debugger sends a verifying message when the breakpoint address is valid.

DEBUG >
at 'mis-main2'.#100

AT 'MIS-MAIN2'.#100
AT> 'MIS-MAIN2'.#100 ADDED
DEBUG >

In the above example, the programmer encloses the process name in single quotation marks (') because the name contains an embedded hyphen (-). Quotation marks are required for any name that contains embedded delimiters.