135 lines
6.4 KiB
HTML
135 lines
6.4 KiB
HTML
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||
|
|
<html>
|
||
|
|
<head>
|
||
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
||
|
|
<meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation">
|
||
|
|
<title>How a source debugger uses the APIs to debug ILE or OPM programs</title>
|
||
|
|
<!-- Begin Header Records ========================================== -->
|
||
|
|
<!-- All rights reserved. Licensed Materials Property of IBM -->
|
||
|
|
<!-- US Government Users Restricted Rights -->
|
||
|
|
<!-- Use, duplication or disclosure restricted by -->
|
||
|
|
<!-- GSA ADP Schedule Contract with IBM Corp. -->
|
||
|
|
<!-- Change History: -->
|
||
|
|
<!-- YYMMDD USERID Change description -->
|
||
|
|
<!-- DEBUG1 SCRIPT A converted by B2H R4.1 (346) (CMS) by V2KEA304 -->
|
||
|
|
<!-- at RCHVMW2 on 29 Jan 1999 at 16:05:09 -->
|
||
|
|
<!-- Restructured for V5R2 ========================================== -->
|
||
|
|
<!-- End Header Records -->
|
||
|
|
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
<!-- Java sync-link ================================================== -->
|
||
|
|
<script type="text/javascript" language="Javascript" src="../rzahg/synch.js">
|
||
|
|
</script>
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
<h2>How a source debugger uses the APIs to debug ILE or OPM programs</h2>
|
||
|
|
|
||
|
|
<p>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.</p>
|
||
|
|
|
||
|
|
<p>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 <a href="QTESTRSD.htm">Start
|
||
|
|
Source Debug</a> (QteStartSourceDebug) API, which indicates to the system that
|
||
|
|
a source debugger is running.</p>
|
||
|
|
|
||
|
|
<p>When an ILE program is debugged, the <a href="QTERTVMV.htm">Retrieve Module
|
||
|
|
Views</a> (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
|
||
|
|
<strong>view</strong> 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.</p>
|
||
|
|
|
||
|
|
<p>To be debugged, a module has to have at least one view: the statement view.
|
||
|
|
A <strong>statement view</strong> 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:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>Procedure name</li>
|
||
|
|
|
||
|
|
<li>Statement number</li>
|
||
|
|
|
||
|
|
<li>Statement type associated with any high-level language statement in the
|
||
|
|
module</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p>The source debugger application uses the <a href="QTEREGDV.htm">Register
|
||
|
|
Debug View</a> (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:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>Retrieving the text associated with the views</li>
|
||
|
|
|
||
|
|
<li>Adding a breakpoint to the program at a certain location in a view</li>
|
||
|
|
|
||
|
|
<li>Displaying variables that are defined in the program</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p>The source debugger application uses the <a href="QTERTVVT.htm">Retrieve
|
||
|
|
View Text</a> (QteRetrieveViewText) API to retrieve the text of a view. Every
|
||
|
|
view has text associated with it that can be retrieved using the
|
||
|
|
QteRetrieveViewText API.</p>
|
||
|
|
|
||
|
|
<p>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.</p>
|
||
|
|
|
||
|
|
<p>The <a href="QTEMAPVP.htm">Map View Position</a> (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.</p>
|
||
|
|
|
||
|
|
<p>When the debug session is over, the source debugger application issues the
|
||
|
|
<a href="QTEENDSD.htm">End Source Debug</a> (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.</p>
|
||
|
|
|
||
|
|
<p>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.</p>
|
||
|
|
|
||
|
|
<p>For a coding example of how to write a source debugger, see <a href="../apiref/apiexusdeb.htm">Using Source
|
||
|
|
Debugger APIs</a> in the API examples.</p>
|
||
|
|
|
||
|
|
<hr>
|
||
|
|
<center>
|
||
|
|
<table cellpadding="2" cellspacing="2">
|
||
|
|
<tr align="center">
|
||
|
|
<td valign="middle" align="center">
|
||
|
|
<a href="#Top_Of_Page">Top</a> |
|
||
|
|
<a href="debug1.htm">Debugger APIs</a> |
|
||
|
|
<a href="aplist.htm">APIs by category</a></td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
</center>
|
||
|
|
</body>
|
||
|
|
</html>
|
||
|
|
|