AT CHANGE command (remote debug mode)

Gives z/OS® Debugger control when the program changes the specified variable value.

Read syntax diagramSkip visual syntax diagramATCHANGE"reference"'reference';
'reference' or "reference"
A valid z/OS Debugger reference in the current programming language.

Usage notes

  • When you enter an AT CHANGE command, the breakpoint is set relative to the location the program is stopped, which might not be the program displayed in the source view. For example, your program is stopped at program SUB1, which was called by program MAIN1, and the source view displays the source for program SUB1. Then, you click on MAIN1 in the Debug view so that the source view displays the source for MAIN1. If you enter the command AT CHANGE "Var1", a breakpoint is set to monitor any changes to a variable called "Var1" in SUB1, not a variable called "Var1" in MAIN1.
  • If an AT CHANGE breakpoint is set on a file record of a BLOCKED QSAM file that is open OUTPUT or EXTEND, the breakpoint might not occur as expected when the WRITE statement is used. The breakpoint behavior in this case is not predictable because the file record is mapped onto the data management buffer.

    To get predictable AT CHANGE behavior in this case, set up the file to use a SAME RECORD AREA clause.

  • Data is watched only in storage; hence a value that is being kept in a register because of compiler optimization cannot be watched. In addition, the z/OS Debugger variables %GPRn, %Rn, %FPRn, %LPRn, %EPRn, and any assembler or disassembly symbols representing registers cannot be watched.
  • Only entire bytes are watched; bits or bit strings within a byte cannot be singled out.
  • Because AT CHANGE breakpoints are identified by storage address and length, it is not possible to have two AT CHANGE breakpoints for the same area (address and length) of storage. That is, an AT CHANGE command replaces a previous AT CHANGE command if the storage address and length are the same. However, any other overlap is ignored and the breakpoints are considered to be for two separate variables. For example, if the storage address is the same, but the length is different, the AT CHANGE command does not replace the previous AT CHANGE.
  • When more than one AT CHANGE breakpoint is triggered at a time, AT CHANGE breakpoints are triggered in the order that they were entered. However, if the triggering of one breakpoint causes a variable watched by a different breakpoint to change, the ordering of the triggers will not necessarily be according to when they were originally entered. For example, 
    AT CHANGE y LIST y;
AT CHANGE x y = 4;
GO;

    If the next statement to be executed in your program causes the value of x to change, the CHANGE x breakpoint is triggered when z/OS Debugger gains control. Processing of CHANGE x causes the value of y to change. If you type GO; after being informed that CHANGE x was triggered, z/OS Debugger triggers the CHANGE y breakpoint (before returning control to your program).

    In this case, the CHANGE y breakpoint was entered first, but the CHANGE x breakpoint was triggered first (because it caused the CHANGE y breakpoint to be triggered).

  • The referenced variable must exist when the AT CHANGE breakpoint is defined.
  • An AT CHANGE breakpoint gets removed automatically when the specified variable is no longer defined. AT CHANGEs for C static variables are removed when the module defining the variable is removed from storage. For C storage that is allocated using malloc() or calloc(), this occurs when the dynamic storage is freed using free().
  • Changes are not detected immediately, but only at the completion of any command that has the potential of changing storage or variable values.
  • C and C++ AT CHANGE breakpoint requirements
    • The variable must be an lvalue or an array.
    • The variable must be declared in an active block if the variable is a parameter or has a storage class of auto.
    • A CHANGE breakpoint defined for a static variable is automatically removed when the file in which the variable was declared is no longer active. A CHANGE breakpoint defined for an external variable is automatically removed when the module where the variable was declared is no longer active.
    • If reference is a pointer, z/OS Debugger stops when the contents of storage at the address given by that pointer changes.
  • COBOL AT CHANGE breakpoint requirements
    • AT CHANGE using a storage address should not reference a data item that follows a variable-size element or subgroup within a group. COBOL dynamically remaps the group when a variable-size element changes size.
    • Be careful when examining a variable whose allocated storage follows that of a variable-size element. COBOL dynamically remaps the storage for the element any time it changes size. This could alter the address of the variable you want to examine.
    • You cannot set a CHANGE breakpoint for a COBOL file record before the file is opened.
    • The variable, when in the local storage section, must be declared in an active block.
    • The qualification operator "::" is not supported in Debug Console commands. Use the "OF" or "IN" qualification operator instead.
  • PL/I AT CHANGE breakpoint requirements
    • CHANGE breakpoint is removed for based or controlled variables when they are FREEd and for parameters and AUTOMATIC variables when the block in which they are declared is no longer active.
    • CHANGE monitors only structures with single scalar elements. Structures containing more than one scalar element are not supported.
    • The variable must be a valid reference for the current block.
    • The breakpoint is automatically removed after the referenced variable ceases to exist.
    • A CHANGE breakpoint monitors the storage allocated to the current generation of a controlled variable. If you subsequently allocate new generations, they are not monitored.
  • When you free storage with the STORAGE RELEASE macro in an assembler or disassembly program, it is not possible to detect when the storage is freed. If you set an AT CHANGE breakpoint on storage freed by a STORAGE RELEASE macro, unexpected results might occur, such as the triggering of the breakpoint at unexpected times.
  • For optimized COBOL programs, the specified variable cannot be a variable that was discarded due to compiler optimization.
  • When you use a COBOL level-88 variable on an AT CHANGE command, the current setting of the value is saved. z/OS Debugger stops at the breakpoint only if the setting of the COBOL level-88 variable changes from the saved value to a different value. For example, if the saved value was TRUE and the new value is FALSE, z/OS Debugger stops at the breakpoint.
  • To use a COBOL level-88 variable with the AT CHANGE command, you (through a z/OS Debugger command) or the program must have previously set the variable to one of the values specified in the variable's declaration. If you do not do this, z/OS Debugger behavior becomes unpredictable.
  • If reference references 64-bit addressable storage, z/OS Debugger assumes that the storage location is 64-bit addressable storage. Otherwise, z/OS Debugger assumes that the storage location is 31-bit addressable storage.

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