The first section of this chapter describes the facilities that let you control the execution of your program. The second section discusses environment control issues. The third section explains how to examine, modify, and evaluate the contents of data items. The last section of this chapter describes other features, such as the macro facility, debugger command files, and on-line help.
This section explains the CodeWatch facilities that are used to control program execution. You may control the execution of your program in the following ways:
Breakpoints are used to suspend program execution at specified locations so that you may execute various debugging actions, such as evaluating variables, single statement stepping, and so on. The Breakpoint facility is used to set a breakpoint at a specified statement or to modify the characteristics of a breakpoint already set at that statement. Up to 64 breakpoints can be active at any one time. Breakpoints may be conditional and may have associated action lists (sequences of debugger commands to be executed when the breakpoint is incurred).
There are three pertinent commands to the Breakpoint facility: BREAKPOINT, NBREAKPOINT, and LBREAKPOINT:
You may specify whether or not process control should return to the debugger when a specified signal is generated. This is done with the Catch facility. You may also specify whether or not the user program is to continue as if it had or had not incurred the given signal. This is done with the Ignore option.
There are three pertinent commands to the Catch facility: CATCH, NCATCH, and LCATCH:
Program execution may be single stepped one or more source-level statements at a time. It is possible to set default stepping modes:
There are three pertinent commands to the Step facility: STEP, DSTEP, and LSTEP.
Tracing enables information about all block entries and statements to be announced as the program executes. Entry tracing allows an action list to be associated and may be conditional.
There are three pertinent commands to the Trace facility: TRACE, LTRACE, and NTRACE.
Watchpoints are used to monitor specified variables. The Watchpoint facility is used to designate a given variable to be watched. When the contents of the watched variable change, program execution stops and control is returned to the debugger. Watchpoints may be conditional and may have associated action lists (sequences of debugger commands to be executed when the watchpoint is incurred).
There are three pertinent commands to the Watch facility: WATCH, NWATCH, and LWATCH.
During a debugging session, CodeWatch maintains an execution pointer, which tracks the current point of program execution. When execution of the program has been halted by a debugger action, the pointer maintains the location as the current execution point. The current execution point can always be determined using the WHERE command. This allows you to control the execution of the program by using one of several simple debugger facilities.
The CONTINUE command is used to begin program execution or to resume execution following a breakpoint or a step operation.
The GOTO command moves the execution pointer to a specified statement. Program execution resumes at this point when a Continue or Step is issued. The statement is specified by a line number, a simple statement label, or a statement label followed by a line number offset or statement offset. The named statement must exist in the current program block. Once the debugger has executed the Goto, it displays the new execution point.
The RELOAD command restarts the user program, preserving any explicitly set breakpoints, tracepoints, and watchpoints with associated action lists. A subsequent Continue or Step will start program execution from the beginning of the program.
The RETURN command transfers the current execution point to the exit point of the current procedure. If the procedure returns a value, an expression must be given indicating the value to be returned. For more information, see the section Modifying Return Values.
The QUIT command causes termination of the debugging session. Selecting the Exit item in the File menu is equivalent to issuing the QUIT command.
CodeWatch does not require a program-to-debug at startup time. If no program-to-debug is supplied to Code Watch, CodeWatch comes up standalone. However, on UNIX systems, it will first look for a.out as the default program name. When CodeWatch comes up standalone, a LOAD or ATTACH command must be used to specify the program to be debugged.
The LOAD command loads the symbol table from a specified file into CodeWatch as the primary executable for debugging. It also purges the internal CodeWatch symbol table of any previously loaded executables or shared libraries.
The ATTACH command attaches CodeWatch to the "pid" (a decimal number) and performs a LOAD command, as described above. Attached programs that call exit () or that die are not automatically reloaded. Use the RELOAD command for this.
Programs may also be attached at the time of invocation, for example,
cwcmd -pid 3268 myprog.out
In many cases during a debugging session, it is necessary to refer to an environment to establish a frame of reference for identifying variables or statement identifiers. An environment is simply a program block, which the program refers to by specifying the name of the block or any statement within the block. This allows the debugger to find a specific instance of a variable or statement. Usually, a simple block name is adequate to specify an environment. It refers to the most recent activation of that block. To establish some other activation of the block as an environment, use a block activation number.
An active environment exists on the program stack as a stack frame containing automatic data for the environment. However, environments that do not exist on the program stack can also be referenced; such environments are called inactive environments. For example, a procedure that has not been called, and thus has no stack frame, is inactive. Another example of an inactive environment is one that is referenced by a block name followed by an activation number that is higher than the current activation of the block. It is possible to examine static and external data in inactive environments and to set breakpoints in them. An active environment must be specified to examine automatic data or procedure arguments.
The Environment facility sets the current evaluation environment to provide scope to the debugger for identifying variables and statements. The environment specified can be a simple block name or a block name followed by an activation number or a statement identifier. An activation number is used to establish as an environment or an activation of a block other than the most recent one. A statement identifier is merely a convenient means of identifying the block that immediately contains the statement. If the environment argument is not specified, the evaluation environment is set to the environment containing the current execution point.
Whenever the debugger continues after program execution pauses (for example for a breakpoint or single step) the evaluation environment is reset to the environment containing the current execution point.
There are two pertinent commands to the Environment facility: ENVIRONMENT and LENVIRONMENT. The ENVIRONMENT command is used to change environments. The LENVIRONMENT command is used for listing information about environments.
The STACK command is used to print a traceback of a specified number of stack frames.
This section describes the various methods and facilities to access, modify, and display symbolic information.
The rules for identifying variables in the debugger are almost the same as the rules defined for the evaluation language. The same naming conventions are used, and all type and scope rules apply. One exception is that an environment name followed by a backslash (\) may be used to reference a variable in another program block. The names of variables are case-sensitive or case-insensitive, depending on the language of the module in which they are contained.
Elements of arrays are referenced using the constructs of the source language. CodeWatch allows access to array slices in programs written in Open PL/I, LPI-C, LPI-COBOL, LPI-FORTRAN, and LPI-PASCAL. See the language-specific chapters (Chapters 9 through 15) for information about exact syntax.
The Evaluate command is used to evaluate and print the resultant value of expressions in the source language program. When the expression is evaluated, appropriate conversions are performed. Various display mode options (binary, decimal, octal, hexadecimal, and so on) are available.
The resultant value of an expression may be assigned to a named variable in the user program. When the expression is evaluated, appropriate type conversions are performed according to the rules of the source language. The resultant value is assigned to the named variable. If the type conversion is illegal, the debugger will issue an error message.
The LET command is used for variable assignment.
Note: If the current environment is within a module compiled by LPI-C, the LET command or Change dialog is equivalent to evaluating an assignment expression. (In C, assignments are merely expression operators with side effects.)
The Arguments command prints the arguments for an environment. The environment specified must be the name of an active procedure. (See the section Environment Control.) If an environment argument is omitted, the debugger defaults to the current evaluation environment.
The ARGUMENTS command lists the arguments for the given (or default) environment.
The Return facility allows you to set the return value of a procedure. Execution control is transferred to the exit point of the current procedure, and if an expression is specified, it is used as the return value for that procedure.
There are two pertinent commands to the Return facility: RETURN and LRETURN. The RETURN command transfers control to the exit point of the current procedure and allows you to set the return value. The LRETURN command lists the return value for the current procedure.
The TYPE command prints the resultant data type of an expression in terms of the data descriptions of the current source language.
The TYPE command is used to access declaration types.
This section describes the CodeWatch facilities for searching, printing, and displaying different locations in the source file(s).
The FIND command locates a line in the source file containing a specified text string.
The Source facility allows you to change the source file being displayed or to list information about the source files in the executable being debugged.
There are two pertinent commands to the Source facility: SOURCE and LSOURCE. The SOURCE command allows you to change the source file to be displayed. The LSOURCE command lists information about source files in the user program.
The WHERE command reports either a specified location or the current point of execution. The specified location may be a name of a routine, a line number, or a statement label.
The POINT command locates a line number within the debug source file and reports that line. If no line number is specified, the line corresponding to the current source file pointer is printed. The source file pointer is the pointer to the current line in the current source file.
In the graphical interface, double clicking on a line is equivalent to using the POINT command.
The PRINT command prints a specified number of source lines from the current debug source file or prints the current source line.
This section describes additional features of CodeWatch.
The Macro facility is used to define a macro as shorthand for a series of debugger commands that may be reused during the debugging session. Sixty-four macros may be defined at any one time. The series of debugger commands is specified as an action list. (For information on action lists, see the section "Using Action Lists.) Once a macro has been defined, its name may be used just like any other debugger command name. The macro in the command line is replaced by the debugger commands specified in the action list. Those commands are executed normally.
Note: Do not choose a macro name that is the same as a debugger command name because the macro name will override the debugger command for that debugging session.
If the last (or only) command in the series of debugger commands does not end with a semicolon, any additional arguments that appear on the command line after the macro name are supplied as arguments to the last command in the macro definition.
There are three pertinent commands to the Macro facility: MACRO, LMACRO, and NMACRO. The MACRO command creates new macros. The LMACRO command lists macros. The NMACRO command deletes macros.
The SAVE command writes out commands to a specified disk file to reset all current breakpoint, watchpoint, and/or macro settings for use in a later debugging session. The file can be read in by using the Read command.
The READ command is used to execute debugger command files, displaying each command to the screen as the command is executed.
The LOG command can be used to create debugger command files by causing all subsequent debugger commands to be logged to a specified file.
Both the command-line interface and the graphical interface have a help facility. Click Help in the menu bar, or use the HELP command.
The HELP command with no parameters lists all of the available CodeWatch commands. If the HELP command is followed by command-name, help text for that command is displayed. If you need help for a specific command, you may specify the appropriate abbreviation for that command rather than the full command name. For sample output from the HELP command, see the section Help.
Copyright © 2009 Micro Focus (IP) Ltd. All rights reserved.