MONITOR command

The MONITOR command defines or redefines a command and then displays the output in the monitor window (full-screen mode) or log file (batch mode). The following commands are the only commands you can use with the MONITOR command:

  • DESCRIBE
  • LIST
  • Null
  • QUERY

z/OS® Debugger maintains a list of your most recently entered MONITOR commands. Each command entered is assigned a number between 1 and 99 or you can assign it a number. Use these numbers to indicate to z/OS Debugger which MONITOR command you want to redefine.

Read syntax diagramSkip visual syntax diagramMONITOR GLOBALLOCALcu_specintegercommandDEFAULTHEXintegerHEXDEFAULT ;
GLOBAL
Specifies that the monitor definition is global. That is, it is not associated with a particular compile unit.
LOCAL
Specifies that the monitor definition is local to a specific compile unit. Using z/OS Debugger, the specified output is displayed only when the current qualification is within the associated compile unit.
cu_spec
A valid compile unit specification. This specifies the compile unit associated with the monitor definition.
integer
An integer in the range 1 to 99, indicating what command in the list is replaced with the specified command and the order that the monitored commands are evaluated. If omitted, the next monitor integer is assigned. An error message is displayed if the maximum number of monitoring commands already exists.
command
A DESCRIBE, LIST, Null, or QUERY command whose output is displayed in the monitor window or log file.
HEX
Specifies that the value of the variable be displayed in hexadecimal format. You can specify the HEX parameter only with a MONITOR LIST expression command or the MONITOR n command where n is the nth command in the MONITOR list and it must be a LIST expression command.
DEFAULT
Specifies that the value of the variable be displayed in its declared data type. You can specify the DEF parameter only with a MONITOR LIST expression command or the MONITOR n command where n is the nth command in the MONITOR list and it must be a LIST expression command.

Usage notes

  • You can enter HEX or DEF in the prefix area of the monitor window to display the selected line in hexadecimal or the default representation, respectively.
  • The HEX and DEF prefix commands operate only on an individual structure element or array element when you enter them in the prefix area associated with that element.
  • A monitor number identifies a global monitor command, a local monitor command, or neither.
  • Using z/OS Debugger, monitor output is presented in monitor number sequence.
  • If a number is provided and a command omitted, a Null command is inserted on the line corresponding to the number in the monitor window. This reserves the monitor number.
  • You can only specify a monitor number that is at most one greater than the highest existing monitor number.
  • To clear a command from the monitor, use the CLEAR MONITOR command.
  • Replacement only occurs if the command identified by the monitor number already exists.
  • When SET AUTOMONITOR ON is in effect, z/OS Debugger adds an entry that is not visible after the last active entry in the monitor list. If you specify a number and it is either equal to or one more than the last active entry, z/OS Debugger inserts the new MONITOR command in the last active entry and uses the next higher entry for SET AUTOMONITOR ON.

    Note: The SET AUTOMONITOR ON command occupies 1 (for CURRENT or PREVIOUS) or 2 (for BOTH) entries in the monitor list. These entries are not included in the list of Monitor commands from the LIST MONITOR command.

  • The MONITOR LIST command does not allow the POPUP, TITLED, and UNTITLED options, except TITLED WSS. For more information about the TITLED WSS option, see LIST expression command. If the Working-Storage Section contains large amounts of data, monitoring it can add a substantial amount of overhead and might produce unpredictable results.
  • When using the MONITOR LIST command, simple references (or C lvalues) display identifying information with the values, whereas expressions and literals do not.
  • The GLOBAL and LOCAL keywords also affect the default qualification for evaluation of an expression. GLOBAL indicates that the default qualification is the currently executing point in the program. LOCAL indicates that the default qualification is to the compile unit specified.
  • LOCAL monitors are suspended when the enclave containing the compile unit terminates or when the load module containing the compile unit is deleted. If the associated compile unit reappears later in the same debugging session, the LOCAL monitors are restored. However, because the original monitor number might be in use at that time, they will not always be restored with the same monitor number.
  • If the DATA option of the PLAYBACK ENABLE command is in effect for the current compile unit, you can use the MONITOR command while you replay recorded statements by using the PLAYBACK commands.
  • A MONITOR LIST command can be evaluated only when the programming language currently in effect is the same as it was when the MONITOR LIST command was issued. Therefore, if the programming language is changed by one of the following actions, the evaluation of the MONITOR LIST command fails, and a message is displayed:
    • Suspending execution in a compile unit written in a language different from the programming language that was in effect when the original MONITOR command was entered.
    • Entering the SET PROGRAMMING LANGUAGE command.
    • Entering the SET QUALIFY command.
    • Entering the LOADDEBUGDATA command.
  • You can enter the M prefix command by using the Source window prefix area to add the variables on that line to the Monitor window. For the list of supported compile units, see M prefix (full-screen mode).
  • If one or more variables in the Monitor Local List expression is not defined in the specified compile unit, z/OS Debugger displays an error message and does not establish a MONITOR.
  • If a duplicate MONITOR command is entered, z/OS Debugger ignores the command and issues a message that a duplicate command has been entered. If the commands are the same when LIST MONITOR is entered, they are considered to be duplicates; likewise, if they are different when LIST MONITOR is entered, they are considered unique.

Examples

  • Replace the 10th command in the monitor list with QUERY LOCATION. This is a global definition; therefore, it is always present in the monitor output. 
    MONITOR 10 QUERY LOCATION;
  • Add a monitor command that displays the variable abc and is local to compile unit myprog. The monitor number is the next available number. 
    MONITOR LOCAL myprog LIST abc;

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