AT STATEMENT command

Gives z/OS® Debugger control at each specified statement or line within the given set of ranges.

Read syntax diagramSkip visual syntax diagramATevery_clauseLINESTATEMENTstatement_id_range(,statement_id_range)*WHENconditioncommand;
*
Sets a breakpoint at every STATEMENT or LINE.
command
A valid z/OS Debugger command. If you are using remote debug mode, you can specify only commands that are supported in remote debug mode.
condition
A valid z/OS Debugger 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 z/OS Debugger, this breakpoint is cleared at the end of the last process in the application. For a non-CICS application on z/OS Debugger, 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, z/OS Debugger 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, z/OS Debugger 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 z/OS Debugger reaches the statement, it evaluates the condition. If the condition evaluates to true, z/OS Debugger stops and runs the command associated with the breakpoint.
  • z/OS Debugger evaluates references in a WHEN condition before it runs a statement.
  • When z/OS Debugger evaluates the condition and the condition is invalid, z/OS Debugger does one of the following actions:
    • If SET WARNING is set to ON, z/OS Debugger stops and displays a message that it could not evaluate the condition. You need to enter a command to indicate what action you want z/OS Debugger to take.
    • If SET WARNING is set to OFF, z/OS Debugger does not stop nor display a message that it could not evaluate the condition. z/OS Debugger 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.