The following sections describe debugger concepts including action lists, pointers, environments, CodeWatch error messages, and program recovery.
An action list is a set of one or more CodeWatch commands specified for execution at breakpoints, after steps, at watchpoints, at tracepoints, or as macro definitions. The command-line syntax requires action lists to be surrounded by square brackets ( [ ] ). The commands must be separated by semicolons. You may use spaces after semicolons to aid readability. The commands that you enter in an action list are not checked for correctness until they are executed. The command-line syntax for the action list is as follows:
[ command1; command2; ...; commandn ]
A typical action list that could be set at a breakpoint is as follows:
EVALUATE COUNTER; STEP; E DISTANCE; CONTINUE
In more advanced debugging, commonly used sequences of commands can be defined as an action list with the Macro facility. The single macro name can then be used repeatedly throughout the debugging session to refer to a complex series of actions. (For an explanation of defining macros, see the section Macro.)
The debugger maintains two conceptual pointers: the execution pointer and the source file pointer. This section explains these pointers and how they are used during a debugging session.
The debugger maintains a pointer to the current execution point. This is the point at which execution resumes or begins following a Step or Continue. The execution pointer is reset during execution of the program. The Reload command sets the execution pointer to the start of the program. Only a Goto or Return can directly reset the execution pointer. The WHERE command will display the current execution point. In the Windows interface, the highlighted line in the Source window indicates the current execution point.
The debugger also maintains a pointer to the line in the source file currently being displayed. The CodeWatch Source command changes the current source file being displayed. The POINT and PRINT commands change and display the source file pointer, respectively. The Environment command without any operands resets the source file pointer to the current execution point.
The environment is a frame of reference for the debugger to identify program entities such as certain instances of statements and variables. This section explains these entities and how to refer to them in the context of a debugging session.
Program blocks are units of code that provide scope and context for the debugger. Program blocks are defined according to the source language. Refer to the appropriate language chapter for language-specific definitions of program blocks.
Activation numbers pertain to only recursive procedures and to languages that allow recursive procedures.
A procedure is active when it has been called during program execution. Each new call to a procedure counts as a new activation. The activation number specifies a unique activation of a procedure when more than one activation exists. Multiple activations occur when a procedure is recursive (A calls A) or indirectly recursive (A calls B calls A). Activation numbers are either absolute or relative.
An absolute activation number is simply a positive integer. Number 1 denotes the first activation of a procedure, number 2 the second, and so forth. To refer to an activation of a procedure using absolute activation numbers, the procedure name is followed by a colon (:) and the positive integer that denotes the activation.
A relative activation number is either zero or a negative integer. A relative activation number specifies the number of activations to count backwards from the most recent activation. The number 0 denotes the most recent activation. The activation directly preceding the most recent activation is denoted by -1. For example, if there have been five activations of the procedure FACTORIAL, FACTORIAL:0 refers to the fifth activation and FACTORIAL:-2 refers to the third activation. This activation can also be referred to as FACTORIAL:3 (that is, using the absolute activation number 3).
Each activation of a procedure has its own distinct values for automatic (or local) data, and each activation may have different actual parameters or arguments. An activation number can be used to specify the environment for evaluating or displaying variables and procedure arguments. An activation number can also be used when setting a breakpoint in a particular activation of a procedure.
If the activation number is omitted from the name, the debugger uses a default of 0, the most recent activation. The only exception to this is Breakpoint, where omitting the activation number means that a breakpoint is to be taken on every activation of the procedure.
Commands such as Breakpoint require identification of statements within the program being debugged. Statement identifiers are either source line numbers or statement labels.
The simplest way to refer to a statement is by using its source line number, that is, the physical line number in the source file on which the statement starts.
If an unqualified source file line number is specified (no environment reference), the first executable statement on the specified line, if present, or the first executable line following that line is used by the debugger.
If a source file line number is qualified by an environment reference, for example, "SIFT\18", the translation of the line number to an executable statement is executed in the same manner as described for unqualified line numbers, except that the set of executable statements that the line number can be translated to is restricted to those contained in the specified environment block.
The way to refer to a labeled statement is to use its statement label. For any language in which statement labels are numbers, such as Pascal or FORTRAN, a percent character (%) must be used in front of the statement label. For example, in the following Pascal code
325:
326: 9999: writeln('ERROR: INVALID DATA.');
327: end. {Program Terminates}
the statement references 326 and %9999 both refer to the writeln statement.
In the following PL/I code:
9: DUMMY 10: %INCLUDE 'MYFILE.PL1';/*PL/I sample */ 11: CHKPAGE: 12: if I = 66 then 13: do; put skip; I = 0; goto DONEIT; 14: end; 15: I = I + 1; DONEIT: J = 0; K = 0; 16: L = 0;
the CodeWatch commands B 11 and B CHKPAGE are equivalent, and both refer to statement number 11.
A line number offset can be used to locate a statement when it is not labeled or its source line number is unknown. A line number offset is formed by placing a plus character (+) followed by a positive integer after a source line number or a statement label. For example, line 15 in the previous example can be referred to by the program as 11 + 4 or as CHKPAGE + 4. Of course, 15 + 0 refers to the same line.
A statement offset must be used to refer to an unlabeled statement that is not the first statement on a line. A statement offset is formed by placing a period followed by a positive integer (indicating the number of statements from the beginning of the line) after the line number offset. (If the line number offset equals zero, a plus character must be used.) For example, the K = 0 statement on line 15 of the previous example can be referred to by the debugger as 15 + 0.2 or CHKPAGE + 4.2.
Every procedure has two special statements: the entry point to and the exit point from the procedure. The entry point is the place during execution at which the procedure has been called, but before other prelude code has run. A procedure's entry point is referred to within CodeWatch by specifying the procedure name followed by a backslash (\) and %ENTRY (or simply %E), for example,
READ_INPUT\%ENTRY.
The entry point to the current activation of a procedure may simply be referred to as %ENTRY (or %E).
The exit point is the place after which the return value (if any) has been computed and the return statement has been executed. All local variables are still defined. An exit point is referred to by the procedure name followed by a backslash and %EXIT (or %Ex), for example,
READ_INPUT\%EXIT.
The exit point to the current activation of a procedure may be referred to by %EXIT (or %Ex).
Entry and exit points may not be referred to in conjunction with statement offsets.
A statement reference may need to be qualified by a reference to the environment in which the statement occurs. This is done by putting the block name of the environment (with an optional activation number) and a backslash in front of the statement reference. For example:
PRINT_OUT\10
Using just the backslash without the block name refers to the environment containing the current execution point.
Many source programs have the contents of separate files inserted into the program at compilation. Programs written in PL/I, BASIC, C, FORTRAN, or Pascal use an include statement or directive for this purpose; COBOL programs use a COPY statement.
When the debugger encounters one of these statements in a program, you can display the contents of the included file by using Source followed by the filename cited in the INCLUDE directive. The lines in the file will be numbered consecutively from the first line in the file. To return to displaying lines from the source file containing the current environment, simply use the Source command with no arguments. See the section Examining the Source Program for more information.
Support for include file handling has been added for Open PL/I. This applies to include files that contain executable code. The current set of functionality is implemented as follows:
Using the macro preprocessor mfpp with CodeWatch is also allowed. CodeWatch will use the original source file (rather than the expanded preprocessed output of mfpp). Stepping "through" macros works similarly to the include file support described above.
For LPI-BASIC, LPI-COBOL, LPI-FORTRAN, and LPI-Pascal, executable code contained within included files cannot be debugged with CodeWatch.
When CodeWatch encounters an error condition, a message is displayed at your terminal. The following sections describe common CodeWatch error messages.
When the debugger session begins, the debugger may issue several different kinds of warnings.
A warning may be issued if the source file is newer than the program and/or STB file. Out-of-date files may be present for any of the following reasons:
The following is an example of this type of warning message.
**Warning** Source file newer than program and .stb files for main.
A warning may be issued if an STB file for a module compiled in debug mode is not found. This would be an error if the debugger could not find any STB files; however, the debugger will issue a warning only if one or more (but less than all) STB files are missing.
The following is an example of this type of warning message.
**Warning** No debug data for environment
** Source file "y.pl1"
** Symbol table file "y.stb"
When the debugging session cannot begin, the debugger will display an error message at invocation. This indicates that a filename required by CodeWatch is an error because one or more of the following is true:
The debugger issues a message when the command syntax is incorrect. The error message contains at least three lines of text: the first lines describe the error, the second to last line echoes the command line as it was entered, and the last line contains a caret ( ^ ), indicating the approximate location of the error in the command line above. After displaying an error message, the debugger issues a prompt and waits for another command. The following are examples of the message feature:
CodeWatch> TYPEPRIMES
**Error** Invalid Command
TYPEPRIMES
^
CodeWatch> TRACE EMTRY
**Error** Syntax error
TRACE EMTRY
^
The fourth kind of error occurs when the debugger cannot correctly interpret a command line because of an incorrect variable name, an invalid argument, or some similar problem. With some semantic errors, the command line is echoed and a caret ( ^ ) is placed under it indicating the approximate location of the error. Two samples are shown from the command-line interface, as follows:
CodeWatch> EVALUATE ths_prime
**Error** Undefined variable or built-in function
EVALUATE ths_prime
^
CodeWatch> BREAKPOINT 100000
**Error** Statement 100000 not found in procedure
CodeWatch has the ability to recover from and to reasonably debug user programs that have stopped because of certain operating system errors. When this occurs, the following are indicated by the debugger:
If the routine in which the program stopped was compiled in debug mode, the source file line number of the execution point at the time of the error will also be given. The current evaluation environment will automatically be set to this environment and the debugging session may continue.
If the routine in which the program stopped was not compiled in debug mode, the environment of the most recently called routine that was compiled in debug mode is indicated, and the current evaluation environment is set to that environment. In this case, most debugger actions are allowed, including continuing execution from the point at which the program received the error. Note that it is not legal to use the Step or Goto commands from a non-debug routine.
Whether or not program execution stops because of a signal depends on the CodeWatch default catch settings for the signal. In most cases, you can modify the behavior by using the CATCH command. For more information, see the section Catch.
The STACK command can provide a stack traceback to indicate the sequence of subroutine calls up to the time of the error.
Copyright © 2009 Micro Focus (IP) Ltd. All rights reserved.