Prism 7.0 Software User's Guide

817-0088-10

Contents

Preface

1. Prism Environment

Overview

The Prism Environment's Operating Modes

MP Mode Summary

Look and Feel of the Prism Programming Environment

Loading and Executing Programs

Debugging

Visualizing Data

Editing and Compiling

Obtaining Online Help and Documentation

Customizing the Prism Programming Environment

2. Using the Prism Environment

Before Entering the Prism Environment

Supported Languages and Compilers

Compiling and Linking Your Program

Combining Compiler Options

Setting Up Your Working Environment

DISPLAY Variable

Starting the Prism Environment

Starting in MP Program Mode

Specifying Multiple Processes

Specifying One Process per Available CPU

Specifying a Threaded View of Programs

Specifying a Nonthreaded View of Programs

Specifying a Threaded View for a Single-Process Program

Running MP Prism in the Background

Attaching to a Running MP Job

Starting in Serial Programming Mode

Attaching to a Running Serial Program

After Starting the Prism Environment

Loading a Multiprocess Program From Within the Prism Environment

After Loading a Program

The Prism Prompt

Enabling Support for Spawned MPI Processes

Specifying Which Spawned Executables to Debug

Attaching to a Job or Process

Associating a Program or Process With a Core File

Specifying X Toolkit Options

Specifying Input and Output Files

Specifying Runtime Environment Options

Passing Command-Line Options to Secondary Sessions

Executing Commands Within the Prism Environment

Using a Mouse

Using Keyboard Alternatives to the Mouse

Issuing Commands

Using the Menu Bar

Keyboard Accelerators

Using the Source Window

Moving Through the Source Code

Selecting Text

Splitting the Source Window

Using the Line-Number Region

Using the Command Window

Using the Command Line

Using the History Region

Redirecting Output

Logging Commands and Output

To Specify the Name of a Log File.

To Append the Log to an Existing File

To Turn Off Logging

Rerunning a Prism Session That Was Saved to a Log File

Writing Expressions in the Prism Environment

How the Prism Environment Chooses the Correct Variable or Procedure

Using Qualified Names

Using Fortran Intrinsic Functions in Expressions

Using C Arrays in Expressions

Using Array-Section Syntax in C Arrays

Hints for Detecting NaNs and Infinities

Using Fortran 90 Generic Procedures

Issuing Solaris Commands

To Issue Solaris Commands From Within the Prism Environment

Changing the Current Working Directory

Setting and Displaying Environment Variables

Killing Processes Within the Prism Environment

To Kill a Process or Job Running Within the Prism Environment

To Kill a Spawned Prism Session

Leaving the Prism Environment

To Exit a Single-Job Prism Session

To Quit a Spawned Prism Session

3. Loading and Executing a Program

Loading a Program

To Load a Program From the Menu Bar

To Load a Program From the Command Window

What Happens When You Load a Program

Associating a Core File With a Loaded Program

To Associate a Core File With a Loaded Program

To Examine the Core File of a Local Process

Attaching to a Running Message-Passing Process

To Attach to a Running Message-Passing Process

To Attach to Multiple Jobs When Starting Prism

Detaching From a Running Process

Executing a Program in the Prism Environment

To Run a Program

Program I/O

Status Messages

Stepping and Continuing Through a Program

Waiting for and Interrupting Processes

Execution Pointer

Rerunning Spawned Prism Sessions

Controlling Programs With the Commands-Only Interface

Using Psets in the Prism Environment

Using the Psets Navigator

Using the Psets Window

Predefined Psets

Defining Psets

Naming Psets

Combining Named Psets and Pset Expressions

Viewing Pset Contents From the Psets Window

Viewing Pset Contents From the Command Line

Deleting Psets

The Current Pset

Current Pset and Predefined Psets

Current Pset and Variable Psets

The Current Process

Scope in the Prism Environment

The cycle Pset

Cycle Visualizer Window

Hiding Threads From Psets

Using Psets in Commands

To Use a Pset Qualifier

Using Unbounded Psets in Commands

Using Snapshots of Unbounded Psets in Commands

Referring to Nonexistent Thread Identifiers

Using the Prism Environment With Sun MPI Client/Server Programs

Choosing the Current File and Function

To Change the Current File

To Change the Current Function or Procedure

Creating a Directory List for Source Files

To Add a Directory to the Search Path

4. Debugging a Program

Overview of Events

Using the Event Table

Description of the Event Table

Adding an Event

Deleting an Existing Event

Editing an Existing Event

Disabling and Enabling Events

Saving Events

Events Taking Pset Qualifiers

Events and Dynamic Psets

Events and Variable Psets

Actions in Events

Events and Deleted Psets

Setting Breakpoints

Using the Line-Number Region

What Happens in a Split Source Window

Using the Event Table and the Events Menu

Setting a Breakpoint Using Commands

Examples of the stop Command

Tracing Program Execution

Using the Event Table and Events Menu

Using the Command Window

Displaying and Moving Through the Call Stack

To Display the Call Stack

Moving Through the Call Stack

Displaying the Where Graph

Panning and Zooming in the Where Graph

Combining Debug and Optimization Options

Interpreting Interaction Between an Optimized Program and the Prism Environment

Accessing Variables in Optimized Routines

Debugging Spawned Sun MPI Processes

Debugging Spawned Sessions Using the Commands-Only Interface

Prism Commands With Special Functions in Spawned Sessions

Error Conditions Arising From Spawned Sessions

Examining the Contents of Memory and Registers

To Display Memory

To Display the Contents of Registers

5. Visualizing Data

Overview of Data Visualization

Printing and Displaying

Visualization Methods

Data Visualization Limits

Choosing the Data to Visualize

To Print or Display a Variable or Expression at the Current Program Location

To Print or Display From the Source Window

To Print or Display From the Events Menu

To Print or Display From the Event Table

To Print or Display From the Command Window

To Print or Display the Contents of a Register

To Set the Context

To Specify the Radix

Working With Visualizers

Using the Data Navigator in a Visualizer

Using the Display Window in a Visualizer

Using the Options Menu

Updating and Closing the Visualizer

Saving, Restoring, and Comparing Visualizers

To Save the Values of a Variable

To Restore the Data

To Compare the Data

Visualizing Structures

Expanding Pointers

More About Pointers in Structures

Augmenting the Information Available for Display

Printing the Type of a Variable

To Print the Type of a Variable From the Menu Bar

To Print the Type of a Variable From the Source Window

To Print the Type of a Variable From the Command Window

What Is Displayed

Changing the Radix of Data

Printing Pointers as Array Sections

To Print an Array by Section

To View a Pointer as a One-Dimensional Array

To Dereference an Array of Pointers

To Cast Pointers

Visualizing Multiple Processes

To Find Out the Value and Process Number for an Element

To Open a Cycle Visualizer Window

Visualizing MPI Message Queues

To Launch the MPI Queue Visualizer

To Select the Queue to Visualize

To Zoom Through Levels of Message Detail

To Control the Values of Message Labels

To Sort Messages

To Display Message Fields

Interpreting Message Dialog Fields

Displaying Communicator Data

Displaying MPI Message Queue Text

Displaying and Visualizing Sun S3L Arrays

To Display the Data Type of an Array Handle

To Create an S3L Parallel Array

To Display and Visualize Sun S3L Parallel Arrays

To Visualize the Layouts of S3L Parallel Arrays

To Print or Display an S3L Array Using the layout Intrinsic

6. Editing and Compiling Programs

Editing Source Code

To Start the Default Editor on the Current Source File

Using the make Utility

Creating the Makefile

Using the Makefile

7. Getting Help

Prism Online Help Systems

To Get Help in the Prism Environment

Using the Browser-Based Help System

Choosing Selections From the Help Menu

Getting Help on Using the Mouse

Obtaining Help From the Command Window

Obtaining Online Documentation

Viewing Manual Pages

8. Customizing the Prism Programming Environment

Initializing the Prism Environment

Customizing MP Prism Mode

Using the Tear-Off Region

Adding Menu Selections to the Tear-Off Region

Adding Prism Commands to the Tear-Off Region

Creating Aliases for Commands and Variables

To Create an Alias for a Prism Command

To Remove an Alias

To Set Up an Alternative Name for a Variable or Expression

Changing Prism Resource Defaults

To Launch the Prism Customize Utility

Changing a Resource Setting

Resource Descriptions

Where the Prism Environment Stores Your Changes

Changing Prism Environment Defaults

Adding Prism Resources to the X Resource Database

Specifying the Editor and Its Placement

Specifying the Window for Error Messages

Changing the Text Fonts

Changing Colors

Changing Keyboard Translations

Changing Keyboard Translations in Text Widgets

Changing General Motif Keyboard Translations

Changing Xterm Use With I/O

Changing the Way the Prism Environment Signals an Error

Changing the make Utility to Use

Changing How the Prism Environment Treats Stale Data in Visualizers

Specifying a Different Browser for Displaying Help

Changing the Way the Prism Environment Handles Fortran 90 Generic Procedures

9. Troubleshooting

Avoid Using the -xs Compiler Option

Keep .o Files after Compilation

Expect a Pause After Issuing the First run Command

Monitor Your Use of Color Resources

Expect Only Stopped Processes to Be Displayed in the Where Graph

Use Only the MP Mode of the Prism Environment to Load MPI Programs

Verify That /opt/SUNWlsf/bin Is in Your PATH

MP Prism Environment Freezes on Startup

A. Commands-Only Mode of the Prism Environment

B. C++ and Fortran 90 Support

C. The Scalar Mode of the Prism Environment

To Launch the Prism Environment in Scalar Mode

To Attach To a Running Process From Within the Prism Environment