This chapter lists and describes all of the CodeWatch commands in alphabetical order. The definitions consist of subsections that contain information on use, command syntax, a brief description, and a command-line example.
Prints the arguments of a specified procedure environment.
ARGUMENTS [environment]
where:
| environment | Is a name of an active procedure |
The ARGUMENTS command prints the arguments to a named procedure environment. The procedure environment can be any program block. For more information., see the section Environment Control.
If the environment name is omitted, the debugger defaults to the current evaluation environment.
In this example, the arguments to the "sift" procedure are displayed.
CodeWatch> ARGUMENTS sift
N = 10 { fixed binary (31) }Attaches CodeWatch to a pid and executes a LOAD command.
ATTACH pid filename
where:
| pid | Is a decimal process identification number |
| filename | Is the name of a file to be loaded |
The ATTACH command attaches CodeWatch to the "pid" (a decimal number) and performs a LOAD command. 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
Note The ATTACH command may not be supported on some systems.
CodeWatch> ATTACH 3768 myprog.out
Suspends program execution to allow for debugger actions.
BREAKPOINT [statement-id] [[action-list]] [/IF {logical-expr} [/ELSE[action-list]]] [/SKIP=n] [/IGNORE | /NIGNORE [/ALL]] [/SILENT | /NSILENT]
where:
| statement-id | Identifies the statement at which the breakpoint will be set or modified |
| action-list | Specifies a set of one or more CodeWatch commands separated by semicolons |
| logical-expr | Can be any expression that may occur in the source language program, including references to simple as well as aggregate (such as array, record, and structure elements) type variables, returning a boolean value |
The BREAKPOINT command is used to set a breakpoint at a specified statement or to modify the characteristics of a breakpoint already set at that statement. If the statement identifier is not specified, the breakpoint will be set at the current execution point; that is, the statement to be executed when program execution is resumed. The maximum number of breakpoints that can be active at one time is 64.
Breakpoints can be set at the entry point (%ENTRY) of external routines that have or have not been compiled in debug mode and at lines containing executable statements within routines that have been compiled in debug mode. Lines containing only comments or declarations, or only the keyword ELSE (else), are not valid breakpoint locations. If you try to set a breakpoint at one of these locations, the debugger will set the breakpoint at the first executable statement after the one named in the command.
If the statement identifier is qualified by a block name with an explicit activation number, the breakpoint applies only to that activation. If a block activation number is not specified, the breakpoint will be taken on every activation of the specified statement. The numbered activation may be higher than the most recent activation of the block. Relative activation numbers are converted to absolute activation numbers when the breakpoint is set. For more information, see the section Block Activation Numbers.
If an action list is specified, it is set as the action to be performed when the breakpoint is taken. To remove an action list using command-line syntax, simply specify a null action-list, that is [ ]. To remove an action list using the Breakpoint dialog, simply delete the text in the Action List edit field. An action list of CONTINUE causes the breakpoint to act like a simple tracepoint; at each execution of the statement a message identifies the statement and execution continues.
A breakpoint counter is associated with each breakpoint. When the breakpoint is created, the counter is set to zero; each time the breakpoint is encountered the counter is incremented by one. All breakpoint counters are set to zero when the program is reloaded.
If a skip count is specified, a breakpoint skip counter is set to the value specified, causing the breakpoint to be skipped that number of times. Once the breakpoint skip counter is set, it remains in effect until its value decreases to zero.
If the Ignore option is specified, the breakpoint is flagged to be ignored and is not executed when it is encountered. The Ignore option is useful to temporarily disable a breakpoint. Turning off the Ignore flag sets the breakpoint in effect again. This is done by specifying the /NIGNORE option. It is possible to set all breakpoints to be ignored or not ignored. This is done by specifying the option /ALL in conjunction with /IGNORE or /NIGNORE.
When a breakpoint is encountered, CodeWatch normally prints a message specifying the line at which the breakpoint is set. This message can be suppressed by using the Silent option; this is especially useful if a debug-time "patch" is desired within your program. To create a patch, set a breakpoint at the beginning of the code that causes the program error. The breakpoint should include the Silent option and an action list that performs a work-around assignment ending with a GOTO command (to circumvent the program error) and a CONTINUE command. The debugger will then perform the specified action list at the breakpoint and continue execution without any interaction.
A conditional expression may be used to qualify the breakpoint; it must be the last option on the command line. When a breakpoint with the If option is set, the executing program will be suspended and the debugger will be activated whenever the breakpoint is encountered. The IF condition is then evaluated. The evaluation always takes place in the environment and language of the program statement. If the IF condition is false, program execution continues and the breakpoint is never reported. If the IF condition is true, the debugger incurs a breakpoint as usual.
When a breakpoint with a conditional expression is set at a particular program statement, the executing program will be suspended and the debugger will be activated whenever that program statement is about to be executed. The following will then occur:
In the following example, a breakpoint is set at the entry point of the READ_INPUT procedure with an action list evaluating the value of MAXV.
CodeWatch> B READ_INPUT\%ENTRY [E MAXV]
CodeWatch> C
Break at PRIMES.READ_INPUT\%ENTRY
MAXV = 10 {fixed binary (31)}
In the following example, a conditional breakpoint is set on line 94. Program execution will stop if the variable COUNT is greater than 3; otherwise, the debugger will evaluate COUNT and continue.
CodeWatch> B SIFT\94 /IF {COUNT>3} /ELSE [E COUNT]
CodeWatch> CONTINUE
COUNT = 1 {fixed binary (31)}
COUNT = 2 {fixed binary (31)}
COUNT = 3 {fixed binary (31)}
Break at PRIMES.SIFT\94Calls a user procedure or function.
CALL subroutine-name [(argument-list)]
where:
| subroutine-name | Is a block name that may or may not return a value |
| argument-list | Is a list of variable names and/or constants separated by commas |
The CALL command will set up any given arguments and perform a subroutine call to the specified subroutine (function or procedure). If a breakpoint is set within a called subroutine (or in a routine which it in turn calls), then it is taken as usual. In this case, a new debugger prompt is used to indicate that a different level of debugger invocation has been entered. At this point, debugging can continue as usual, including stack tracebacks (with traceback only to the called routine), and calling another routine, thus entering yet a higher debugger invocation level. In this way, there is no change in the debugging environments across subroutine calls.
If the called subroutine is a function, the return value of the function will be printed at the end of the call. Functions may also be called through the use of Evaluate and Let, for example,
LET x = foo(y) * z
or:
EVALUATE foo(x) * foo(goo(y,foo(123))) / z
For more information, see the sections Evaluate and Let.
Functions that are defined or declared in the current execution environment may be called. In this case, the number and type of arguments given will be checked against the declaration or definition of the subroutine. If they do not match, an error will be given and the call will not be made.
It is not required that called functions be compiled in debug mode. If they are not, however, it will not be possible to set breakpoints within that function. The calling conventions of the source language of the environment from which the call is being made are properly upheld (for example, call-by-value versus call-by-reference).
Non-local Gotos within a called function are legal and executed only if the target is within an environment that has been called (that is, activated) subsequent to the initial call. If it is not, an error will be given and the call aborted.
The CALL command will not accept as an argument block names containing characters not allowed in a variable name for the source language of the current scope.
The maximum number of arguments allowed to be passed to a called routine is 240.
Illegal non-local Gotos within a called function do generate an appropriate error message and abort the call. However, the user program is terminated and must be reloaded using Reload to continue debugging.
The following call takes no arguments.
CodeWatch> CALL page_in_info ()
The following is a function call returning an integer.
CodeWatch> CALL get_user_id(name)
174 { int }
The following is the same call as in the previous example, except that a breakpoint is incurred at the entry point of get_user_id.
CodeWatch> CALL get_user_id(name) Break at get_user_id\%ENTRY DEB(1:get_user_id)>
Returns process control to the debugger when the given signal is generated.
CATCH {/DEFAULT | [/NIGNORE|/IGNORE] signal}
where:
| signal | Can be either a signal name mnemonic (such as SIGALRM, SIGINT, and so on) or the signal number corresponding to that mnemonic. Signal names may be specified in either uppercase or lowercase letters |
.
The occurrence of a signal that is set to be caught and ignored will cause process control to return to the debugger. When the child (user) process is subsequently resumed (for example, by using Step or Continue), it will continue as if it had not incurred the given signal. The occurrence of a signal that is set to be caught and not ignored (/NIGNORE), will cause process control to return to the debugger. When the child process is subsequently resumed, it will continue as if it had incurred the given signal. The occurrence of a signal that is not set to be caught will not cause process control to return to the debugger.
By default, certain signals are caught by the debugger. The Default option will reset all CATCH settings back to the debugger's default settings.
Use the command LCATCH /ALL to get a list of current signal settings.
Note: The signals SIGILL and SIGTRAP are permanently set to be ignored by the debugger. These are special signals because they are used by the debugger for breakpointing. You cannot modify the settings for these two signals.
In the following example, process control will return from the child process to the debugger when SIGALRM is generated.
CodeWatch> CATCH /IGNORE SIGALRM Changing SIGALRM to be caught and ignored.
When the child process resumes, it will ignore the SIGALRM and continue as if it had never generated a SIGALRM.
In the following example, the number 28 represents the signal SIGWINCH. Process control will return from the child process to the debugger when a SIGWINCH is generated.
CodeWatch> CATCH /NIGNORE 28 Changing SIGWINCH to be caught and not ignored.
When the child process resumes, it will recognize the signal SIGWINCH and continue as if it had incurred a SIGWINCH.
Displays CodeWatch command-line arguments.
COMMANDLINE
The COMMANDLINE command displays the command-line arguments specified to the user program. Command- line arguments may be specified to the user program either on the CodeWatch command line upon invocation of the debugger, or by using the RELOAD command.
In the following two separate examples, the command-line arguments are displayed. Note that the primes executable file being debugged takes no command-line arguments, whereas the myprog executable file was invoked with two command-line arguments.
CodeWatch> COMMANDLINE Command line : "primes" CodeWatch> COMMANDLINE Command line : "myprog" "-b" "-verbose"
Begins or continues program execution.
CONTINUE
The CONTINUE command is used to begin program execution initially or following a reload operation, or to resume program execution following a breakpoint or a step operation.
The CONTINUE command is often the last command in an action-list.
In this example, program execution is continued until the breakpoint is encountered.
CodeWatch> CONTINUE Break at PRIMES.READ_INPUT\%ENTRY
In the following example, a breakpoint is set at line 119 of the main program and a watchpoint is set on the variable n with an action list to continue program execution. The debugger will report when the contents of n have changed.
CodeWatch> BREAKPOINT 119 CodeWatch> WATCH n /ACTION [C] CodeWatch> CONTINUE Input maximum prime boundary: 10 Program Stopped due to a Watchpoint Watched variable N modified about line PRIMES\118 New Value: 10 {fixed bin (31)) Break at PRIME\119
Detaches from the currently attached process.
DETACH
Detaches CodeWatch from the currently attached process.
Note: The DETACH command may not be supported on some systems.
Sets the default mode and/or action-list for Step.
DSTEP [ IN|OVER ]
[ BACTION | SACTION | BOTH ]
[ [action-list] ]
where:
| action-list | Specifies a set of one or more CodeWatch commands separated by semicolons |
The DSTEP command sets the default stepping mode to either In or Over called routines and/or sets the default action-list for Step. If Dstep is not used, Over is the default stepping mode.
The Baction, Saction, and Both default stepping modes are intended to be used to step to a user-specified breakpoint. You may specify that the breakpoint action list be executed (Baction), the default step action list be executed (Saction), or both action lists be executed (Both).
In the following example, the default stepping mode is set to In and the PRINT command is set as the default action to be executed at each step. When the subsequent Step is executed, the current execution point is displayed and the current source line is printed.
CodeWatch> DSTEP IN [PRINT] CodeWatch> STEP Step at PRIMES.SIFT\%ENTRY 76: sift: procedure(n);
Sets the current evaluation environment.
ENVIRONMENT [environment]
where:
| environment | Can be a simple block name or a block name followed by an activation number or a statement identifier |
The ENVIRONMENT command sets the current evaluation environment to provide scope to the debugger for identifying variables and statements.
An activation number is used to establish, as an environment, an activation of a block other than the most recent one. If the environment argument is not specified, the evaluation environment is set to the environment containing the current execution point, and the current source file pointer is set to the current execution point. Whenever the environment changes during program execution, the evaluation environment is reset to the environment containing the current execution point.
In the following example, the current evaluation environment is changed to PRIMES, and then it is reset to the previous evaluation environment by using Environment without any arguments.
CodeWatch> ENVIRONMENT PRIMES
CodeWatch> E n
N = 5 {fixed binary (31)}
CodeWatch> ENV
Environment reset to PRIMES.READ_INPUTEvaluates and prints the resultant value of expressions.
EVALUATE [[/display mode] expression] EVALUATE [[/display mode] [ /NSDM | /NSMF | /SDM | /SMF | /SM | /NSM | /DM | /MF | /ALL | /INTERNAL] [ /DERIVED ] [ /PRIVATE | /PUBLIC | /PROTECTED | /ACCESSIBLE ]… EVALUATE [/STRING c-char-ptr] EVALUATE [/MACRO c-macro-defn]
where:
| display mode | Is one of ASCII, BIT, FLOAT, HEX, INTEGER, or OCTAL |
| expression | Can be any expression that may occur in the source language program, including references to simple as well as aggregate (such as array, record, and structure elements) type variables |
| c-char-ptr | Is a C expression whose resultant type is char * |
| c-macro-defn | Is a C preprocessor macro definition name |
The EVALUATE command is used to evaluate and print the resultant value of expressions in the source language program. If the expression is omitted, Evaluate uses the previous expression that was evaluated. If no previous expression was evaluated, an error message is generated.
The display mode is the mode in which the value of the expression is to be printed. The valid display modes are Ascii, Bit, Float, Hex, Integer, and Octal. The display modes are defined in Table 6-1.
| Display | |
|---|---|
| Mode Definition | |
| AScii | Displays the value as a series of Ascii characters. |
| Bit | Displays each bit in the value as a 1 or a zero. |
| Float | Displays the value as a single-precision floating-point number. |
| Hex | Displays the value as a series of hexadecimal numbers. |
| Integer | Displays the value as a series of signed decimal numbers. |
| Octal | Displays the value as a series of unsigned octal numbers. |
Using the command-line interface, it is possible to change the value of simple variables using the LET command. For more information, see the section Let.
Array evaluation and array slice evaluation is possible depending on the language of the current environment. All of the language-specific chapters in this manual have an "Array Evaluation" section that describes how each particular language evaluates arrays.
Using CodeWatch, it is possible to evaluate C preprocessor macro definitions. This is because the LPI-C compilers contains an integrated preprocessor rather than use a stand-alone separate preprocessor. This allows information about preprocessor macro definitions to be passed along to the debugger. The EVALUATE and TYPE commands will display the macro definition of the specified name.
In the case of name conflicts (that is, when a preprocessor macro definition follows a declaration or definition of a variable in the source file), then the debugger will display information about both the macro and the variable. If only information about the macro definition is desired, then you may specify the Macro option.
The display mode option has no effect on the display of a preprocessor macro definition. If the macro displayed is passed parameters, they are reported as <mac-param-1>, <mac-param-2>, and so on.
The String option may be used to dereference C char pointers; This allows you to evaluate the null-terminated sequence of characters to which a C pointer points.
If the expression to be evaluated includes a function call, then a subroutine call to the specified function will be made. Breakpoints are disabled during function calls when using the EVALUATE command. If you want a breakpoint in a called routine to be incurred, use the CALL command. For more information, see "Call" on page 49.
In this example, the value of data items in the SIFT routine is evaluated.
CodeWatch> EVALUATE THIS_PRIME
THIS_PRIME = 7 {fixed binary (31))
In this example, a cross section of the array PRIMES from 1 to count -1, where count equals 4, is evaluated.
CodeWatch> EVALUATE PRIMES (1 : count - 1)
PRIMES(1) = 1 {fixed binary (31))
PRIMES(2) = 2 {fixed binary (31))
PRIMES(3) = 3 {fixed binary (31))Locates and prints a specified string.
FIND [/IGNORE] [string]
where:
| string | Is a sequence of characters |
The FIND command locates a line in the source file containing a specified string and reports that line.
Quotation marks may be used to delimit the string but they are not required. If the string is not specified, the default value will be the string specified in the previous Find. If there is no string specified in the first instance of Find, an error message will be generated.
The debugger finds the first occurrence of the string after the current file position in the source file, then prints the line containing that occurrence of the string. By default, Find is case-sensitive, so that string "ABC" differs from "abc" and "Abc". When the ignore case option is turned on with Find, it is case-insensitive, so that the string "ABC" is the same as the string "abc" and "Abc".
If the string is not found, the current source file pointer is positioned at the last line of the user program.
In this example, the string "main" is located.
CodeWatch> FIND main 108: /* main procedure */
If the string is not identical in terms of case to the string in the source file, it will not be found. For example:
CodeWatch> FIND MAIN String not found: "MAIN"
In the following example, the search is case-insensitive.
CodeWatch> FIND /IGNORE MAIN 108: /* main procedure */
Moves the execution pointer to a specified statement.
GOTO statement-id
where:
| statement-id | Can be a line number, a simple statement label, or a statement label followed by a line number offset or statement offset |
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 named statement must exist in the current program block.
Notes: It is not valid to put an activation number on the statement-id. If the activation number of an existing previous block invocation is put on the statement-id, it is ignored; otherwise, the following error message is displayed:
specified activation does not exist
It is not possible to use Goto to go to the %EXIT point of a block. The RETURN command, however, can be used to go to the %EXIT point.
When a Goto is executed, the debugger displays the current execution point.
In this example, the execution point is changed to line 21 from the previous execution point as displayed by the Where command. For more information, see the section Where.
CodeWatch> WHERE Current execution point is PRIMES.READ_INPUT\%ENTRY CodeWatch> GOTO 21 Execution point is now PRIMES.READ_INPUT\21
Displays help text for debugger commands.
HELP [command-name]
where:
| command-name | Is the full spelling of a CodeWatch command or its accepted abbreviation |
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.
The following is an excerpt of the text displayed when invoking the HELP command with the BREAKPOINT command name abbreviation.
CodeWatch> HELP B
The BREAKPOINT command suspends execution to allow for debugger actions.
Command Syntax
Breakpoint [ statement-id ]
[[action-list] ]
[/IF { logical-expr } [/ELse [action-list] ]]
[/Skip=n]
[/Ignore | /Nlgnore [/All]]
[/SILent | /NSILent]
Kills the current child process.
KILL
Kills the current child process, and purges the CodeWatch internal symbol table.
CodeWatch> KILL
Lists information on breakpoints.
LBREAKPOINT [statement-id|/ALL ]
where:
| statement-id | Names the statement at which the breakpoint is to be listed |
The LBREAKPOINT command lists information on a single breakpoint or on all breakpoints.
If the statement identifier is omitted, information is listed on the breakpoint at the current execution point. If /ALL is specified, information is listed on all breakpoints. The information listed includes the skip count, execution count (the number of times the breakpoint has been encountered) and any specified action-list.
In this example, all breakpoints are listed.
CodeWatch> LBREAKPOINT /ALL Break set at PRIMES\114 (count = 1) Break set at PRIMES\119 (count = 2) Break set at PRIMES.READ_INPUT\%ENTRY (count=1) [E maxv;] Break set at PRIMES.ISPRIME\%ENTRY (count = 1)
Lists Catch settings for a given signal.
LCATCH [/ALL | signal]
where:
| signal | Can be either a signal name mnemonic (such as SIGALRM, SIGINT, and so on) or the signal number corresponding to that signal. Signal names may be specified in either uppercase or lowercase letters. If neither a signal name nor /ALL command is specified, all of the signals currently set to be caught are displayed |
The LCATCH command with no arguments lists all of the signals that are currently set to be caught. When used with the /ALL option, LCATCH lists two sets of signals, those that are currently set to be caught and those that are currently set to not be caught. The LCATCH command, with a signal name specified, lists Catch settings for that given signal.
In the following example, the current Catch settings for the signal SIGALRM are listed.
CodeWatch> LCATCH SIGALRM SIGALRM not being caught.
In this example, the signals currently set to be caught and those that are set not to be caught are listed.
CodeWatch> LCATCH /ALL CATCHing signals: SIGINT SIGQUIT SIGILL SIGTRAP SIGIOT SIGEMT SIGFPE SIGKILL SIGBUS SIGSEGV SIGSYS SIGPIPE SIGTERM SIGURG SIGSTOP SIGTTIN SIGTTOU SIGIO SIGXCPU SICXFSZ SIGPROF SIGVTALRM Not CATCHing signals: SIGHUP SIGALRM SIGTSTP SIGCONT SIGCHLD SIGWINCH SIGLOST SIGUSR2
Lists the current evaluation environment.
LENVIRONMENT [/ALL ] [/FULL]
The LENVIRONMENT command lists the current evaluation environment.
The All option lists all environments within the source file.
The Full option lists the current environment, the first and last source file line numbers in that environment, and the text offsets for the beginning and end of code in that environment. The offsets correspond to those found in the expanded listing generated by the Compiler.
In this example, the current evaluation environment displayed is PRIMES.READ_INPUT.
CodeWatch> LENVIRONMENT Evaluation environment is PRIMES.READ_INPUT
Assigns a value of an expression to a name.
LET name = expression
where:
| name | Is the name of any variable or destination construct (such as a substring or based reference in PL/I) that occurs in the source language program |
| expression | Can be any expression allowed by the source language whose value can be converted to the data type of the named variable |
The LET command assigns a value of an expression to a name. When the expression is evaluated, appropriate type conversions are performed. The resultant value is assigned to the named variable. If the type conversion is illegal, the debugger will issue an error message.
The value of a character string constant can be changed by enclosing the expression within single or double quotation marks, depending on the source language.
In C, assignments are merely expression operators with side effects. Therefore, Evaluate provides the same functionality as Let in other languages.
Breakpoints are disabled during function calls using the LET command. If you want a breakpoint in a called routine to be incurred, use the CALL command.
In this example, the value of MAXV is assigned a new value (MAXV/ 2).
CodeWatch> EVALUATE MAXV
MAXV = 10 {fixed binary (31))
CodeWatch> LET MAXV = MAXV/2
CodeWatch> EVALUATE MAXV
MAXV = 5 [fixed binary (31))Lists the macro definitions.
LMACRO { macro1, macro2, ..., macron | /ALL }The LMACRO command lists the definition of one or more specified macros or the definitions for all currently defined macros. The debugger lists the action-list that was defined for the macro. Either the indicated macro-name(s) or /ALL must be specified.
In this example, all of the macro definitions are listed.
CodeWatch> LMACRO /ALL FIG = [FIND /IGNORE] INFO = [LB /A; LENV; LMA /A; WHERE]
Loads the symbol table from a specified file as the primary executable file.
LOAD filenameThe LOAD command loads the symbol table from filename into CodeWatch as the primary executable file for debugging. It also purges the internal CodeWatch symbol table of any previously loaded executable files or shared libraries.
CodeWatch> LOAD myprog.out
Logs debugger commands and, optionally, output to a specified file or files.
LOG [/FuLL]filename
where:
| filename | Is the pathname of any file allowing write permission to the user |
The Log command causes all subsequent debugger commands to be appended to the specified file.
The /FULL option specifies that all output from the debugger be logged to the specified file in addition to all debugger commands. It is possible to log commands to one file and commands-and-output to another file. This would be done by the commands:
CodeWatch> LOG filel CodeWatch> LOG /FULL file2
The NLOG command takes an optional file name that tells the debugger which log session to stop. If no file name is given, the debugger will first check if commands are being logged to a file (no /FULL). If so, that log session is stopped. If there is no such log session, the debugger checks to see if commands-and-output to a file (/FULL) are being logged. If so, that log session is stopped.
CodeWatch> LOG temp CodeWatch> FIND Main 77 REM ** Main Program ** CodeWatch> BREAKPOINT 89 CodeWatch> PRINT 20 77: REM ** Main Program ** 78: INTEGER max_value, max_primes, n 79: REM REAL a 80: 81: max_value = 1000 82: max_primes = 500 CodeWatch> NLOG Ending debugger command logging to "temp" CodeWatch> !cat temp FIND Main BREAKPOINT 89 PRINT 20
Lists the return value of a function.
LRETURN
When the current execution point is at the exit point of a function, Lreturn prints the value to be returned by the function.
In this example, the return value for the PRIMES function is listed.
CodeWatch> LRETURN
Return value for PRIMES is 15 {fixed binary (31)}Prints the name of the current source file being displayed.
LSOURCE [/ALL] [/FULL]
The All, Full, Both, and Map buttons access the Lsource dialog. The Lsource dialog is for information only and no action may be executed. Specifying the Both button is the same as specifying both the /ALL and /FULL command-line options.
The LSOURCE command prints the name of the source file currently being displayed as well as the time and date of its creation. If the source file being displayed does not contain the current evaluation environment, Lsource also displays the source file that does contain the current evaluation environment. See the section Source.
If the Full option is specified, the name of the symbol table file associated with the source file containing the current evaluation environment will also be displayed. If the All option is specified, all of the source files in the program being debugged that were compiled in debug mode will be displayed.
In this example, the name of the symbol table file associated with the source file containing the current evaluation environment, the source file, and the source file currently being displayed are listed.
CodeWatch> LSOURCE Current display source file is "primes.pl1" (PL/I) Apr 11 11:06:51 1991
Lists the current stepping mode and the default action-list.
LSTEP
The LSTEP command lists the current mode of stepping, that is, either In or Over, the default action-list, and the default action-list to be executed when stepping to a breakpoint.
In this example, the default stepping mode is in, the step action-list contains the Print command, and the action-list that will be executed upon stepping to a user breakpoint is the step action (Print).
CodeWatch> LSTEP Step IN; Execute STEP action Action = [PRINT;]
Lists the current tracing mode.
LTRACE
The LTRACE command lists the current mode of tracing, that is, statement and/or entry.
In this example, the current tracing mode is listed. Note that no conditional expression is specified.
CodeWatch> LTRACE
TRACE ENTRY [C;] /IF {}Lists information on watchpoints.
LWATCH {variable|/ALL}
where:
| variable | Specifies a variable in the source program |
The LWATCH command lists information on the given watchpoint. If /ALL is specified, information is listed on all watchpoints. The information listed includes the skip count, execution count (the number of times the watchpoint has been incurred), specified switch settings, and any specified action-list.
In the following example, all of the existing watchpoints are listed.
CodeWatch> LWATCH /ALL Watchpoint set for N (count = 1) /NSILENT /NIGNORE [C;]
Defines a macro.
MACRO macro-name = [action-list]
where:
| action-list | Specifies a set of one or more CodeWatch commands separated by semicolons |
The MACRO command is used to define a macro as shorthand for an action-list. Sixty-four macros can be defined at any one time.
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.
The action-list is specified in the usual way. (For information on specifying 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 then executed normally.
If the last (or only) command in the action-list does not end with a semicolon, any additional arguments to that command can appear on a command line after the macro name. For example, suppose the following macro has been defined:
FOO = [ LET A = A + ]
The command FOO 3 can then be entered to add 3 to A.
In this example, the macro info is defined that lists all breakpoints, the current evaluation environment, all macros, and the current execution point.
CodeWatch> MACRO info = [LB /ALL; LENV; LMACRO /ALL; WHERE] CodeWatch> info Break set at PRIME\118 (count = 2) Break set at PRIMES.READ_INPUT\%ENTRY Break set at PRIME.ISPRIME\%ENTRY (COUNT = 1) Evaluation environment is PRIMES.ISPRIME info = [LB /ALL; LENV; LMA /ALL; WHERE] Current execution point is PRIMES.ISPRIME\%EXIT
In the following example, the macro fig is defined to perform a case-insensitive search for the string you wish to specify as an argument.
CodeWatch> MACRO fig = [FIND /IGNORE] CodeWatch> fig MAIN /* Main program */
Removes breakpoints.
N BREAKPOINT [statement-id | /ALL ]
where:
| statement-id | Is used to name the statement at which the breakpoint is to be removed |
The NBREAKPOINT command removes the breakpoint at the specified statement.
If the statement-id is omitted, the breakpoint at the current execution point is removed. If /ALL is specified, all breakpoints currently set are removed.
In the following example, the breakpoint at line 94 is removed.
CodeWatch> NB 94
In the following example, all breakpoints are removed.
CodeWatch> NBREAKPOINT /ALL
Prevents process control from returning to the debugger when the given signal is generated.
NCATCH signal
where:
| signal | Can be either a signal name mnemonic (such as SIGALRM, SIGINT, and so on) or the signal number corresponding to that signal. Signal names may be specified in either uppercase or lowercase |
The NCATCH command prevents process control from returning to the debugger when the given signal is generated. The child (user) process continues without interruption, as if the given signal had been generated. This implies that user-defined handlers will be executed.
In the following example, the process control will not return from the child process to the debugger when a SIGALRM is generated.
CodeWatch> NCATCH SIGALRM Changing SIGALRM to now not be caught.
As a result, Ncatch allows the child process to continue uninterrupted when a SIGALRM is generated. If the user process has its own signal handler for a SIGALRM, that signal handler will be executed.
Kills the current child process.
NLOAD
Kills the current child process and purges the CodeWatch internal symbol table.
CodeWatch> NLOAD
Stops the logging of debugger commands and/or commands-and-output to a file or files.
NLOG [filename]
where:
| filename | Is the name of a log file specified in a previous LOG command |
The NLOG command ceases logging of debugger commands or commands-and-output to a file or files specified in the previous LOG command.
CodeWatch> LOG temp CodeWatch> FIND Main 77 REM ** Main Program ** CodeWatch> BREAKPOINT 89 CodeWatch> PRINT 20 77: REM ** Main Program ** 78: INTEGER max_value, max_primes, n 79: REM REAL a 80: 81: max_value = 1000 82: max_primes = 500 CodeWatch> NLOG Ending debugger command logging to "temp" The file "temp" will contain CodeWatch> !cat temp FIND Main BREAKPOINT 89 PRINT 20
Removes macro definitions.
NMACRO {macro1, macro2, …, macron, | /ALL }The NMACRO command removes the definition of one or more specified macros or the definitions of all currently defined macros. Either the specific macro name(s) or /ALL must be specified.
In this example, the macro named info is removed.
CodeWatch> NMACRO info
In this example, all macro definitions are removed.
CodeWatch> NMACRO /ALL
Reads the dynamic loader map and displays information about the currently loaded shared libraries.
Shared library debugging has these limitations: CodeWatch does not dynamically monitor the dynamic load map. If a shared library is loaded into CodeWatch via the SHLIB command, and that library is being programmatically loaded and unloaded, you must manually load and unload the symbols via SHLIB and NSHLIB, since there is no guarantee that the library will always be mapped to the same virtual address. However, use of the NMAP command and noting load addresses will indicate whether this is actually necessary.
When attaching to a process, both CodeWatch and the executable file associated with the attached process must be on a local disk. The operating system does not allow attaching to processes whose executable file is on a network disk. An attempt to ATTACH when the file is not local fails because of a security violation.
When attaching to a process that programmatically loads shared libraries (that is, a process that is linked without the -a archive option on HP-UX), you must run the HP-UX utility pxdb on the shared library.
Examples:
pxdb -s enable filename pxdb -s status filename pxdb -s disable filename
This utility marks status bits in the shared library that cause it to be mapped into a private data space for debugging rather than shared text. In the case of libraries that are bound into the executable file, CodeWatch does work equivalent to this at startup (and reload) before the dynamic loader runs. Since CodeWatch cannot do this for shared libraries that are programmatically loaded, the pxdb utility is required.
On reloading a program that uses shared libraries, the symbols from all shared libraries are purged from the internal CodeWatch symbol table. The symbols from the primary executable remain intact. Symbols are purged because the shared libraries may not be loaded at the same addresses on the next access.
Purges the symbols of the shared library specified by slibfile from the CodeWatch internal symbol table.
Disables entry or statement tracing.
NTRACE {ENTRY | STATEMENT}The NTRACE command disables entry or statement tracing. If ENTRY is specified, any action-list and condition are removed as well.
In this example, TRACE STATEMENT is disabled.
CodeWatch> NTRACE STATEMENT
Removes watchpoints.
NWATCH {variable|/ALL}
where:
| variable | Specifies the variable being watched |
The NWATCH command removes the watchpoint for the given variable. If /ALL is specified, all watchpoints currently set are removed.
In the following example, the watchpoint for the variable n is removed from the current listing.
CodeWatch> LWATCH /ALL Watchpoint set for n (count = 1) /NSILENT /NIGNORE [C;] CodeWatch> NWATCH n CodeWatch> LWATCH /ALL No watchpoints are currently set.
Displays the contents of a specified area of user memory in a specified format.
PEEK [/TEXT | /DATA]
[/HEX | /DECIMAL | /OCTAL]
[/LONG | /SHORT | /BYTE]
[/count] address
where:
| count | Is a numeric constant |
| address | Is a numeric constant. (For format information, see the following Description section.) |
The PEEK command displays the contents of a designated amount of user program memory in a designated format starting at a given address.
If the Text option is specified, the user text segment of the program is read. If the Data option is specified, the user data segment of the program is read. The Data option is the default.
The base of the displayed memory may be specified as being hexadecimal, decimal, or octal, depending on the options Hex, Decimal, or Octal, respectively. Hex is the default.
The size of each displayed memory unit may be specified as being 4 bytes (32 bits), 2 bytes (16 bits), or 1 byte (8 bits) by specifying the options Long, Short, or Byte, respectively. When the option Byte is specified, the ASCII representation of the byte is also displayed. Long is the default.
The number of memory units to be displayed may be specified by using the Count option. This consists of a slash "/" followed by a decimal number. A count of one is the default.
The format of the given address may be either hexadecimal, decimal, or octal, depending on how it is written. A hexadecimal number must begin with a 0x or 0X or contain at least one of the hexadecimal digits "a" through "f" (case in-sensitive). An octal number must begin with a 0 and contain only octal digits "0" through "7". A decimal number may contain only any of the decimal digits "0" through "9".
The following PEEK command displays five lines (4-bytes) in hexadecimal format beginning at address 0x23d8.
CodeWatch> PEEK /5 0x23d8 0x000023D8: 0x4E4141EE 0x000023DC: 0xFFE42F08 0x000023E0: 0x6100FDF6 0x000023E4: 0x584F4E71 0x000023E8: 0x4E71F236
Resets and displays the source file pointer within the current source file.
POINT [+n|–n|n]
where:
| n | Is the line number you specify |
The POINT command relocates the source file pointer within the current source file and prints that line.
If a sign is specified, the debugger relocates the source file pointer to the line that is n lines before (–) or after (+) the current source file pointer. Otherwise, the debugger relocates the source file pointer to the line specified by n. The debugger then prints out the new pointed to line. If n is omitted, the source file pointer is reset to the current execution point, and that line is printed.
In the following example, the source file pointer is reset to line 116 and displayed.
CodeWatch> POINT 116
116: call read input (n);
In this example, the source file pointer is reset to two lines before the current source file pointer, and that line is displayed.
CodeWatch> POINT -2 114: put skip (2);
Changes the contents of a specified area of user memory in a specified format.
POKE [/TEXT | /DATA]
[/FLOAT| /DOUBLE| /LD]
[/LONG | /SHORT | /BYTE]
address-expr, data-expr
where:
| address-expr | Is an expression specifying the memory location to examine. (To find the syntax of an address expression, type HELP Dis.) |
| data-expr | Is an expression specifying the section of memory Poke changes. The data segment is the default |
The /BYTE, /SHORT, and /LONG options, used with integer values, specify the size of memory to be altered (1, 2, or 4 bytes, respectively). /LONG is the default.
The /FLOAT, /DOUBLE, and /LD options, used with floating point values, specify the size of memory to be altered (4, 8, or 12 bytes, respectively).
The following POKE command stores the hexadecimal value 99 at address 0x7FFFE480.
CodeWatch> POKE /TEXT 0x7FFFE48 99
Prints a specified number of lines from the current source file.
PRINT [n]
where:
| n | Indicates the number of source lines to be printed |
The PRINT command prints a specified number of source lines from the current debug source file.
Printing begins at the current line. The current source line is reset to the last line printed. If the argument number is omitted, only the current source line is printed.
In this example, fifteen lines of the primes.pl1 program are printed.
CodeWatch> PRINT 15 108: /* main procedure */ 109: 110: declare n fixed binary(31); 111: 112: put skip; 113: put list (' *** Sieve of Eratosthenes ***'); 114: put skip (2); 115: 116: call read_input(n); 117: 118: do while (n > 1); 119: call sift(n); 120: call read_input(n); 121: end; 122:
Terminates a debugging session.
QUIT
Quit causes termination of the debugging session. Selecting the Exit item in the File menu is equivalent to issuing the QUIT command.
This example shows the message the debugger displays as it exits.
CodeWatch> QUIT CodeWatch Quit ... Bye!
Reads and executes debugger commands from a specified file.
READ filename
where:
| filename | Is any file containing debugger commands. If the file is not in the current working directory, its pathname must be specified |
The READ command is used to execute debugger commands, which are contained in the specified filename. Each command is printed to the terminal as it is executed. Seven levels of Read commands may be nested in debugger command files.
In this example, debugger commands are read in from a file called dbg. After all the commands are read and executed, the debugger prompts for the next command to be entered.
CodeWatch> READ dbg **** Reading commands from "dbg" ... CodeWatch> BREAKPOINT PRIMES\119 /SKIP=0 CodeWatch> BREAKPOINT PRIMES.READ_INPUT\%ENTRY /SKIP=0 [e maxv;] CodeWatch> BREAKPOINT PRIMES.ISPRIME\%ENTRY /SKIP=0 CodeWatch> BREAKPOINT PRIMES.PRINT_OUT\60 /SKIP=0 CodeWatch> BREAKPOINT PRIMES.PRINT_OUT\59 /SKIP=0 CodeWatch> MACRO info=[ lb /a;lenv;lma /a; where ] CodeWatch> **** Done reading commands from "dbg"
Displays the contents of the general machine registers.
REGISTERS
The REGISTERS command displays the contents of all the machine registers as long hexadecimal values. Floating-point registers may or may not be displayed, depending on the target.
The following input from the REGISTERS command is target-specific and may not match what is displayed on your system.
CodeWatch> REGISTERS D0: 0x0000003C D1: 0x00000004 D2: 0x00000001 D3:0x00000000 D4: 0x00000000 D5: 0x00000000 D6: 0x00000000 D7:0x00000000 A0: 0x0EFFFD94 A1: 0x0002037C A2: 0x00000000 A3:0x0EFFFDC8 A4: 0x0EFFFDD0 A5: 0x00000000 A6: 0x0EFFFDB0 A7:0x0EFFFD90 SR: 0x00000000 PC: 0x000023D8 FO: 0x7FFF0000FFFFFFFFFFFFFFFF F1: 0x7FFF0000FFFFFFFFFFFFFFFF F2: 0x7FFF0000FFFFFFFFFFFFFFFF F3: 0x7FFF0000FFFFFFFFFFFFFFFF F4: 0x7FFF0000FFFFFFFFFFFFFFFF F5: 0x7FFF0000FFFFFFFFFFFFFFFF F6: 0x7FFF0000FFFFFFFFFFFFFFFF F7: 0x7FFF0000FFFFFFFFFFFFFFFF FPCR: 0x0000F400 FPSR: 0x00000000 FPIAR: 0x00000000
Reloads the user program.
RELOAD [/ARGUMENTS command-line-arguments] [/NEWARG command-line-arguments] [< filename] [> filename]
where:
| command-line-arguments | Is a list of text strings to be passed to the user program as its arguments. This must be the last option on the RELOAD command line |
| filename | Is the pathname of any file |
The RELOAD command will reinitialize the user program while preserving any explicitly set breakpoints and any associated action lists. All breakpoint counters will be reset to zero.
A subsequent Continue or Step will execute the user program from the beginning.
If the Arguments option is not specified, the program will be initialized with the command-line arguments specified when CodeWatch was invoked. If the Arguments option is specified, the given arguments will be used as command-line arguments to the reinitialized program. If more than one argument is specified, they must be separated by a space. These command-line arguments will be in effect until the next time the program reloads.
If you want to permanently change the command-line arguments of the program being debugged, that is, for the remainder of the debugging session, this is possible using the /NEWARG command-line option. This specifies that the given command-line arguments be used for the remainder of the debugging session. These may be reset by again using the /ARGUMENTS or /NEWARG command-line options.
User program input may be redirected by either specifying the command-line option < filename or by entering a file name in the Stdin edit field of the Reload dialog box.
User program output may be redirected by either specifying the command-line option > filename or by entering a file name in the Stdout edit field of the Reload dialog box. Any error opening filename for either input or output will result in an error message and CodeWatch exiting.
Note: In the RELOAD command-line syntax, there must be a space between the "<" or the ">" and the file name.
By default, user input and output is redirected to and from the xterm window from which CodeWatch was invoked. However, this may be changed using the RELOAD command.
It is possible to redirect input or output back to the terminal after having redirected it elsewhere. To do this, specify the following:
RELOAD < /dev/tty
or:
RELOAD > /dev/tty
for input and output, respectively.
In this example, the debugging session is restarted in the original evaluation environment, with all breakpoints preserved and without returning to the system level.
CodeWatch> RELOAD Command line : "primes" Reloading..ok Initial evaluation environment is PRIMES:(inactive) CodeWatch>
In this example, user program output is redirected to the file primes.out
CodeWatch> RELOAD > primes.out Reloading..ok Initial evaluation environment is PRIMES:(inactive) CodeWatch>
Transfers the execution pointer to the exit point of the current procedure and allows a return value to be set.
RETURN [expression]
where:
| expression | Can be any expression that may occur in the source language program, including references to simple as well as aggregate (such as array, record, and structure elements) type variables |
The RETURN command transfers the current execution pointer to the exit point (%EXIT) of the current procedure. If the procedure returns a value, an expression indicating the return value must be given. An expression should not be given if the procedure does not return a value.
If the current execution point is already at the exit point of the current procedure, no action is taken if the procedure does not return a value, or the return value is set to the given expression if the procedure does return a value.
In this example, the return value of the ISPRIME routine is set to "15".
CodeWatch> RETURN 15
CodeWatch> LRETURN
Return value for PRIMES.ISPRIME is 15 {fixed binary(31)}Writes out commands to reset all currently set breakpoints, watchpoints, and/or macros to a specified file.
SAVE [{/BREAKPOINT |/WATCH |/MACRO}…|/ALL]
filename
where:
| filename | Is the specified file that will contain the breakpoints, watchpoints, and/or macros settings |
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.
If no options or the All option is specified, commands to reproduce all breakpoint, watchpoint, and macro settings will be written to the specified file.
If the Breakpoint option is specified, the breakpoint commands for all current breakpoint settings will be written to the specified file. If the Watch option is specified, the watchpoint commands for all current watchpoint settings will be written to the specified file. If the Macro option is specified, the macro commands for all current macros will be written to the specified file. Any combination of Breakpoint, Watch, and Macro may be used.
The SAVE command will create, not append, the specified file. If the file already exists, the Save will fail and an error will be issued. For more information, see the section Read.
In this example, two debugging sessions are used to demonstrate the SAVE command. In the first session, macros, breakpoints, and watchpoints are saved in the dbg file; in the second session, the saved commands are read from the dbg file.
Session one:
$ cwcmd primes
CodeWatch setting up "primes". Wait...
CodeWatch> BREAKPOINT PRIMES\114
CodeWatch> BREAKPOINT PRIMES\119
CodeWatch> BREAKPOINT PRIMES.READ_INPUT\%ENTRY [E maxv;]
CodeWatch> BREAKPOINT PRIMES.ISPRIME\%ENTRY
CodeWatch> WATCH N /ACTION [C;]
CodeWatch> MACRO fig = [FIND /IGNORE]
CodeWatch> MACRO info=[ LB /A;LENV;LMA /A; WHERE ]
CodeWatch> SAVE dbg
Environment saved to file "dbg"
CodeWatch> QUIT
Session two:
$ cwcmd primes
CodeWatch setting up "primes". Wait...
CodeWatch> READ dbg
**** Reading commands from "dbg" ...
CodeWatch> BREAKPOINT PRIMES\114 /SKIP=0
CodeWatch> BREAKPOINT PRIMES\119 /SKIP=0
CodeWatch> BREAKPOINT PRIMES.READ_INPUT\%ENTRY /SKIP=0 [E maxv;]
CodeWatch> BREAKPOINT PRIMES.ISPRIME\%ENTRY /SKIP=0
CodeWatch> WATCH N /ACTION [C;]
CodeWatch> MACRO fig = [FIND /IGNORE]
CodeWatch> MACRO info = [ LB /A;LENV;LMA /A; WHERE ]
CodeWatch>
**** Done reading commands from "dbg"Loads the symbols from the specified shared library, slibfile, into the CodeWatch internal symbol table.
If slibfile was compiled using the -deb option, the command ENV will enable the display of the shared library source and other normal symbolic debugging.
If slibfile is specified with a simple filename, such as file.sl, CodeWatch first searches the current directory for this shared library. Failing that, it uses the search path indicated by the LPATH environment variable on HP-UX or the LD_LIBRARY_PATH environment variable on Solaris 2 (which are the same variables that are used by the dynamic loader). If the -L option was used at link time to specify library locations, slibfile must specify the full pathname for the shared library.
Changes the current source file to be displayed.
SOURCE [filename]
where:
| filename | Is the name of the source file to be displayed |
The SOURCE command changes the source file to be displayed. This may be used, for instance, when you want to look at the contents of "COPY" or "INCLUDE" files. Referencing these files is discussed in the section Referencing Included or Copied Files.
If the filename is omitted, the current source file is set to the source file associated with the current execution point. The current source file pointer is not explicitly set. To reset the current source file pointer to the current execution pointer, use Environment without any arguments.
Activation of the SOURCE command applies to the current debugger action only. Its effect is lost when the program resumes execution; that is, the current source file is set to the source file associated with the current execution point.
In the following example, the source file from which lines are to be displayed is var.in. The LSOURCE command prints the name of the current source file as well as the name of the source file for the current environment, because it is different.
CodeWatch> SOURCE var.in CodeWatch> LSOURCE Current display source file is "var.in" Source file of current environment is "x.pl1" Current display source file is "var.in" (PL/I) Apr 11 11 :06 :51 1991
Displays information on a specified number of stack frames.
STACK [nframes|/ALL]
[/FULL]
[/ARGUMENTS]
[/LOCALS]
where:
| nframes | Is an integer specifying the count of the most recent stack frames to be displayed |
The STACK command is used to display information on a specified number of stack frames.
If the All option is specified, all stack frames back to your main program are displayed. There are typically a number of system start-up routines called before your main program. The frames for these start-up routines will not be displayed unless the Full option is specified. The Full option is useful only if specified in conjunction with a specified Count or the All option. If neither a specified Count nor the All option is present, only the current stack frame is displayed.
If the Arguments option is specified, the arguments to each procedure are displayed.
If the Locals option is specified, all local variables for each stack frame are displayed.
In this example, information is displayed on all stack frames and the arguments to each procedure.
CodeWatch> STACK /ARGUMENT /ALL
Stack contains 5 frame(s).
Current execution point is PRIMES.SIFT\94
5: Owner is "PRIMES.SIFT"
Arguments:
N = 10 {fixed binary (31)}
Called from PRIMES\119
4: Owner is "PRIMES"
Arguments: None
Main programExecutes a specified number of statements.
STEP [OUT]
[IN|OVER]
[count]
[[action-list]]
where:
| count | Is an integer specifying the number of statements to be executed |
action-list specifies a set of one or more CodeWatch commands separated by semicolons.
The STEP command starts program execution at the current location of the execution pointer and stops execution after one or a specified number of statements.
To execute a single statement, use Step with no options specified. To execute a number of statements, specify a count parameter.
If Step Out is specified, the debugger steps to the exit point of the current routine. If Step Out is specified with a count parameter, the first step is to the exit point of the current routine, and each step thereafter is to a succeeding statement in the calling routine. Thus, if the execution pointer is in a called routine and you want to step to the next executable statement in the calling routine, issue STEP OUT 2. The first step is to the exit point of the current routine, and the second step returns and steps forward in the calling routine. If the execution pointer is already at the exit point of the called routine, issuing Step Out causes the execution pointer to step to the exit point of the calling routine.
If Step In is specified and the current execution point is at a subroutine call, the debugger steps to the entry point of the called routine. If Step In is specified with a count parameter, the entry point is the first step, the first executable statement is another, and so on.
If Step Over is specified, the debugger steps over calls to routines. Step Over is the default mode for the STEP command.
If an action-list is present, it is performed at the last step and is set as the action to be taken for any other Step. To remove the Step action-list, supply a null action-list as an argument to Step. Use the DSTEP command to do this without stepping.
At the completion of a step operation, the debugger issues a message indicating the current execution point in the following format:
Step at x
where x is the location of the current execution point, that is, the statement that is about to be executed.
Note: Step cannot be used when the current execution point of the user program is at a non-local Goto.
In the following example, the default stepping mode is set to step in and the stepping action-list is set to print the current source line. Two step commands are executed (the second command with a count of 2).
CodeWatch> DSTEP IN [P] CodeWatch> STEP Step at PRIMES.SIFT\95 95: primes(count) = this_prime; CodeWatch> S 2 Step at PRIMES.SIFT\97 97: do while (k < n);
In the following example, the debugger steps out of the sift routine.
CodeWatch> STEP OUT Number of primes found was (prime) 5 1 2 3 5 7 Step at PRIMES.SIFT\%EXIT 106: end sift;
Displays all procedure and block entries information during program execution.
TRACE ENTRY [[action-list]] [/IF {logical-expr}]
where:
| action-list | Specifies a set of one or more CodeWatch commands separated by semicolons |
| logical-expr | Can be any expression that may occur in the source language program, including references to simple as well as aggregate (such as array, record, and structure elements) type variables, returning a boolean value |
Tracing enables information about all procedure and block entries to be reported as the program executes.
The TRACE ENTRY command sets tracepoints, which enable tracing of all procedure and block entries by printing a message each time a procedure or block is entered.
When entry tracing is enabled, the debugger will be activated as each procedure or block is entered, and activated again as each procedure or block is exited. The specified action-list applies only to the entry tracepoint; exit tracepoints always print a message and continue.
If an action-list is specified, the debugger will process the commands and print the results. If an action-list is omitted, a default action-list of [CONTINUE] is supplied. A common action-list is [ARGUMENTS; CONTINUE]. An action-list may not refer to statements or variables in a way that is dependent on scope. To take a breakpoint and enter interactive debugging at each entry, supply an explicit null action-list, that is, TRACE ENTRY [ ] .
If a conditional expression is specified, each time an entry point is reached, the value of the expression is evaluated, and if it is true, the message is printed; if it is false, no message is printed.
In the graphical interface, the TRACE ENTRY command is especially useful because it allows you to watch your code execute. Rather than simply issuing a message as entry and exit points are reached, CodeWatch updates the Source window with the source file for the current environment and highlights the line corresponding to each entry or exit point.
In the following example, entry tracing is turned on and program execution is continued.
CodeWatch> TRACE ENTRY CodeWatch> C Input maximum prime boundary: 10 **** PRIMES.READ_INPUT\%EXIT Break at PRIMES\119
Displays each source statement as it is executed.
TRACE STATEMENT
The TRACE STATEMENT command sets tracepoints, which enable the tracing of every statement by printing a message identifying the statement.
At each statement, if there is no other action to be performed (that is, if there is no breakpoint, entry trace, single step action, and so on), the identifying message is printed and execution continues.
In the graphical interface, the Trace Statement command is especially useful because it allows you to watch your code execute. Rather than simply issuing a message as statements are reached, CodeWatch updates the Source window with the source file for the current environment and highlights each line as it executes.
In the following example, statement tracing is turned on and program execution is continued.
CodeWatch> TRACE STATEMENT CodeWatch> CONTINUE **** PRIMES\112 **** PRIMES\113 Break at PRIMES\114
Displays the resultant type of an expression.
TYPE [/FULL] expression
where:
| expression | Can be any expression that may occur in the source language program, including references to simple as well as aggregate (such as array, record, and structure elements) type variables |
The TYPE command prints the resultant type of an expression.
If the expression refers to a structure or record, the Full option can be used to display the entire structure or record.
In the following example, declaration information about various data items is displayed.
CodeWatch> TYPE COUNT COUNT fixed binary (31) automatic CodeWatch> TY FLAGS FLAGS(1:1000) bit (1) automatic
Sets watchpoints on specified variables.
WATCH variable [/SILENT|/NSILENT] [/IGNORE|/NIGNORE] [/SKIP=n] [/ACTION[action-list] [/IF{logical-expr}]
where:
| variable | Specifies the variable to be watched |
| n | Is the value you assign to the skip counter |
| action-list | Specifies a set of one or more CodeWatch commands separated by semicolons |
| logical-expr | Can be any expression that may occur in the source language program, including references to simple as well as aggregate (such as array, record, and structure elements) type variables, returning a boolean value |
Watchpoints are used to monitor any changes to data. The WATCH command designates the given variable to be watched. When the contents of the watched variable change, program execution stops and control is returned to the debugger.
The Silent option will not output modified variables when a watchpoint is encountered; the output simply reports that the program has stopped because of a watchpoint. Turning off the Silent option allows the debugger to output the modified variable, the location of the change, and the old and new values of the watched variable.
The Ignore option allows the debugger to disregard a watched variable. In other words, when the given watchpoint is encountered, it will not be reported and the program will continue without interruption. Turning off the Ignore option allows the debugger to recognize and report any occurrence of the given watchpoint.
A watchpoint counter is associated with each watchpoint. When the watchpoint is created, the counter is set to zero; each time the watchpoint is incurred, the counter is incremented by one. When a program is reloaded, all counters are set to zero.
The Skip option assigns a watchpoint skip counter to the given variable, which is set to the value you specify. As a result, the watchpoint will be skipped the specified number of times. Once the watchpoint skip counter is set, it remains in effect until the value decreases (resets) to zero.
An action-list is one or more debugger commands separated by a semicolon, which may specify that program execution is to continue. Any specified action-list is executed when a watchpoint is incurred.
Note: It is not necessary to enclose the action list for the Watch dialog in square brackets (as is necessary for the command syntax).
A conditional expression may be used to qualify the watchpoint; it must be the last option on the command line. When a watchpoint with the If option is set, the executing program will be suspended and the debugger will be activated whenever the watched variable is changed. The IF condition is then evaluated. The evaluation always takes place in the environment and language of the program statement. If the IF condition is false, program execution continues and the watchpoint is never reported. If the IF condition is true, the debugger incurs a watchpoint as usual.
A watchpoint is incurred when a watched variable has changed, the skip counter is either zero or not specified, and the Ignore option is not specified. When a watchpoint is encountered, the following occurs:
In the following example, a watchpoint is set on variable n with an action-list to continue program execution. The value of n is input from the user.
CodeWatch> WATCH n /ACTION [C]
CodeWatch> CONTINUE
Input maximum prime boundary: 10
Program Stopped due to a Watchpoint
Watched variable N modified about line PRIMES\118
New Value: 10 {fixed binary (31)}
Break at PRIME\119Displays either the current execution point or the location of a specified statement.
WHERE [statement-id]
where:
| statement-id | Is a statement label or a source line number |
The WHERE command prints a location as the name of a routine followed by a statement label.
If the statement identifier is a statement label, the name of the routine containing the label and the source line number of the label are printed. If the statement identifier is a source line number, the name of the routine is printed. If the statement identifier argument is omitted, the name of the routine and the line number of the current execution point are printed.
In the following example, the next executable statement is located and the location is displayed.
CodeWatch> WHERE 108 Line 108 is not an executable statement ... WHERE using statement PRIMES\112 instead. PRIMES\112
In this example, the current execution point is displayed.
CodeWatch> WHERE Current execution point is PRIMES.READ_INPUT\%ENTRY
Invokes the host operating system command interpreter to perform a specified command. This command is available only on UNIX systems.
! command
(Press <Return> to continue)The ! command invokes the command interpreter to read the remainder of the line following the ! command. Refer to your UNIX documentation for information on UNIX commands.
The ! command followed by the UNIX sh command pushes to a new command interpreter. To return to the debugger, type <Ctrl D> or exit.
In this example, the UNIX pwd command is invoked, which lists the current working directory.
CodeWatch> !pwd /usr/hicks/pllprogs
Copyright © 2009 Micro Focus (IP) Ltd. All rights reserved.