Tips on Debugging COBOL

Here are some tips and tricks on debugging COBOL applications in the Visual Studio IDE:

Add a Watch
Right-click a variable in the editor and choose Add Watch.
Attach to a Running Process
See To attach to a running process and debug.
Attach to a 64-bit Running Process
See To attach to a 64-bit running process and debug.
Autos Window
Displays the variables used in the current and in the previous statements and enables you to change their values or add watches to them. To display the window, click Debug > Windows > Autos.

For variables in a copybook that are modified by COPY… REPLACING statements in your code, the Autos window displays all values defined in the source code. When there are multiple COBOL programs in your project that perform a COPY… REPLACING in a copybook, the Autos window only uses the replacing values found in the first COBOL program.

Breakpoint-Setting
Double-click in the left margin of editor next the a line of code, or position the cursor on the line and press F9. You can also choose Debug > Toggle Breakpoint or choose Breakpoint > Insert Breakpoint from the editor context menu.
Note: Tracepoints are supported only when debugging .NET COBOL code.
Breakpoints Window
Displays a list of all breakpoints and tracepoints set in the code. Double-click on a breakpoint in the window to position the cursor on the line for which it has been added.
Break on Data Change
Works with COBOL watchpoints. When the value of a data item on which a watchpoint has been set changes or a condition applied to the watchpoint has been met, the debugger breaks the execution of the program and highlights the line after the data change. The IDE opens the COBOL Watchpoints window and highlights the data item that was changed in it. Works for native code only.
COBOL Source Information
COBOL Source Information (CSI) provides a quick and easy way of providing you with information about your program when you are working on it. You enter a query in the CSI query control and CSI returns the results of the query in the Micro Focus Code Analysis window.
COBOL Visualizer
The COBOL visualizer is a window in Visual Studio that you can use while debugging. It enables you to view and edit COBOL data in either hexadecimal format or as a text.
COBOL Watchpoint-Setting
Note: COBOL watchpoints are supported in native COBOL only.
To add a watchpoint from the editor, right-click a data item and select Add COBOL Watchpoint. Alternatively, you can add watchpoints from the Watchpoints (Native COBOL) window. To disable or remove the watchpoints, choose Debug > COBOL Watchpoints > Disable/Delete All Watchpoints.
DataTips and Pin To Source
Provide information about the variables in the source code. To display the DataTip for a variable, you can hover it. This works only in break mode when the execution stops and with variables that are used at run time.

If you need to keep the DataTip for a variable open, right-click on the variable in the code and choose Pin To Source.

Debug Profiles
Available from the Debug tab in the project's properties. COBOL projects can have multiple debug profiles where a debug profile stores a set of properties which specify how to start debugging the application.
Debug Tooltip for Subscripted OCCURS Items
You can configure the debug tooltip for subscripted OCCURS items to either display the elements of arrays or to display the value of the current expression. To do this, right-click in the editor, click COBOL Debug Tooltip Style and either enable or disable Show COBOL OCCURS or reference modification value. Use the following default key sequence to change the style of the tooltip in the editor - ALT+T, T.
Debugging standalone COBOL files
This only applies to native COBOL. You can debug standalone COBOL files in the IDE without a project as follows:
  1. Ensure the file has been compiled - see To compile individual files.
  2. Check and specify any debug options as required. You can do this in the following two places:
    • For standalone files - in the file properties window (accessed using F4) and the options in the Debug section.
    • In the Debugging Options dialog box, which starts immediately after you start debugging.

    You can specify any command line arguments, the start program and the working directory.

  3. Click Debug > Step into.

    If configured in the IDE options (Tools > Options > Micro Focus Tools > Standalone Editing > General), this opens the Debugging Options dialog box. Specify your preferences and click OK.

    The IDE enters in debug mode.

  4. Stet through the code in the usual way.

If you need to make changes to the code to fix problems, you must recompile before you start debugging again.

The recommended way to work is to include all source files in a project because this enables full support for the IDE editing, compiling and debugging features. There is limited support in the IDE for standalone files, such that are not part of a project and Visual COBOL provides a path to create projects for these files in order to enable full editor, build and debug functionality. To create a project from a standalone file, right-click in the editor and click Create COBOL Project.

Find All References
In the editor, right-click a COBOL data item, a section or a paragraph name in the code and select Find All References. A list of all places in the solution that contain the reference to the item is displayed in the Find Symbol Results window. Double-clicking on an item in the list positions the cursor on the line of code that includes the element.
Find Symbol Results Window
To display the window, click View > Find Results > Find Symbols Results. Displays the results of Find All References command in the editor. Double-click an item in the list to position the cursor on the line that includes the referenced item.
Go To Location
The text field on the COBOL toolbar (click Tools > Customize > Toolbars and click COBOL, if this is hidden) enables you to locate the definition of a variable or an expression. Type a variable name or an expression in the field, then either click Edit > Go To Location or click Go To Location (Enter a COBOL Term and Go To Definition) in the COBOL toolbar. This is equivalent to pointing to the variable in the editor and pressing F12.

To return to where you were in the code, click Navigate Backwards (Navigate Backwards).

Just-In-Time Debugging

Enables just-in-time debugging for when an application causes an error. To enable Just-In-Time Debugging for native COBOL code, click Tools > Options > Debugging > Just-In-Time Debugging. Check Micro Focus Native Debugger. Works with native code only.

Memory Window
Allows you to see the contents of memory for a given address. This can be a pointer reference, the address of data-item or an integer value. To display the window, click Debug > Windows > Memory > Memory n. Works for native COBOL only.
Peek Definition
Right-click on a data item in the editor and click Peek Definition. Opens a small window, embedded in the editor, showing the data item definition.

You can edit the code in the embedded window. You can also open several peek definition windows and use the breadcrumbs navigation to switch between them.

Program Breakpoints
Note: Program breakpoints are supported in native COBOL only, and are not supported with nested programs.
You can break into a program whenever it or one of its entry points is called.
Right-click in the code in the editor, and click Add COBOL Program Breakpoint.
Program Flow Graph
Right-click a program in the Solution Explorer or in the editor. Select Program Flow Graph. The Program Flow Graph displays in a new tabbed view.
Quick Browse
The Quick Browse dialog box (click in the COBOL toolbar to open it), part of the COBOL Source Information (CSI) functionality, enables you to run CSI queries and returns the results of the queries in the Output window's COBOL Source Information tab.
Remote Debugging
You can debug a process running on a remote system if the machines are connected using TCP/IP. See Remote Debugging.
Ensure that the local and remote systems are networked using TCP/IP. To connect to the remote machine and debug a program, choose Project > projectProperties and go to the Debug tab. Check Enable remote machine and fill in the name or the IP address of the remote machine and the TCP port number.
Run To Cursor
Right-click a line of code in the editor and select Run To Cursor. This starts a debugging session and executes the code till the line on which you positioned the cursor.
Shortened names in the debug tooltip
You can specify whether the debug tooltips display the fully qualified data names (such as c of b of a) or shortened names (simply c). To change your preference from the editor, click COBOL Debug Tooltip Style and either enable or disable Show qualified names for data items.
Start Debugging
Choose Debug > Start Debugging or, alternatively, press F5 or F11. F5 starts debugging and runs the application until a breakpoint or an error occurs. F11 starts debugging and breaks on the first statement that can be debugged.
Stop Debugging
Choose Debug > Stop Debugging. You can also click in the Debug toolbar.
Threads Window
Shows all threads that are running in the process. To display the window, choose Debug > Windows > Threads.
Tracepoint-Setting
Tracepoints are conditional breakpoints. When the debugger hits a tracepoint, it performs an action instead of or before stopping the execution. To set a tracepoint, click on the line of code where you need to set one and choose Debug > Toggle Tracepoint or from the context menu choose Breakpoint > Insert Tracepoint and specify the action to perform. Tracepoints are supported only when debugging .NET COBOL code.
Variable Windows
Include windows, such as for example Autos, Locals, Quick Watch, Watch, for monitoring and editing values and expressions.
Watch Window
Enables you to watch the values of variables and expressions. To open the window, click Debug > Windows > Watch > Watch n while debugging. To change the format of displaying the values from decimal to hexadecimal, right-lick in the window, and click Hexadecimal Display.

To change the format of display of the values on individual rows in the Watch window, click a row, press F2, and type: Variable,h or Variable,x to always display the values in hexadecimal format; Variable,d to always display the values of variables in decimal format, and of strings - as text.

Watchpoints (Native COBOL) Window
Enables you to add data items as watchpoints, and monitor their values in a decimal or hexadecimal display. To open the window, click Debug > Windows > COBOL Watchpoints.