% mprun -np 0 -x lsf prism a.out

% mprun -n -np 4 prism &

set follow_spawn=onset debug_spawn_aout="beta gamma"

you can left-click on the icon to obtain information about using the mouse in the window.

---

Note - The Prism environment assumes that you have a standard three-button mouse.

---

Using Keyboard Alternatives to the Mouse

You can use a keyboard to perform many of the same functions you can perform with a mouse. This section lists the supported keyboard alternatives.

In general, to use a keyboard alternative, the focus must be in the screen region where you want the action to take place. The focus is generally indicated by the location cursor, which is a heavy line around the region.

General keyboard alternatives to mouse control are listed in TABLE 2-2.

TABLE 2-2 General Keyboard Alternatives to Mouse Control

Key Name	Description
Tab	Use the Tab key to move the location cursor from field to field within a window or dialog box. Each button in a window or box constitutes one field. The location cursor highlights the relevant button when you tab to the field.
Shift-Tab	Use the Shift-Tab keys to perform the same function as Tab, but in the reverse direction.
Return	Use the Return key to choose a highlighted choice in a menu or to perform the action associated with a highlighted button in a window or dialog box.
Arrow keys	Use the up, down, left, and right arrow keys to move within a field. For example, when the location cursor highlights a list, you can use the up and down arrow keys to move through the choices in the list. In some windows that contain text, pressing the Control key along with an up or down arrow key scrolls the text one-half page.
F1	Use the F1 key instead of the Help button to obtain help about a window or dialog box.
F10	Use the F10 key to move the location cursor to the menu bar.
Meta	Use the Meta key along with the underlined character in the desired menu item to display a menu or dialog box (equivalent to clicking on the item with the mouse). The Meta key has different names on different keyboards; on some it is the Left or Right key.
Control-C	Use the Control-C key combination to interrupt command execution.
Esc	Use the Esc key instead of the Close or Cancel button to close the window or dialog box in which the mouse pointer is currently located.

The keys and key combinations described in TABLE 2-3 work on the command line and in text-entry boxes -- that is, fields in a dialog box or window where you can enter or edit text.

TABLE 2-3 Text-Entry Keyboard Alternatives

Key Name	Description
Back Space	Deletes the character to the left of the I-beam cursor.
Delete	Same as Backspace.
Control-A	Moves to the beginning of the line.
Control-B	Moves back one character.
Control-D	Deletes the character to the right of the I-beam cursor.
Control-E	Moves to the end of the line.
Control-F	Moves forward one character.
Control-K	Deletes to the end of the line.
Control-U	Deletes to the beginning of the line.

In addition, you can use keyboard accelerators to perform actions from the menu bar; see Keyboard Accelerators for Main Menu Selections.

Issuing Commands

You can issue commands in the Prism environment from the command line in the command window. Most commands duplicate functions you can perform from the menu bar. Some functions, however, are only available via commands. See the Prism Reference Manual for complete information about Prism commands. See Using the Command Window for instructions on entering commands in the command window.

Many commands have the same syntax and perform the same action in both the Prism environment and the Solaris debugger dbx. There are differences, however; you should check the reference description of a command before using it.

---

Using the Menu Bar

The menu bar is the line of titles across the top of the main window of the Prism environment.

Each title is associated with a pull-down menu from which you can perform actions within the Prism environment.

Keyboard Accelerators

A keyboard accelerator is a shortcut that lets you choose a frequently used menu item without displaying its pull-down menu. Keyboard accelerators consist of the Control key plus a function key; you press both at the same time to perform the action. The keyboard accelerator for a keyboard menu selection is displayed next to the name of the selection. If nothing is displayed, there is no accelerator for that selection.

The keyboard accelerators (on a Sun keyboard) are listed in TABLE 2-4.

TABLE 2-4 Keyboard Accelerators for Main Menu Selections

Accelerator	Function
Control-F1	Run
Control-F2	Continue
Control-F3	Interrupt
Control-F4	Step
Control-F5	Next
Control-F6	Where
Control-F7	Up
Control-F8	Down

---

Using the Source Window

The source window displays the source code for the executable program loaded into the Prism environment. (Chapter 3 describes how to load a program into the Prism environment and how to display the different source files that make up the program.) When you execute the program and execution then stops for any reason, the source window updates to show the code being executed at the stopping place. The Source File field at the top of the source window lists the name of the file displayed in the window.

You can resize the source window by dragging the small resize box at the lower right of the window. If you change the window's size, the new size is saved when you leave the Prism environment.

You cannot edit the source code displayed in the source window. This must be done within an editor, which can be called up from within the Prism environment. See Chapter 6 for instructions on editing programs.

Moving Through the Source Code

You can move through a source file displayed in the source window by using the scroll bar on the right side of the window. You can also use the up and down arrow keys to scroll a line at a time, or press the Control key along with the arrow key to move half a page at a time.

To return to the current execution point, type Control-X in the source window.

To Search for Text in a String or Regular Expression

Type:

(prism all) /regexp

or

(prism all) ?regexp

The /regexp command searches forward in the file for the string (or regular expression) that you specify and repositions the file at the first occurrence it finds. The ?regexp command searches for the string (or regular expression) in the reverse direction.

Selecting Text

You can select text in the source window by dragging over it with the mouse; the text is then highlighted. Or double-click with the mouse pointer on a word to select that word. Left-click anywhere in the source window to deselect text.

Right-click in the source window to display a menu that includes actions to perform on the selected text, as shown in FIGURE 2-2. For example, select Print to display a visualizer containing the value(s) of the selected variable or expression at the current point of execution. See Chapter 5 for a discussion of visualizers and printing. To close the pop-up menu, right-click anywhere else in the main window.

 FIGURE 2-2 Pop-up Menu in Source Window

You can display the definition of a function by pressing the Shift key while selecting the name of the function in the source window. This is equivalent to choosing the Func selection from the File menu and selecting the name of the function from the list. When selecting the function name, highlight only the name, not arguments to the function.

Splitting the Source Window

You can split the source window to simultaneously display the source code and assembly code of the loaded program.

To Split the Source Window

1. Load the program of interest.

2. Right-click in the source window to display the pop-up menu.

3. Click on the Show source pane selection in the pop-up menu.

This displays another menu.

4. Choose the Show .s source selection from the menu.

This causes the assembly code for your program to be displayed in the bottom pane of the window, as shown in FIGURE 2-3.

 FIGURE 2-3 Split Source Window

To Return to a Single Source Window

1. Right-click in the pane you want to close.

2. Choose Hide this source pane from the pop-up menu.

---

Using the Line-Number Region

The line-number region shows the line numbers associated with the source code displayed in the source window. FIGURE 2-4 shows a portion of a line-number region, with a breakpoint set.

 FIGURE 2-4 Line-Number Region

You will see the following symbols in the line-number region:

• The > symbol in the line-number region in FIGURE 2-3 is the execution pointer. When a program is being executed, the execution pointer points to the next line to be executed for the most-active function call or to the call site for functions higher on the stack. If you move elsewhere in the source code, typing Control-X returns to the current execution point.
• A B displayed next to a line number indicates that all processes in the current pset have a breakpoint set at that line. A b is displayed next to a line number when some, but not all, processes in the current pset have a breakpoint set at that line. Methods for setting breakpoints are described in Setting Breakpoints.

Shift-click on the B or b in the line-number region to display the event associated with the breakpoint. See Overview of Events for a discussion of events.

• A T is displayed next to a line number when all processes in the current pset have a tracepoint set at that line. A t is displayed next to a line number when some, but not all, processes in the current pset have a tracepoint set at that line. See Tracing Program Execution for additional information.

Shift-click on T or t in the line-number region to display the event associated with the tracepoint. See Overview of Events for a discussion of events.

• The - symbol is the scope pointer; it indicates the current source position (that is, the scope). The Prism environment uses the current source position to interpret names of variables. When you scroll through source code, the scope pointer moves to the middle line of the code that is displayed. Various Prism commands also change the position of the scope pointer.
• The * symbol is used when the current source position is the same as the current execution point; this happens whenever execution stops.

---

Note - If a breakpoint and tracepoint are both set at a given line, the breakpoint is indicated, but not the tracepoint.

---

---

Using the Command Window

The command window is the area at the bottom of the main window in which you type commands and receive Prism output.

The command window consists of two boxes: the command line at the bottom and the history region above it. FIGURE 2-5 shows a command window.

 FIGURE 2-5 Command Window With History Region

You can resize the command window and scroll through it independently of the main window. If you do not intend to issue commands in the command window, you might want to make this window smaller so that you can display more code in the source window. If you use the command window frequently, you might want to make it bigger. If you change the size of the window, the new size is saved when you leave the Prism environment.

Using the Command Line

You can type in the command-line box whenever it is highlighted and an I-shaped cursor, called an I-beam, appears in it. See TABLE 2-3 for a list of keystrokes you can use in editing the command line. Press Return to issue the command. Type Control-C to interrupt execution of a command (or choose the Interrupt selection from the Execute menu).

You can issue multiple commands on the Prism command line, separating them with semicolons (;). There is one exception to this--you cannot follow a file name argument with a semicolon because the Prism environment parses it as part of the file name.

The Prism environment keeps the commands that you issue in a buffer. Type Control-P to display the previous command in this buffer. Type Control-N to display the next command in the buffer. You can then edit the command and issue it in the usual way.

During long-running commands (for example, when you have issued the run command to start a program executing), you may still be able to execute other commands. If you issue a command that requires that the current command complete execution, you receive a warning message and the Prism environment waits for the command to complete.

Using the History Region

Commands that you issue on the command line are echoed in the history region, above the command line. The Prism environment's response appears beneath the echoed command. The Prism environment also displays other messages in this area, as well as command output that you specify to go to the command window. Use the scroll bar at the right of this box to move through the display.

To Specify the Maximum Number of Lines in the History Region

Type:

(prism all) set $history = value

For example:

set $history = 2000

This limits the maximum number of lines in the history buffer to 2000. The default is 10,000.

The Prism environment uses memory in maintaining a large history region. A smaller history region, therefore, may improve performance and reduce the chances of the Prism environment running out of memory.

To Select Text in the History Region

1. Select text using one of these methods:

• Double-click to select the word on which the mouse pointer is positioned.
• Triple-click to select the line on which the mouse pointer is located.
• Press the left mouse button and drag the mouse over the text to select it.

2. Click the middle mouse button to paste the selected text into other text areas.

To Re-Execute a Command

1. Triple-click on a line in the history region to select it.

2. Click the middle mouse button with the mouse pointer still in the history region.

3. Click the middle mouse button with the mouse pointer on the command line.

The selected text appears on the command line but is not executed. This gives you an opportunity to edit the text before executing it.

Redirecting Output

To Redirect Output to a File

Type:

(prism all) where @ filename

For example,

(prism all) where @ where.output

This puts the output of the where command (a stack trace) into the file where.output in your current working directory within the Prism environment. This method works for most commands.

To Redirect Output to a Window

Type:

(prism all) where on window

This directs the output of the where command to the Prism environment window specified by the window argument. The argument window must be one of:

• command (abbreviated com) - This sends output to the command window; this is the default.
• dedicated (abbreviated ded) - This sends output to a window dedicated to output for this command. If you subsequently issue the same command and specify that output is to be sent to the dedicated window, this window will be updated. For example:

(prism all) list on ded

This displays the output of the list command in a dedicated window. Some commands that have equivalent menu selections display their output in the standard window for the menu selection.

• snapshot (abbreviated sna) - This creates a window that provides a snapshot of the output. If you subsequently issue the same command and specify that output is to be sent to the snapshot window, the Prism environment creates a separate window for the new output. The time each window was created is shown in its title. Snapshot windows let you save and compare outputs.
• windowname - This creates a window with a name you have created. Windowname appears in the title of the window. This is useful if you want a particular label for a window. For example, if you were doing a stack trace at line 22, you could issue this command:

(prism all) where on line 22

This labels the window with the location of the stack trace.

---

Note - The output of edit, make, and sh cannot be redirected. The output of run can, however, be redirected by > and other shell redirection conventions.

---

Logging Commands and Output

You can use the log command along with the source command to replay a session in the Prism environment. When replaying a Prism session, however, you must edit the log file to remove Prism output.

Use the log file for logging commands and output from within the Prism environment.

To Specify the Name of a Log File.

Type:

(prism all) log @ filename

The log file filename will be located in the current directory. This can be helpful in saving a record of a Prism session. For example,

(prism all) log @ prism.log

logs output to the file prism.log.

To Append the Log to an Existing File

Type:

(prism all) log @@ filename

To Turn Off Logging

Type:

(prism all) log off

Rerunning a Prism Session That Was Saved to a Log File

To Rerun a Saved Prism Debug Session

Type:

(prism all) source filename

where filename is the name of the log file.

---

Writing Expressions in the Prism Environment

While working in the Prism environment, there are circumstances in which you may want to write expressions that the Prism environment will evaluate. For example, you may want to print or display expressions or specify an expression as a condition under which an action is to take place. You can write these expressions in the language of the program you are working on. This section discusses additional aspects of writing expressions.

How the Prism Environment Chooses the Correct Variable or Procedure

Multiple variables and procedures can have the same name in a program. This can be a problem when you specify a variable or procedure in an expression. To determine which variable or procedure you mean, the Prism environment tries to resolve its name by using these rules:

1. Prism first tries to resolve the name using the scope of the current function. For example, if you use the name x and there is a variable named x in the current function or the current file, the Prism environment uses that x. The current function is ordinarily the function at the program's current stopping point, but you can change this, as described in Choosing the Current File and Function.

2. If this fails to resolve the name, the Prism environment goes up the call stack looking for the variable x in the caller of the current function, and then its caller, and so on, following the scoping and visibility rules of the current language.

3. If no match is found in any routine active on the stack, the Prism environment searches the static and global name spaces. If no match is found there, the Prism environment prints an error.

4. If the name is not found in the call stack, the Prism environment arbitrarily chooses one of the variables or procedures with the name in the source code. When the Prism environment prints out the information, it adds a message of the form "[using qualified name]". Qualified names are discussed below.

Using Qualified Names

You can override the way that the Prism environment resolves names by qualifying the name.

A fully qualified name starts with a back-quotation mark, or back-quote, (`). The symbol farthest to the left in the name is the load object, followed optionally by the file, followed optionally by the procedure, followed by the variable name. Each element is preceded by a backquote (`). Examples of the Prism environment's identifier syntax are shown in TABLE 2-5.

TABLE 2-5 Prism Identifier Syntax

Syntax	Description
a	Specifies the variable a in the current scope. An error is reported if no variable a exists in the current scope.
`a	Specifies the variable a in the global scope.
``a	Specifies the variable a in the global or file-static scope.
`foo.c`a	Specifies the variable a in file foo.c.
`foo.c`foo`a	Specifies the variable a in the procedure foo in the file foo.c.
`foo`a	Specifies the variable a in function foo (if foo is active).
`a.out`foo.c`foo`a	Specifies the variable a in function foo in file foo.c in load object a.out.
`a.out`foo.c`foo:line`a	Specifies the variable a at line number line in function foo in file foo.c in load object a.out.
`foo.x`foo.cc`Symbol::print:71`dummy	Specifies the variable dummy at line number 71 in member function print of class Symbol in file foo.cc in load object foo.x.
"foo.c":line	Specifies the line number line in the file foo.c. Note the use of double quotes.

To Display the Fully Qualified Name of a Variable

Type:

(prism all) which identifier

This command displays the fully qualified name, as described below.

Partially qualified names do not begin with `, but have a ` in them. For example,

foo`a

In this case, the Prism environment looks up the function name on the left first and picks the innermost symbol with that name that is visible from your current location. This is useful primarily in referring to variables in routines on the call stack.

Use the whereis command to display a list of all the fully qualified names that match the identifier you specify.

The Prism environment assigns its own names to variables in local blocks of C code. This approach disambiguates variable names, in case you reuse a variable name in more than one of these local blocks.

When debugging Fortran, the Prism environment attempts to be case-insensitive in interpreting names, but uses case to resolve ambiguities.

Using Fortran Intrinsic Functions in Expressions

The Prism environment supports the use of a subset of Fortran intrinsic functions in writing expressions; the intrinsics work for all languages that the Prism environment supports, except as noted below.

The intrinsics, along with the supported arguments, are:

• ALL(logical array) - Determines whether all elements are true in a logical array. This works for Fortran only.
• ANY(logical array) - Determines whether any elements are true in a logical array. This works for Fortran only.
• CMPLX(numeric-arg, numeric-arg) - Converts the arguments to a complex number. If the intrinsic is applied to Fortran variables, the second argument must not be of type complex or double (double-precision complex).
• COUNT(logical array) - Counts the number of true elements in a logical array. This works for Fortran only.
• ILEN(I) - Returns one less than the length, in bits, of the two's-complement representation of an integer. If I is nonnegative, ILEN(I) has the value
  log2(I + 1); if I is negative, ILEN(I) has the value log2(-I).
• IMAG(complex number) - Returns the imaginary part of a complex number. This works for Fortran only.
• MAXVAL(array) - Computes the maximum value of all elements of a numeric array.
• MINVAL(array) - Computes the minimum value of all elements of a numeric array.
• PRODUCT(array) - Computes the product of all elements of a numeric array.
• RANK(scalar or array) - Returns the rank of the array or scalar.
• REAL(numeric argument) - Converts an argument to real type. This works for Fortran only.
• SIZE(array) - Counts the total number of elements in the array.
• SUM(array) - Computes the sum of all elements of a numeric array.

The intrinsics can be either uppercase or lowercase.

Using C Arrays in Expressions

The Prism environment handles arrays slightly differently from the way C handles them.

For example, in a C program, you might make the following declaration and use a in an expression:

int a[10];

The type of a converts from "array of ints" to "pointer to int". Following the rules of C, therefore, a Prism command like this one should print a hexadecimal pointer value:

(prism all) print a + 2

Instead, it prints two more than each element of a (that is, a[0] + 2, a[1] + 2, etc.). This enables you to do array operations and use visualizers on C arrays in the Prism environment. The print command and visualizers are discussed in Chapter 5.

To get the C behavior, issue the command as follows:

(prism all) print &a + 2

Using Array-Section Syntax in C Arrays

You can use Fortran 90 array-section syntax when specifying C arrays. This syntax is useful, for example, if you want to print the values of only a subset of the elements of an array. The syntax is:

(lower-bound: upper-bound: stride)

where

• lower-bound - Specifies the lowest-numbered element you choose along a dimension; it defaults to 0.
• upper-bound - Specifies the highest-numbered element you choose along the dimension; it defaults to the highest-numbered element for the dimension.
• stride - Specifies the increment by which elements are chosen between the lower bound and upper bound; it defaults to 1.

You must enclose the values in parentheses (rather than brackets), as in Fortran. If your array is multidimensional, you must separate the dimension specifications with commas within the parentheses, again as in Fortran.

For example, if you have the following array:

int a[10][20];

you can issue the following command to print the values of elements 2-4 of the first dimension and 2-10 of the second dimension:

(prism all) print a(2:4,2:10)

Hints for Detecting NaNs and Infinities

The Prism environment provides expressions that you can use to detect NaNs (values that are "not a number") and infinities in your data. These expressions derive from the way NaNs and infinities are defined in the IEEE standard for floating-point arithmetic.

To Find Out if x Is a NaN

Use the expression:

(x .ne. x)

For example, if x is an array, issue this command to print only the elements of x that are NaNs:

(prism all) where (x .ne. x) print x

The print command is discussed in Chapter 5.

Also, note that if there are NaNs in an array, the mean of the values in the array will be a NaN. The mean is available via the Statistics selection in the Options menu of a visualizer--see Chapter 5 for details.

To Find Out if x Is an Infinity

Type:

(prism all) (x * 0.0 .ne. 0.0)

---

Using Fortran 90 Generic Procedures

You can use Fortran 90 generic procedures in any Prism command or dialog box that asks for a procedure. If you do so, the Prism environment prompts you for the name(s) of the specific procedure(s) you want to use.

For example, you use the syntax stop in procedure to set a breakpoint in a procedure. If you use this syntax for a generic procedure in the Prism graphical interface, a dialog box like the one shown in FIGURE 2-6 is displayed.

 FIGURE 2-6 Generic Procedure Dialog Box

The commands-only interface of the Prism environment prompts you in a similar fashion, as shown below:

Copyright © 2002, Sun Microsystems, Inc. All rights reserved.