Source Debugger APIs

• The source debugger that is shipped with the OS/400 licensed program. A source debugger is a tool for debugging Integrated Language Environment (ILE) programs or original program model (OPM) programs by displaying a representation of their source code.

• Any other debugger that IBM or a business partner writes.

Debugger functions are designed to help you write and maintain your applications. You can run your programs in a special testing environment while closely observing and controlling the processing of these programs in the testing environment. You can write a debugger application that interacts with the APIs provided in this chapter, or you can use the debugger provided with the AS/400 system.

No special commands specifically for testing are contained in the program being tested. The same program being tested can run normally without changes. All debugger APIs must be called within the job in which the Start Debug (STRDBG) command is issued. The debugger APIs should not be called from within the program being tested. With the debugger APIs provided, you interact with your programs symbolically in the same terms as the high-level language (HLL) in the program. You refer to variables by their names and to locations as the line and the column within a view. In addition, the debugger functions are only applicable to the job in which they are set up. The same program can be used at the same time in another job without being affected by the debugger functions set up.

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 were previously 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 is currently 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.