Source Window
-
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.
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.
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:
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:
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
-
Copyright © 2001
by SAS Institute Inc., Cary, NC, USA. All rights reserved.