Document revision date: 30 March 2001

The SEARCH command enables you to display any source lines that contain an occurrence of a specified string.

The syntax of the SEARCH command is as follows:

SEARCH[/qualifier[, ...]] [range] [string]

The range parameter can be a module name, a range of line numbers, or a combination of both. If you do not specify a module name, the debugger uses the current scope to find source lines, as with the TYPE command (see Section 6.3).

By default, the SEARCH command displays the source line that contains the first (next) occurrence of a string in a specified range (SEARCH/NEXT). The command SEARCH/ALL displays all source lines that contain an occurrence of a string in a specified range. For example, the following command line displays the source line that contains the first occurrence of the string pro in module SCREEN_IO:

DBG> SEARCH SCREEN_IO pro

The remaining examples use source lines from one COBOL module, in the current scope, to show various aspects of the SEARCH command.

The following command line displays all source lines within lines 40 to 50 that contain an occurrence of the string D:

DBG> SEARCH/ALL 40:50 D module COBOLTEST 40: 02 D2N COMP-2 VALUE -234560000000. 41: 02 D COMP-2 VALUE 222222.33. 42: 02 DN COMP-2 VALUE -222222.333333. 47: 02 DR0 COMP-2 VALUE 0.1. 48: 02 DR5 COMP-2 VALUE 0.000001. 49: 02 DR10 COMP-2 VALUE 0.00000000001. 50: 02 DR15 COMP-2 VALUE 0.0000000000000001. DBG>

After you have found an occurrence of a string in a particular module, you can enter the SEARCH command with no parameters to display the source line containing the next occurrence of the same string in the same module. This is similar to using the TYPE command without a parameter to display the next source line. For example:

DBG> SEARCH 42:50 D module COBOLTEST 42: 02 DN COMP-2 VALUE -222222.333333. DBG> SEARCH module COBOLTEST 47: 02 DR0 COMP-2 VALUE 0.1. DBG>

By default, the debugger searches for a string as specified and does not interpret the context surrounding an occurrence of the string (this is the behavior of SEARCH/STRING). If you want to locate an occurrence of a string that is an identifier in your program (for example, a variable name) and exclude other occurrences of the string, use the /IDENTIFIER qualifier. The command SEARCH/IDENTIFIER displays only those occurrences of the string that are bounded on either side by a character that cannot be part of an identifier in the current language.

The default qualifiers for the SEARCH command are /NEXT and /STRING. If you want to establish different default qualifiers, use the SET SEARCH command. For example, after the following command is executed, the SEARCH command behaves like SEARCH/IDENTIFIER:

DBG> SET SEARCH IDENTIFIER

Use the SHOW SEARCH command to display the default qualifiers currently in effect for the SEARCH command. For example:

DBG> SHOW SEARCH search settings: search for next occurrence, as an identifier DBG>

6.6 Controlling Source Display After Stepping and at Eventpoints

By default, the debugger displays the associated source line when a breakpoint, tracepoint, or watchpoint is triggered and upon the completion of a STEP command.

When you enter a STEP command, the debugger displays the source line at which execution is paused after the step. For example:

DBG> STEP stepped to MAIN\%LINE 16 16: RANGE := 500; DBG>

When a breakpoint or tracepoint is triggered, the debugger displays the source line at the breakpoint or tracepoint, respectively. For example:

DBG> SET BREAK SWAP DBG> GO . . . break at MAIN\SWAP 47: procedure SWAP(X,Y: in out INTEGER) is DBG>

When a watchpoint is triggered, the debugger displays the source line corresponding to the instruction that caused the watchpoint to be triggered.

The SET STEP [NO]SOURCE command enables you to control the display of source code after a step and at breakpoints, tracepoints, and watchpoints. SET STEP SOURCE, the default, enables source display. SET STEP NOSOURCE suppresses source display. For example:

DBG> SET STEP NOSOURCE DBG> STEP stepped to MAIN\%LINE 16 DBG> SET BREAK SWAP DBG> GO . . . break at MAIN\SWAP DBG>

You can selectively override the effect of a SET STEP SOURCE command or a SET STEP NOSOURCE command by using the qualifiers /SOURCE and /NOSOURCE with the STEP, SET BREAK, SET TRACE, and SET WATCH commands.

The STEP/SOURCE command overrides the effect of the SET STEP NOSOURCE command, but only for the duration of that STEP command (similarly, STEP/NOSOURCE overrides the effect of SET STEP SOURCE for the duration of that STEP command). For example:

DBG> SET STEP NOSOURCE DBG> STEP/SOURCE stepped to MAIN\%LINE 16 16: RANGE := 500; DBG>

The SET BREAK/SOURCE command overrides the effect of the SET STEP NOSOURCE command, but only for the breakpoint set with that SET BREAK command (similarly, SET BREAK/NOSOURCE overrides the effect of SET STEP SOURCE for the breakpoint set with that SET BREAK command). The same conventions apply to the SET TRACE and SET WATCH commands. For example:

DBG> SET STEP SOURCE DBG> SET BREAK/NOSOURCE SWAP DBG> GO . . . break at MAIN\SWAP DBG>

6.7 Setting Margins for Source Display

The SET MARGINS command enables you to specify the leftmost and rightmost source-line character positions at which to begin and end the display of a source line (respectively, the left and right margins). This is useful for controlling the display of source code when, for example, the code is deeply indented or long lines wrap at the right margin. In such cases, you can set the left margin to eliminate indented space in the source display, and you can decrease the right margin setting to truncate lines and prevent them from wrapping.

For example, the following command line sets the left margin to column 20 and the right margin to column 35.

DBG> SET MARGINS 20:35

Subsequently, only that portion of the source code that is between columns 20 and 35 is displayed when you enter commands that display source lines (for example, TYPE, SEARCH, STEP). Use the SHOW MARGINS command to identify the current margin settings for the display of source lines.

Note that the SET MARGINS command affects only the display of source lines. It does not affect the display of other debugger output (for example, output from an EXAMINE command).

The SET MARGINS command is useful mostly in line (noscreen) mode. In screen mode, the SET MARGINS command has no effect on the display of source lines in a source display, such as the predefined display SRC.

Screen mode is an enhancement to the command line interface of the OpenVMS debugger that enables you to simultaneously display separate groups of data about the debugging session, in a manner similar to that available with the Compaq DECwindows Motif for OpenVMS user interface (see Part 3). For example, you can display source code in one portion of the screen, register contents in a different portion, debugger output in another portion, and so on.

To invoke screen mode, press PF3 on the keypad (or enter the SET MODE SCREEN command). To return to line-oriented debugging, press PF1 PF3 (or enter the SET MODE NOSCREEN command).

Screen mode output is best displayed on VT-series terminals with higher numbers than VT52, and on workstations running VWS. The larger screen of workstations is particularly suitable to using a number of displays for different purposes.

This chapter covers the following topics:

• Screen mode concepts and terminology used throughout the chapter
• Using different kinds of displays
• Directing debugger output to different displays by assigning display attributes
• Using predefined displays SRC, OUT, PROMPT, INST, REG, IREG, and FREG (Alpha only), which are automatically available when you enter screen mode
• Scrolling, hiding, deleting, moving, and resizing a display
• Creating a new display
• Specifying a display window
• Creating a display configuration
• Saving the current state of screen displays
• Changing your terminal screen's height and width during a debugging session and the effect on display windows
• Using screen-related debugger built-in symbols
• Using predefined windows
• Enabling country-specific features for screen mode

Many screen mode commands are bound to keypad keys. For key definitions, see Appendix A.

A display is a group of text lines. The text can be lines from a source file, assembly-language instructions, the values contained in registers, your input to the debugger, debugger output, or program input and output.

You view a display through its display window, which can occupy any rectangular area of the screen. Because a display window is typically smaller than the associated display, you can scroll the display window up, down, right, and left across the display text to view any part of the display.

Figure 7-1 is an example of screen mode that shows three display windows. The name of each display (SRC, OUT, and PROMPT) appears at the top left corner of its display window. The display name serves both as a tag on the display itself and as a name for future reference in commands.

Figure 7-1 Default Screen Mode Display Configuration

Figure 7-1 is the default display configuration established when you first invoke screen mode. SRC, OUT, and PROMPT are three of the predefined displays that the debugger provides when you enter screen mode (see Section 7.4). You can modify the configuration of these displays as well as create additional displays.

Displays SRC, OUT, and PROMPT have the following basic characteristics:

• SRC is a source-code display that occupies the upper half of the screen (it displays Fortran code in Figure 7-1). The name of the source module displayed, SQUARES$MAIN, is to the right of the display name.
• OUT, located in a window directly below SRC, shows the output of debugger commands.
• PROMPT, at the bottom of the screen, shows the debugger prompt and debugger input.

Conceptually, displays are placed on the screen as on a pasteboard. The display most recently referenced by a command is put on top of the pasteboard by default. Therefore, depending on their screen locations, display windows that you have referenced recently might overlay or hide other display windows.

The debugger maintains a display list, which is the pasting order of displays. Several keypad key definitions use the display list to cycle through the displays currently on the pasteboard.

Every display belongs to a display kind (see Section 7.2). The display kind determines what type of information the display can capture and display, such as source code, or debugger output. The display kind defines whether displayed data is paged into the memory buffer or discarded when the memory buffer overflows. The display kind also determines how the contents of the display are generated.

The contents of a display are generated in two ways:

• Some displays are automatically updated. Their definition includes a command list that is executed whenever the debugger gains control from the program. The output of the command list forms the contents of those displays. Display SRC belongs to that category: it is automatically updated so that an arrow points to the source line at which execution is currently paused.
• Other displays, for example, display OUT, are updated in response to commands you enter interactively. For a display of this type to be updated, it must first be assigned an appropriate display attribute (with the SELECT command). The display attribute identifies the display as the target display for one or more types of output (see Section 7.3).

The names of any attributes assigned to a display appear to the right of the display name, in lowercase letters. In Figure 7-1, SRC has the source and scroll attributes (SRC is the current source display and the current scrolling display), OUT has the output attribute (it is the current output display), and so on. Note that, although SRC is automatically updated by its own built-in command, it can also receive the output of certain interactive commands (such as EXAMINE/SOURCE) because it has the source attribute.

The concepts introduced in this section are developed in more detail in the rest of this chapter.

7.2 Display Kinds

Every display has a display kind. The display kind determines the type of information a display contains, how that information is generated, and whether the memory buffer associated with the display is paged.

Typically, you specify a display kind when you use the DISPLAY command to create a new display (if you do not specify a display kind, an output display is created). You can also use the DISPLAY command to change the display kind of an existing display with the following keywords:

DO (command[,...])
INSTRUCTION
INSTRUCTION (command)
OUTPUT
REGISTER
SOURCE
SOURCE (command)

The contents of a register display are generated and updated automatically by the debugger. The contents of other kinds of displays are generated by commands, and these display kinds fall into two general groups.

A display that belongs to one of the following display kinds has its contents updated automatically according to the command or command list you supply when defining that display:

DO (command[,...])
INSTRUCTION (command)
REGISTER
SOURCE (command)

The command list specified is executed each time the debugger gains control from your program, if the display is not marked as removed. The output of the commands forms the new contents of the display. If the display is marked as removed, the debugger does not execute the command list until you view that display (marking that display as unremoved).

A display that belongs to one of the following display kinds derives its contents from commands that you enter interactively:

INSTRUCTION
OUTPUT
SOURCE

To direct debugger output to a specific display in this group, you must first select it with the SELECT command. The technique is explained in the following sections and in Section 7.3. After a display is selected for a certain type of output, the output from your commands forms the contents of the display.

7.2.1 DO (Command[;...]) Display Kind

A DO display is an automatically updated display. The commands in the command list are executed in the order listed each time the debugger gains control from your program. Their output forms the contents of the display and erases any previous contents.

For example, the following command creates the DO display CALLS at window Q3. Each time the debugger gains control from the program, the SHOW CALLS command is executed and the output is displayed in CALLS, replacing any previous contents.

DBG> DISPLAY CALLS AT Q3 DO (SHOW CALLS)

The following command creates a DO display named V2_DISP that shows the contents of elements 4 to 7 of the vector register V2 (using Fortran array syntax). The display is automatically updated whenever the debugger gains control from the program:

DBG> DISPLAY V2_DISP AT RQ2 DO (EXAMINE %V2(4:7))

The default size of the memory buffer associated with any DO display is 64 lines. When the memory buffer is full, the oldest lines are discarded to make room for new text. You can use the DISPLAY/SIZE command to change the buffer size.

7.2.2 INSTRUCTION Display Kind

An instruction display shows the output of an EXAMINE/INSTRUCTION command within the instruction stream of a routine. Because the instructions displayed are decoded from the image being debugged and show the exact code that is executing, this kind of display is particularly useful in helping you debug optimized code (see Section 14.1).

In the display, one line is devoted to each instruction. Source-line numbers corresponding to the instructions are displayed in the left column. The instruction at the location being examined is centered in the display and is marked by an arrow in the left column.

Before anything can be written to an instruction display, you must select it as the current instruction display with the SELECT/INSTRUCTION command.

In the following example, the DISPLAY command creates the instruction display INST2 at RH1. The SELECT/INSTRUCTION command then selects INST2 as the current instruction display. When the EXAMINE/INSTRUCTION X command is executed, window RH1 fills with the instruction stream surrounding the location denoted by X. The arrow points to the instruction at location X, which is centered in the display.

DBG> DISPLAY INST2 AT RH1 INSTRUCTION DBG> SELECT/INSTRUCTION INST2 DBG> EXAMINE/INSTRUCTION X

Each subsequent EXAMINE/INSTRUCTION command updates the display.

The default size of the memory buffer associated with any instruction display is 64 lines; however, you can scroll back and forth to view all the instructions within the routine. You can use the DISPLAY/SIZE command to change the buffer size and improve performance.

7.2.3 INSTRUCTION (Command) Display Kind

This is an instruction display that is automatically updated with the output of the command specified. That command, which must be an
EXAMINE/INSTRUCTION command, is executed each time the debugger gains control from your program.

For example, the following command creates the instruction display INST3 at window RS45. Each time the debugger gains control, the built-in command EXAMINE/INSTRUCTION .%INST_SCOPE\%PC is executed, updating the display.

DBG> DISPLAY INST3 AT RS45 INSTRUCT (EX/INST .%INST_SCOPE\%PC)

This command creates a display that functions like the predefined display INST. The built-in EXAMINE/INSTRUCTION command displays the instruction at the current PC value in the current scope (see Section 7.4.4).

If an automatically updated instruction display is selected as the current instruction display, it is updated like a simple instruction display by an interactive EXAMINE/INSTRUCTION command (in addition to being updated by its built-in command).

The default size of the memory buffer associated with any instruction display is 64 lines; however, you can scroll back and forth to view all the instructions within the routine. You can use the DISPLAY/SIZE command to change the buffer size and improve performance.

7.2.4 OUTPUT Display Kind

An output display shows any debugger output that is not directed to another display. New output is appended to the previous contents of the display.

Before anything can be written to an output display, it must be selected as the current output display with the SELECT/OUTPUT command, or as the current error display with the SELECT/ERROR command, or as the current input display with the SELECT/INPUT command. See Section 7.3 for more information about using the SELECT command with output displays.

In the following example, the DISPLAY command creates the output display OUT2 at window T2 (the display kind OUTPUT can be omitted from this example, because it is the default kind). The SELECT/OUTPUT command then selects OUT2 as the current output display. These two commands create a display that functions like the predefined display OUT:

DBG> DISPLAY OUT2 AT T2 OUTPUT DBG> SELECT/OUTPUT OUT2

OUT2 now collects any debugger output that is not directed to another display. For example:

• The output of a SHOW CALLS command goes to OUT2.
• If no instruction display has been selected as the current instruction display, the output of an EXAMINE/INSTRUCTION command goes to OUT2.
• By default, debugger diagnostic messages are directed to the PROMPT display. They can be directed to OUT2 with the SELECT/ERROR command.

The default size of the memory buffer associated with any output display is 64 lines. When the memory buffer is full, the oldest lines are discarded to make room for new text. You can use the DISPLAY/SIZE command to change the buffer size.

	privacy and legal statement
4538PRO_013.HTML