Debugger CommandsThis section defines the debugger commands: APPS, ALIAS, BREAKPOINT, CALLS, DEBUG, DISPLAY, DOWN, DUMP, EVALUATE, GO, HELP, MEMORY, QUIT, RECORD, SCOPE, SET, STEP, SYMBOLS, TYPE , UP and WATCH.
Debugger command syntaxLike MicroStation commands, debugger commands may be entered with only the shortest string possible to uniquely identify it. For example, for the QUIT command, any of the following commands are acceptable: Q, QU, QUI and QUIT.
The format of the commands is as follows:
command/modifier arguments[,arguments..]
Commands and modifiers are keywords. For any keyword, you need to enter only enough characters to uniquely identify the keyword.
Modifiers are usually optional. A command may take more than one modifier.
The APPS command lists the currently loaded mdl applcations. It shows the most recently loaded mdl application first, and shows the current debug application with an asterisk next to its name.
The ALIAS command defines simple aliases for the debugger's command interface. When it starts processing a command line, the debugger first determines if the first token in the command line corresponds to an alias. If so, the debugger replaces the token with the alias string and repeats the process.
This substitution process is iterative but not recursive. The debugger continues this process until there are no matches, but a given alias can only be used once in the expansion of a given command line.
For example, consider how the debugger handles the command line next if next is aliased to s, and s is aliased to s/into. The debugger first substitutes s for next. Then it checks the aliases again and substitutes s/into for s. Then it checks the aliases again. This time, it does not use the definition of s because it has already been used on this command line.
The search for alias is case sensitive. Therefore, it is possible to alias s to one command and S to another command.
The syntax for the alias command is:
ALIAS <NAME> <SUBSTITUTION STRING>
The substitution string may appear with or without quotation marks. If quotation marks are used, they are not included as part of the alias definition. Quotation marks are required if the alias definition includes a semi-colon. Without the quotation marks, the semi-colon is interpreted as a statement terminator.
Use the /delete modifier to delete an alias. If the alias name is specified, then that alias is deleted. If the /all modifier is specified after /del, then all of the aliases are deleted. If /all is not specified and no name is specified, then the user is queried regarding each alias.
The following examples show ways to use variations of the ALIAS command:
The BREAKPOINT command lists or modifies break points. It accepts a series of code points separated by commas as arguments. A code point can be specified by a function name, a line number, or a period to refer to the current address. The line number may be preceded by a string to specify a filename. Following are the acceptable modifiers for the BREAKPOINT command:
The following examples show ways to use variations of the BREAKPOINT command:
The BREAKPOINT command may contain a statement block on the same line. The statement consists of a list of MDL debugger commands. The entire list is enclosed in curly braces. The statements are separated by semi-colons. The following example shows how the statement block can be used:
b displayElement {if (elP->ehdr.type != 3) {eval/str "type is"; elP->ehdr.type;go}}
When the breakpoint occurs, the MDL debugger evaluates the conditional
(elP->ehdr.type != 3). If it is true, then the debugger executes the following three debugger commands:eval/str "type is"
elP->ehdr.type
goOtherwise, it stops at the breakpoint.
The following breakpoint never stops. It just displays the type if it is not 3.
b displayElement {if (elP->ehdr.type!=3) {eval/str "type is"; elP->ehdr.type;go} else {go}}
The CALLS command determines the sequence of calls that caused the current function to be reached. The output of calls also reports the parameter values to each function. The stack trace also prefixes each line with a frame number. This frame number can be used as input to the SCOPE command.
This command uses the following modifier:
/<count>The DEBUG command sets the current debug task id. This allows you to set break points in more than one mdl application at a time. Use the APPS command to see the list of currently loaded mdl applications, and to determine the current debug application.
To use the DEBUG command to change the current debug task, enter:
in the MDL debugger window.
The DISPLAY command displays data in formats other than the format implied by the type of data. The MDL debugger also accepts EVALUATE as a synonym for DISPLAY.
The DISPLAY command supports modifiers for selecting data size, for selecting output radix, and for controlling how strings are displayed.
The modifiers /char, /short, /long and /double select data size. Without one of these modifiers, the debugger determines the data size based on the expression supplied as an argument. If one of these modifiers is used, it can be combined with a repeat count in the following format:
The modifiers /hex, /octal and /decimal specify how integer values and pointers should be displayed.
The modifier /str specifies that the debugger should display strings for fields that are of type array of characters or array of unsigned chars, and all fields that are of type pointer to char or pointer to unsigned char.
The modifier /wstr specifies that the debugger should display strings for fields that are strings of type MSWideChar. When the debugger encounters an array of type MSWideChar or a pointer to MSWideChar, it converts the MSWideChar strings to a
multi-byte string, and then displays the multi-byte string.The DOWN command selects the scope the debugger uses for evaluating expressions. It moves the context one step farther from the scope that contains the last execution point.
See "The UP command" and "The SCOPE command" for more information.
The DUMP command provides a formatted dump of a block of memory, giving both the ASCII and numeric representations of the data.
Use one of the following modifiers to specify the data size: /char, /short or /long. Also, a repeat count may be specified as an modifier. Both the count of bytes to dump and the data size are remembered from the previous dump command if they are not specified.
If an address is specified, it is used as the starting address for the dump. If no address is specified, the DUMP command starts with the first address following the previous dump.
The following examples show ways to use variations of the DUMP command:
The GO command tells MicroStation to resume program execution. It can also specify some temporary break points. It accepts a code point specification as arguments. This specification can be a line number, function name, or period for the current address.
The following examples show various ways to use the GO command:
The HELP command displays helpful information on the MDL debugger's commands.
The command uses the following modifiers: /alias, /breakpoint, /calls, /display,
/down, /go, /if, /memory, /quit, /record, /scope, /set, /step, /symbols, /type, /up and /watch.The following examples show various commands for which HELP information can be obtained:
The IF command evaluates an expression and conditionally executes the debugger commands that follow the conditional clause. The statements that follow the conditional clause must be enclosed in {curly braces}. The IF command may have an else clause.
The IF command is intended primarily for use with break points. See "The BREAKPOINT command" and "The IF command" for examples.
The MEMORY command displays the starting addresses of all blocks of memory currently allocated by the application. The list does not contain the addresses of freed blocks.
All blocks in the list were allocated with malloc, calloc or realloc. The block may have been allocated by the application calling these functions directly, or by the application calling other built-in functions that call the memory allocation functions.
The following modifier can be used:
/sizeIf the environment variable MS_DEBUGMDLHEAP is defined, then MicroStation remembers the size of every block of memory allocated with malloc, calloc or realloc by every MDL program. Therefore, when it displays the address of each block of memory it can also display the size. Use the /size modifier to tell MicroStation to display the sizes.
The QUIT command exits from the debugger and unloads the application. The debugger window is not closed, though it does become inactive. It can be minimized then to hide it from view.
The RECORD command causes MicroStation to start recording the debugger's input and output.
The following modifiers can be used:
/input, /output, /all, /append, /replace, /stop, /default/input specifies that only the input from the user should be recorded. /output specifies that only the debugger's output should be recorded. /all specifies that both the input and output should be recorded.
/append specifies that the information should be appended to the recording file.
/replace specifies that the recording file should be replaced if it currently exists./stop means stop recording.
/default means that current command should not start or stop record. The modifiers and file name are saved as default for the subsequent record commands.
After the modifiers, specify a file name in a quoted string.
The defaults are to append to the file mdldebug.log, recording both input and output.
The following examples show ways to use variations of the RECORD command:
The scope command lets the programmer set the scope to any scope in the stack trace, or to any source file in the application. The syntax for the scope command is:
scope <new frame number>
scope .
scope <source file name>To get the frame number, use the calls command. Frame number 0 always refers to the currently executing frame. As with the other debugger commands, the dot refers to the current execution point. Therefore, scope 0 and scope . are synonymous.
scope <source file name> sets the scope to a specific source file. After this command is executed, there is no function scope available. Only the file scope is available.
The UP and DOWN commands can be used to change the scope to the next or previous scope.
The SET command controls various aspects of the debugger's behavior.Use the SET CASE command to control whether the MDL debugger's C expression evaluation is case sensitive. set case on makes it case sensitive. set case off makes it case insensitive. By default, the debugger is not case sensitive.
Use the SET TAB command to control the tab stop intervals used by the debugger when displaying source code. By default, the debugger uses a tab stop interval of 8. The command set tab 1 sets the tab stop interval to 1, essentially turning off tab expansion.
The STEP command controls debugger activation. When used with one of the following modifiers, this command specifies when the debugger will be activated:
The SYMBOLS command lists the MDL application's symbols that can be used in debugger commands.
This command accepts a string used to restrict the list of symbols displayed as an argument. The following modifiers are used: /functions, /variables and /structures.
The following examples explain various ways the SYMBOLS command is used:
The TYPE command types the line following the last line typed. It accepts the argument <line numbers>. A line number can be provided as a number, a number preceded by a source filename, a dot to refer to the line corresponding to the current execution address, or a function name. If no line number is specified, the line following the last line printed is specified.
The following modifier can be used:
/<count>The following examples show ways to use variations of the TYPE command:
The UP command selects the scope the debugger uses for evaluating expressions. It moves the context 1 step closer to the scope that contains the last execution point.
See"The DOWN command" and "The SCOPE command" for more information.
The WATCH command invokes the MDL debugger when a location in memory is modified. This command is only supported in the DOS version.
On the PC, WATCH is implemented with the hardware debug registers. A maximum of 4 watch points exists. Because of restrictions for the hardware registers, WATCH can watch only one byte rather than the entire variable specified.
The argument for a watch instruction must be an expression that evaluates to a pointer type. If the program contains the declaration int i1;, &i1 is a valid argument. However, i1 is not since it evaluates to type integer. If the program contains the declaration int *pInteger;, pInteger and &pInteger are valid arguments. pInteger watches the address pInteger points to. &pInteger watches the address of the variable pInteger.
The following modifier is used with this command:
/<count>