 |
previous next top contents index framed top this page unframed
6.1. File Menu
The File menu consists of commands that affect the entire GUI
session, and of commands that deal with opening and closing
files and switching among buffers.
6.1.1. File->Edit buffer...
Edit a buffer. The buffer can be a new buffer or an existing buffer
that may or may not be in a window.
Opens the Edit Buffer window, which contains the following controls:
Each buffer name may be shown in the list with one or more of the letters D, S, and A, meaning that the buffer is dirty (has unsaved changes), has been saved in the current edit session, or is in an anchored window (one that the editor will not move around automatically), respectively. This status information is just for your edification and does not affect your ability to select any of the buffers.
Note: If the selected buffer is already in a window, it stays in that window; i.e., the window location controls are ignored.
Opens the Edit File window, which is a standard Motif file selection widget with some additional controls. The controls are as follows:
Note: You can ignore the Filter, Directories, and Files gadgets and just type a file name in the Selection text field.
Note: If the selected file is already in a buffer, the debugger asks whether you want to use that buffer. If you say No, you will probably be prompted for a new buffer name because all buffer names must be unique; you may choose any name that is not the name of some other buffer. If the selected file is already in a visible buffer and you agree to use that buffer, the New window location control is ignored.
Figure 6–4. Write buffer ...? Dialog Box
 |
If Use for all current and future buffers is checked, the specified front end becomes the default.
The foreign editor loads the file that is in the current buffer. An error message appears if the current buffer is not associated with a file (e.g., CMDLOG).
If the current buffer has unsaved changes, it is not automatically saved before invoking the other editor. Once the other editor is started, changes it makes are not automatically picked up by MAINEDIT. Therefore, if you make changes, you should do so with only one editor or the other, or some changes will be lost.
The remoteCmdLinePrefixNoNode parameter in the $MAINDEBUG group (used for remote debugging, as described in Section 4.37 of the MAINDEBUG User's Guide) is also used as the prefix for the name of the program invoked by the File->Invoke foreign editor menu item. For example, if this variable specifies an xterm window (the default on UNIX), the foreign editor is run in an xterm window.
Note: If this command seems to have no effect, it could be because
xterm is not accessible.
6.1.6. File->Kill buffers...
Opens the Kill Buffers window, which contains the following
control:
When a buffer is killed, the editor forgets its contents.
If the buffer had unsaved changes, the editor asks whether to save.
6.1.7. File->Kill windows...
Opens the Kill Windows window, which contains the following
control:
This command removes the window with the specified buffer from the
display, but does not kill the buffer itself, so the editor has not
lost any changes you have made.
You can bring the buffer back into a window using the
Edit Buffer dialog.
6.1.8. File->Global options...
Opens the Global Options window, which controls parameters that apply to all buffers:
Note: The debugger puts buffers into readonly mode to guard against inadvertent changes by the user that would put the source text out of sync with the object MODULE. Turn off readonly mode if you want to alter the contents of a buffer.
Opens the Local Options window, which controls parameters that apply to the indicated buffer:
Note: The margins can also be changed by explicit editor scrolling commands or by moving the cursor if Automatic Horizontal Scroll is in effect.
Note: To open the Local Options window for the buffer in a
particular window (not necessarily the current window), click the
Custom (usually the rightmost)
mouse button anywhere on the window's status line.
6.1.10. File->Resume program
Resume any program that was invoked from the debugger or
editor but has been suspended.
If there is no such program,
beeps and displays Nothing to escape to
on the message line.
6.1.11. File->Exit
Leave MAINSAIL and return to the program (e.g., shell) from which
MAINSAIL was invoked.
MAINSAIL asks for confirmation.
If you want to abort the current MAINSAIL program but keep running
MAINSAIL, choose Execution->Abort user program instead.
6.2. Edit Menu
The Edit menu consists of commands for editing text.
Text-editing facilities that do not appear on the Edit menu
are described in Section 3.8.5.
6.2.1. Edit->Undo
Undoes the previous change to the current buffer (not available in
CMDLOG).
Usually, a series of keystrokes that modify a line at the same point
count as a
single change.
Successive invocations of Undo undo progressively earlier changes
until the limit is reached on the number of changes the editor
remembers (the limit is fairly high).
6.2.2. Edit->Redo
Redo an undone change.
Once a change has been undone,
it can be redone (put back)
until some command other than Undo/Redo is issued.
6.2.3. Edit->Cut
Copy the current selection to the paste buffer (an invisible place
where text is stored temporarily), then delete it.
Beeps and says No selection on the message line if there is no
selection or if the cursor is located outside the selection.
Move text from one place to another in a file by cutting then pasting
it.
6.2.4. Edit->Copy
Copy the current selection to the paste buffer, but do not delete
the selected text.
You can then paste the copied text elsewhere in your buffer to have
two copies of the same text in the file,
or paste it in another buffer to copy text from one file to another.
6.2.5. Edit->Paste
Insert the contents of the paste buffer at the cursor, or if the
cursor is located in the selection,
replace the selection with the contents of the paste buffer.
The contents of the paste buffer are unchanged.
6.2.6. Edit->Delete
Delete the text of the current selection, but do not copy it to the
paste buffer.
Beeps and says No selection on the message line if there is no
selection or if the cursor is located outside the selection.
You can still get the deleted text back using Edit->Undo.
If the cursor is located inside the selection, you can also delete the
text of the selection with the BACKSPACE or DELETE key.
6.2.7. Edit->Insert pageMark
Insert a page mark before the current line.
A page mark is represented in a file as an eop (form feed) character. In an editor window, it is represented by a special line beginning and ending with PAGE.
To delete a page mark, select some text on the page mark line,
and choose Edit->Delete,
or use the DELETE or BACKSPACE key.
6.2.8. Edit->Go to->Previous page
Moves the cursor to the beginning of the previous page (the first
line after the page mark) in the
current buffer.
6.2.9. Edit->Go to->Next page
Moves the cursor to the beginning of the next page in the current
buffer.
6.2.10. Edit->Go to->Page.line...
Opens the Go to Page and Line window, which contains the following control:
Note: A page and line can be given along with the keyboard shortcut for this command; e.g., META 5.3G goes to page 5, line 3 in the current buffer (depress the META key while typing the entire string 5.3G).
Opens the Go to Absolute Line window, which contains the following control:
Note: A line number can be given along with the keyboard shortcut for this command; e.g., META 5$G goes to line 5 in the current buffer (depress the META key while typing the entire string 5$G).
Opens the Search dialog window, which contains the following controls:
Click on the PatternHelp button to display the Pattern Help window, which contains a description of the meanings of various characters within patterns (see Figure 6–17).
6.3.1. Subcommands->Execute Subcommand...
This brings up the Execute Subcommand window, which allows you to
type an arbitrary MAINEX subcommand.
Any informational or error messages from the subcommands
go into CMDLOG.
The parameters and their corresponding MAINEX subcommands are:
The output from those subcommands that periodically display information
is written with direct terminal I/O, i.e., goes to the standard output
of the MAINSAIL process (usually showing up in the terminal emulator
window from which MAINSAIL was invoked).
6.3.4. Subcommands->Searchpaths...
Display the Searchpaths window,
which includes a list of the searchpaths
currently in effect for this MAINSAIL process.
Searchpaths can be defined outside the GUI with the MAINEX
SEARCHPATH subcommand.
You can add to the list by typing a searchpath in the text widget and clicking Set Searchpath, or remove searchpaths by selecting searchpaths in the list and clicking Delete Selected Searchpaths.
You can add new logical names by typing them into the text widget and clicking Add Logical File Name, or remove logical names by selecting them and clicking Delete Selected Logical File Names.
You can add new aliases by typing them into the text widget and clicking Define Alias, or remove aliases by selecting them and clicking Delete Selected Aliases.
You can add new associations by typing them into the text widget and clicking Make Association, or remove associations by selecting them and clicking Delete Selected Associations.
You can add new global symbols by typing them into the text widget and clicking Define Global Symbol, or remove symbols by selecting them and clicking Delete Selected Global Symbols.
Each window contains three lists: a list of open libraries, a list of file name associations, and a list of library name associations. You can add to any list by typing in the text widget and clicking the appropriate button at the bottom of the window. You can remove entries from any list by selecting them and clicking Delete Selected Entries.
You can use the radio buttons to control whether MAINSAIL searches open libraries first or individual MODULE files first when opening a MODULE.
Figure 6–29. Open Module Window
 |
Enter the name of the MODULE you want to open in the dialog box.
Opening a MODULE makes it the current MODULE of the debugger command context (with no current PROCEDURE). The bound data section, if it has been created, becomes the current data section. Typically you open a MODULE when you want to set a breakpoint in it, or examine values in its bound data section.
Opening a MODULE also creates a buffer containing the source file
for the MODULE if such a buffer does not already exist. This buffer
is displayed in a new window unless the buffer is already
in a window.
6.4.2. Access->Dispose module...
Figure 6–30. Dispose Module Window
 |
Enter the name of the MODULE you want to dispose in the dialog box.
This command disposes a MODULE's objmod (the executable code) and
its intmod (support information about the MODULE generated by the
compiler) if they are in memory. If in a given MAINSAIL session you
recompile a MODULE that you have been using, and then want to rerun
your program using the newly compiled objmod and intmod, you must
use this command. If you do not, the old version of the objmod and
intmod are used if they are in memory. Compiling a MODULE does not
cause the MAINSAIL runtime system to discard an existing objmod or
intmod in memory; only this command does.
6.4.3. Access->Open module instance...
Figure 6–31. Open Module Instance Window
 |
In the dialog box, enter a (LONG) INTEGER, (LONG) BITS, ADDRESS, or POINTER expression whose value is the ADDRESS of a data section.
This command opens the MODULE for the referenced data section, and makes the referenced data section the current data section.
You typically open a MODULE instance when you want to examine the
value of some of the variables in the referenced data section.
6.4.4. Access->Open coroutine...
Figure 6–32. Open Coroutine Window
 |
In the dialog box, enter the name of the coroutine you want to open.
Changes the debugger context to the indicated coroutine. The current
PROCEDURE is set to the first debuggable
PROCEDURE in the call chain
starting at the resume point of the coroutine. Only the current
coroutine's stack is accessible to the debugger
commands that move up and
down the stack.
6.4.5. Access->Open intlib...
Figure 6–33. Open Intlib Window
 |
In the dialog box, enter the name of the intmod library file you want to open.
Opens the indicated file as an intmod library and puts it at the
head of the list of intmod libraries searched by the debugger. This
makes its intmods available to the debugger.
6.4.6. Access->Open modlib...
Figure 6–34. Open Modlib Window
 |
In the dialog box, enter the name of the objmod library file you want to open.
Opens the indicated file as an objmod library, making its objmods
available for execution.
6.5. Breaks Menu
The Breaks menu includes commands to set, remove, and examine
breakpoints in your program.
6.5.1. Changing Breakpoint Definitions
The definition of a breakpoint can specify:
Any aspect of the breakpoint's definition can be changed in the Break Points window, which is opened by selecting Break->Show breakpoints... (see Section 6.5.6). This window shows the definition of one breakpoint at a time; the Prev and Next buttons move among breakpoints in the order they were set.
A quick way to see the definition of a particular breakpoint is to click the Custom mouse button anywhere in the breakpoint box that encloses the statement associated with the breakpoint. This action opens the Breakpoints window showing the definition of the indicated breakpoint.
Note: You can set a breakpoint this way only in the current MODULE. To change the current MODULE, move up or down the call stack or open a MODULE using Access->Open module....
Figure 6–36. After Moving the Cursor to the Start of j .+ 2 and Choosing Breaks->Set breakpoint at cursor
 |
Note: You can set a breakpoint only in the current MODULE. To change the current MODULE, move up or down the call stack or open a MODULE or MODULE instance.
Figure 6–37. After Moving the Cursor to the Start of j .+ 2 and Choosing Breaks->Set temp breakpoint at cursor
 |
Note: You can remove a breakpoint only from the current MODULE. To
change the current MODULE, move up or down the call stack or open a
MODULE or MODULE instance.
6.5.5. Breaks->Remove all breakpoints
Removes all permanent and temporary breakpoints.
6.5.6. Breaks->Show breakpoints...
Opens the Breakpoints window, showing the definition of the first
breakpoint you defined that is still in effect. This window shows
the definition of one breakpoint at a time; the Prev and Next
buttons can be used to move among definitions.
You can use the Breakpoints window to examine or to change the definition of any breakpoint and to define new breakpoints. To define a new breakpoint, use the Next button to move past the definitions of all breakpoints to an empty definition. Then fill in the Module field and either the Procedure field, the ModuleDspl field, or both Procedure and ModuleDspl fields.
The Breakpoints window contains the following controls:
Note: Do not confuse the “break count”, which is set as an argument to a Continue, Skip, or Jump command with the “count break”, which causes a break when the debuggable PROCEDURE count reaches a specified value (see Breaks->Set count break).
Note: A quick way to open the Breakpoints window showing the display of a particular breakpoint is to click the Custom (usually the rightmost) mouse button anywhere in the breakpoint box that surrounds the statement.
The debugger maintains a “debuggable PROCEDURE entry count”, which is the number of entries to PROCEDUREs in debuggable MODULEs since program execution began. When the debuggable PROCEDURE count reaches the “count break” value, a break occurs.
The debuggable PROCEDURE entry count is displayed in the lower left corner of the main window, and can also be examined as the system variable $count.
Figure 6–39. Count Break Window
 |
The Count Break window contains the following controls:
The MODULE, PROCEDURE, and code displacement of the command context are shown towards the bottom left of the main window whenever there is a command context. Sometimes the command context consists only of a MODULE without a PROCEDURE or code displacement, in which case only the MODULE name appears.
6.6.1. MoveTo->Caller
Moves to the caller of the current PROCEDURE.
Changes the current debugger context to the closest debuggable calling
PROCEDURE. Opens a new window (and creates a new buffer) if
necessary. The cursor is moved to the statement from which the
PROCEDURE was called.
6.6.2. MoveTo->Callee
Moves to the callee of the current PROCEDURE.
Changes the current context to the closest debuggable callee
PROCEDURE. Opens a new window (and creates a new buffer) if
necessary. The cursor is moved to the current statement within the
called PROCEDURE.
6.6.3. MoveTo->Break context
Moves to the current break context (the current execution point).
Changes the current context to the debuggable PROCEDURE at which
execution was interrupted. Opens a new window (and creates a new
buffer) if necessary. The cursor is moved to the interrupted
statement.
6.6.4. MoveTo->Command context
Moves to the current debugger command context.
This is different from the current break context if, e.g., the
MoveTo->Caller command has been issued.
In this case, the command context is considered to be that of the
caller, while the break context continues to be the point at
which execution was interrupted.
6.6.5. MoveTo->Exception
Moves to the statement at which an exception occurred.
This command is valid only if an exception is active. In the case of
nested exceptions, this command can be used to show successively
nested exceptions.
6.6.6. MoveTo->Handler
Moves to the handler for the exception that is the current context.
This command undoes the most recent MoveTo->Exception command.
6.6.7. MoveTo->Code dspl...
Displays the Move to Code Dspl window.
In the text widget, you can enter a code displacement.
Determine the statement in the current MODULE that contains the
indicated code displacement, and set the current context to the
PROCEDURE that contains that statement. Displacements are given in
iUnits (which are just bytes: see Section 2.5 of the MAINDEBUG User's Guide).
This command is infrequently used since the debugger automatically positions to source code locations when useful; e.g., when a breakpoint occurs, the debugger positions to the statement at which the break occurred. However, it is sometimes useful if you want to start your debug session by setting a breakpoint at a particular place (other than the start of a PROCEDURE, for which you can use the PROCEDURE name). Some MAINSAIL error messages report code displacements, so if you have recorded such an error message, you may already know an appropriate code displacement. Directly specifying the offset of a breakpoint allows you to avoid searching through the source file for the right place to set the breakpoint.
6.7.1. Show->Value...
Display the value of one or more expressions in CMDLOG.
To see the value in a data browser window instead,
create a data browser (if there is not one already)
using Show->Data browser; see Chapter 4.
If there is a current selection, it is treated as the expression whose value is to be shown. The value is written to CMDLOG immediately, and no dialog box is popped up.
If there is no current selection, you can specify multiple expressions (separated by commas) in the Show Values window that is displayed. Long expressions may occupy multiple lines.
Note: Expression evaluation occurs in the current command context.
The expression must
be legal at the current context. If necessary, move up or down the
call stack to change the command
context before evaluating an expression;
e.g., if you want to examine a local variable, you must move to the
PROCEDURE that contains the local variable before evaluating it.
6.7.2. Show->Object...
Display the contents of one or more dynamic objects in CMDLOG.
To see the objects in a data browser window instead,
create a data browser (if there is not one already)
using Show->Data browser; see Chapter 4.
If there is a current selection, it is treated as the POINTER expression (or ADDRESS, LONG INTEGER, or LONG BITS expression that is converted to a POINTER) that points to the object to be shown. The information is written to CMDLOG immediately, and no dialog box is popped up.
If there is no current selection, you can specify multiple POINTER expressions (separated by commas) in the Show Objects window that is displayed. Long expressions may occupy multiple lines.
If there is a current selection, it is treated as the identifier, and no dialog box is popped up.
If there is no current selection, the Show Declaration Original Source window pops up. You can type the identifier in the text widget.
The identifier is evaluated in the current “compiler context”. The compiler context's MODULE context is the same as the MODULE part of the command context. The PROCEDURE context (if any) is the PROCEDURE where the debugger cursor is located; there is no PROCEDURE context if the cursor is outside any PROCEDURE for the current MODULE.
This command finds the declaration even if it occurred in an intmod from which the current MODULE restored. Of course, the intmod must be in sync with the source file from which the intmod was created, because the debugger must display the source file in order to show the declaration.
If the identifier is a PROCEDURE name, only the PROCEDURE header is shown, not the body.
If there is a current selection, it is treated as an identifier (or list of identifiers separated by commas), and no dialog box is popped up.
If there is no current selection, the Show Declaration Synthesized Source window pops up. You can type one or more identifiers, separated by commas, into the text widget.
As with Show->Declaration->Original source..., the identifiers are evaluated in the compiler context.
A data browser is a self-contained window that supports browsing of data structures. It is generally far more convenient to peruse data structures with a browser than with the line- or display-oriented commands. Data browsers are described in more detail in Chapter 4.
Opens the Show Memory window, which lets you examine any memory location as any MAINSAIL data type. The window contains the following controls:
Boolean
Integer
Long Integer
Real
Long Real
Bits
Long Bits
String
Address
Charadr
Pointer
Text
Hex Dump
Blank Line (insert a blank line into the display)
Clear Display
Repeated clicks retrieve consecutive values in the specified direction. Values are written to the text widget at the top of the window.
Note: Evaluation of the ADDRESS expression occurs in the current context.
Opens the Options window, which contains the following controls that affect debugger options:
Note: The data browser is described in Chapter 4.
Note: The data browser is described in Chapter 4.
Also note: This mode is compatible with Display Local Variables. The same data browser pane shows both at the same time.
Note: These modes are described in Section 4.32 of the MAINDEBUG User's Guide. You can usually ignore this option.
Note: This option can also be set in the Watch Expr window. For more information about watch expressions, see Section 4.3.
6.8.1. Execution->Step over calls
Single-step execution of the debugged program,
stepping over called PROCEDUREs.
6.8.2. Execution->Step into calls
Single-step execution of the debugged program,
stepping into called PROCEDUREs.
6.8.3. Execution->Trace procs...
This command causes the name and arguments to each PROCEDURE to be
written to the specified trace file as each PROCEDURE is invoked.
The Trace Procs window comes up and asks for the trace file name.
If no name is given but you select OK,
the output goes to CMDLOG.
Continue execution from the indicated code displacement. This displacement must be within the current PROCEDURE, and has certain other restrictions as described in the MAINDEBUG manual.
Remote debugging is a feature you will probably need to use only under unusual circumstances; see Section 4.37 of the MAINDEBUG User's Guide for details.
The Remote Debug window contains two text fields:
If you specify a host, it must be the same platform as the current host. By default, the child process runs on the specified host, and the terminal emulator window also appears on that host's display.
If there is currently a local debugging session going on, an error message is issued on the message line. Otherwise, an xterm window (or other window that you have specified in your parameter file; see Section 4.37 of the MAINDEBUG User's Guide for details) for the remote MAINSAIL process is created, and MAINSAIL initializes itself. At this point execution pauses so that you may set breakpoints; issue Execution->Continue->From break to continue the remote MAINSAIL execution.
Debugging the remote MAINSAIL process is generally identical to debugging locally; all the facilities of the debugger are available, but they refer to events and data in the remote process instead of the local one.
The xterm window disappears when the remote process is finished
executing.
6.8.9. Execution->Local debug
This changes from remote execution to local execution.
If there is currently a remote debugging session going on, it
is terminated immediately.
6.8.10. Execution->Abort user program
Terminate the program invoked from the debugger
(by raising $abortProgramExcpt).
If you issue this command
when you are not running a program, an error message is printed on
the message line.
Otherwise, the program is terminated immediately.
6.8.11. Execution->Invoke module...
Displays the Invoke Module window, from which you can invoke any MAINSAIL MODULE. For example, you can start the execution of the program to be debugged or run a utility MODULE such as COMPIL.
The Invoke Module window contains the following controls:
Pops up the Compile Declarations window. You can enter declarations to be compiled by the debugger in the text widget.
Declarations and macro definitions are compiled in the current context. Directives such as SOURCEFILE or RESTOREFROM are also allowed. A PROCEDURE declaration is not allowed.
The declared identifiers can be used in debugger commands in any context. Try to choose names that will not conflict with program identifiers; e.g., use dbg as a prefix on all declared identifiers. Variables declared in this way are often called “debugger variables”.
Debugger variables are often useful, even though they can be used only in expressions and statements issued to the debugger. For example, an INTEGER could be declared and incremented by the commands portion of a breakpoint to count how many times the breakpoint has been encountered. To do this:
Statements are compiled in the current context, then executed immediately.
For example, you can invoke a
PROCEDURE foo with arguments a, b, and
c by
using foo(a,b,c) as the parameter.
Either select the indicated
text (if it already occurs in the source file) and paste it into the
text widget or type the text directly.
6.8.15. Execution->Execute commands...
Pops up the Execute Commands window, in which you can enter
character-based commands from line- and display-oriented debugger
interfaces.
The character-based debugger commands are executed immediately.
This command is rarely useful since more accessible ways are provided
for almost all the underlying debugger commands.
6.9. Command Buttons
The command buttons on the left side of the main window
allow you to issue the more frequently used commands
with a single mouse click. The command buttons are listed below in the
order in which they appear on the screen from top to bottom. Next to
each button is a short description of the command it performs; the
next line is the name of the corresponding menu item. For a
more detailed description of the command, refer to the description of
the corresponding menu item.
Motif-Based MAINSAIL Tools Reference Guide, Chapter 6
