AT STATEMENT command

Gives Debug Tool control at each specified statement or line within the given set of ranges.


>>-AT--+--------------+--+-----------+-------------------------->
       '-every_clause-'  +-LINE------+   
                         '-STATEMENT-'   

>--+-statement_id_range-----------+--+-----------------+-------->
   |    .-,------------------.    |  '-WHEN--condition-'   
   |    V                    |    |                        
   +-(----statement_id_range-+--)-+                        
   '-*----------------------------'                        

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

*: Sets a breakpoint at every STATEMENT or LINE.
command: A valid Debug Tool command. If you are using remote debug mode, you can specify only commands that are supported in remote debug mode.
condition: A valid Debug Tool conditional expression.

Usage notes

With Enterprise COBOL for z/OS® Version 5, you cannot set AT STATEMENT breakpoints for statements that are inside a declarative section.
With Enterprise COBOL for z/OS Version 5, you can set AT STATEMENT breakpoints for the WHEN and EVALUATE statements.
You cannot use the AT STATEMENT command (except for the AT STATEMENT * form) while you debug a disassembled program. Instead, use the AT OFFSET command.
A STATEMENT breakpoint set for a nonactive compile unit (one that is not in the current enclave), is suspended until the compile unit becomes active. A STATEMENT breakpoint set for a compile unit that is deleted from storage is suspended until the compile unit is reloaded. A suspended breakpoint cannot be triggered until it is reactivated.
For a CICS® application on Debug Tool, this breakpoint is cleared at the end of the last process in the application. For a non-CICS application on Debug Tool, it is cleared at the end of a process.
You can specify the first relative statement on each line in any one of three ways. If, for example, you want to set a STATEMENT breakpoint at the first relative statement on line three, you can enter AT 3, AT 3.0, or AT 3.1. However, Debug Tool logs them differently according to the current programming language as follows:
- For C and C++
  The first relative statement on a line is specified with "0". All of the above breakpoints are logged as AT 3.0.
- For COBOL or PL/I
  The first relative statement on a line is specified with "1". All of the above breakpoints are logged as AT 3.1. For optimized COBOL programs, the first relative statement is the first executable statement. This might not be the first statement if the optimizer discarded the first statement.
When the STORAGE run-time option is in effect, the AT STATEMENT command cannot be used to set a breakpoint in the prologue of an assembler compile unit between the first BALR 14,15 instruction and the following LR 13,x instruction.
The AT STATEMENT command cannot be used while you replay recorded statements by using the PLAYBACK command.
You can restrict the circumstances under which the AT STATEMENT break point is raised by specifying a WHEN condition. If a WHEN condition is specified, Debug Tool stops at the AT STATEMENT break point if the specified statement matches the current statement and the WHEN condition is true.
The following conditional operators can be used in a condition:
=

Compare the two operands for equality.

¬=

Compare the two operands for inequality.

<

Determines whether the left operand is less than the right operand.

>

Determines whether the left operand is greater than the right operand.

<=

Determines whether the left operand is less than or equal to the right operand.

>=

Determines whether the left operand is greater than or equal to the right operand.

&

Logical "and" operation.

|

Logical "or" operation.
If you use the AT STATEMENT command with a WHEN condition, every time Debug Tool reaches the statement, it evaluates the condition. If the condition evaluates to true, Debug Tool stops and runs the command associated with the breakpoint.
Debug Tool evaluates references in a WHEN condition before it runs a statement.
When Debug Tool evaluates the condition and the condition is invalid, Debug Tool does one of the following actions:
- If SET WARNING is set to ON, Debug Tool stops and displays a message that it could not evaluate the condition. You need to enter a command to indicate what action you want Debug Tool to take.
- If SET WARNING is set to OFF, Debug Tool does not stop nor display a message that it could not evaluate the condition. Debug Tool continues running the program.

Examples

Set a breakpoint at statement or line number 23. The current programming language setting is COBOL.
```
AT 23 LIST 'About to close the file';
```
Set breakpoints at statements 5 through 9 of compile unit mycu. The current programming language setting is C.
```
AT STATEMENT "mycu":>5 - 9;
```
Set breakpoints at lines 19 through 23 and at statements 27 and 31.
```
AT LINE (19 - 23, 27, 31);
```
or
```
AT LINE (27, 31, 19 - 23);
```
To set a breakpoint at statement or line 100 that is raised only when the value of myvar is equal to 100, enter the following command:
```
AT 100 WHEN myvar=100;
```

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

Related references
every_clause syntax
statement_id_range and stmt_id_spec
AT OFFSET command (disassembly)
PLAYBACK commands
Debug Tool commands supported in remote debug mode