test

Prism 6.0 User's Guide

Chapter 3 Loading and Executing a Program

This chapter describes how to load and run programs within the Prism environment.

For this chapter, you should already have an executable program that you want to run within Prism. You can also develop a new program by calling up an editor within Prism; see Chapter 8, Editing and Compiling Programs. See the following sections:

Loading a Program

Before you can execute or debug a program in Prism, you must first load the program into Prism. You can load only one program at a time.

As described in Chapter 2, Using Prism, you can load a program into Prism by specifying its name as an argument to the prism command. If you don't use this method, you can load a program once you are in Prism by using one of the methods discussed next.

From the Menu Bar

Choose the Load selection from the File menu. (It is also by default in the tear-off region.) A dialog box appears, as shown in Figure 3-1.

Figure 3-1 Load Program Filter

Graphic

To load a program, you can simply double-click on its name, if the name appears in the Programs scrollable list. Or, you can put its path name into the Selection box, then click on Load. To put the file's path name into the Selection box, you can either type it directly in the box or click on its name in the Programs list. The Programs list contains the executable programs in your current working directory; see " Changing the Current Working Directory".

Use the Load-Program Filter box to control the display of file names in the Programs list; the box uses standard Solaris filters. For example, you can click on a directory in the Directories list if you want to change to that directory. But the Programs list does not update automatically to show the programs in the new directory. Instead, the filter changes to directory-name/*, indicating that all files in directory-name are to be displayed. Click on Filter to display the file names of the programs. Or simply double-click on the directory name in the Directories list to display the programs in the directory.

If you want to use a different filter, you can edit the Load-Program Filter box directly. For example, change it to directory-name/prog* to display only programs beginning with prog.

Click on Cancel or press the Esc key if you decide not to load a program.

From the Command Window

Issue the load command on the command line, with the name of the executable program as its argument. For example,

load myprogram

The program you specify is loaded.

What Happens When You Load a Program

Once a program is successfully loaded:

You can now issue commands to execute and debug this program.

If Prism can't find the source file, it displays a warning message in the command window. Choose the Use selection from the File menu to specify other directories in which Prism is to search; see " Creating a Directory List for Source Files".

Loading Subsequent Programs

You can load only one program at a time. If you have a program loaded and you want to switch to a new program, simply load the new program; the previously loaded program is automatically unloaded. If you want to start fresh with the current program, issue the reload command with no arguments; the currently loaded program is reloaded into Prism.

Associating a Core File With a Loaded Program

As mentioned in Chapter 2, Using Prism, you can have Prism associate a core file with a program by specifying its name after the name of the program on the prism command line.

You can also do this by loading the program and then issuing the core command, specifying the name of the corresponding core file as its argument.

Note that the core command is not available in MP Prism. Instead, you must specify the name of the process core file from the Prism command line; as below. 

% prism a.out corefile

In either case, Prism reports the error that caused the core dump and loads the program with a stopped status at the location where the error occurred. You can then work with the program within Prism. You can, for example, examine the stack and print the values of variables. You cannot, however, continue execution from the current location.

Examining Local Process Core Files

You can use Prism to examine a core file created for a message-passing program. To do this, specify the core file name on the command line, after the name of the executable program. For example, 

% prism a.out corefile

When Prism comes up, you can issue commands like where and print to inspect the state of your process at the time the core dump was taken. But note these restrictions:

Attaching to a Running Process

Prism enables you to attach to running processes of scalar programs and message-passing programs.

Attaching to a Running Process (Serial Program)

As described in " Attaching to a Process", you can load a running process into Prism by specifying the name of the executable program and the process ID of the corresponding running process on the Prism command line.

You can also attach to a running process from within Prism.

Note -

To attach to the running process of a serial program, the process must be running on the same node as Prism.

To attach to a running process from within Prism:

  1. Find out the process's ID by issuing the Solaris command ps.

  2. Load the executable program for the process into Prism.

  3. Issue the attach command on the Prism command line, using the process's process ID as the argument.

With either method of attaching to the process, the process is interrupted; a message is displayed in the command window giving its current location, and its status is stopped. You can then work with the program in Prism as you normally would. The only difference in behavior is that it does not do its I/O in a special Xterm window; see " Program I/O".

To detach from a running process, issue the command detach from the Prism command line. The process continues to run in the background from the point at which it was stopped in Prism; it is no longer under the control of Prism. Note that you can detach any process in Prism via the detach command, not just processes that you have explicitly attached.

Note -

Use the kill command to terminate the process or job (rather than releasing it to run in the background) currently running within Prism.

Attaching to a Running Message-Passing Process

You can load the processes of a message-passing job into Prism.

To attach to running message-passing programs, obtain the job ID of the processes

For example, using the LSF environment: 

host4-0 54 =>bjobs
JOBID USER STAT QUEUE FROM_HOST EXEC_HOST JOB_NAME SUBMIT_TIME
15232 jay  RUN  hpc   host4-0   host4-0   chess    Sep
24 13:35 host4-1

  1. Specify the job ID of the processes (not an individual process ID) on the prism command line, after the name of the executable program.

  2. Use the -n (or -np, -c, -p) option when you request that Prism attach to a job. Without one of these options, Prism assumes that the ID number is a process ID rather than a job ID.

For example, 

% prism -n 2 mpiprog 15232

starts MP Prism and attaches to the running processes in job 15232. See the LSF Batch User's Guide for further information about bjobs. See the Sun MPI 4.0 User's Guide: With CRE for further information about mpps.

You can also attach to a single process of a message-passing program by specifying its process ID, just as you do in scalar Prism; see " Attaching to a Running Process (Serial Program)". If you do this, however, you won't be able to view or debug what is happening in the other processes.

If you attach to a program under MP Prism, your job will be automatically detached from MP Prism if you quit or run another program. You can detach from the job by issuing the detach command from within Prism.

MP Prism only lets you detach when all the processes in the job are stopped. The detach operation itself sets them all running again, outside control of the debugger.

Executing a Program in Scalar Prism

To execute a program, you must first load it, as described in " Loading a Program". Once you start the program running, you can step through it, and interrupt and continue execution.

See " Loading a Program" for information on executing a program in MP Prism.

Running a Program

To run a program:

If you have command-line arguments, choose the Run (args) selection from the Execute menu. A dialog box is displayed, in which you can specify any command-line arguments for the program; see Figure 3-2. If you have more arguments than fit in the input box, they scroll to the left. Click on the Run button to start execution.

Figure 3-2 Run (args) Dialog Box

Graphic

When the program starts executing, the status region displays the message running.

You can continue to interact with Prism while a program is running, but many features will be unavailable. Unavailable selections are grayed out in menus. If you issue a command that cannot be executed while the program is running, it is queued until the program stops.

Program I/O

Prism by default creates a new window for a program's I/O. This window persists across multiple executions and program loads, giving you a complete history of your program's input and output. If you prefer, you can display I/O in the Xterm from which you invoked Prism; see " Resources".

Stepping Through a Program

You must begin execution by choosing Run or Run (args) (or issuing run from the command line). If execution stops before the program finishes (for example, because you have set a breakpoint), you can then step through the program, as described in this section. To step through the entire program, set a breakpoint at the first executable line, and then run to it. (See " Setting Breakpoints" for information on setting breakpoints.)

From the menu bar:

The execution pointer moves to indicate the next line to be executed.

From the command window:

If execution takes considerable time--for example, because Next calls a long-running function--the status changes to running. You can use Prism, but many commands will be unavailable. Unavailable selections are grayed out in menus.

Interrupting and Continuing Execution

To interrupt execution, choose Interrupt from the Execute menu or type Control-c. The status changes to interrupted, and the source window updates to show the point at which execution stopped.

To continue execution after a program has been interrupted, choose Continue from the Execute menu, or issue the cont command from the command line. (Or you can step through the program, as described above.)

Continue and Interrupt are available by default in the tear-off region.

Status Messages

Prism displays the status messages before, during, and after the execution of a program, as listed in Table 3-1.

Table 3-1 Status Messages

Message  

Meaning 

error

Prism has encountered an internal error. 

connected

Prism has connected to other nodes to work on a message-passing program. 

connecting

Prism is connecting to other nodes in order to work on a message-passing program. 

initial

Prism is starting up without a program loaded. 

interrupted

The program has been interrupted. 

loading

Prism is loading a program. 

not started

The program is loaded but not yet started. 

running

The program is running. 

stopped

The program has stopped at a breakpoint or signal. 

terminated

The program has run to completion and the process has gone away. 

Executing a Program in MP Prism

You start execution of a program in MP Prism just as you do in scalar Prism--by issuing the run command or choosing the Run or Run (args) selection from the Execute menu. See "Executing a Program in Scalar Prism". You can also attach to an already-running program using the attach command, as described in " Attaching to a Running Message-Passing Process". Prism displays the program I/O in the same fashion as described in " Program I/O".

Note the key advantage of using Prism with a Sun MPI program: The Sun MPI program is viewed as a single parallel program; all processes of the parallel program are visible from within a single Prism session. You do not have to attach a separate debugger to each Sun MPI process.

Stepping and Continuing Through a Program

In MP Prism, menu actions such as Step and Next apply to the processes belonging to the current set of processes. The MP Prism term for a set of processes is pset. MP Prism supports several kinds of pre-defined psets as well as user-defined psets. For information about psets, see "Using Psets in MP Prism".

Scalar Prism (like other debuggers) waits for a step, next, or cont command to finish executing before letting you issue most other commands. This behavior is unnecessarily restrictive in MP Prism, however; therefore, if one process or set of processes is executing code, you can still issue commands that affect other processes. For example, you can switch to a different pset and start or stop execution of its processes.

Interrupting and Waiting for Processes

It is useful in debugging message-passing programs to wait for a specific process or set of processes to stop executing, or to be able to interrupt execution of individual processes. Because message-passing programs are distributed among multiple, separate machines, extra consideration must be given to controlling selected subsets of processes. MP Prism therefore provides the commands interrupt and wait.

Use the interrupt command to forcibly interrupt execution of a specified process or set of processes. The MP Prism term for a set of processes is pset. For information about psets, see "Using Psets in MP Prism".

For example,

interrupt pset 0

interrupts execution of process 0.

interrupt pset running

interrupts all processes in the predefined process set (pset) running.

Using the interrupt command resets the predefined pset interrupted so that it includes the newly interrupted processes. Processes leave this pset when they continue execution.

In MP Prism, the Interrupt selection from the Execute menu interrupts processes in the current pset that are running.

Use the wait command to wait for a specified process or processes to stop execution. A process is considered to have stopped if it has entered the done, break, interrupted, or error state.

There are two versions of the wait command:

(prism notx) wait every

waits for every process in the pset notx to stop. The current process will be whatever it would normally be; see " Current Pset". This is the default behavior of the wait command.

wait any pset foo

waits for the first process in pset foo to stop.

There are corresponding Wait Any and Wait Every selections in MP Prism's Execute menu. They apply to the processes of the current set.

You can end the wait by

Note that, if you prefer that step and next commands wait for processes to finish executing before letting you issue other commands, you can issue them along with the wait command. For example,

step; wait

This says: Execute the next line, then wait for all processes in the current pset to finish execution.

If you use this command sequence frequently, you can provide an alias for it via the alias command. Prism provides the default alias contw for these commands:

cont; wait

Execution Pointer

In Scalar Prism, the > symbol in the line-number region points to the next line to be executed; see " Using the Line-Number Region". In a message-passing program, there can be multiple execution points within the program. MP Prism marks all the execution points for the processes in the current set by a > in the line-number region (or a * if the current source position is the same as the current execution point). Shift-click on this symbol to display a pop-up window that shows the process(es) for which the symbol is the execution pointer.

Finding Out Execution Status

Issue the pstatus command to find out the execution status of processes. You can find out the execution status of the members of the specified process set (pset) if you issue pstatus with a pset qualifier. For information about psets and pset qualifiers, see "Using Psets in MP Prism".

Without a pset qualifier, pstatus displays the execution status of the members of the current set. For example,

(prism all) pstatus
process 0: running
process 1: stopped in procedure "pawn_moves" at "chess.c":49
process 2: interrupted in procedure "construct_move" at "chess.c":1187
process 3: interrupted in procedure "rook_check" at "chess.c":746

Setting MPI_INIT_TIMEOUT

Sun MPI has timeouts built into the software to help detect when there are problems starting an MPI job. However, you may trigger these timeouts erroneously when you are debugging programs, such as when using Prism. You should disable the timeouts prior to using Prism on a Sun MPI program. You can use the environment variable MPI_INIT_TIMEOUT to lengthen or disable the timeout time. When you set MPI_INIT_TIMEOUT to a positive integer, the timeout value is set to that time in seconds. When you set MPI_INIT_TIMEOUT to 0 or a negative integer, the timeout is disabled. The default value is 600 seconds (10 minutes).

For example, to disable timeouts (in a C shell): 

% setenv MPI_INIT_TIMEOUT -1

Again in a C shell, to set timeouts to 5 minutes: 

% setenv MPI_INIT_TIMEOUT 300

Executing a Program in the Commands-Only Mode of MP Prism

When you issue the run command to execute a program in the commands-only mode of MP Prism, the program starts up in the background. If the program needs to read terminal input, you must then issue the fg command at the (prism) prompt to run the program in the foreground. You cannot execute Prism commands while the program is executing in the foreground. To have the program run in the background and regain the (prism) prompt, type Control-z.

Quitting

Issuing the quit command terminates the debugging session. Before quitting, MP Prism will kill your debugged process if it was started with run, or it will detach from it if you previously attached.

Using Psets in MP Prism

MP Prism provides you with the capability of viewing your message-passing program at the level of an individual process, a group of processes, or all processes that make up the program. For example, at times it may be useful to look at the status of process 0, because you have reason to believe there is a problem with it. At other times you may want to look at all processes that have encountered an error, or at all processes in which the value of a particular variable exceeds a certain number.

These groups of processes, typically chosen because they have some useful characteristic in common, are referred to as psets (pronounced "pee-sets"). MP Prism treats a pset as a unit; for example, you can use the name of a pset as a qualifier for many commands. The command is then executed for each process in the set. For example, you can set a breakpoint that applies only to processes in a specified pset. (See " Using Psets in Commands" for more information.) In addition, many graphical actions apply only to processes in a pset.

If you don't need to view your program at the level of an individual process or a subset of processes, you can also view its operation on all the processes that make up the message-passing program.

You can view psets in the Psets window, as described in " Using the Psets Window" and " Viewing the Contents of Psets".

Note -

MP Prism assigns a logical ID number to each process that makes up a message-passing program. For example, in an 8-process message-passing program, the individual processes would be numbered 0-7. These numbers are used to identify processes in psets. Do not confuse these numbers with the Solaris process IDs (pids) assigned by the system to the message-passing processes.

As described in " Predefined Psets", Prism provides predefined psets for certain standard groups of processes; for example, the set of all processes in an error state is a predefined pset. You can also define your own psets, as described in " Defining Psets"; for example, you can define a pset to be those processes in which variable x is greater than 0. " Deleting Psets" describes how to delete psets.

If you don't specify a pset as a qualifier to a command (that can take a pset qualifier), the command is executed on the current pset; many graphical actions also apply to processes in the current set. The concept of the current pset is described in " Current Pset". " The Current Process" describes the current process, which is a distinguished process within a pset.

" The cycle Pset" describes the cycle pset, which is a predefined pset with special characteristics.

Using the Psets Window

You can use the Psets window to view the current status of the processes in your program and to perform many of the actions associated with psets.

To display the window:

Figure 3-3 shows the Psets window for a 16-process message-passing program, including several user-defined psets.

Figure 3-3 Psets Window

Graphic

The various components of the window are described in detail in later sections. Here is a brief overview:

Predefined Psets

MP Prism provides the predefined psets described below.

Except for the pset all, these sets are dynamic; that is, as a program executes, Prism automatically adjusts the contents of each set to reflect the program's current state.

In addition, there are two set names that have special meaning: current and cycle. They are discussed in " Current Pset" and " The cycle Pset", respectively.

Defining Psets

You can create psets in MP Prism. This section describes the syntax of pset creation.

Syntax for Defining a Pset

This section describes the syntax you can use to specify a pset. As described below, you can assign a name to a pset you specify using this syntax; this provides a useful shorthand for complicated pset specifications.

First, to specify a pset as an argument to a command:

To apply a command to a specific pset, use the pset keyword, followed by a process specification. Put this pset clause at the end of the command line (but before an on window clause, if any). Thus,

print x pset error

prints the values of the variable x in the predefined pset error. (See " Visualizing Multiple Processes in MP Prism" for a discussion of printing variables in MP Prism.)

To specify your own pset as part of this pset clause:

Specify an individual process number. An individual process can constitute a pset. Thus,

print x pset 0

prints the value of x in process 0.

Specify the name of a pset. Name a pset using the define pset command, as described in the section "Naming Psets," below. Thus,

print x pset foo

prints x in the processes you have defined to be members of pset foo.

Specify a list of process numbers. Separate the numbers with commas. Thus,

print x pset 0, 4, 7

prints x in processes 0, 4, and 7.

Ranges and strides are allowed. Use a colon between two process numbers to indicate a range. Use a second colon to indicate the stride to be used within this range. Thus,

print x pset 0:10

prints x in processes 0 through 10. And

print x pset 0:10:2

prints x in processes 0, 2, 4, 6, 8, and 10.

You can also combine comma-separated process numbers and range specifications. For example,

print x pset 0, 1, 3:5, 8

prints x in processes 0, 1, 3, 4, 5, and 8.

Specify a union, difference, or intersection of psets. To specify the union of two psets, use the symbol +, |, or ||. For example, 

print x pset 0:2 + 8:10

prints x in processes 0, 1, 2, 8, 9, and 10.

print x pset foo | bar

prints x in processes that are members of either pset foo or pset bar.

Prism evaluates the pset expression from left to right. If a process returns true for the first part of the expression, it is not evaluated further. In the above example, if a process is a member of foo, its value of x is printed; Prism does not check its membership in bar.

Use a minus sign to specify the difference of two psets. For example,

print x pset stopped - foo

prints x in all processes that are stopped except those belonging to the pset foo.

To specify the intersection of two psets, use the &, &&, or * symbol. For example,

print x pset foo & bar

prints x in processes that are members of both pset foo and pset bar. If a process returns false for the first part of the expression, it is not evaluated further. In the above example, if a process is not a member of foo, Prism doesn't bother checking its membership in bar; it won't be printed in any case.

Prism must evaluate a pset expression in each process at the time the command is executed; the processes must be stopped for Prism to do this. The evaluation fails if any of the processes being evaluated are running. Using the predefined pset stopped on the left of an intersection expression is a useful way of ensuring that a command applies only to stopped processes.

Thus,

print x pset stopped & foo

prints x only in the members of foo that are stopped.

Specify a condition to be met. Put braces around an expression that evaluates to true or false in each process. Processes in which the expression is true are part of the set.

Thus,

print x pset { y > 1 }

prints x in processes where y is greater than 1. And

print x pset all - { y == 1 }

prints x in all processes except those in which y is equal to 1.

Membership in a set defined with this syntax can change based on the current state of your program; such a pset is referred to as variable. See " Evaluating Variable Psets " to learn how to update the membership of a variable pset.

For this syntax to work, the variable must be active in all processes in which the expression is evaluated. If the variable isn't active in a process, you get an error message and the command is not executed. To ensure that the command is executed, use the intrinsic isactive in the pset definition. The expression isactive(variable) returns true if variable is on the stack for a process or is a global.

Thus, you could use this syntax to ensure that x is printed:

print x pset stopped && {isactive(x)}

Naming Psets

You can assign a name to a pset. This is convenient if you plan to use the set frequently in your Prism session.

Use the syntax described above to specify the pset. You can use any name except the names that Prism pre-defines; see " Predefined Psets". The name must begin with a letter; it can contain any alphanumeric character, plus the dollar sign ($) and underscore (_).

For example,

define pset odd 1:31:2

creates a pset called odd containing the odd-numbered processes between 1 and 31. 

define pset xon { x .NE. 0 }

defines a pset consisting of those processes in which x is not equal to 0. Note that x must be active in all processes for this syntax to work. As described above, you can use the intrinsic isactive to ensure that x is active in the processes that are evaluated. For example,

define pset xon { isactive(x) && (x .NE. 0) }

Both versions create a variable pset whose contents will change based on the value of x. See below for more discussion of variable psets. Finally, note that all processes must be stopped for this syntax to work. To ensure that the definition applies only to stopped processes, use this syntax:

define pset xon stopped && { isactive(x) && (x .NE. 0) }

Dynamic user-defined psets are deleted when you reload a program. To get a list of these psets before reloading, issue the command show psets. You can then use this list to help reissue the define pset commands. See " Viewing the Contents of Psets" for more information about show psets.

Evaluating Variable Psets

Prism evaluates the membership of a variable pset when it is defined. If no processes meet the condition (for example, because the program is not active), Prism prints appropriate error messages, but the set is defined.

Subsequently, you can re-evaluate the membership of the pset by issuing the eval pset command, specifying the name of the pset as its argument. For example,

eval pset xon

evaluates the membership of the pset xon. This causes the display for the pset to be updated in the Psets window.

Note that this evaluation will fail if:

For example, if you issue this command:

define pset foo { x > 0 }

you must make sure that all processes are stopped, and x is active on all processes, when you issue the command

eval pset foo

To ensure that the evaluation succeeds, you would need to use the more complicated syntax described above:

define pset foo stopped && { isactive(x) && (x > 0) }

This ensures that the evaluation takes place only in processes that are stopped and in which x is active.

If an evaluation fails, the membership of the pset remains what it was before you issued the eval pset command.

You can use the eval pset command in event actions; see " Events Taking Pset Qualifiers (MP Prism Only)".

Note the difference between dynamic and variable psets. The membership in both can change as a program executes. Dynamic psets are predefined sets like stopped and interrupted; Prism automatically updates their membership as the program executes. Variable psets are defined by the user, and the user must explicitly update their membership by issuing the eval pset command.

Viewing the Contents of Psets

This section describes the methods you use to display psets in MP Prism.

From the Psets Window

The easiest way to view the contents of psets is to use the Psets window.

By default, the window displays the current pset (which starts out being the predefined pset all), and the psets break, running, and error. When you create a new pset via the define pset command, that set is also displayed automatically.

The processes within a pset are numbered starting at the upper left, increasing from left to right and then jumping to the next row. You can display information about them as follows:

To display a pset, choose the Show selection from the Options menu in the Psets window This displays a list of psets; the predefined psets are at the top, followed by any user-defined set names. Click on a set name, and that set is displayed in the window.

To hide a pset, choose the Hide selection from the Options menu. Once again, this displays the list of predefined and user-defined psets. Click on a set name to remove that set from the display.

Note that hiding a pset doesn't otherwise affect its status; it still exists and can be used in commands.

Note also that there are choices All Sets and all in the Show and Hide submenus. The All Sets choice refers to all psets; the all choice refers to the predefined pset all.

If you have too many psets to be shown in the display window of the Psets window, the navigator rectangle to the right of the Cycle arrows lets you pan through the psets. The white box in the rectangle shows the position of the display area relative to all the psets that are to be displayed:

Graphic

You can either drag the box or click at a spot in the rectangle. The box moves to that spot, and the display window shows the psets in this area of the total display.

To display more psets at the same time, click on the Zoom up arrow to the right of the navigator rectangle. This reduces the size of the boxes representing the psets. Clicking on the Zoom down arrow increases the size of these boxes. By default, the boxes are at their highest zoom setting.

From the Command Line

Use the show pset command to print the contents of the pset you specify. For example, the command

show pset stopped

might produce this response:

The set contains the following processes:
0:3.

The show pset command is discussed further in " Finding Out the Current Pset".

The show psets command displays the contents and status of all psets.

(prism all) show psets
foo: 
    definition = 0:31:2
    members = 0,2,4,6,8,10,12,14,16,18,20,22,24,26,28,30
    current process = 0
break: 
    definition = break
    members = nil
    current process = (none)
done: 
    definition = done
    members = 0:31
    current process = 0
interrupted: 
    definition = interrupted
    members = nil
    current process = (none)
error: 
    definition = error
    members = nil
    current process = (none)
running: 
    definition = running
    members = nil
    current process = (none)
stopped: 
    definition = stopped
    members = nil
    current process = (none)
current: 
    definition = 6, 9, 12
    members = 6,9,12
    current process = 6
cycle: 
    definition = 6, 9, 12
    members = 6,9,12
    current process = 6
all: 
    definition = all
    members = 0:31
    current process = 12

Deleting Psets

You can delete named psets that you have defined. You cannot delete any predefined pset except cycle; see " The cycle Pset". To delete a pset:

delete pset xon

deletes the pset named xon.

See " Events Taking Pset Qualifiers (MP Prism Only)" for a discussion of the effect of deleting a pset on events that have been defined to affect the members of that set.

Current Pset

The command syntax described in " Defining Psets" lets you apply a command to a specific pset. If you don't use this syntax, the command is applied to the current pset; current is a predefined pset name in Prism. In addition, many graphical actions in MP Prism apply only to the members of the current set.

When a program is first loaded, the current pset is the default pset, all.

You can change the current pset via the Psets window or from the command line. 

pset foo

changes the current pset to foo.

You can also use the pset command with the pset-specification syntax described in " Defining Psets". For example,

pset 0:15:3

You cannot change the current pset to one that has no members. If you try to do so, nothing happens in the Psets window, and you get a message like this one in the history region of the command window:

Cannot set current pset to running -- it
is empty.

Finding Out the Current Pset

MP Prism provides many ways of finding out the current pset:

Note -

In giving examples of MP Prism commands, the (prism) prompt is used only when necessary to show the effect of a command.

To list the processes in the current pset, issue the show pset command without arguments:

(prism foo) show pset
pset 'current' is defined as 'foo'.
The set contains the following processes: 1,2.

The Psets window also displays the processes in the current pset.

Current Pset and Dynamic Psets

" Predefined Psets" described dynamic psets--predefined sets like running, stopped, and interrupted, whose contents Prism automatically updates during the execution of the program.

If you choose a dynamic pset to be the current pset, you create a static pset that consists of the processes that are members of the dynamic set at the time you issue the pset command (or otherwise choose it to be the current set). To make this clear, the (prism) prompt changes to list the processes that are members of this static set. For example, if processes 0, 1, and 13 are the only processes that are stopped, the pset command has this effect: 

(prism all) pset stopped
(prism 0:1, 13)

Output of the show pset command is explicit under these circumstances:

(prism all) pset stopped
(prism 0:1. 13) show pset
The current set was created by evaluating the pset
'stopped' once at the time when it became the current set.
The set contains the following processes: 0:1, 13.

Issuing the pset command with no arguments displays the same information.

Note that the (prism) prompt can become quite long if there are many processes in a current pset derived from a dynamic pset. By default, the prompt length is limited to 25 characters. You can change this default by issuing the set command with the $prompt_length variable, specifying the maximum number of characters to appear in the pset part of the prompt. For example, this command shortens the prompt long_pset_name to long_pset:

(prism long_pset_name) set $prompt_length=9
(prism long_pset)

Current Pset and Variable Psets

" Defining Psets" describes how to create variable psets--user-defined psets whose membership can change in the course of program execution. You use the eval pset command to update the membership of a variable pset. If you make a variable pset your current set, its membership is determined by the most recent eval pset command you have executed for the set. If you have not executed an eval pset command to update the set's membership, the membership continues to be what it was when you created the set.

The Current Process

Each pset has a current process. The current process has a variety of uses in MP Prism:

By default, the current process is the lowest-numbered process in the set. You can change this as described below.

(prism all) process 2
The current process is now 2.

Issue the process command without any arguments to print the current process of the current pset.

When you change a current process, by any of the methods described above, the pset keeps this new current process until you explicitly change it. That is, if you switch to a different current set, then switch back to the original set, the original set will still have the same current process.

The cycle Pset

In debugging a message-passing program, you may often want to look in turn at each process within a pset--for example, to see what the problem is for each process in the error pset. The cycle pset provides you with a convenient way of doing this.

You create a cycle pset out of an existing pset. If the existing pset is dynamic, the cycle pset is statically fixed when you create it. You can then cycle through each process in this pset to examine it in turn.

By default, the cycle pset is equivalent to the current pset. You can set it to some other pset via the define pset command, as described in " Defining Psets". For example,

(prism all) define pset cycle foo

copies foo into the cycle pset.

You can cycle through the processes in the cycle pset as follows:

Clicking on a Cycle arrow does this:

Note that changing the cycle pset erases any previous cycling information. For example, if you do the following:

  1. Make foo the current set and cycle partway through it.

  2. Make bar the current set.

  3. Once again make foo the current set.

    Then you start at the beginning again when you cycle through the members of foo.

  4. From the source-window pop-up menu - Choose Cycle from this menu to advance to the next member of the cycle pset.

Cycle Visualizer Window

MP Prism includes a Cycle window type for visualizing data. When you print a variable's value to the Cycle window, the value changes to that of the variable in the new process whenever you cycle through the members of the cycle pset. For more information, see " Visualizing Multiple Processes in MP Prism".

Using Psets in Commands

As mentioned at the beginning of "Using Psets in MP Prism", some commands can take a pset as a qualifier; they are listed at the end of this section. Put this qualifier after any arguments to the command, but before the optional on window syntax that specifies the window in which output is to be displayed. A command with a pset qualifier applies only to the processes in the set. If you omit the qualifier, the command applies to the processes in the current set.

Thus,

stop at 12 pset error

sets a breakpoint at line 12 for the processes in pset error.

where pset 0:10 on dedicated

displays the Where graph for processes 0 through 10. See " Where Graph" for a description of the Where graph. 

trace at 12 if x > 10

creates a trace event for the members of the current pset.

Note that this last command applies only to the members of the current pset. To apply it to all processes, use the syntax

trace at 12 if x > 10 pset all

Many commands, of course, cannot logically take a pset qualifier. You get an error message if you try to issue one of these commands with a pset qualifier.

Here are the Prism commands that can take a pset qualifier: 

address/
assign
call
catch
cont, contw
display
ignore
interrupt
next, nexti
print
pstatus
return
step, stepi
stop, stopi
trace, tracei
wait
whatis
where

Using MP Prism With Sun MPI Client/Server Programs

You can use a Prism session to debug only one Sun MPI job at a time. Therefore, if an MPI job spawns or connects to another job (using MPI_Comm_accept and MPI_Comm_connect to implement client/server communication, for example), the current Prism session nonetheless has control only of the parent or server MPI job. It cannot debug the children or clients of that job. To debug a child or client program it is necessary to launch an additional Prism session.

To use Prism to debug a Sun MPI program, the program must be written in the SPMD (single process, multiple data) style--that is, all processes that make up a Sun MPI program must be running the same executable.

Note -

MPI_Comm_spawn_multiple can create multiple executables with only one job id; therefore, you cannot use Prism to debug jobs with different executables that have been spawned with this command.

Choosing the Current File and Function

Prism uses the concepts of current file and current function.

The current file is the source file currently displayed in the source window. The current function is the function or procedure displayed in the source window. You might change the current file or function if, for example, you want to set a breakpoint in a file that is not currently displayed in the source window, and you don't know the line number at which to set the breakpoint.

In addition, changing the current file and current function changes the scope used by Prism for commands that refer to line numbers without specifying a file, as well as the scope used by Prism in identifying variables; see " How Prism Chooses the Correct Variable or Procedure" for a discussion of how Prism identifies variables. The scope pointer (-) in the line-number region moves to the current file or current function to indicate the beginning of the new scope.

To change the current file:

Figure 3-4 File Window

Graphic

To change the current function or procedure:

By default, the Func window displays only functions in files compiled with the -g switch. To display all functions in the program, click on the Select All Functions button. The button then changes to Show -g Functions; click on it to return to displaying only the -g functions.

Note that if the function you choose is in a different source file from the current file, changing to this function also has the effect of changing the current file.

Creating a Directory List for Source Files

If you have moved a source file, or if for some other reason Prism can't find it, you can explicitly add its directory to Prism's search path.

Figure 3-5 Use Dialog Box

Graphic