How a Source Debugger Uses the APIs to Debug ILE or OPM Programs
The Start Debug command has a parameter, SRCDBGPGM, that specifies which program is called when an ILE or OPM program is debugged. The system calls this program, indicating that the debug session is to begin. It also calls this program when the user wants to show the Display Module Source display. When OPM programs are to be debugged, the additional OPMSRC(*YES) parameter must be specified on the Start Debug command.
When the system calls the source debugger program, indicating the start of a debug session, that program uses source debugger APIs to perform debug functions. The first API that is called is the Start Source Debug (QteStartSourceDebug) API, which indicates to the system that a source debugger is running.
When an ILE program is debugged, the Retrieve Module Views (QteRetrieveModuleViews) API is used to obtain information about the views available in the modules of that program. For an OPM program, information about the views available for that program is obtained. These views previously were created by the compiler by using the create view APIs for ILE programs. For OPM programs, the views were created by using OPTION(*SRCDBG) or OPTION(*LSTDBG) on the appropriate OPM language create program command. The OPM CL, COBOL, and RPG languages are supported by the source debugger APIs. A view is text that is displayed by the source debugger. A module may have several views, depending on the debug data supplied by the compiler of that module. OPM programs always have a statement view, and either a source or listing view, depending on the OPM compiler option selected. See the appropriate language reference manual to determine which views are available.
To be debugged, a module has to have at least one view: the statement view. A statement view is a low-level view that contains information about each high-level statement in that module. This view is not meant to be displayed, although there is text associated with that view. The information in the statement view text can be used by the source debugger to determine the following:
- Procedure name
- Statement number
- Statement type associated with any high-level language statement in the module
The source debugger application uses the Register Debug View (QteRegisterDebugView) API to register the views of a program. Once these views are registered, various debug operations can be performed against these views. These operations include:
- Retrieving the text associated with the views
- Adding a breakpoint to the program at a certain location in a view
- Displaying variables that are defined in the program
The source debugger application uses the Retrieve View Text (QteRetrieveViewText) API to retrieve the text of a view. Every view has text associated with it that can be retrieved using the QteRetrieveViewText API.
When a program is being debugged and it stops at a breakpoint, the system indicates that it has stopped by calling the Program-Stop Handler exit program. This program is passed a line number in the statement view where the program being debugged has stopped.
The Map View Position (QteMapViewPosition) API is used to map positions in one view to positions in another view. For example, if the source debugger currently is displaying a source view in a module, and a breakpoint occurs, the Program-Stop Handler exit program is called. This program is passed a line number in the statement view of that module, which indicates at which statement the program has stopped. To show the position in the source view where the program has stopped, the application maps the statement view position to a source view position. This mapping function is made possible by maps, which are created by the ILE compiler using the create view APIs, or by the debug data, which is created by OPM compilers.
When the debug session is over, the source debugger application issues the End Source Debug (QteEndSourceDebug) API, which removes all ILE and OPM programs from debug mode. No source debugger APIs can be issued until the source debug session is ended with the End Debug Command and started again with the Start Debug command.
The Create View APIs require the application to bind to the service program QTECRTVS in library QSYS. All other Source Debugger APIs require the application to bind to the service program QTEDBGS in library QSYS. All source debugger API functions are then available to the application.
For a code example of how to write a source debugger, see Example: Using source debugger APIs.
[ Back to top | Debugger APIs | APIs by category ]