AOCTRACE
Purpose
The AOCTRACE command turns the SA z/OS® system operations debugging feature on or off. AOCTRACE allows you to activate:
- Debugging globally
- Debugging for specific REXX script
- Debugging at a certain level of detail
- Tracing for a particular message
- REXX trace for a specific REXX script
Syntax
Parameters
- MSG/id
- The message that is being traced.
- rexx_exec
- The name of the REXX script that you want to debug.
- ON
- Turns the debugging feature on.
If you do not specify a REXX script or message, AOCTRACE activates a global debugging flag. This causes each SA z/OS system operations REXX script that is invoked to write a record (AOF700I) to the netlog showing the parameters that it was invoked with.
If you do specify a REXX script or message, only that REXX script or message writes messages to the netlog. The netlog shows when and where the REXX script was called, and what parameters were given.
If you specify a REXX script or message but not a trace, an intermediate level of debugging is activated for the specified REXX script or message. This causes the REXX script to issue a number of messages describing its actions. Note, however, that not all REXX scripts support this facility.
- OFF
- Turns the debugging feature off.
If a REXX script is specified, this option deactivates both the intermediate and REXX tracing for the specified REXX script.
If a message is specified, this option deactivates message tracing for the specified message.
If a REXX script or message is not specified, this option disables the global trace.
- trace
- The type of REXX trace
that you want for the specified REXX script. Valid values are:
- A
- All
- R
- Results
- I
- Intermediates
- C
- Commands
- E
- Errors
- F
- Failures
- L
- Labels
- O
- Off
- N
- Normal
- routine_name
- The REXX script that is being traced.
- level
- Specifies the debug level that allows you to limit the amount
of debug information that is written to the netlog. The meaning of
the level depends on the particular REXX script.
- NORM
- This is the default. Control flow and important data area is written to the netlog.
- MAX
- Extensive logging of control flow and data areas and structures.
- /AM
- Indicates that data received from the automation manager is not traced.
- /SLAVE
- Indicates that data received from the command slave is not traced.
- TARGET
- For information on the TARGET parameter, see TARGET Parameter.
- OUTMODE
- For information on the OUTMODE parameter, see OUTMODE Parameter.
For further information about AOCTRACE command usage, see "Appendix C - Problem Determination" of IBM Z System Automation User's Guide.
Restrictions and Limitations
The trace operand can only be used on interpreted REXX scripts.
Using the trace on certain REXX scripts can cause execution problems, particularly with REXX scripts that trap messages.
The REXX trace setting of S (Scan) is not available.
Message tracing only works from the command line.
Examples
If you enter aoctrace
on you see a message indicating that the debugging facility
has been enabled. While the debugging facility is enabled, message
AOF700I is written to the netlog for each procedure being processed.
AOFKAANL SA z/OS - Command Dialogs Line 1 of 8
Domain ID = IPSFP ---------- AOCTRACE ---------- Date = 08/16/08
Operator ID = NETOP1 Time = 17:41:18
Enter ADD in the Command line to create an entry
Cmd: A Add C Change D Turn off Debug R Reset T Turn off Trace
Cmd CLIST System Dbg Level T Subroutines/Messages being traced
--- -------- -------- --- -------- - -----------------------------------------
*GLOBAL* KEY4 Y
*MSG* KEY4 IEF403
*MSG* KEY4 IEF404
EVJEATDF KEY4 Y R
EVJESPRQ KEY4 Y
EVJESPSC KEY4 Y
EVJESRST KEY4 Y
INGRMORD KEY4 Y
INGRYST0 KEY4 Y Y AOF_SHOW_LIST_PANEL
Command ===>
PF1=Help PF2=End PF3=Return PF6=Roll
PF9=Refresh PF10=ALL_OFF PF12=Retrieve The first entry
is the *GLOBAL* entry. This entry is always shown. It shows whether
the global debug option is on or off. You cannot modify the setting
with a command code. To set the global debugging option specify AOCTRACE
ON or AOCTRACE OFF on the command line.
*MSG* in the CLIST column indicates a message trace entry. The message ID is shown in the Subroutines/Messages being traced column. As with the Global entry (*GLOBAL*), message trace entries cannot be modified on this panel: you must use the AOCTRACE MSG/id,ON|OFF command entered at the command line to do so.
The following information is shown:
- The CLIST field shows the name of the REXX script.
- The System field shows the name of the system where debugging or tracing is active.
- The Dbg field indicates whether or not debug mode is on. Y indicates that debug mode is turned on.
- The Level field indicates the debug level.
- The T (Trace) field shows the Trace option specified for the REXX script.
- The Subroutines/Messages being traced field shows the list of subroutines that are being traced.
- A
- Allows you to add debug or trace settings for another REXX script. The panel shown in Figure 2 is displayed where you can specify the REXX script name and optionally overtype the other settings.
- C
- Allows you to modify the debug or trace settings of the selected REXX script. The panel shown in Figure 2 is displayed showing the current settings. Here you can overtype the appropriate values.
- D
- Turns off the debug option for the selected REXX script.
- R
- Turns off the debug and trace option for the selected REXX script.
- T
- Turns off the trace option for the selected REXX script.
Use the PF10 key to turn off the debug and trace option for ALL displayed REXX scripts.
The ADD command
can also be entered at the command line to define the debug or trace
settings for a REXX script.
AOFKAAND SA z/OS - Command Dialogs
Domain ID = IPUN8 ---------- AOCTRACE ---------- Date = 08/16/08
Operator ID = NETOP1 Time = 17:50:21
Specify or revise the following parameters:
Clist name INGRVRP0
debug mode ON (ON or OFF)
debug detail level (NORM, MAX, /AM, /SLAVE)
REXX trace option (A, R, I, C, E, F, L, O N)
Subroutines to be traced: (* for all)
- or -
Message ID ________________________________
Command ===>
PF1=Help PF2=End PF3=Return PF6=Roll PF12=Retrieve - Clist name
- Specify the name of the clist (that is, REXX script) When turned ON, the REXX script will write debug information to the NetView log. Note that if you have already specified a REXX script with the AOCTRACE command, or entered the command code C next to a REXX script on the main AOCTRACE panel, this field will contain that REXX script name and cannot be changed.
- debug mode
- Specify ON to turn on the REXX script's debug mode.
- debug detail level
- Specify the debug level for the REXX script. The meaning
of the debug level varies from REXX script to REXX script. Standard
values are:
- NORM
- This is the default. Control flow and important data area is written to the netlog.
- MAX
- Extensive logging of control flow and data areas and structures.
- /AM
- Indicates that data received from the automation manager is not traced.
- /SLAVE
- Indicates that data received from the command slave is not traced.
- REXX trace option
- Specify the trace setting for the REXX
script. It can be one of the following:
- A
- All
- R
- Results
- I
- Intermediates
- C
- Commands
- E
- Errors
- F
- Failures
- L
- Labels
- O
- Off
- N
- Normal
- _
- Default
For more information about trace settings, see TRACE in z/OS TSO/E REXX Reference.
Notes:- The REXX script debug setting need not be ON to use REXX script trace.
- Specifying REXX trace option A, I, or R makes individual REXX script debugging ineffective.
- Subroutines to be traced
- Specify the list of subroutines to be traced. By default, only the REXX script main routine will be traced. You can specify more than one subroutine name separated by a blank character. Specify '*' to trace all subroutines.
- Message ID
- Specify the message identifier to be traced.