# Error Handling and Debugging

Windows Debugging Environment |

The Windows version of PxPlus includes a debugging environment that can be accessed via the PxPlus icon drop-down menu by selecting Debugging Environment. It comprises four separate windows that allow you to display lines of code, set break points, monitor variables and/or expressions, and work in a stand-alone command console while executing a program for testing.

To access these tools, simply press the key combination Alt + Spacebar + D, and then select one of the following debugging actions: TraceWindow, WatchWindow, BreakWindow or CommandWindow.

Debugging functionality can also be set on-the-fly in PxPlus using the 'OPTION' mnemonic:

> print 'OPTION'("DebugWindow","Trace")

## Disabling the Debugging Environment

The debugging facilities are automatically disabled if a lead program (see LPG system variable) is specified in the command for launching PxPlus. This can be overridden by adding the line DEBUG=1 to the [Config] section of the INI file. (The name of the INI file can be obtained via the ARG(-1) function.)

The debugging environment can be disabled by setting the DEBUG option to a value of -1 (negative one) in the INI file.

See INI Contents for explanations of these options.

## TraceWindow

TraceWindow is used to trace the execution of an application. It displays (up to) the last 4096 lines executed, which can be saved to a file for subsequent analysis. The menu items for this window include:

Options |
Always on Top | Displays TraceWindow always on top of PxPlus.
Font | Changes font and font size for text in TraceWindow.
Auto-Start | Auto-activates TraceWindow when PxPlus starts.
Log all Errors | Logs errors trapped by ERR=, DOM=, SETERR.
Suppress Program trace | Suppresses normal program tracing.
Suppress System Library | Suppresses trace output from any program in the system library.
Trace If status | Adds trace lines to both any active trace file (or console) and the Trace Window that consist of any IF condition evaluated and its result (True or False). The tracing of IF conditions is also available when single stepping through a program. The output consists of "IF: xxxxxx ! True/False" immediately after the trace line output and displays with a pale red or green background to clearly indicate if the results are True (green) or False (red). #### Note: The IF output is shown only if the line is displayed on the trace (i.e. no display on protected programs). The 'IT' system parameter can also be used to control the setting for this option. (The Trace If status option was added in PxPlus 2018.) (The tracing of IF conditions when single stepping through a program was added in PxPlus 2019.)
Jump trace | Traces every transfer of control executed within the program and displays information that identifies the location (program/line number) of the logic executed. (The Jump trace option was added in PxPlus 2018.)
Trace to file | Initiates the output of the TraceWindow to a serial file. When first selected, the system will request a file name, create it, and begin sending all of the data from the TraceWindow to this file. While the trace file is active (that is, tracing is being captured to a file), a small check mark will appear beside the "Trace to file" option on the menu. If you select this entry again, the system will stop output to the file, and the check mark will be removed.
AutoOpen trace file | Automatically logs all trace output to a file. The output will be sent to the last file defined in the "Trace to file" whenever the TraceWindow is active. #### Note: Trace output is only sent to the trace file if the TraceWindow is active. The window may be minimized, but tracing will end when it is closed.
Suppress Display | Suppresses the display of the trace output.
Host Trace | (WindX Only) Log All Errors and Trace Programs options for server-side programs. Trace lines from the host are prefixed with <h>.
Show Property GET | Enables/disables property GET option.
Show Property SET | Enables/disables property SET option.
Trace file Opens | Enables/disables trace file opens option.
Trace Program Loads | Controls the tracing of every program load and provides information as to why the load occurred (associated RUN, CALL, PERFORM, etc.).
Trace SQL commands | Outputs a trace of all SQL commands issued by the system when running against a database.
File open Failures | Enables/disables trace file open failures option.
File IO operation trace | Enables/disables file IO operation trace option.
DebugPlus with Backtrace | Enables/disables DebugPlus backtrace option.
Exit | Closes TraceWindow.
Edit |
Copy | Copies TraceWindow contents to the Windows Clipboard.
Find | Search forward/backwards for search string.
Save to file | Save TraceWindow contents to a file.
Clear trace list | Clear the contents of the TraceWindow.
Trace List Size | Options for setting the size of the trace buffer window: 1K, 2K, 8K, 16K or 32K lines. If the selected trace buffer is smaller than the data currently in the buffer, then the trace buffer will be reset.

The SETTRACE PRINT directive can be used throughout an application to output directly to the TraceWindow; however, this directive is ignored if the Suppress Program Trace option is active.

Under WindX, TraceWindow serves a dual purpose. Normal tracing/error logging options are relative to the WindX workstation itself. Host tracing capabilities are controlled by a separate Options item. This allows the application to follow program execution on the server while tracing remote calls back to the workstation.

## WatchWindow

WatchWindow allows you to constantly monitor variables and/or expressions during program execution. These settings may be copied to the Clipboard or saved in a file for subsequent reload. The menu items for this window include:

Options |
Always on Top | Displays WatchWindow always on top of PxPlus.
Font | Changes font and font size for text in WatchWindow.
Auto-Load | Auto-loads watch values from the last Save to file.
No data break | Output without breaks.
50 byte data break | Automatic breaking of string data every 50 bytes.
100 byte data break | Automatic breaking of string data every 100 bytes.
Host Watch | (WindX Only) Enables/disables server-side watch values.
Exit | Closes WatchWindow.
Edit |
Copy | Copies WatchWindow settings/contents to the Clipboard.
Save to file | Save WatchWindow settings/contents to a file.
Load from file | Load settings from a previously saved file.
Clear all watches | Remove all of the current watch values.
Add new watches | Prompts for a variable/expression to add to WatchWindow. The window stays open after a new watch is added to allow multiple watches to be added one after the other. (The ability to add multiple new watches consecutively was added in PxPlus 2022.)
Delete current watch | Delete the currently selected watch value from the window.
Add new watches |
| Same as selecting Add new watches on the Edit menu.

(The "Add new watches" top-level menu was added in PxPlus 2022.)

## BreakWindow

BreakWindow is used to assign logical break points for halting execution in an application. You can specify the name of the program, line reference, and optional condition to test. The menu items for this window include:

Options |
Always on Top | Displays BreakWindow always on top of PxPlus.
Font | Changes font and font size for text in BreakWindow.
Auto-Start | Auto-activates BreakWindow when PxPlus starts.
Host Breakpoints | (WindX Only) Enables/disables server-side break points.
Exit | Closes the BreakWindow.
Edit |
Copy | Copies BreakWindow contents to the Clipboard.
Save to file | Save BreakWindow settings to a file.
Load from file | Load settings from a previously saved file.
Clear all breaks | Remove all of the break points.
Add new breaks | Establish a new break point with the parameters listed below. The window stays open after a new break point is added to allow multiple break points to be added one after the other.
Program | Program name to add a break point to. Click the Browse button to specify a program name.
Statement | Statement (number or label) for the break point.
Break when | Break when on variable name or Boolean expression.
Changes | Changes condition regarding variable specified.
Is true | "Is true" condition regarding Boolean expression specified.
Limit to current level/object | Select this check box to indicate that the value specified is only checked when the program/process runs at the current level or is sharing the variable stack with the current level, as in the case of an object or PERFORM directive. Selecting this option prevents the break point from being "tested" when a subroutine is called.
(The ability to add multiple new break points consecutively was added in PxPlus 2022.)
Delete current break | Delete the currently selected break point from the window.
Add new breaks |
| Same as selecting Add new breaks on the Edit menu.

(The "Add new breaks" top-level menu was added in PxPlus 2022.)

## CommandWindow

This window can be used to handle all console commands without disrupting your standard screen display. The menu items for this window include:

Options |
Always on Top | Displays CommandWindow always on top of PxPlus.
Font | Changes font and font size for text in CommandWindow.
Auto-Start | Auto-activates CommandWindow when PxPlus starts.
Exit | Closes the CommandWindow.
Program |
New program | Set up an empty "No Name" program file.
Load | Load a program from a file.
Save | Save the current program file.
Save as | Allows you to name and save the current program file.
Print Setup | Set up the printer options, paper size, etc.
Print | Print the current program.
Edit |
Copy | Specify a range of lines to copy to the Clipboard.
Paste | Pastes text from the Clipboard.
List lines | Specify a starting and ending statement range to list.
Delete lines | Specify a starting and ending statement range to delete.
Find | Find a text value in the current program.
Replace | Find and replace a specified text value.
Renumber | Renumbers the current program.
Run |
| Start execution of the current program.
Step |
| Single step through the current program.
Terminate |
| Stop execution of the current program.

#### Note:
The CommandWindow facility is also available under WindX.