This appendix contains the manual pages for the PE tools commands discussed throughout this book. Each manual page is organized into the sections listed below. The sections always appear in the same order, but some appear in all manual pages while others are optional.
NAME
pdbx - Invokes the pdbx debugger, which is the command-line debugger built on dbx.
SYNOPSIS
pdbx [program [program_options]] [poe options] [-c command_file] [-d nesting_depth] [-I directory [-I directory]...] [-F] [-x] pdbx -a poe process id [limited poe options] [-c command_file] [-d nesting_depth] [-I directory [-I directory]...] [-F] [-x] pdbx -h
The pdbx command invokes the pdbx debugger. This tool is based on the dbx debugger, but adds function specific to parallel programming.
FLAGS
Because pdbx runs in the Parallel Operating Environment, it accepts all the flags supported by the poe command.
| Note: | poe uses the PATH environment variable to find the program, while pdbx does not. |
See the poe manual page in IBM Parallel Environment for AIX: Operation and Use, Volume 1, Using the Parallel Operating Environment for a description of these options. Additional pdbx flags are:
Lazy reading mode is useful when debugging large executable files, or when paging space is low. With lazy reading mode on, only the required symbol table information is read upon initialization of the remote dbx sessions. Because all symbol table information is not read at dbx startup time when in lazy reading mode, local variable and related type information will not be initially available for functions defined in other files. The effect of this can be seen with the whereis command, where instances of the specified local variable may not be found until the other files containing these instances are somehow referenced.
DESCRIPTION
pdbx is the Parallel Environment's command-line debugger for parallel programs. It is based, and built, on the AIX debugging tool dbx.
pdbx supports most of the familiar dbx subcommands, as well as additional pdbx subcommands.
To use pdbx for interactive debugging you first need to compile the program and set up the execution environment as you would to invoke a parallel program with the poe command. Your program should be compiled with the -g flag in order to produce an object file with symbol table references. It is also advisable to not use the optimization option, -O. Using the debugger on optimized code may produce inconsistent and erroneous results. For more information on the -g and -O compiler options, refer to their use on other compiler commands such as cc and xlf. These compiler commands are described in IBM AIX Version 4 Commands Reference
pdbx maintains dbx's command-line interface and subcommands. When you invoke pdbx, the pdbx command prompt displays to mark the start of a pdbx session.
When using pdbx, you should keep in mind that pdbx subcommands can either be context sensitive or context insensitive. In pdbx, context refers to a setting that controls which task(s) receive the subcommands entered at the pdbx command prompt. A default command context is provided which contains all tasks in your partition. You can, however, set the command context on a single task or a group of tasks you define. Context sensitive subcommands, when entered, only affect those tasks in the current command context. Context insensitive subcommands are not affected by the command context setting.
If you are already familiar with dbx, you should be aware that some dbx subcommands behave somewhat differently in pdbx. Be aware that:
When a task hangs (there is no pdbx prompt) you can press <Ctrl-c> to acquire control. This displays the pdbx subset prompt pdbx-subset([group | task]), and provides a subset of pdbx functionality:
You can change the subset of tasks to which context sensitive commands are directed. Also, you can understand more about the current state of the application, and gain control of your application at any time, not just at user-defined breakpoints.
At the pdbx subset prompt, all input you type at the command line is intercepted by pdbx. All commands are interpreted and operated on by the home node. No data is passed to the remote nodes and STDIN is not given to the application. Most commands at the pdbx subset prompt produce information about the application and then produce another pdbx subset prompt. The exceptions are the halt, back, on, and quit commands. For more information, see "Context Switch when Blocked".
ENVIRONMENT VARIABLES
Because the pdbx command runs in the Parallel Operating Environment, it interacts with the same environment variables associated with the poe command. See the poe manual page in IBM Parallel Environment for AIX: Operation and Use, Volume 1, Using the Parallel Operating Environment for a description of these environment variables. As indicated by the syntax statements, you are also able to specify poe command line options when invoking pdbx. Using these options will override the setting of the corresponding environment variable, as is the case when invoking a parallel program with the poe command. Additional variables are:
If no linenumber is specified (and the colon is omitted), the sourcefile field is taken to be a function or subroutine name, and a "stop in" is performed on entry to the function.
If MP_DEBUG_INITIAL_STOP is undefined, the default stop location will be the first executable line in the function main. For Fortran source programs, it will be the first executable line in the main program.
EXAMPLES
To start pdbx, first set up the execution environment as you would for the poe command, and then enter:
pdbx
After initialization, you should see the prompt:
pdbx(all)
FILES
.pdbxinit (Initial commands for pdbx in ./ or $HOME)
.pdbxinit.process_id.task_id (Initial commands for the individual dbx tasks)
For more information on .pdbxinit see Table 2 and "Reading Subcommands From a Command File".
| Note: | The following temporary files are created during the execution of
pdbx in attach mode:
|
RELATED INFORMATION
Commands: dbx(1), mpcc(1), mpcc_r(1), mpCC(1), mpCC_r(1), mpxlf(1), mpxlf_r(1), pedb(1), poe(1)
alias [alias_name [alias_string]]
The alias subcommand creates aliases for pdbx subcommands. The alias_name parameter is the alias being created. The alias_string is the pdbx subcommand for which you wish you define an alias, and is a single pdbx subcommand. If used without parameters, the alias subcommand displays all current aliases. If only alias_name is specified, it lists the alias name and the alias string that is assigned to it. This subcommand is context insensitive.
A number of default aliases are provided by pdbx. They are:
Apart from these, aliases are only known during the current pdbx session. They are not saved between pdbx sessions, and are lost upon exiting pdbx.
| Note: | One method for reusing aliases is to define them in .pdbxinit to allow them to be created for each pdbx execution. The default aliases are available after the partition has been loaded. |
Aliases can also be removed using the unalias subcommand for the pdbx command.
alias mas on master alias w on workers
This will allow you to switch the command context between the master and workers groups by typing:
mas
to switch context to the "master" group, or:
w
to switch context to the "workers" group.
alias p
alias
Related to this subcommand is the pdbx unalias subcommand.
assign <variable> = <expression>
The assign subcommand assigns the value of an expression to a variable.
pdbx(all) assign x = 5
pdbx(all) assign x = y
pdbx(all) assign z = 'z'
pdbx(all) assign B = false
pdbx(all) assign Y = "Hello World"
pdbx(all) set $unsafeassign
attach all attach <task_list>
The attach subcommand is used to attach the debugger to some or all the tasks of a given poe job.
Individual tasks are separated by spaces. A range of tasks may be separated by a dash or a colon. For example, the command attach 2 4 5-7 would mean to attach to tasks 2,4,5,6, and 7.
attribute attribute [<attribute_number> ...]
The attribute subcommand displays information about the user thread, mutex, or condition attributes objects defined by the attribute_number parameters. If no parameters are specified, all attributes objects are listed.
For each attributes object listed, the following information is displayed:
Related to this subcommand are the condition mutex and thread subcommands.
back
The back command returns you to a pdbx prompt when you were already at a pdbx subset prompt. You can use the command if you want the application to continue as it was before <Ctrl-c> was issued. Also, you can use it at the pdbx subset prompt if all of the nodes are checked into "debug ready" state, and you want to do full pdbx processing.
The back command is only valid at the pdbx subset prompt.
call <procedure> (<parameters>)
The call subcommand runs a procedure specified by the procedure parameter. The return code is not printed. If any parameters are specified, they are passed to the procedure being run.
The program stack will be returned to its previous state after the procedure specified by call completes. Any side effect of the procedure, such as global variable updates, will remain.
Related to this subcommand is the print subcommand.
case [default | mixed | lower | upper]
The case subcommand changes how pdbx interprets symbols. The default handling of symbols is based on the current language. If the current language is C, C++, or undefined, the symbols are not folded. If the current language is Fortran, the symbols are folded to lowercase. Use this command if a symbol needs to be interpreted in a way not consistent with the current language.
Entering the case subcommand with no parameters displays the current case mode. The parameters include:
catch catch <signal_number> catch <signal_name>
The catch subcommand with no arguments prints all signals currently being caught. If a signal is specified, pdbx will trap the signal before it is sent to the program. This is useful when the program being debugged has signal handlers.
When the program encounters a signal that is being caught to the debugger, a message stating which signal was detected is shown, and the pdbx prompt is displayed. To have the program continue and process the signal, issue the cont subcommand with the signal option. Other execution control commands and the cont subcommand without the signal option will cause the program to behave as if it had never encountered the signal.
A signal may be specified by number or name. Signal names are by default case insensitive and the "SIG" prefix is optional.
By default all signals are caught except SIGHUP, SIGKILL, SIGPIPE, SIGALRM, SIGCHLD, SIGIO and SIGVIRT. When debugging a threaded application (including those compiled with mpcc_r, mpCC_r or mpxlf_r), all signals are caught except SIGHUP, SIGKILL, SIGALRM, SIGCHLD, SIGIO and SIGVIRT.
Related to this subcommand are the ignore and cont subcommands.
condition condition [<condition_number> ...] condition [wait | nowait]
The condition subcommand displays the current state of all known conditions in the process. Condition variables to be listed can be specified through the <condition_number> parameters, or all condition variables will be listed. Users can also choose to display only condition variables with or without waiters by using the wait or nowait options.
The information listed for each condition is as follows:
Related to this subcommand are the attribute mutex and thread subcommands.
cont cont <signal_number> cont <signal_name>
The cont subcommand allows execution to continue from where the program last stopped, until either the program finishes or another breakpoint is reached. If a signal is specified, it is given to the program, and the process continues as though it received the signal. If a signal is not specified, the process continues as though it had not been stopped.
Related to this subcommand are the catch, ignore, step, stepi, next, and nexti subcommands.
dbx dbx_subcommand
The dbx subcommand is context sensitive and will pass the specified dbx_subcommand directly to the dbx running on each task in the current context with no pdbx intervention. The specified dbx_subcommand can be any valid dbx subcommand.
| Note: | The pdbx command uses dbx to access tasks on individual nodes. In many cases, pdbx saves and requires its own state information about the tasks. Some dbx commands will circumvent the ability of pdbx to maintain accurate state information about the tasks being debugged. Therefore, use the dbx subcommand with caution. In general, dbx subcommands used to display information will have no adverse side effects. The dbx subcommands clear, detach, edit, multproc, prompt, run, rerun, screen, and the sh subcommand with no arguments are currently unsupported under pdbx and should not be used. |
To display the events that the dbx running as task 1 recognizes, enter:
on 1 dbx status
Related to this subcommand is the dbx command.
delete [event_list] | [*] | [all]
The delete subcommand removes events (breakpoints and tracepoints) of the specified event numbers. An event list can be specified in the following manner. To indicate a range of events, enter the first and last event numbers, separated by a colon or dash. To indicate individual events, enter the numbers, separated by a space or comma. You can specify " * ", which deletes all events that were created in the current context. You can also specify "all", which deletes all events, regardless of context.
The event number is the one associated with the breakpoint or tracepoint. This number is displayed by the stop and trace subcommands when an event is built. Event numbers can also be displayed using the status subcommand.
The output of the status command shows the context from which the event was created. Event numbers are unique to the context in which they were set. Keep in mind that, in order to remove an event, the context must be on the appropriate task or task group.
Assume the command context is set on task 1 and the output of the status subcommand is:
1:[0] stop in celsius all:[0] stop at "foo.c":19 all:[1] trace "foo.c":21
To delete all these events, you would do one of the following:
on 1 delete 0 on all delete 0,1 OR on 1 delete 0 on all delete * OR delete all
Related to this subcommand are the pdbx status, stop, and trace subcommands.
detach
The detach subcommand detaches pdbx from all tasks that were attached. This subcommand causes the debugger to exit but leaves the poe application running.
dhelp dhelp <dbx_command>
The dhelp command with no arguments displays a list of dbx commands about which detailed information is available.
If you type dhelp with an argument, information will be displayed about that command.
| Note: | The partition must be loaded before you can use this command, because it invokes the dbx help command. It is also required that a task be in "debug ready" state to process this command. |
Related to this subcommand is the pdbx help subcommand.
<address> / [<mode>] <address> , <address> / [<mode>] <address> / [<count>] [<mode>]
The display memory subcommand, which does not have a keyword to initiate the command, displays a portion of memory controlled by the address(es), count(s) and mode(s) specified.
If an address is specified, the display contents of memory at that address is printed. If more than one address or count locations are specified, display contents of memory starting at the first <address> up to the second <address> or until <count> items are printed. If the address is ".", the address following the one most recently printed is used. The mode specifies how memory is to be printed. If it is omitted the previous mode specified is used. The initial mode is "X".
The following modes are supported:
down [count]
The down subcommand moves the current function down the stack the number of levels specified by count. The current function is used for resolving names. The default for the count parameter is one.
The up and down subcommands can be used to navigate through the call stack. Using these subcommands to change the current function also causes the current file and local variables to be updated to the chosen stack level.
Related to this subcommand are the up, print, dump, func, file, and where commands.
dump dump <procedure> dump . dump <module name>
The dump subcommand prints the names and values of variables in a given procedure, or the current one if nothing is specified. If the procedure given is ".", then all active variables are printed. If a module name is given, all variables in the module are printed.
Related to this subcommand are the up, down, print, and where subcommands.
file [file]
The file subcommand changes the current source file to the file specified by the file parameter. It does not write to that file. The file parameter can specify a full path name to the file. If the parameter does not specify a path, the pdbx program tries to find the file by searching the use path. If the parameter is not specified, the file subcommand displays the name of the current source file. The file subcommand also displays the full or relative path name of the file if the path is known.
Related to this subcommand is the func subcommand.
func [procedure]
The func command changes the current function to the procedure or function specified by the procedure parameter. If the procedure parameter is not specified, the default current function is displayed. Changing the current function implicitly changes the current source file to the file containing the new function. The current scope used for name resolution is also changed.
Related to this subcommand is the file subcommand.
goto <line_number> goto"<filename>" : <line_number>
The goto subcommand causes the specified source line to be run next. Normally, the source line must be in the same function as the current source line. To override this restriction, use the set subcommand with the $unsafegoto flag.
gotoi address
The gotoi subcommand changes the program counter address to the address specified by the address parameter.
group add group_name task_list group delete group_name [task_list] group change old_group_name new_group_name group list [group_name]
The group subcommand groups individual tasks under a common name for easier setting of command context. It can add or delete a group, add or delete tasks from a group, change the name of a group, list the tasks in a group, or list all groups. This subcommand is context insensitive.
Provide a group name that is no longer than 32 characters which starts with an alphabetic character, and is followed by any alphanumeric character combination.
To indicate a range of tasks, enter the first and last task numbers, separated by a colon or dash. To indicate individual tasks, enter the numbers, separated by a space or comma. Individual task identifiers and ranges can also be combined in creating the desired task_list.
| Note: | Group names "all", "none", and "attached" are reserved group names. They are used by the debugger and cannot be used in the group add or group delete commands. However, the group "all" or "attached" can be renamed using the group change command, if it currently exists in the debugging session. |
The add action adds one or more tasks to a new or existing task group. The task_list specified is a list of task identifiers to be included in the new or existing group.
The delete action deletes an existing task group, or deletes one or more tasks from an existing task group. The task_list, if specified, is a list of task identifiers to be deleted from the new or existing group.
The change action changes the name of a task group from old_group_name to new_group_name.
The list action displays the task members for the
group_name specified, or for all task groups. The task
identifiers will be followed by a one-letter status indicator.
| N | Not loaded | the remote task has not yet been loaded with an executable. |
| S | Starting | the remote task is being loaded with an executable. |
| D | Debug ready | the remote task is stopped and debug commands can be issued. |
| R | Running | the remote task is in control and executing the program. |
| X | Exited | the remote task has completed execution. |
| U | Unhooked | the remote task is executing without debugger intervention. |
| E | Error | the remote task is in an unknown state. |
Consider an application running as five tasks numbered 0 through 4.
group add first 0
The pdbx debugger responds with:
1 task was added to group "first".
group add rest 1:4
The pdbx debugger responds with:
4 tasks were added to group "rest".
group change all johnny
The pdbx debugger responds with:
Group "all" has been renamed to "johnny"
group list
The pdbx debugger responds with:
johnny 0:D 1:D 2:D 3:D 4:D first 0:D rest 1:D 2:D 3:D 4:D
group delete first
To delete members 1, 2 and 3 from group "rest", enter:
group delete rest 1 2 3
or
group delete rest 1-3
The pdbx debugger responds with:
Task: 1 was successfully deleted from group "rest". Task: 2 was successfully deleted from group "rest". Task: 3 was successfully deleted from group "rest".
group list
The pdbx debugger responds with:
allTasks 0:R 1:D 2:D 3:U 4:U 5:D 6:D
7:D 8:D 9:D 10:D 11:D
evenTasks 0:R 2:D 4:U 6:D 8:D 10:R
oddTasks 1:D 3:U 5:D 7:D 9:D 11:R
master 0:R
workers 1:D 2:D 3:U 4:U 5:D 6:D 7:D
8:D 9:D 10:R 11:R
Related to this subcommand is the pdbx on subcommand.
halt [all]
By using the halt command, you interrupt all tasks in the current context that are running. This allows the debugger to gain control of the application at whatever point the running tasks happen to be in the applicaton. To a dbx user, this is the same as using <Ctrl-c>. This command works at the pdbx prompt and pdbx subset prompt. If you specify "all" with the command, all running tasks, regardless of context, are interrupted.
| Note: | At a pdbx prompt, the halt command never has any effect without "all" specified. This is because by definition, at a pdbx prompt, none of the tasks in the current context are in "running" state. |
The halt all command at the pdbx prompt affects tasks outside of the current context. Messages at the prompt show the task numbers that are and are not interrupted, but the pdbx prompt returns immediately because the state of the tasks in the current context is unchanged.
When using halt at the pdbx subset prompt, the pdbx prompt occurs when all tasks in the current context have returned to "debug ready" state. If some of the tasks in the current context are running, a message is presented.
Related to this subcommand are the pdbx tasks and group list subcommands.
help - display subjects help <subject> - display details
The help command with no arguments displays a list of pdbx commands and topics about which detailed information is available.
If you type help with one of the help commands or topics as the argument, information will be displayed about that subject.
Related to this subcommand is the pdbx dhelp subcommand
hook
The hook subcommand allows you to reestablish control over all tasks in the current command context that have been unhooked using the unhook subcommand. This subcommand is context sensitive.
on 2 hook
or
on 2 hook
on rest hook
or
on rest hook
Listing the members of the task group "all" using the list action of the group subcommand will allow you to check which tasks are hooked and which are unhooked. Enter:
group list all
The pdbx debugger will display a list similar to the following:
0:D 1:U 2:D 3:D
Tasks marked with the letter D next to them are debug ready, hooked tasks. In this case, tasks 0, 2, and 3 are debug ready. Tasks marked with the letter U are unhooked. In this case, task 1 is unhooked.
Related to this subcommand are the dbx detach subcommand and the pdbx unhook subcommand.
ignore ignore <signal_number> ignore <signal_name>
The ignore subcommand with no arguments prints all signals currently being ignored. If a signal is specified, pdbx stops trapping the signal before it is sent to the program.
A signal may be specified by number or name. Signal names are by default case insensitive and the "SIG" prefix is optional.
All signals except SIGHUP, SIGKILL, SIGPIPE, SIGALRM, SIGCHLD, SIGIO, and SIGVIRT are trapped by default. When debugging a threaded application (including those compiled with mpcc_r, mpCC_r, or mpxlf_r), all signals except SIGHUP, SIGKILL, SIGALRM, SIGCHLD, SIGIO, and SIGVIRT are trapped by default.
The pdbx debugger cannot ignore the SIGTRAP signal if it comes from a process outside of the program being debugged.
Related to this subcommand is the catch subcommand.
list [procedure | sourceline-expression[, sourceline-expression]]
The list subcommand displays a specified number of lines of the source file. The number of lines displayed is specified in one of two ways:
| Tip: | Use on <task> list, or specify the ordered standard output option. |
In this case, the list subcommand displays lines starting a few lines before the beginning of the specified procedure and until the list window is filled.
The sourceline-expression parameter should consist of a valid line number followed by an optional + (plus sign), or - (minus sign), and an integer. In addition, a sourceline of $ (dollar sign) can be used to denote the current line number. A sourceline of @ (at sign) can be used to denote the next line number to be listed.
All lines from the first line number specified to the second line number specified, inclusive, are then displayed, provided these lines fit in the list window.
If the second source line is omitted, 10 lines are printed, beginning with the line number specified in the sourceline parameter.
If the list subcommand is used without parameters, the default number of lines is printed, beginning with the current source line. The default is 10.
To change the number of lines to list by default, set the special debug program variable, $listwindow, to the number of lines you want. Initially, $listwindow is set to 10.
To list the lines 1 through 10 in the current file, enter:
list 1,10
To list 10, or $listwindow, lines around the main procedure, enter:
list main
To list 11 lines around the current line, enter:
list $-5,$+5
To list the next source line to be executed, issue:
pdbx(all) list $ 0: 4 char johnny = 'h'; 1: 4 char johnny = 'h';
To just show 1 task, since both are at the same source line:
pdbx(all) on 0 list $ 0: 4 char johnny = 'h';
To create an alias to list just task 0:
pdbx(all) alias l0 on 0 list
To list line 5:
pdbx(all) l0 5 0: 5 char jessie = 'd';
To list lines around the procedure sub:
pdbx(all) l0 sub
0: 21
0: 22 /* return ptr to sum of parms, calc and sub1 */
0: 23 int *sub(char *s, int a, int k)
0: 24 {
0: 25 int *tmp;
0: 26 int it = 0;
0: 27 int i, j;
0: 28
0: 29 /* test calc */
0: 30 i = 1;
0: 31 j = i*2;
To change the next line to be listed to line 25:
pdbx(all) move 25
To list the next line to be listed minus two:
pdbx(all) l0 @-2 0: 23 int *sub(char *s, int a, int k)
Related to this subcommand is the dbx list subcommand.
listi [procedure | at SourceLine | address [,address]]
The listi subcommand displays a specified set of instructions from the current program counter, depending on whether you specify procedure, source line, or address.
The listi subcommand with the procedure parameter lists instructions from the beginning of the specified procedure until the list window is filled.
Using the at SourceLine flag with the listi subcommand displays instructions beginning at the specified source line and continuing until the list window is filled. The SourceLine variable can be specified as an integer, or as a file name string followed by a : (colon) and an integer.
Specifying a beginning and ending address with the listi subcommand, using the address parameters, displays all instructions between the two addresses.
If the listi subcommand is used without flags or parameters, the next $listwindow instructions are displayed. To change the current size of the list window, use the set $listwindow=Value command.
load program [program_options]
The load subcommand loads the specified application program to be debugged on the task(s) in the current context. You can optionally specify program_options to be passed to the application program. pdbx will look for the program in the current directory unless a relative or absolute pathname is specified. The load subcommand is context sensitive. All tasks in the partition must have an application program loaded before other context sensitive subcommands can be issued. This subcommand enables you to individually or selectively load programs. If you wish to load the same program on all tasks in the partition, the name of the program can be passed as an argument to the pdbx command at startup.
To load the program "mpprob1" on all tasks in the current context, enter:
load mpprob1
map
The map subcommand displays characteristics for each loaded portion of the application. This information includes the name, text origin, text length, data origin, and data length for each loaded module.
mutex mutex [<number> ...] mutex [lock | unlock]
The mutex subcommand displays the current status of all known mutual exclusion locks in the process. Mutexes to be listed can be specified through the <number> parameter, or all mutexes will be listed. Users can also choose to display only locked or unlocked mutexes by using the lock or unlock options.
The information listed for each mutex is as follows:
Related to this subcommand are the attribute condition and thread subcommands.
next [number]
The next subcommand runs the application program up to the next source line. The number parameter specifies the number of times the subcommand runs. If the number parameter is not specified, next runs once only.
The difference between this and the step subcommand is that if the line contains a call to a procedure or function, step will stop at the beginning of that block, while next will not.
If you use the next subcommand in a multi-threaded application program, all the user threads run during the operation, but the program continues execution until the running thread reaches the specified source line. By default, breakpoints for all threads are ignored during the next command. This behavior can be changed using the $catchbp set variable. If you wish to step the running thread only, use the set command to set the variable $hold_next. Setting this variable may result in deadlock, since the running thread may wait for a lock held by one of the blocked threads.
Related to this subcommmand are the nexti, step, stepi, return, cont, and set subcommands.
nexti [number]
The nexti subcommand runs the application program up to the next instruction. The number parameter specifies the number of times the subcommand will run. If the number parameter is not specified, nexti runs once only.
The difference between this and the stepi subcommand is that if the line contains a call to a procedure or function, stepi will stop at the beginning of that block, while nexti will not.
If you use the nexti subcommand in a multi-threaded application program, all the user threads run during the operation, but the program continues execution until the running thread reaches the specified machine instruction. If you wish to step the running thread only, use the set command to set the variable $hold_next. Setting this variable may result in deadlock since the running thread may wait for a lock held by one of the blocked threads.
Related to this subcommand are the next, step, stepi, return, cont, and set subcommands.
on {group_name | task_id} [subcommand]
The on subcommand sets the current command context used to direct subsequent subcommands at a specific task or group of tasks. The context can be set on a task group (by specifying a group_name) or on a single task (by specifying a task_id).
When a context sensitive subcommand is specified, it is directed to the given context without changing the current command context. Thus, specifying the optional subcommand enables you to temporarily deviate from the command context.
| Note: | The pdbx prompt will be presented after all of the tasks in the temporary context have completed the specified command. It is possible using <Ctrl-c> followed by the back or the on command to issue further pdbx commands in the original context. |
By using the on and group subcommands, the number of subcommands issued and the amount of debug data displayed can be tailored to manageable amounts.
When you switch context using on context_name, and the new context has at least one task in the running state, a message is displayed stating that at least one task is in the running state. Thus, no pdbx prompt is displayed until all tasks in this context are in the debug ready state.
When you switch to a context where all states are in the debug ready state, the pdbx prompt is displayed immediately.
At the pdbx subset prompt, on context_name causes one of the following to happen: either a pdbx prompt is displayed; or a message is displayed indicating the reason why the pdbx prompt will be displayed at a later time. This is generally because one of the tasks is in running state. See "Context Switch when Blocked" for more information on the pdbx subset prompt.
At a pdbx prompt, you cannot use on context_name pdbx_command if any of the tasks in the specified context are running.
Assume you have an application running as 15 tasks, and the output of the group list subcommand lists the existing task groups as:
all 0:D 1:U 2:D 3:D 4:D 5:D 6:U 7:D
8:D 9:D 10:R 11:R 12:R 13:U 14:U
johnny 0:D
jessica 2:D 3:D 8:D
un 1:U 6:U 13:U 14:U
run 10:R 11:R 12:R
deb 2:D 3:D 4:D 5:D 8:D 9:D
on johnny stop at 31
The pdbx debugger responds with:
johnny:[0] stop at "ring.f":31
on jessica stop in ring
The pdbx debugger responds with:
jessica:[0] stop in ring
on johnny
The pdbx debugger responds with the prompt:
pdbx(johnny)
stop at 48 if len < 1
The pdbx debugger responds with:
johnny:[1] stop at "ring.f":48 if len < 1
on jessica status
The pdbx debugger responds with:
jessica:[0] stop in ring
on 2
The pdbx debugger responds with the prompt:
pdbx(2)
Then, enter:
trace 57
The pdbx debugger responds with:
2:[0] trace "ring.f":57
status all
The pdbx debugger responds with:
2:[0] trace "ring.f":57 johnny:[0] stop at "ring.f":48 johnny:[1] stop at "ring.f":56 if len < 1 jessica:[0] stop in ring
Related to this subcommand is the pdbx group subcommand.
print expression ... print procedure ([parameters])
The print subcommand does either of the following:
To display the value of x and the value of y shifted left two bits, enter:
print x, y << 2
To display the value returned by calling the sbrk routine with an argument of 0, enter:
print sbrk(0)
To display the sixth through the eighth elements of the Fortran character string a_string, enter:
print &a_string + 5, &a_string + 7/c
Related to this subcommand are the dbx assign and call subcommands, and the pdbx set subcommand.
quit
The quit subcommand terminates all program tasks, and ends the pdbx debugging session. The quit subcommand is context insensitive and has no parameters.
Quitting a debug session in attach mode causes the debugger and all the members of the original poe application partition to exit.
To exit the pdbx debug program, enter:
quit
registers
The registers subcommand displays the values of general purpose registers, system control registers, floating-point registers, and the current instruction register.
Registers can be displayed or assigned to individually by using the following predefined register names:
By default, the floating-point registers are not displayed. To display the floating-point registers, use the unset $noflregs command.
Notes:
return [procedure]
The return subcommand causes the program to execute until a return to the procedure, specified by the procedure parameter, is reached. If the procedure parameter is not specified, execution ceases when the current procedure returns.
/<regular_expression>[/] ?<regular_expression>[?]
The search forward (/) or search backward (?) subcommands allow you to search in the current source file for the given <regular_expression>. Both forms of search wrap around. The previous regular expression is used if no regular expression is given to the current command.
Related to this subcommand is the regcmp subroutine.
set [variable] set [variable=expression]
The set subcommand defines a value for the set variable. The value is specified by the expression parameter. The set variable is specified by the variable parameter. The name of the variable should not conflict with names in the program being debugged. A variable is expanded to the corresponding expression within other commands. If the set subcommand is used without arguments, the currently set variables are displayed.
Related to this subcommand is the unset subcommand.
sh <command>
The sh subcommand passes the command specified by the command parameter to the shell on the remote task(s) for execution. The SHELL environment variable determines which shell is used. The default is the Bourne shell (sh).
| Note: | The sh subcommand with no arguments is not supported. |
To run the ls command on all tasks in the current context, enter:
sh ls
To display contents of the foo.dat data file on task 1, enter:
on 1 cat foo.dat
skip [number]
The skip subcommand continues execution of the program from the current stopping point, ignoring the next breakpoint. If a number variable is supplied, skip ignores that next amount of breakpoints.
Related to this subcommand is the cont subcommand.
source commands_file
The source subcommand reads pdbx subcommands from the specified commands_file. The commands_file should reside on the node where pdbx was issued and can contain any commands that are valid on the pdbx command line. The source subcommand is context insensitive.
To read pdbx subcommands from a file named "jessica", enter:
source jessica
Related to this subcommand is the dbx source subcommand.
status status all
A list of pdbx events (breakpoints and tracepoints) can be displayed by using the status subcommand. You can specify "all" after this command to list all events (breakpoints and tracepoints) that have been set in all groups and tasks. This is valid at the pdbx prompt and the pdbx subset prompt.
Because the status command without "all" specified is context sensitive, it will not display status for events outside the context.
Assume the following commands have been issued, setting various breakpoints and tracepoints.
on all stop at 19 trace 21 on 0 trace foo at 21 on 1 stop in func
To display a list of breakpoints and tracepoints for tasks in the current "task 1" context, enter:
status
The pdbx debugger responds with lines of status like:
1:[0] stop in func all:[0] stop at "foo.c":19 all:[1] trace "foo.c":21
Notice that the status from the "task 0" context does not get displayed since the context is on "task 1". Also notice that event 0 is unique for the "task 1" context and the "group all" context.
To see an example of status all, enter:
status all
The pdbx debugger responds with:
0:[0] trace foo at "foo.c":21 1:[0] stop in func all:[0] stop at "foo.c":19 all:[1] trace "foo.c":21
Related to this subcommand are the pdbx stop, trace, and delete subcommands.
step [number]
The step subcommand runs source lines of the program. You specify the number of lines to be executed with the number parameter. If this parameter is omitted, the default is a value of 1.
The difference between this and the next subcommand is that if the line contains a call to a procedure or function, step will enter that procedure or function, while next will not.
If you use the step subcommand on a multi-threaded program, all the user threads run during the operation, but the program continues execution until the interrupted thread reaches the specified source line. By default, breakpoints for all threads are ignored during the step command. This behavior can be changed using the $catchbp set variable.
If you wish to step the interrupted thread only, use the set subcommand to set the variable $hold_next. Setting this variable may result in debugger induced deadlock, since the interrupted thread may wait for a lock held by one of the threads blocked by $hold_next.
| Note: | Use the $stepignore variable of the set subcommand to control the behavior of the step subcommand. The $stepignore variable enables step to step over large routines for which no debugging information is available. |
Related to this subcommand are the stepi, next, nexti, return, cont, and set commands.
stepi [Number]
The stepi subcommand runs instructions of the program. You specify the number of instructions to be executed with the number parameter. If the parameter is omitted, the default is 1.
If used on a multi-threaded program, the stepi subcommand steps the interrupted thread only. All other user threads remain stopped.
Related to this subcommand are the step, next, nexti, return, cont, and set subcommands.
stop if <condition> stop at <source_line_number> [if <condition>] stop in <procedure> [if <condition>] stop <variable> [if <condition>] stop <variable> at <source_line_number> [if <condition>] stop <variable> in <procedure> [if <condition>]
Specifying stop at <source_line_number> causes the breakpoint to be triggered each time that source line is reached.
Specifying stop in <procedure> causes the breakpoint to be triggered each time the program counter reaches the first executable source line in the procedure (function, subroutine).
Using the <variable> argument to stop causes the breakpoint to be triggered when the contents of the variable changes. This form of breakpoint can be very time consuming. For better results, when possible, further qualify these breakpoints with a source_line or procedure argument.
Specify the <condition> argument using the syntax described by "Specifying Expressions".
The stop subcommand sets stopping places called "breakpoints" for tasks in the current context. Use it to mark these stopping places, and then run the program. When the tasks reach a breakpoint, execution stops and the state of the program can then be examined. The stop subcommand is context sensitive.
Use the status subcommand to display a list of breakpoints that have been set for tasks in the current context. Use the delete subcommand to remove breakpoints.
Specifying stop at <source_line_number> causes the breakpoint to be triggered each time that source line is reached.
Specifying stop in <procedure> causes the breakpoint to be triggered each time the program counter reaches the first executable source line in the procedure (function, subroutine).
Using the <variable> argument to stop causes the breakpoint to be triggered when the contents of the variable changes. This form of breakpoint can be very time consuming. For better results, when possible, further qualify these breakpoints with a source_line or procedure argument.
Specify the <condition> argument using the syntax described by "Specifying Expressions".
Notes:
To set a breakpoint at line 19 of a program, enter:
stop at 19
The pdbx debugger responds with a message like:
all:[0] stop at "foo.c":19
Related to this subcommand are the dbx stop and which subcommands, and the pdbx trace, status, and delete subcommands.
tasks [long]
With the tasks subcommand, you display information about all the tasks in the partition. Task state information is always displayed. If you specify "long" after the command, it also displays the name, ip address, and job manager number associated with the task.
Following is an example of output produced by the tasks and tasks long command.
pdbx(others) tasks 0:D 1:D 2:U 3:U 4:R 5:D 6:D 7:R pdbx(others) tasks long 0:Debug ready pe04.kgn.ibm.com 9.117.8.68 -1 1:Debug ready pe03.kgn.ibm.com 9.117.8.39 -1 2:Unhooked pe02.kgn.ibm.com 9.117.11.56 -1 3:Unhooked augustus.kgn.ibm.com 9.117.7.77 -1 4:Running pe04.kgn.ibm.com 9.117.8.68 -1 5:Debug ready pe03.kgn.ibm.com 9.117.8.39 -1 6:Debug ready pe02.kgn.ibm.com 9.117.11.56 -1 7:Running augustus.kgn.ibm.com 9.117.7.77 -1
Related to this subcommand is the pdbx group subcommand.
thread thread [<number>...] thread [info] [<number> ...] thread [run | wait | susp | term] thread [hold | unhold] [<number> ...] thread [current] [<number>]
The thread subcommand displays the current status of all known threads in the process. Threads to be displayed can be specified through the <number> parameters, or all threads will be listed. Threads can also be selected by states using the run, wait, susp, term, or current options. The info option can be used to display full information about a thread. The hold and unhold options affect whether the thread is dispatchable when further execution control commands are issued. A thread that has been held will not be given any execution time until the unhold option is issued. The thread subcommand displays a column indicating whether a thread is held or not. No further execution will occur if the interrupted thread is held.
The information displayed by the thread subcommand is as follows:
The displayed thread (">") is the thread that is used by other pdbx commands that are thread specific such as:
down dump file func list listi print registers up where
The displayed thread defaults to be the interrupted thread after each execution control command. The displayed thread can be changed using the current option.
The interrupted thread ("*") is the thread that stopped first and because it stopped, in turn caused all of the other threads to stop. The interrupted thread is treated specially by subsequent step, next, and nexti commands. For these stepping commands, the interrupted thread is stepped, while all other (unheld) threads are allowed to continue.
To force only the interrupted thread to execute during execution control commands, set the $hold_next set variable. Note that this can create a debugger induced deadlock if the interrupted thread blocks on one of the other threads.
Note that the pdbx documentation uses "interrupted thread" in the same way the dbx documentation uses "running thread". Also, the pdbx documentation uses "displayed thread" in the same way the dbx documentation uses "current thread".
Related to this subcommand are the attribute condition and mutex subcommands.
trace [in <procedure>] [if <condition>] trace <source_line_number> [if <condition>] trace <procedure> [in <procedure> ] [if <condition>] trace <variable> [in <procedure>] [if <condition>] trace <expression> at <source_line_number> [if <condition>]
Specifying trace with no arguments causes trace information to be displayed for every source line in your program.
Specifying trace <source_line_number> causes the tracepoint to be triggered each time that source line is reached.
Specifying trace [in <procedure>] causes the tracepoint to be triggered each time your program executes a source line within the procedure (function, subroutine).
Using the <variable> argument to trace causes the tracepoint to be triggered when the contents of the variable changes. This form of tracepoint can be very time consuming. For better results, when possible, further qualify these tracepoints with a source_line or procedure argument.
Specify the <condition> argument using the syntax described by "Specifying Expressions".
The trace subcommand sets tracepoints for tasks in the current context. These tracepoints will cause tracing information for the specified procedure, function, sourceline, expression or variable to be displayed when the program runs. The trace subcommand is context sensitive.
Use the status subcommand to display a list of tracepoints that have been set in the current context. Use the delete subcommand to remove tracepoints.
Specifying trace with no arguments causes trace information to be displayed for every source line in your program.
Specifying trace <source_line_number> causes the tracepoint to be triggered each time that source line is reached.
Specifying trace [in <procedure>] causes the tracepoint to be triggered each time your program executes a source line within the procedure (function, subroutine).
Using the <variable> argument to trace causes the tracepoint to be triggered when the contents of the variable changes. This form of tracepoint can be very time consuming. For better results, when possible, further qualify these tracepoints with a source_line or procedure argument.
Specify the <condition> argument using the syntax described by "Specifying Expressions".
Notes:
To set a tracepoint for the variable "foo" at line 21 of a program, enter:
trace foo at 21
The pdbx debugger responds with a message like:
all:[1] trace foo at "bar.c":21
Related to this subcommand are the dbx trace and which subcommands, and the pdbx stop, status, and delete subcommands.
unalias alias_name
The unalias subcommand removes pdbx command aliases. The alias_name specified is any valid alias that has been defined within your current pdbx session. The unalias subcommand is context insensitive.
To remove the alias "p", enter:
unalias p
Related to this subcommand is the pdbx alias subcommand.
unhook
The unhook subcommand enables you to unhook tasks. Unhooking allows tasks to run without intervention from the pdbx debugger. You can later reestablish control over unhooked tasks using the hook subcommand. The unhook subcommand is similar to the detach subcommand in dbx. It is context sensitive and has no parameters.
on 2 unhook
or
on 2 unhook
on rest unhook
or
on rest unhook
Listing the members of the task group "all" using the list action of the group subcommand will allow you to check which tasks are hooked, and which are unhooked. Enter:
group list all
The pdbx debugger will display a list similar to the following:
0:D 1:U 2:D 3:D
Tasks marked with the letter U next to them are unhooked tasks. In this case, task 1 is unhooked. Tasks marked with the letter D are debug ready, hooked tasks. In this case, tasks 0, 2, and 3 are hooked.
Related to this subcommand is the dbx detach subcommand and the pdbx hook subcommand.
unset name
The unset subcommand removes the set variable associated with the specified name.
Related to this subcommand is the set subcommand.
up [count]
The up subcommand moves the current function up the stack the number of levels you specify with the count parameter. The current function is used for resolving names. The default for the count parameter is 1.
The up and down subcommands can be used to navigate through the call stack. Using these subcommands to change the current function also causes the current file and local variables to be updated to the chosen stack level.
Related to this subcommand are the down, print, dump, func, file, and where subcommands.
use [directory ...]
The use subcommand sets the list of directories to be searched when the pdbx debugger looks for source files. If the subcommand is specified without arguments, the current list of directories to be searched is displayed.
The @ (at sign) is a special symbol that directs pdbx to look at the full path name information in the object file, if it exists. If you have a relative directory called @ to search, you should use ./@ in the search path.
The use subcommand uses the + (plus sign) to add more directories to the list of directories to be searched. If you have a directory named +, specify the full path name for the directory (for example, ./+ or /tmp/+).
Related to this subcommand are the file and list subcommands.
whatis <name>
The whatis subcommand displays the declaration of what you specify as the name parameter. The name parameter can designate a variable, procedure, or function name, optionally qualified with a block name.
Related to this subcommand are the whereis and which subcommands.
where
The where subcommand displays a list of active procedures and functions. For example:
pdbx(all) where init_trees(), line 23 in "funcs5.c" colors(depth = 30, str = "This is it"), line 61 in "funcs5.c" newmain(), line 59 in "funcs2.c" f6(), line 25 in "funcs2.c" main(argc = 1, argv = 0x2ff21c58), line 125 in "funcs.c"
Related to this subcommand are the dbx up and down subcommands.
whereis identifier
The whereis subcommand displays the full qualifications of all the symbols whose names match the specified identifier. The order in which the symbols print is not significant.
Related to this subcommand are the whatis and which commands.
which identifier
The which subcommand displays the full qualification of the given identifier. The full qualification consists of a list of the outer blocks with which the identifier is associated.
Related to this subcommand are the whatis and whereis subcommands.
NAME
pedb - Invokes the pedb debugger, which is the X-Windows interface of the PE debugging facility.
SYNOPSIS
pedb [[program] program options] [poe options] [X options] [[-I source directory]...] [-d nesting depth] [-x] pedb -a poe process id [limited poe options] [X options] [[-I source directory]...] [-d nesting depth] [-x] pedb -h
The pedb command invokes the pedb debugger, which is the X-Windows interface of the PE debugging facility.
FLAGS
The pedb command accepts standard X-Windows flags. Because the pedb command runs in the Parallel Operating Environment, it also accepts the flags supported by the poe command. See the poe manual page for a description of these POE options. Additional pdbx flags are:
DESCRIPTION
The pedb command invokes the X-Windows interface of the PE debugging facility. It runs in the Parallel Operating Environment.
To use pedb for interactive debugging, you first need to compile the program and set up the execution environment as you would to invoke a parallel program with the poe command. Your program should be compiled with the -g flag in order to produce an object file with symbol table references. It is also advisable to not use the optimization option, -O. Using the debugger on optimized code may produce inconsistent and erroneous results. For more information on the -g and -O compiler options, refer to their use on other compiler commands such as cc and xlf. These compiler commands are described in IBM AIX Version 4 Commands Reference
ENVIRONMENT VARIABLES
Because the pedb command runs in the Parallel Operating Environment, it interacts with most of the same environment variables associated with the poe command. See the poe manual page in IBM Parallel Environment for AIX: Operation and Use, Volume 1, Using the Parallel Operating Environment for a description of these environment variables. As indicated by the syntax statements, you are also able to specify poe command line options when invoking pedb. Using these options will override the setting of the corresponding environment variable, as is the case when invoking a parallel program with the poe command.
In conjunction with pedb array visualization, you can set the MP_DEBUG_BIN_DIR evironment variable to customize this feature. See Appendix D. "Visualization Customization and Data Explorer Samples" for more information.
EXAMPLES
To start the pedb debugger, enter:
pedb weather temperate asia -procs 16 -labelio yes
This will invoke pedb running the weather application on a partition containing 16 nodes with all program output labeled by task id.
The pedb window automatically opens to mark the start of the debug session.
FILES
host.list (Default host list file)
/usr/lib/X11/app-defaults/Pedb (Xdefaults file)
RELATED INFORMATION
Commands: pdbx(1), poe(1), mpxlf(1), mpcc(1), cc(1), xlf(1) mpxlf_r(1) mpcc_r(1) mpCC_r(1)
NAME
vt - Starts the Visualization Tool, which is an X-Windows tool that enables you to visualize performance characteristics of your partition, or playback traces generalized from a POE program.
SYNOPSIS
vt [-tracefile trace_file] [-tfile trace_file] [-configfile configuration_file] [-cfile configuration_file] [-spath directory_list] [-norm] [-cmap] [-go]
The vt command starts the Visualization Tool for visualizing performance characteristics of a program or the system. This X-Windows tool consists of a group of displays which present specific, often complex, information is easily-interpretable forms such as bar charts and strip graphs. VT can be used to play back traces generated during a program's execution (trace visualization), or as an online monitor to study the operational status and activity of processor nodes (performance monitoring).
FLAGS
DESCRIPTION
The vt command starts the Visualization Tool. This is an X-Windows tool for visualizing performance characteristics of your program and system. It consists of a group of displays, or views, which present complex information in easily-interpretable forms such as bar charts and strip graphs. The VT views can be used for trace visualization and online performance monitoring.
ENVIRONMENT VARIABLES
EXAMPLES
To load the trace file mytrace, the configuration file myconfig, and to begin playback immediately upon starting VT:
vt -tfile mytrace -cfile myconfig -go
To start VT and add the directories /u/files/source and /u/hink/source to the source code search path:
vt -spath /u/files/source:/u/hink/source
To start VT for performance monitoring if you are in an environment where the SP system Resource Manager is not available:
vt -norm
FILES
host.list (Default host list file)
/usr/lib/X11/app-defaults/Vt (Xdefaults file)
$HOME/tracefilename.pplog (Default file name where the results of the trace file post-processing will be written)
RELATED INFORMATION
Commands: poestat(1)