(prism all) display x on dedicated as colormap(prism all) display y/4 on dedicated as histogram(prism all) display [0:128:2]z on dedicated as text

Type:

(prism all) print $name

or

(prism all) display $name

where name is the name of the register of interest. For example, this prints the contents of the program counter register:

(prism all) print $pc

See To Display the Contents of Registers for a list of register names supported by the Prism environment.

Type:

(prism all) where (expression) print variable

or

(prism all) where (expression) display variable

You can precede the print or display command with a where statement that can make elements of a variable or array inactive. Inactive elements are not printed in the Command window; Overview of Data Visualization describes how they are treated in visualizers. Making elements of a variable or array inactive is referred to as setting the context.

The expression must evaluate to true or false for every element of the variable or array being printed.

For example,this prints only the values of i that are greater than 0:

(prism all) where (i .gt. 0) print i

You can use certain Fortran intrinsics in the where statement. For example, this prints the element of a that has the largest value:

(prism all) where (a .eq. maxval(a)) print a

This is equivalent to the MAXLOC intrinsic function. See Writing Expressions in the Prism Environment for more information on writing expressions in the Prism environment.

Note that setting the context affects only the printing or displaying of the variable.
It does not affect the actual context of the program as it executes.

Type:

(prism all) print/radix variable

or

(prism all) display/radix variable

radix can be b (binary), d (decimal), x (hexadecimal), or o (octal).

For example, this prints the binary representation of pvar1 in the Command window:

(prism all) print/b pvar1

The following example displays the hexadecimal values of pvar2 in a dedicated window:

(prism all) display/x pvar2 on dedicated

The default radix is decimal, unless you have used the set $radix command to change it; see To Change the Default Radix.

---

Working With Visualizers

The window that contains the data being printed or displayed is called a visualizer. FIGURE 5-3 shows a visualizer for a three-dimensional array.

 FIGURE 5-3 Visualizer for a Three-Dimensional Array

The visualizer consists of two parts: the data navigator and the display window. There are also File and Options pull-down menus.

The data navigator shows which portion of the data is being displayed and provides a quick method for moving through the data. The appearance of the data navigator depends on the number of dimensions in the data. It is described in more detail in Using the Display Window in a Visualizer.

The display window is the main part of the visualizer. It shows the data, using a representation that you can choose from the Options menu. The default is text; that is, the data are displayed as numbers or characters. FIGURE 5-3 is a Text visualizer. The display window is described in more detail in Using the Options Menu.

The File menu lets you save, update, or cancel the visualizer. The Options menu, among other things, lets you change the way values are represented. Both menus are described more fully later in this section.

Using the Data Navigator in a Visualizer

The data navigator helps you move through the data being visualized. It has different appearances, depending on the number of dimensions in your data.

For one-dimensional arrays and parallel variables, the data navigator is the scroll bar to the right of the data. The numbers to the right of the buttons for the File and Options menus indicate the coordinates of the first element that is displayed. The elevator in the scroll bar indicates the position of the displayed data relative to the entire data set.

For two-dimensional data, the data navigator is a rectangle in the shape of the data, with the axes numbered. The white box inside the rectangle indicates the position of the displayed data relative to the entire data set. You can either drag the box or click at a spot in the rectangle. The box moves to that spot, and the data displayed in the display window changes.

For three-dimensional data, the data navigator consists of a rectangle and a slider, each of which you can operate independently. The value to the right of the slider indicates the coordinate of the third dimension. Changing the position of the bar along the slider changes which two-dimensional plane is displayed out of the
three-dimensional data.

For data with more than three dimensions, the data navigator adds a slider for each additional dimension.

You can change the way the visualizer lays out your data by changing the numbers that label the axes.

1. Click in the box surrounding the number.

It is highlighted, and an I-beam appears.

2. Type in the new number of the axis; you don't have to delete the old number.

The other axis number automatically changes. For example, if you change axis 1 to 2, axis 2 automatically changes to become axis 1.

Using the Display Window in a Visualizer

The display window shows the data being visualized.

In addition to using the data navigator to move through the data, you can drag the data itself relative to the display window by holding down the left mouse button; this provides finer control over the display of the data.

To find out the coordinates and value of a specific data element, click it while pressing the Shift key. Its coordinates are displayed in parentheses, and its value is displayed beneath them. If you have set a context for the visualizer, you also see whether the element is active or inactive. Drag the mouse with the Shift key pressed, and you see the coordinates, value, and context of each data element over which the mouse pointer passes.

You can resize the visualizer to display more or less data either horizontally or vertically.

1. Click on File to pull down the File menu.

2. Perform one of the following:

• Choose Update from this menu to update the display window for this variable, using the value(s) at the current program location. See Updating and Closing the Visualizer for more information on updating a visualizer.
• Choose Save or Save As to save the visualizer's values to a file. See To Save the Values of a Variable for more information.
• Choose Diff or Diff With to compare the visualizer's values with values stored in a file. See To Compare the Data for more information.
• Choose Snapshot to create a copy of the visualizer, which you can use to compare with later updates.
• Choose Close to cancel the visualizer.

Using the Options Menu

Click on Options to pull down the Options menu. See FIGURE 5-4.

 FIGURE 5-4 Options Menu in a Visualizer

Choose Representation from the Options menu.

This displays another menu that gives the choices for how the values are represented in the display window. The choices are described below.

• Choose Text to display the values as numbers or letters. This is the default. For information about changing the default, see To Change the Default Representation.
• Choose Histogram to display the values of an array or parallel variable in a histogram. See FIGURE 5-5 for an example.

The vertical axis displays the number of data points; the horizontal axis displays the range of values. The Prism environment divides up this range evenly in creating the histogram bars. It prints summary data above the histogram.

Shift-click on a histogram bar to display the range and number of data points it represents.

Note that the histogram represents all the values of the variable, not just those shown in the two-dimensional slice of data that happens to be displayed in other representations.

 FIGURE 5-5 Histogram Visualizer

• Choose Dither to display the values as a shading from black to white. Groups of values in a low range are assigned more black pixels; groups of values in a high range are assigned more white pixels. This has the effect of displaying the data in various shades of gray. FIGURE 5-6 shows a two-dimensional dither visualizer. The lighter area indicates values that are higher than values in the surrounding areas; the darker area indicates values that are lower than surrounding values.
• You can left-click on a histogram visualizer bar to get a pop-up window, showing its contents.

For complex numbers, the Prism environment uses the modulus.

 FIGURE 5-6 Dither Visualizer

• Choose Threshold to display the values as black or white. By default, the Prism environment uses the mean of the values as the threshold; values less than or equal to the mean are black, and values greater than the mean are white. FIGURE 5-7 shows a threshold representation of a three-dimensional array.

For complex numbers, the Prism environment uses the modulus.

 FIGURE 5-7 Threshold Visualizer

• Choose Colormap (if you are using a color workstation) to display the values as a range of colors. By default, the Prism environment displays the values as a continuous spectrum from blue (for the minimum value) to red (for the maximum value). You can change the colors that the Prism environment uses; see Changing Colors.

For complex numbers, the Prism environment uses the modulus.

• Choose Graph to display values as a graph, with the index of each array element plotted on the horizontal axis and its value on the vertical axis. A line connects the points plotted on the graph. This representation is particularly useful for
  one-dimensional data, but can be used for higher-dimensional data as well; for example, in a two-dimensional array, graphs are shown for each separate
  one-dimensional slice of the two-dimensional plane.

FIGURE 5-8 shows a graph visualizer for a one-dimensional slice of an array.

 FIGURE 5-8 One-Dimensional Graph Visualizer

• Choose Surface (if your data has more than one dimension) to render the
  three-dimensional contours of a two-dimensional slice of data. In the representation, the two-dimensional slice of data is tilted 45 degrees away from the viewer, with the top edge farther from the viewer than the bottom edge. The data values rise out of this slice. FIGURE 5-9 is an example.

 FIGURE 5-9 Surface Visualizer

• Choose Vector to display data as vectors. The data must be a Fortran complex or double-complex number, or a pair of variables to which the CMPLX intrinsic function has been applied (see Using Fortran Intrinsic Functions in Expressions). The complex number is drawn showing both magnitude and direction. The length of the vector increases with magnitude. Because direction is difficult to see for smaller vectors, the minimum vector length is five pixels. By default, the lengths of all vectors scale linearly with magnitude, varying between the minimum and maximum vector lengths. FIGURE 5-10 shows a vector visualizer.

 FIGURE 5-10 Vector Visualizer

Type:

(prism all) set $viz = "representation"

By default, the Prism environment creates new visualizers with a Text representation. Set the Prism variable viz to control the representation that is applied when a new visualizer is created. Possible values are:

• Text
• Histogram
• Dither
• Threshold
• Colormap
• Graph
• Surface
• Vector

Choose Parameters from the Options menu.

This displays a dialog box in which you can change various defaults that the Prism environment uses in setting up the display window; see FIGURE 5-11. If a parameter is grayed out or missing, it does not apply to the current representation.

 FIGURE 5-11 Visualization Parameters Dialog Box

The parameters for all representations except the histogram representation are:

• Field Width - Type a value in this box to change the width of the field that the Prism environment allocates to every data element.

For the text representation, the field width specifies the number of characters in each column. If a number is too large for the field width you specify, dots are printed instead of the number.

For dither, threshold, colormap, and vector representations, the field width specifies how wide (in pixels) the representation of each data element is to be. By default, dither, threshold, and colormap visualizers are scaled to fit the display window. Note, however, that for dither visualizers, the gray shading may be more noticeable with a smaller field width.

For the graph representation, the field width specifies the horizontal spacing between elements.

For the surface representation, it specifies the spacing of elements along both directions of the plane.

• Precision - Type a value in this box to change the precision with which the Prism environment displays real numbers in a text visualizer. The precision must be less than the field width. By default, the Prism environment prints the values of doubles with 16 significant digits, and floating-point values with seven significant digits. You can change this default by issuing the set command with the $d_precision variable (for doubles) or the $f_precision variable (for floating-point values). For example,

(prism all) set $d_precision = 11

sets the default precision for doubles to 11 significant digits.

• Minimum and Maximum - For colormap representations, use these variables to specify the minimum and maximum values that the Prism environment is to use in assigning color values to the data elements. Data elements that have values below the minimum and above the maximum are assigned default colors.

For graph, surface, and vector representations, these parameters represent the bottom and top of the range that is to be represented. Values below the minimum are shown as the minimum; values above the maximum are shown as the maximum.

By default, the Prism environment uses the entire range of values for all these representations.

• Threshold - For threshold representations, use this variable to specify the value at which the Prism environment is to change the display from black to white. Data elements whose values are at or below the threshold are displayed as black; data elements whose values are above the threshold are displayed as white. By default, the Prism environment uses the mean of the data as the threshold.

The parameters for the histogram representation are:

• Bar Width - Specifies the width in pixels of each histogram bar (except for the bars representing infinities and NaNs, which must be wide enough to fit the Inf or NaN label underneath). The default is 10 pixels.
• Bar Height - Specifies the height in pixels of the largest histogram bar.
  The default is 100 pixels.
• Minimum - Specifies the minimum value to be included in the histogram.
  By default the actual minimum value is used.
• Maximum - Specifies the maximum value to be included in the histogram.
  By default the actual maximum value is used.

If you specify a different minimum or maximum, values below the minimum or above the maximum are not displayed in the histogram but are counted as outliers instead; the number of outliers is displayed above the histogram.

• Max Buckets - Specifies the number of "buckets" into which values are to be poured--in other words, the number of histogram bars to be used. The default is 30. (The Prism environment might use fewer to make the horizontal labels come out evenly.)

Choose Ruler from the Options menu.

This toggles the display of a ruler around the display window.

The ruler is helpful in showing which elements are being displayed. FIGURE 5-12 shows a three-dimensional threshold visualizer with the ruler displayed.

In the surface representation, the ruler cannot indicate the coordinates of elements in the vertical axis, since they change depending on the height of each element. However, you can press the Shift key and left-click to display the coordinates and value of an element.

 FIGURE 5-12 Threshold Visualizer With a Ruler

Choose Statistics from the Options menu.

This displays a window containing statistics and other information about the variable being visualized.

The window contains:

• The name of the variable
• Its type and number of dimensions
• The total number of elements the variable contains and the total number of active elements, based on the context you set within the Prism environment (see the next section for a discussion of setting the context)
• The variable's minimum, maximum, and mean; these statistics reflect the context you set for the visualizer

FIGURE 5-13 gives an example of the Statistics window.

 FIGURE 5-13 Statistics for a Visualizer

For complex numbers, the Prism environment uses the modulus.

Choose Set Context from the Options menu.

In this dialog box, you can specify which elements of the variable are to be considered active and which are to be considered inactive. Active and inactive elements are treated differently in visualizers:

• In text, graph, surface, and vector visualizers, inactive elements are grayed out.
• In colormap visualizers, inactive elements by default are displayed as gray. You can change this default; see Changing Colors.
• Context has no effect on dither and threshold visualizers.

FIGURE 5-14 shows the Set Context dialog box.

 FIGURE 5-14 Set Context Dialog Box

By default, all elements of the variable are active; this is the meaning of the keyword "everywhere" in the text-entry box. To change this default, you can either edit the text in the text-entry box directly or click on the Where button to display a menu. The choices in the menu are everywhere and other:

• Choose everywhere to make all elements active.
• Choose other to erase the current contents of the text-entry box. You can then enter an expression into the text-entry box.

In the text-entry box, you can enter any valid expression that will evaluate to true or false for each element of the variable.

The context you specify for printing does not affect the program's context; it just affects the way the elements of the variable are displayed in the visualizer.

Click on Apply to set the context you specified. Click on Cancel or press the Esc key to close the dialog box without setting the context.

1. Choose Radix from the Options menu.

2. Choose one of the items from the submenu: Decimal, Hex, Octal, and Binary.

Updating and Closing the Visualizer

If you created a visualizer by issuing a display command, it automatically updates every time the program stops execution.

If you created the visualizer by issuing a print command, its display window is grayed out when the program resumes execution and the values in the window are outdated.

Choose Update from the visualizer's File menu.

Choose Close from the File menu, or press the Esc key.

---

Saving, Restoring, and Comparing Visualizers

You can save the values of a variable or expression to a file. You can subsequently visualize these values and compare them with the values in another visualizer , such as the same variable later in the run or the same variable during a separate execution of the program. This provides a convenient way of spotting changes in the values of a variable.

You can save the values of a variable or expression to a file for later use.

Perform one of the following:

• From the command line - Use the command varsave to save the values of a variable or expression to a file.

Its syntax is:

varsave "filename" expression

where filename is the name of the file to which the data is to be saved, and expression is the variable or expression whose values are to be saved.

For example, this saves the values of the variable alpha in the file alpha.data in your current working directory within the Prism environment:

(prism all) varsave "alpha.data" alpha

The following saves the results of the expression alpha*2 in the file with the path name /u/kathy/alpha2.data:

(prism all) varsave "/u/kathy/alpha2.data" alpha*2

• From a visualizer - Use the Save or Save As selection from a visualizer's File menu to save the visualizer's values to a file.

If you choose Save As, a dialog box appears in which you can specify the name of the file to which the values are to be saved; see FIGURE 5-15.

 FIGURE 5-15 Saving a Visualizer's Data to a File

The highlighted directory is the current working directory. If you want to put the file there, simply type its name in the Save As box and click on OK.

If you want to put the file in another directory, click on the directory. (The parent directories of the current working directory are shown above it in the Directories list; its subdirectories are listed beneath it.) This displays the subdirectories of the directory you clicked on. You can traverse the directory structure in this manner until you find the directory in which you want to put the file, or you can simply type the entire path name in the Save As box.

Choose the Save selection to save the values in the file you most recently specified. If you have not specified a file, the values are saved in a file called noname.var in your current working directory.

This intrinsic brings values you have saved to a file back into the Prism environment.

Type:

(prism all) command varfile("filename")

where filename is the name of the file that contains the values you want to restore.

You can use the varfile intrinsic anywhere you could have used the original variable or expression that you saved to a file. For example, if you saved x:

(prism all) varsave "x.var" x

then the command

(prism all) print varfile("x.var")

is equivalent to

(prism all) print x

Note that this enables you to save a variable's values, then print them during a later Prism session without having a program loaded or running.

You can compare a variable or expression whose values have been saved in a file with another version of the variable or expression. This comparison could take place later in the same run of the program, during a subsequent run, or even during a second, simultaneous Prism session.

You can also compare the values with those of another variable, as long as both variables have the same base type (that is, you can't compare integers with
floating-point numbers).

Perform one of the following:

• From the command line - Type:

(prism all) print - varfile ("filename")

or

(prism all) display - varfile ("filename")

This performs a comparison between two versions of a variable or expression.

For example, if you saved x in the file x.var:

(prism all) varsave "x.var" x

then this command prints the difference between the current and saved values of x:

(prism all) print x - varfile("x.var")

If an element is printed as 0, it is the same in both versions. If it is nonzero, its value is different in the two versions.

• From a visualizer - Select Diff or Diff With from a visualizer's File menu.

This performs a comparison between the visualizer's values and the values stored in a file.

Select Diff With to choose the file containing the values. It displays a dialog box like the one shown in FIGURE 5-16.

 FIGURE 5-16 Diff With Dialog Box

The dialog box has the same format as the Save As dialog box described in To Save the Values of a Variable. It lists the files found in your current working directory in the Prism environment. Click on a file name, then click OK to choose the file. Or type a file name in the Diff With text-entry box and click OK.

Choose Diff to compare the visualizer's values to those in the most recently specified file. If no file has been specified, values are compared to those in the file noname.var in your current working directory in the Prism environment.

Once you have specified a file via Diff or Diff With, the Prism environment creates a new visualizer that displays the difference in values between the visualizer and the file. If an element's value in the new visualizer is 0, the value is the same in both versions. If it is nonzero, it is different in the two versions.

You can work with this visualizer as you would any visualizer. For example, you can change the representation and display summary statistics.

---

Visualizing Structures

If you print a pointer or a structure (or a structure-valued expression) in a window, a structure visualizer appears.

FIGURE 5-17 shows an example of a structure visualizer.

 FIGURE 5-17 Structure Visualizer

The structure you specified appears inside a box; this is referred to as a node. The node shows the fields in the structure and their values. If the structure contains pointers, small boxes appear next to them; they are referred to as buttons. Left-click on a node to select it. Use the up and down arrow keys to move between buttons of a selected node.

You can perform various actions within a structure visualizer, as described below.

Expanding Pointers

You can expand scalar pointers in a structure to generate new nodes. (You cannot expand a pointer to a parallel variable.)

Perform one of the following:

• With the mouse - Left-click a button to expand the pointer. For example, clicking the button next to the nav field in FIGURE 5-17 changes the visualizer as shown in FIGURE 5-18.
• From the keyboard - Use the right arrow key to expand and visit the node pointed to by the current button. If the node is already expanded, pressing the right arrow key simply visits the node. Use the left arrow key to visit the parent of a selected node.

 FIGURE 5-18 Structure Visualizer, With One Pointer Expanded

Perform one of the following:

• With the mouse - Double-click or Shift-left-click on the node.
• From the keyboard - Press the Shift key along with the right arrow key.
• From the Options menu - Click Expand. The cursor turns into a target; move the cursor to the node you are interested in and left-click.

Perform one of the following:

• With the mouse - Triple-click or Control-left-click on the node.
• From the keyboard - Press the Control key and the right arrow key.
• From the Options menu - Click Expand All. The cursor turns into a target; move the cursor to the node you are interested in and left-click.

Perform one of the following:

• Left-click and drag through the data navigator or the display window to pan through the data.
• Left-click on the Zoom arrows to "zoom" in and out on the data.
• Click on the down arrow to zoom out and see a bird's-eye view of the structure. Click on the up arrow to get a closeup.
• Left-click on a node in a zoomed-out structure visualizer to pop up a window showing the full contents of the node.

For information about navigating through visualizers, see Using the Data Navigator in a Visualizer and Using the Display Window in a Visualizer.

FIGURE 5-19 shows part of a complicated structure visualizer after zooming out.

 FIGURE 5-19 Zooming Out in a Structure Visualizer

The selected node is centered in the display window whenever you zoom in or out.

To delete a node (except the root node):

• With the mouse - Middle-click on a node (except the root node).
• From the Options menu - Click Delete. The cursor turns into a target; move the cursor to the node you want to delete and left-click.

Deleting a node also deletes its children (if any).

More About Pointers in Structures

Note the following about pointers in structure visualizers:

• Null pointers have "ground" symbols next to them.
• If you have previously expanded a pointer, it has an arrow next to its button; you cannot expand the pointer again. This prevents infinite loops on circular data structures.
• A pointer containing a bad address has an X drawn over its button.

Augmenting the Information Available for Display

You can provide a special function for each of your data types that makes additional information available to the Prism environment. This enables the Prism environment to more accurately display the contents of structures with that data type.

For C or C++ union types, you can identify which member of the union is valid. For a pointer within a structure, you can specify that the pointer's target is an array of elements, rather than a single element, and you can further specify the length of the array.

You must embed these specifications within a special function that is compiled and linked with your program being debugged. The function has the following form:

void prism_define_typename (typename *ptr);

where typename is the tag name of one of your structure data types. Thus, you can define one such function for each of your data types. When the Prism environment displays a variable of this type, it checks whether an augmentation function is defined in the program. If so, the Prism environment calls the function, passing a pointer to the instance of the structure being displayed. Your function can then look at the instance to choose valid union members and to size dynamic arrays.

You communicate this information back to the Prism environment with the following call, which is defined in /opt/SUNWhpc/include/prism.h:

void prism_add_array(char *member_name, int len);

This call specifies that the pointer named member_name points to an array of length len. The pointer's name, member_name, is the name of one of the members of the structure, as found in the structure's C or C++ declaration. The results are undefined if member_name is not a pointer.

The following call specifies that the member named name is of type union, and of all the members of this union, only valid_member is to be displayed.

void prism_add_union(char *name, char *valid_member);

Both name and valid_member are names as found in the C or C++ declarations of structs or unions.

Link your program with the library libprism.so in /opt/SUNWhpc/lib.

Sun HPC ClusterTools software currently supplies both static (libprism.a) and shared versions (libprism.so) of this library. Use the shared version.

Assume that data in the declaration below is a dynamic array:

struct Vector { int len; int *data; };

The function you write looks like this:

#include "prism.h" void prism_define_Vector(struct Vector *v) { prism_add_array("data", v->len); }

Assume that the member type discriminates the union value in this example:

enum Type {INT, DOUBLE}; struct Value { enum Type type; union { int i; double d; } value; };

The function you write would look like this:

#include "prism.h" void prism_define_Value(struct Value *val) { if (val->type == INT) prism_add_union("value", "i"); else prism_add_union("value", "d"); }

There are no restrictions on the number or order of calls to prism_add_union and prism_add_array.

To Update and Close a Structure Visualizer

1. Update the structure visualizer by left-clicking Update in the File menu.

This updates a structure visualizer. When you do this, the root node is reread; the Prism environment attempts to expand the same nodes that are currently expanded. (The same thing happens if you reprint an existing structure visualizer.)

2. Close the structure visualizer by left-clicking Close in the File menu.

---

Printing the Type of a Variable

The Prism environment provides several methods for finding out the type of a variable.

To Print the Type of a Variable From the Menu Bar

1. Select Whatis from the Debug menu.

The Whatis dialog box appears; it prompts for the name of a variable.

2. Click on Whatis.

This displays the information about the variable in the Command window.

3. Click on Type.

The Prism environment treats name as a type name.

To Print the Type of a Variable From the Source Window

1. Select a variable by double-clicking it or by dragging over it while pressing the left mouse button.

2. Hold down the right mouse button.

A pop-up menu appears.

3. Choose Whatis from this menu.

Information about the variable appears in the Command window.

To Print the Type of a Variable From the Command Window

Type:

(prism all) whatis [type] variable

If you specify a type (struct, class, enum, or union) before the name of the variable, the Prism environment treats variable as a type name. The type keywords resolve ambiguities where there are types and variables with the same name.

What Is Displayed

The Prism environment displays information about the variable in the Command window. In this example, the whatis command is used with variable primes:

whatis primes logical primes(1:999)

To Modify Visualizer Data

Type:

(prism all) assign variable = value

This assigns new values to a variable or an array.

For example,

(prism all) assign x = 0

assigns the value 0 to the variable x. You can put anything on the left-hand side of the statement that can go on the left-hand side in the language you are using --
for example, a variable or a Fortran array section.

If the right-hand side does not have the same type as the left-hand side, the Prism environment performs the proper type coercion.

Changing the Radix of Data

To Change the Radix of a Value

Type:

(prism all) value = base

This changes the radix of a value in the Prism environment. The value can be a decimal, hexadecimal, or octal number. Precede hexadecimal numbers with 0x; precede octal numbers with 0 (zero). The base can be D (decimal), X (hexadecimal), or O (octal). The Prism environment prints the converted value in the Command window.

For example, to convert 100 (hex) to decimal, issue this command:

(prism all) 0x100=D

The Prism environment responds:

256

To Print the Names and Values of Local Variables

Type:

(prism all) dump routine

To print the names and values of all local variables in a function or procedure, specify its name. If you omit the function name, dump uses the current function. If you specify a period, dump prints the names and values of all local variables in the functions in the stack.

---

Printing Pointers as Array Sections

The Prism environment enables you to print simple arrays by section. The following examples assume the following declarations and code:

double da[]={0.1,1.1,2.1,3.1,4.1,5.1,6.1,7.1,8.1,9.1,10.1}; double *pd=da; int a[]={0,1,2,3,4,5,6,7,8,9,10}; int *pa=a; int *par[10]; int **ppi=par; void *ptr=(void*)da; ... for(i=0;i<10;i++) par[i]=&a[9-i]; <------ assume that the program is stopped here ------ ...

To Print an Array by Section

Type

(prism all) print array-name[section-specifier]

For example,

(prism) print a[1:5:2] a[1:5:2] = (1:3) 1 3 5

To View a Pointer as a One-Dimensional Array

Type

(prism all) print pointer[section_specifier]

Specify a section when printing the pointer.

For example:

(prism all) print pa[1:5:2] pa[1:5:2] = (1:3) 1 3 5

To Dereference an Array of Pointers

Type

(prism all) *pointer[section_specifier]

If the array element is a pointer, then the Prism environment enables you to dereference the section.

For example,

(prism all) *par[1:5:2] = (1:3) 8 6 4

To Cast Pointers

Type

(prism all) print ((type*)pointer)[section _specifier]

For example,

(prism all) print ((double*)ptr)[1:4:2] ((double*)ptr)[1:4:2] = (1:2) 1.100000000000000 3.100000000000000

Currently, the Prism environment supports only one level of dereferencing.

Assuming this declaration:

int **appi[2];

The Prism environment does not support:

(prism all) print **(appi[0:1])

Although the Prism environment allows one level of dereferencing for sections, the Prism environment does not support indexing. Thus, the Prism environment allows:

(prism all) print *par[1:5:2]

but the Prism environment does not allow:

(prism all) print par[1:5:2][0]

---

Visualizing Multiple Processes

When you print or display an object in the Prism environment, the data are shown for all processes in the pset you specify. If you do not include a pset qualifier, the current pset will be the source. Choosing the Print or Display selection from the Debug menu prints or displays data for processes in the current pset.

If there is only one process in the pset, the visualizer that is displayed is no different from the visualizer you would see in the scalar mode of the Prism environment.

If the pset contains more than one process, the Prism environment adds a dimension to the visualizer. The extra dimension represents the processes in the set. For example, if the variable is scalar, the Prism environment displays a one-dimensional array that represents the value of the variable in each process. If you are printing a one-dimensional array, the Prism environment uses a two-dimensional visualizer.

For C programs, axis 0 represents the processes. For Fortran 77 programs, the highest-numbered axis represents the processes.

The Prism environment can aggregate data from multiple processes only if the expression has the same size and number of dimensions in each process; if it doesn't, the Prism environment prints an error message.

In the example shown in FIGURE 5-20, the variable board is an 8x8 array (representing a chess board); the current pset contains four processes. Therefore, the Prism environment displays a three-dimensional visualizer. Axis 0 represents the processes. The figure shows the values of board in the first process in the set. You drag the white bar in the slider portion of the data navigator to display the values in the other processes in the set. (Note that, for a two-dimensional Fortran array, where axis 3 would represent the processes, you might want to rearrange the display axes so that axis 3 is on the slider. You can do this by clicking in the box to the left of the slider and changing the number to a 3.)

 FIGURE 5-20 Visualizer in the Prism Environment (Threshold Representation)

To Find Out the Value and Process Number for an Element

Shift-click on the element.

Printing to the history region or in the commands-only mode of the Prism environment works the same way. Axis 0 represents the processes. Here is a portion of the history-region output for the data shown below:

(prism all) print board board = process 0 (0,0,0:4) 4 1 0 3 0 (0,0,5:7) -1 0 -4 (0,1,0:4) 2 1 0 0 0 (0,1,5:7) 0 -1 0 (0,2,0:4) 3 1 0 0 0 (0,2,5:7) 2 -1 -3 (0,3,0:4) 5 0 0 0 -1 (0,3,5:7) 0 0 -5 (0,4,0:4) 4 0 0 -2 0 (0,4,5:7) 0 0 -6 (0,5,0:4) 0 1 0 0 0 (0,5,5:7) 0 -1 0 (0,6,0:4) 0 1 0 0 0 (0,6,5:7) 0 -1 0 (0,7,0:4) 6 -1 0 0 0 (0,7,5:7) 0 -1 -4 process 1 (1,0,0:4) 4 1 0 3 0 (1,0,5:7) -1 0 -4 (1,1,0:4) 2 1 0 1 0 ...

The elements of axis 0 do not necessarily correspond to the numbers of the processes they represent. For example, if you were visualizing a variable in pset
(1, 3, 5, 7), element 0 of axis 0 would represent process 1, element 1 would represent process 3, and so forth.

The Prism environment provides a Cycle visualizer window you can use to display the values of a variable in the cycle pset. See The cycle Pset for more information.

To Open a Cycle Visualizer Window

Type

(prism all) print variable on cycle

The Prism environment displays a window containing the value of variable in the current process of the current pset. If you then issue the cycle command or otherwise cycle through the members of the cycle pset, this window automatically updates to display the value of x in the next member of the set. This provides a convenient way of examining a particular variable in a series of processes.

---

Visualizing MPI Message Queues

The Prism MPI queue visualizer allows you to examine message queues created by your Sun MPI program. The visualizer shows you the status of messages generated by nonblocking send and receive routines that have not been reaped by a call to MPI_Test or MPI_Wait.

By showing you the state of the queue, detailing the messages that have not completed, the Prism environment gives you clues regarding where your program's logic can be tuned.

The Prism queue visualizer also shows you unexpected receive routines, indicating performance or correctness problems:

• Performance - An unexpected receive indicates the receipt of a message before a posted matching receive; you might receive an extra copy of the message.
• Correctness - An unexpected receive can arise due to an intended receive's not having been posted or having been posted incorrectly, such as with the wrong tag. The program could deadlock due to errors.

In addition to viewing the status of messages, you can also view the contents of the messages themselves to ensure that the correct data was transmitted.

---

Note - The Prism environment does not display blocking sends and receives on message queues. If a blocking routine such as an MPI_Send hangs your program, you can use the Prism environment to display a stack backtrace to find the problem, showing the MPI_Send present on the stack. The Prism environment also does not display MPI generalized requests.

---

To Launch the MPI Queue Visualizer

Choose the MPI Msgs selection under the Prism Debug menu.

This selection is available only when a program linked to the Sun MPI library has been loaded into the Prism environment. See FIGURE 5-21 for an example.

Each row of messages displayed in the message queue window corresponds to a process rank, numbered from zero. The following sections describe how each part of the MPI queue visualizer window affects the display of messages.

To Select the Queue to Visualize

Choose an item from the View menu.

This selects the queues to visualize. You can view three classes of MPI queues for each rank:

• Posted Sends
• Posted Receives
• Unexpected Receives

You can view queues only when a rank has stopped. Otherwise, the visualizer displays the label running for that rank. Prism reevaluates the queue every time the rank stops.

To Zoom Through Levels of Message Detail

Click the Zoom buttons to navigate through four levels of message detail.

By default, the MPI queue visualizer opens at zoom level three. Examples of the zoom levels are illustrated in FIGURE 5-21 through FIGURE 5-24.

FIGURE 5-21 shows a single pixel per message. This zoom level is useful when examining very large MPI jobs.

 FIGURE 5-21 Queue Visualizer at Zoom Level One

FIGURE 5-22 shows a simple box per message. The size of the box increases with the size of the message.

 FIGURE 5-22 Queue Visualizer at Zoom Level Two

FIGURE 5-23 shows a single label on a message. Clicking the buttons on the Show menu toggles the labels. Label choices are Source/Destination and Tag.

 FIGURE 5-23 Queue Visualizer at Zoom Level Three

FIGURE 5-24 shows the entire message.

 FIGURE 5-24 Queue Visualizer at Zoom Level Four

To Control the Values of Message Labels

Click the toggle buttons under Show on the MPI queue visualizer.

This controls the value of the message labels:

• Select Source/Dest to show the source or destination rank for the message.
• Select Tag to show the MPI tag of the message.

Clicking the Show toggle buttons affects the display of messages at zoom level three only.

To Sort Messages

Choose selections from the Sort Rows By and Sort Cols By option menus.

These sort messages by row or by column using the criteria listed in TABLE 5-2 and TABLE 5-1.

TABLE 5-1 Row Sort Criteria

Sort Criteria	Description
Rank	Sort rows from the smallest to the largest process rank (the default).
Message Count	Sort by the number of messages posted.
Message Volume	Sort by the sum of the sizes, in bytes, of all messages for each rank.

TABLE 5-2 Column Sort Criteria

Sort Criteria	Description
Order posted	Sort messages by the order in which messages are posted by the MPI program, with the earliest posted on the left. This is the default. The use of MPI send operations for transmitting large messages might queue and dequeue the message several times once the rendezvous begins. In such cases, the posted order seen in the visualizer will, at some point, no longer match the programmatic order. At present there is no way to distinguish such messages.
Source/Destination	Sort by the source rank for receives and the destination rank for sends.
Tag	Sort by the messages' tag values.
Size	Sort by size in bytes, from small to large.
Communicator	Sort by communicator address.
Protocol	Group messages sent with the same transport protocol. Protocols are loopback, shared memory, RSM, and TCP.

The MPI queue visualizer does not scale message labels to exactly correspond to the size of the messages they represent. Collections of labels of small messages can appear disproportionately large when compared to the label of a single, very large message, even when the number of bytes in the single large message exceeds the total size of the collection of smaller messages.

To Display Message Fields

Click an individual message.

This opens the Message dialog box, shown in FIGURE 5-25.

 FIGURE 5-25 Message Dialog Box

Interpreting Message Dialog Fields

The fields in the Message dialog box are described in TABLE 5-3.

TABLE 5-3 Message Dialog Box Fields

Field Name	Description
Buffer	The address of the message.
Size	The length (in bytes) of the message.
Tag	The MPI tag argument passed in the call to post the message.
Comm	The name of the MPI communicator in which the message belongs, or the communicator's address if it is unnamed. Click on the Communicator View button to display the Communicator dialog box.
To	The rank of the destination of the message. Prism displays this field only for posted sends.
From	The rank of the sender of the message. Prism displays this field only for posted receives or unexpected receives.
Protocol	The implementation method by which the message has been sent. Possible values are: loopback, shared memory, RSM, and TCP.
Datatype	The MPI data type of the message, with the size of a single data type element in bytes. If this is a user-defined data type, click on the Data Type View button to display the Data Type dialog box. See To Display Data Types for more information about the Data Type dialog box.The View button is available only for user-defined data types.
Contents	The contents of the message. Click on the triangular button to open or close the contents area. Click on More repeatedly to scroll through the message.

When the Message dialog box displays a posted receive, it displays the value of the buffer address as null (indicating that no buffer has been allocated) and disables the Contents button.

When the Message dialog box displays an unexpected receive, it shows the delivered message with no data type. This characteristic is due to MPI design, since a posted receive declares the data type. Here too, the Contents button is disabled, and the visualizer displays the value of the buffer address as null.

Displaying Communicator Data

The Prism environment displays MPI Communicators in the Communicators region of the MPI queue visualizer window. The visualizer does not display all the communicators that have been created in an MPI program; rather, it displays only communicators referenced by currently posted messages. Thus, if no messages are visible, the visualizer displays no communicators.

The Prism environment displays as many as three distinct communicators. Each communicator is color coded, and messages are drawn using the color of their communicator. If more than three communicators are present, then the excess are grouped together under a single color labeled Others.

To Change Communicator Colors

Set the following X resources in the Prism application defaults file:

• Prism.comm1Color
• Prism.comm2Color
• Prism.comm3Color
• Prism.commOtherColor

For information about modifying values in the Prism applications defaults file, see Changing Prism Environment Defaults.

To Display Communicator Data

Press any of the Communicator buttons.

This reveals the Communicator dialog box.

 FIGURE 5-26 Communicator Dialog Box

FIGURE 5-26 shows the Communicator dialog box, which includes the information described in TABLE 5-4.

TABLE 5-4 Communicator Dialog Box Fields

Field Name	Description
Name	Name of the communicator.
Address	The address of the communicator
Fortran handle	The Fortran identifier for the communicator, if defined. Built-in communicators such as MPI_COMM_WORLD have predefined Fortran handles. Other communicators are assigned a Fortran handle only if they are used in a Fortran subroutine.
Topology	The options are: Cartesian - Communicators created using MPI_Cart_create Graph - Communicators created using MPI_Graph_create None - All others
Size	The number of ranks
Remote size	Shown only for intercommunicators; the size of the remote group (the number of ranks). For information about intercommunicators, see the MPI_Intercomm_create man page.
Ranks	The list of ranks. This may be annotated with job identifiers if the communicator was created via an MPI client/server rendezvous or an MPI_Spawn. The ranks displayed for a communicator are relative to MPI_COMM_WORLD, rather than relative to the communicator's parent.

To Display Data Types

Click on the Datatype View button in a Message dialog box.

FIGURE 5-27 shows the Data Type dialog box.

 FIGURE 5-27 Data Type Dialog Box

The fields in the Data Type dialog box are described in TABLE 5-5.

TABLE 5-5 Data Type Dialog Box Fields

Field name	Description
Type	The description of the data type, such as struct or contiguous
Address	The address of the corresponding MPI_Datatype object in the MPI program
Size	The size in bytes of a single element of this data type
Contiguous	An indication that the bytes of this data type are contiguous and may be sent or received without any intermediate packing or unpacking. If the data type is not contiguous, the label changes to Non-contiguous
Additional information	Additional information that is specific to the data type, representing arguments that were passed to MPI to create the data type. This can include offsets, block sizes, pointers to other data types, and so forth. In this example, Displacement, Blocklength, and Oldtype refer to arguments the programmer used when creating the MPI struct data type. Click on buttons that name other data types to display the Data Type dialog box for that other type

---

Displaying MPI Message Queue Text

You can use the mpimsgs command to display (in text format) message queues created by a Sun MPI program. The Prism environment displays the messages in the output window, sorting the messages by rank. The fields of each message are displayed, including message size, tag, to (or from), comm (communicator), protocol, and data type.

Specify send to view Posted Sends, recv to view Posted Receives, or urecv to view Unexpected Receives. Specify the verbose option to display more details about the communicator and to display the contents of the message. For example,

(prism all) mpimsgs send verbose pset foo

The following example shows a typical message with the verbose option enabled,

Queues for Rank 0:   ** 6 Posted Sends: # 0: size = 40 tag = 101 to = 0 comm: name = MPI_COMM_WORLD fortran handle = 1 topology = none size = 4 ranks = 0:3 protocol = loopback data type = int contents:   0 1 2 3 4 5 6 7 8 9

---

Displaying and Visualizing Sun S3L Arrays

In a multiprocess Sun MPI program, a parallel array is an array whose elements may be distributed among the processes of the program. The Prism environment can extract the global dimensionality and distribution information from these arrays and manipulate them as single entities. For the purpose of this discussion, arrays that are not distributed (arrays that belong in their entirety to a single process) are referred to as regular arrays.

Sun S3L's parallel array syntax is based on array handles, which define the properties of the parallel array.

By default, the Prism environment recognizes an array handle as a simple variable. In Fortran 77 and Fortran 90, the array handle is a variable of type integer*8. In C, the array handle is type S3L_array_t.

The following examples assume the code in CODE EXAMPLE 5-1:

CODE EXAMPLE 5-1 S3L Array Demonstration Program

c c Copyright (c) 1998, by Sun Microsystems, Inc. c All rights reserved c program test_prism_s3l c include 's3l/s3l-f.h' c c In f77 programs, s3l arrays are integer*8 c integer*8 a c integer*4 ext(2),local(2),ier c c Initialize the S3L library and the prism/s3l interface. c call s3l_init(ier)   c c Declare a parallel S3L array of size 2 x 3, c with the second dimension distributed. c ext(1) = 2 ext(2) = 3   local(1) = 1 local(2) = 0   call s3l_declare(a,2,ext,S3L_float,local,S3L_USE_MALLOC,ier)   c c Initialize the array randomly by using S3L_rand_lcg c   call s3l_rand_lcg(a,123456,ier) w = 1.0 c c free the resources associated with the parallel S3L array   call s3l_free(a,ier)   c finalize the S3L library.   call s3l_exit(ier) c stop end

Note that, before using the type command, the whatis command reports that the Sun S3L array handle, a, has been declared an integer*8.

To Display the Data Type of an Array Handle

Type

(prism all) whatis array-handle

This shows that the array handle, a, is a variable of type integer*8:

(prism all) whatis a integer*8 a

To Create an S3L Parallel Array

Type

(prism all) type data-type array-handle

This identifies array-handle as a Sun S3L parallel array and specifies its basic data type. Basic data types are int, float, double, complex8, and complex16.

The example below executes the type command, associating the Sun S3L handle, a, with the data type, float, the same type used to declare the element type of the Sun S3L array in your program:

(prism all) type float a "a" defined as "float a"

To Display and Visualize Sun S3L Parallel Arrays

Type

(prism all) print array_handle

or

(prism all) display array_handle

At this point, the Prism environment recognizes a as a Sun S3L array. You could now use the Prism environment's print command to display the values of a, as illustrated in the following example:

(prism all) print a a = (0:1,0) 0.000000 1.000000 (0:1,1) 0.1000000 1.100000 (0:1,2) 0.2000000 1.200000

In all respects, you could use a as you would use any array in the Prism environment. In the following example, you use a as an array variable:

(prism all) assign a=9 (prism all) print a a = (0:1,0) 9.000000 9.000000 (0:1,1) 9.000000 9.000000 (0:1,2) 9.000000 9.000000

Sun S3L arrays are distributed across multiple processes, with all processes having the same global view of the array. Since a has the same content for all processes, the Prism environment prints the values of the array only once.

However, when the Prism environment prints a regular array, it prints the values of the array separately for each process or pset. For regular arrays, the values of the array can differ in each process, since every process has its own copy.

In the following example, larr is a regular array with each process having its own copy of the array:

(prism all) print larr larr = Pset 0 (1:2,1,1) 0.000000 1.000000 (1:2,2,1) 0.1000000 1.100000 (1:2,3,1) 0.2000000 1.200000 Pset 1 (1:2,1,2) 0.000000 1.000000 (1:2,2,2) 0.1000000 1.100000 (1:2,3,2) 0.2000000 1.200000 (prism all) assign larr=larr*5 pset 0 (prism all) print larr larr = Pset 0 (1:2,1,1) 0.000000 5.000000 (1:2,2,1) 0.5000000 5.500000 (1:2,3,1) 1.000000 6.000000 Pset 1 (1:2,1,2) 0.000000 1.000000 (1:2,2,2) 0.1000000 1.100000 (1:2,3,2) 0.2000000 1.200000

The Prism environment also prints expressions involving Sun S3L parallel arrays only once, unless they include a variable in the user program. The following example shows the S3L array, a, in an expression that does not include any other variables. Since the values of a are the same for all processes, its contents are printed only once.

(prism all) print 10* a - 1 10* a - 1 = (0:1,0) -1.000000000000000 9.000000000000000 (0:1,1) 0.00000000000000000 10.00000023841858 (0:1,2) 1.000000029802322 11.00000047683716 (prism all) print a a = (0:1,0) 0.000000 1.000000 (0:1,1) 0.1000000 1.100000 (0:1,2) 0.2000000 1.200000

However, if you use a Sun S3L array in an expression that includes a variable, the Prism environment replicates the array on each process and then evaluates the array separately on each process. The following example adds the variable w to a. The Prism environment prints the results for both processes.

(prism all) print w w = (1:2) 0 0 (prism all) print a+w a+w = Pset 0 (0:1,0,1) 0.000000000000000 1.000000000000000 (0:1,1,1) 0.1000000014901161 1.100000023841858 (0:1,2,1) 0.2000000029802322 1.200000047683716 Pset 1 (0:1,0,2) 0.000000000000000 1.000000000000000 (0:1,1,2) 0.1000000014901161 1.100000023841858 (0:1,2,2) 0.2000000029802322 1.200000047683716

To Visualize the Layouts of S3L Parallel Arrays

Type

(prism all) print layout arrayname

This returns the numbers of the nodes on which the data elements of an S3L array are located. In the following example, the print layout command is used with array a:

(prism all) print layout a layout (a) = a = (0:1,0) 0 0 (0:1,1) 0 0 (0:1,2) 1 1

where a is an S3L array. You can use the Fortran 90 array-section syntax described in Using Array-Section Syntax in C Arrays to specify a range of elements within an S3L array.

To Print or Display an S3L Array Using the layout Intrinsic

Type

(prism all) print layout(arrayname) on window as representation

This creates a visualizer that is the same size and shape as S3L array arrayname. The visualizer displays the rank of the process that is holding each value.

Note that you can specify any visualizer representation--for example, text, dither, or colormap--to display the layout graphically.

Prism 7.0 Software User's Guide

817-0088-10

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