Chapter Contents

Previous

Next
Command Directory

list

Output a Source Line Listing in Line Mode

Move to a Source Line in Full-Screen Mode

ABBREVIATION
l{ist}

FORMATS
Format 1: list
Format 2: list LINENO[:+INTEGER]
Format 3: list +INTEGER[:+INTEGER]
Format 4: list -INTEGER[:[-]INTEGER]
Format 5: list -INTEGER[:+INTEGER]
Format 6: list [FUNCTION-NAME | (SECTION-NAME)] *
Format 7: list [FUNCTION-NAME | (SECTION-NAME)] LINENO[:LINENO]

DESCRIPTION
The list command lists source lines in a program executing under the debugger.

Format 1: In full-screen mode, this format of the list command can be used to return the debugger to the current line in the command scope. In full-screen mode, source code is displayed in the Source window and the current line is highlighted. The Status window displays the command scope as described in Using the Status Window.

In line mode, issuing the list command with no arguments displays the current line in the command scope.

On entry to a function, the current line is the function header line. (Part 2, "Configuring and Using the Debugger," discusses how the debugger finds the source file or files under the different operating systems.)

Format 2: In full-screen mode, the optional :+INTEGER is meaningless; the number of lines displayed in the Source window is determined by the Source window height. However, this format can be used to move to a specific line in the module that is currently displayed in the Source window; although, it is much easier to move to a line by specifying the module and line number in the Module: and Line: fields of the Source window. See Source Window for information about the Module: and Line: fields.

In line mode, this format lists the source line, specified by LINENO, and as many lines after it as you specify in the INTEGER argument. LINENO is a source line number (an integer constant). INTEGER is an integer constant that indicates a number of lines.

Formats 3, 4, and 5: These formats are known as the relative formats. In full-screen mode, list +INTEGER scrolls the Source window down and list - INTEGER scrolls the Source window up the number of lines specified by the INTEGER argument. As explained in format 2, the optional :+INTEGER argument is ignored.

In line mode, each time a range of lines is displayed (a single line can also be thought of as a range of lines), the debugger remembers two lines: LS is the start of the range, and LE is the end of the range. Stopping at a new location resets both LS and LE to the line number of the new location. The relative formats then function as shown in Results of Using the list Command Relative Formats.

Results of Using the list Command Relative Formats
Command Result
list +N1 (table note 1) displays LE through LE+N1
list +N1:+N2
displays LE +N1 through LE+N2
list -N
displays LS-N1 through LS
list -N1:-N2
displays LS-N1 through LS-N2
list -N1:-N2
displays LS-N1 through LS-N2
list -N1:+N2
displays LS-N1 through LE+N2

TABLE NOTE 1:   N1 and N2 are INTEGER arguments. [arrow]

The first time you issue one of the relative formats of the list command from a location where you are stopped, both LS and LE are equal to your current line number. However, LS and LE can be incremented or decremented as a result of issuing a list command. Subsequent list commands result in a range of lines being displayed based on the current value of LS and LE.

Format 6: In line mode, this format lists all lines in the source file or, optionally, all lines in a named section or function. SECTION-NAME is a section name for your program as specified with the sname compiler option or the default. FUNCTION-NAME is the name of a function. You can specify any function name or section name in the calling sequence.

In full-screen mode, this format can be used to move to the first line in the section or function specified by the SECTION-NAME or FUNCTION-NAME argument.

Format 7: In line mode, this format lists the source line in the section or function indicated by the LINENO argument. To list several lines, specify the line number of the first line that you want to list, a colon, and the line number of the last line that you want to list. You can specify any function name or section name in the calling sequence.

In full-screen mode, format 7 can be used to move to the line number, specified by the LINENO argument, in the section or function specified by the SECTION-NAME or FUNCTION-NAME argument.

For both line mode and full-screen mode, the section or function that is specified in formats 6 and 7 must be in the calling sequence.

The previous description of the list command during a line mode session assumes that the debugger is running with auto list set. (You can check the setting with the query command; auto list is the default.) For specialized debugging, you can set auto nolist. In this situation, you should either specify the section or function name as described for formats 6 and 7, or use the list command without arguments to orient the debugger before using any of the formats that require an INTEGER argument.

EXAMPLES
Types of Objects for the monitor Command provides examples of formats 3, 4, and 5. The following are line mode examples of some of the other formats:

list
lists the current source line, which is where execution was interrupted last.

list func1 *
lists all the source lines in the func1 function.

list (comp23) 200:220
lists source lines 200 through 220 of the comp23 compilation.

SYSTEM DEPENDENCIES
The location of the program source file is system-dependent. See Running the Debugger under TSO; Running the Debugger under OS/390 Batch; Running the Debugger under CMS; Using the Debugger from a Remote System; and Using the Debugger in a Cross-Development Environment for information about source file locations under different operating systems.

COMMAND CAN BE ISSUED FROM

PROFILE no
configuration file no
Source window prefix none

SCOPE
The list command uses command scope to supply default function names and section names.

RETURN CODES SET
Successful: number of last line listed
Unsuccessful: 0


Chapter Contents

Previous

Next

Top of Page

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