Source entry breakpoints

Source entry breakpoints provide the ability to set paragraph breakpoints prior to starting a debug session. Because these breakpoints are set using the original source files, they persist between debug sessions. Previously, breakpoints could only be set at the level of the generated program listing files. Setting breakpoints from the original source files allows a more natural edit, compile, debug workflow. Source entry breakpoints are supported for COBOL paragraphs and sections, and PL/I procedures.

About this task

When you edit COBOL with the COBOL Editor or the z Systems® LPEX Editor, a Toggle Paragraph Breakpoint action or a Toggle Section Breakpoint action is available in the left ruler context menu of the editor and the context menu in the outline view, depending on whether the current context is a paragraph or a section.

When you edit PL/I with the PL/I Editor or the z Systems LPEX Editor, a Toggle Procedure Breakpoint action is available in the left ruler context menu of the editor and the context menu for paragraphs in the outline view.

Notes:
  • Source entry breakpoints are not available in IBM® Debug for z/OS®.
  • 64-bit programs are not supported.

During debug sessions, source entry breakpoints cannot be added. However, you can add entry breakpoints with the Toggle Entry Breakpoint action available in the left editor annotation ruler context menu and the context menu of applicable items in the outline view.

The following example COBOL source file, opened from the Remote Systems view, is used to demonstrate source entry breakpoints. The source has a number of paragraphs and you can set breakpoints on these paragraphs in the editor or from the outline view. After setting the breakpoints, you can start the application under the control of the debugger.

Procedure

  1. Open your source file from the Remote Systems view.
    To do so, right-click your file and select Open With > COBOL Editor. In this example, we will work with a file called QUICK.cbl that does some basic sorting operations.
    Open source file
  2. Move to the paragraph that you want to set a breakpoint on.
    In the outline view, you can expand the PROCEDURE DIVISION section to see the paragraphs in the program. In QUICK.cbl, we will select a paragraph called QUICKSORT-THE-TABLE.
    Select paragraph
  3. Set a breakpoint from the ruler area in the source.
    Right-click in the ruler area and select Toggle Paragraph Breakpoint. The source entry breakpoint is set. Note that if you want to remove the breakpoint, right-click the breakpoint and again select Toggle Paragraph Breakpoint.
    Set breakpoint in ruler area
  4. If this is the first time that you set a paragraph entry breakpoint during your edit session, you are prompted to specify a module name and compile unit name for your breakpoint:
    Specify a module and compile unit for the paragraph breakpoint.

    This setting is saved for subsequent breakpoints in the edit session.

    You can use the an asterisk (*) as a wildcard for the module name, but wildcards are not permitted for the compile unit name.

  5. Set a breakpoint from the outline view.
    Breakpoints can also be set in the outline file. Right-click a paragraph in the outline view and select Toggle Paragraph Breakpoint. In this source, we will set a breakpoint on the paragraph PARTITION-ENTRIES.
  6. Review the breakpoints in the breakpoints view.
    The breakpoints view provides a simple way to see all breakpoints that have been set. Breakpoints are listed in the view as you add them. A checkmark indicates that a breakpoint is enabled.
    Review breakpoints in the breakpoints view
  7. Submit the JCL to run the program and start the debugging session.
    Note: the debug daemon must be turned on for the debugger to work.
    Submit JCL
  8. The debug session starts and suspends in the main entry point of the application.
    Debug session starts
  9. Looking at the generated listing file, we can see that the program makes a call to the module where the breakpoints are set. In this example, the module QUICK.
    Note calls in generated listing file
  10. Click the Resume icon to continue the debug session.
    Click Resume
  11. The debugger stops at the first breakpoint that we set in the source: QUICKSORT-THE-TABLE.
    Debugger stops at first breakpoint
  12. In the listing file, we can see that there is a call to the paragraph where the other breakpoint PARTITION-ENTRIES is set.
    Review listing file
  13. Click Resume to continue with the debug session.
    Click Resume
  14. The debugger stops at the next breakpoint.
    Debugger stops at next breakpoint
  15. Disable a breakpoint.
    Source entry breakpoints can be enabled, disabled, created, and deleted just like regular breakpoints. In this example, in the breakpoints view we will clear the checkbox for the PARTITION-ENTRIES breakpoint because it is hit each time the application resumes and we want to allow the application to run to completion. This demonstrates how a breakpoint can be hit just once and then disabled.
    Disable a breakpoint in the breakpoints view
  16. Click Resume to continue the session.
    With the breakpoint disabled, the application can now run to completion normally.
    Click Resume
  17. The debug session completes.
  18. Observe how source entry breakpoints persist.
    Look at the original source file where the breakpoint was set. Even though the debug session has completed, the breakpoint is still set and available for another debug session. This allows a more natural workflow by setting breakpoints in the original source file before debugging starts rather than setting breakpoints in the generated listing during a debug session.
    Persisted breakpoint