AT CHANGE command (full screen mode, line mode, batch mode)

Gives z/OS® Debugger control when either the program or z/OS Debugger command changes the specified variable value or storage location.

Read syntax diagramSkip visual syntax diagramATevery_clauseCHANGEGLOBALLOCAL%CUcu_specreference'reference'WHENcondition%STORAGE(address,length)(,reference'reference'%STORAGE(address,length))command;
GLOBAL
Specifies that the AT CHANGE breakpoint is global. The AT CHANGE breakpoint is not limited to a specific compile unit; it spans the entire application. This is the default.
LOCAL
Specifies that the AT CHANGE breakpoint is limited to a specific compile unit.
cu_spec
A valid compile unit specification. Specifies that the AT CHANGE breakpoint is limited to this compile unit.
condition
A valid, simple z/OS Debugger conditional expression. Simple means that you use only one operator; for example, a < b.
reference
A valid z/OS Debugger reference in the current programming language.
'reference'
A valid z/OS Debugger reference when the current programming language is LangX COBOL.
%STORAGE
A built-in function that provides an alternative way to select an AT CHANGE subject.
address
The starting address of storage to be watched for changes.
length
The number of bytes of storage being watched for changes. This must be a positive integer constant. The default value is 1.
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.

Usage notes

  • 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).

  • %STORAGE is a z/OS Debugger built-in function that is available only with the AT CHANGE command.
  • For a CICS® application on z/OS Debugger, the CHANGE %STORAGE 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.
  • The referenced variables must exist when the AT CHANGE breakpoint is defined. One way to ensure this is to embed the AT CHANGE in an AT ENTRY.
  • 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, variable values, or the logical condition. If you specify a single reference, you can restrict the circumstances under which the CHANGE condition is raised by specifying a WHEN condition. If you enter a z/OS Debugger command that modifies a variable being watched, the CHANGE condition is raised immediately if no WHEN condition is specified. If a WHEN condition is specified, the CHANGE condition is only raised if the variable is modified and the WHEN condition is true. You can force more or less frequent checking by using the SET CHANGE command.
  • 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.
  • 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.
  • For PL/I and C/C++, when you specify a reference, z/OS Debugger calculates the address of the reference only once, when it runs the AT CHANGE command the first time. Thereafter, z/OS Debugger monitors the storage location indicated by that address.
    For the following items, z/OS Debugger recalculates the address of reference each time it monitors the storage location. If the address of reference changes, z/OS Debugger uses the new storage location as the address to monitor:
    • COBOL variables whose address can change
    • Assembler DSECT items that are in the range of an active USING when you enter the AT CHANGE command
    • Assembler absolute locations that are in the range of an active USING when you enter the AT CHANGE command
  • 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.
  • The AT CHANGE command cannot be used while you replay recorded statements by using the PLAYBACK commands.
  • 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. Note that level-88 variables cannot be listed in LangX COBOL.
  • 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.
  • When you use a condition, the variables used in the condition or the condition are not evaluated at the time the breakpoint is set but when the location associated with the AT CHANGE command changes.
  • Only 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 CHANGE command with a WHEN condition, every time the variable changes the condition is evaluated. If the condition evaluates to true, z/OS Debugger stops and runs the command associated with the breakpoint.
  • 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.
  • If you specify address with more than 8 significant digits or 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.

Examples

  • Identify the current location each time variable varbl1 or varbl2 is found to have a changed value. The current programming language setting is COBOL. 
    AT CHANGE (varbl1, varbl2) PERFORM
  QUERY LOCATION;
  GO;
END-PERFORM;
  • When storage at the hex address 22222 changes, print a message in the log. Eight bytes of storage are to be watched. The current programming language setting is C. 
    AT CHANGE %STORAGE (0x00022222, 8)
  LIST "Storage has changed at hex address 22222";
  • Set two breakpoints when storage at the hex address 1000 changes. The variable x is defined at hex address 1000 and is 20 bytes in length. In the first breakpoint, 20 bytes of storage are to be watched. In the second breakpoint, 50 bytes of storage are to be watched. The current programming language setting is C. 
    AT CHANGE %STORAGE (0x00001000, 20)     /* Breakpoint 1 set */
AT CHANGE %STORAGE (0x00001000, 50)     /* Breakpoint 2 set */
AT CHANGE x        /* Replaces breakpoint 1, since x is at  */
                   /* hex address 1000 and is 20 bytes long */
  • Stop when a variable reaches a value that is greater than 200. 
    AT CHANGE MYVAR WHEN MYVAR > 200 ;

    MYVAR > 200 is a condition. Every time the value of MYVAR changes, the condition MYVAR > 200 is evaluated. Changes to MYVAR do not trigger the AT CHANGE breakpoint. Only when MYVAR changes and the condition MYVAR > 200 becomes true is the AT CHANGE breakpoint triggered.

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