Chapter Contents

Previous

Next
Window Directory

Source Window

Source Window

[IMAGE]

DESCRIPTION
The Source window displays source code. It is one of the four primary windows. The other primary windows are Status, Log, and Command. By default, the Source window is displayed below the Status window and above the Log window. Like all the primary windows, the Source window is always open, even when it is obscured by an overlying window.

Source filename The top border of the Source window, which is always present, contains the name of the source file. The format of the source filename is operating-environment specific. The Source window that is shown in Source Window was captured under CMS. If you are running under TSO, your source filenames follow TSO file-naming conventions.

Information displayed in the Source window The first line of the Source window contains the following fields:

Module:
identifies the compilation that is displayed in the Source window. Large programs can be broken down into several modules that are compiled separately to facilitate the debugging of manageably sized pieces of code. You can use the sname compiler option to specify a section name that is used as the module name.

Line:
displays the line number of the first line of source code that is displayed in the visible portion of the Source window text area. The line number changes as you scroll through your source code.

The remaining portion of the Source window contains two unprotected areas that are used to view your source code and issue prefix commands.

line number and prefix area
is displayed on the left side of the window. This area displays line numbers that correspond to the line numbers from your source code file. You can use this area to type and display prefix-area commands. For example, in the Source window that is shown in Source Window, one B (break) prefix command is displayed on line 66.

text area
is located to the right of the line numbers. The text area is used to display source code from the source file that is identified in the top border of the window.

Run scope The highlighted line in the text area shows where your program has stopped. This location in your code determines the run scope, which is displayed in the Status window. For example, in the display that is shown in Source Window, line 63 is highlighted. This line is located in the READIN function, as indicated by the run scope field that is in the Source window.

Scrolling through the Source window The window scroll command is used to scroll through the Source window. In addition to the PF19, PF20, PF22, and PF23 keys that are used to scroll through most windows, there are two additional PF keys that are dedicated to scrolling in the Source window. By default, PF7 is assigned the window scroll source up command and PF8 is assigned the window scroll source down command.

In order to use the PF19, PF20, PF22, or PF23 keys to scroll in the Source window, you must first move the cursor into the Source window. The PF7 and PF8 keys can be used to scroll the Source window when the cursor is located in any window.

When the Source window is scrolled vertically, both the line number and text area are scrolled. However, when the window is scrolled horizontally, only the text area is scrolled.

Jumping to a line The Module: and Line: fields can be used to jump directly to a specific location in your source code. This makes it possible to avoid scrolling over a large number of lines to view source code that is located far from your current position. To jump directly to a specific location in your code, type the module name and line number following the appropriate prompts on the first line of the window and press ENTER. If either the module name or line number is invalid, a Popup window is displayed that enables you to correct your mistake.

Amount of code displayed in the Source window Two factors affect the amount of code that is displayed in the Source window: the visible portion of the window determines how much code is shown at any one time, and the amount of memory that is allocated for source buffers determines the total size of the window (visible plus scrollable portions of the window).

The minimum width of the Source window is 32 columns and the maximum is the width of your terminal; however, the text area that is contained within the window is considerably wider. The text area is always 252 characters wide; only a portion of the text area is visible at one time.

Source buffers are used to hold the information that is displayed in the Source window text area. You can use the window memory command in your configuration file to control the amount of memory that is used for source buffers. Note that the amount of memory that is allocated for window buffers cannot be changed during a session. Increasing source buffer size increases the amount of source code that is held in memory, which, in turn, speeds up display of source code in the Source window. See window for more information about the window command.

Context information in the source text area The debugger displays lines before and after the highlighted line so that the line is displayed in context. The debugger tries to minimize the vertical movement of the source code. Either the window context source command or the Config window can be used to control the number of lines of context information that are shown around the highlighted line.

The window context source command also enables you to specify how many lines in your source code can be jumped without centering the highlighted line in the text area. If the next line to be executed is at least as many lines as you have specified above the top or past the bottom of the window, the next line will be centered when it is highlighted. The window context source command is explained in window.

The Border: and Jump: fields in the Config window can also be used to control the Source window context. See Config Window for details.

Prefix-area commands Commands that can be issued from the prefix area of the line number field are listed in Prefix-Area Commands. These commands can be typed only between the lines that contain the opening and closing braces of a function. Only one command can be typed at any time on a line, though there can be more than one command in effect for that line.

Prefix-Area Commands
Prefix-Area Command Command Name Action
b
break
break on this line
d
disable
disable the request in this line
e
enable
enable the request in this line
g
goto and resume go to (resume execution at) this line
q
query
display all requests that apply to this line
r
runto
run to this line: install a temporary breakpoint and continue execution
t
trace
trace this line

If you enter an invalid prefix-area command, a window appears that enables you to correct the invalid input. Any attempt to issue a valid prefix-area command outside the opening and closing braces of a function causes the debugger to display an error message in a Message window.

Detailed reference information for each of the prefix-area commands is provided in Command Directory.

Enabling and disabling breakpoints and action requests You can use the e (enable) and d (disable) prefix-area commands to enable and disable breakpoint and action requests, provided that only one request is assigned to that line.

The debugger's request system keeps track of your breakpoint and action requests by using a request number. The number is assigned when the request is made. However, the Source window is line-number oriented; therefore, the e and d prefix-area commands can be used only when exactly one request applies specifically to that line. The examples that follow illustrate this.

Suppose that you have issued the following commands to request breakpoints:

break main 24
assigns a breakpoint to line 24 in the main function.

break main 20:30
assigns breakpoints to lines 20 through 30 in the main function.

break main *
assigns breakpoints to every line in the main function.

Each of these commands applies to line 24, but only the first applies specifically to that line. Hence, the debugger will successfully process an e or d command for main 24.

Note:    The query command can be used to display requests by request number. A disabled request is indicated by an asterisk (*) after the request number.  [cautionend]

For the next example, assume that smain is the section name of the compilation that contains main. Issue the following commands:

break main 23
assigns a breakpoint to line 23 of the main function.

on main 23 print x
uses the on command to assign a print command to line 23 in the main function.

trace (smain) 23
assigns a trace command to line 23 of the smain compilation.

All three requests apply specifically to line 23. Therefore, the debugger will not process any e or d commands in line 23; instead, a suitable message will be issued. In this situation you can use the drop, disable, and enable commands with the query command from the Command window to modify your breakpoint and action requests for line 23.

Specifying an entry or return suffix Except for the g (goto) command, any of the prefix-area commands can take an e or r suffix. The e suffix specifies that the command applies to the entry hook of the function within whose scope the command is issued. Conversely, the r suffix specifies that the command applies to the return hook of the function. For example, the following prefix-area commands can be specified:
be Break on entry to this function.
rr Run to the return hook of this function.
dr Disable the request that applies to the return hook of this function.

Visual indication of break, ignore, on, and trace commands The debugger visually indicates the presence of break, ignore, on, and trace commands that are in effect for requests that apply to the following:

Indication consists of one or more of the following characters that appear in the prefix area:
B break
I ignore
O on
T trace

However, no visual indication is given for commands on function entry, return, or call hooks or commands that are specified with the * (all line hooks) parameter.

Input in multiple areas of the Source window If input is specified in more than one area of the Source window, the data is processed in the following order: first the prefix-area commands, then the module-name change, and finally the line-number change.

Extended name support The symbol tables that are used by the debugger to determine the function that was operated on have a 255-character limit. If a module has been compiled with the extname compiler option, the debugger attempts to use the extended name. When a prefix-area command is used to install a request, the debugger temporarily sets the auto extname option during the request installation process to match the setting that was used when the module was compiled. For example, if the module was compiled with the auto extname option in effect, a breakpoint that was installed by a b in the prefix area uses extended names. When the request is installed, the setting of the auto extname option is restored to its previous setting. See auto for additional information.

ADDITIONAL DISCUSSION
Using the Source Window

SEE ALSO


Chapter Contents

Previous

Next

Top of Page

Copyright © 2001 by SAS Institute Inc., Cary, NC, USA. All rights reserved.