Operation and Use, Volume 2

Subcommands of the pdbx command

alias subcommand (of the pdbx command)

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:

t: where
j: status
st: stop
s: step
x: registers
q: quit
p: print
n: next
m: map
l: list
h: help
d: delete
c: cont
th: thread
mu: mutex
cv: condition
attr: attribute

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.

If you have two task groups defined in your pdbx session called "master" and "workers", and you wish to define aliases to easily qualify each, enter:
```
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.
To display the string that has been defined for the alias "p", enter:
```
alias p
 
```
To list all aliases currently defined, enter:
```
alias
 
```

Related to this subcommand is the pdbx unalias subcommand.

assign subcommand (of the pdbx command)

assign <variable> = <expression>

The assign subcommand assigns the value of an expression to a variable.

To assign a value of 5 to the x variable:
```
pdbx(all) assign x = 5
 
```
To assign the value of the y variable to the x variable:
```
pdbx(all) assign x = y
 
```
To assign the character value 'z' to the z variable:
```
pdbx(all) assign z = 'z'
 
```
To assign the boolean value false to the logical type variable B:
```
pdbx(all) assign B = false
```
To assign the "Hello World" string to a character pointer Y:
```
pdbx(all) assign Y = "Hello World"
 
```
To disable type checking, activate the set variable $unsafeassign:
```
pdbx(all) set $unsafeassign
 
```

attach subcommand (of the pdbx command)

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 subcommand (of the pdbx command)

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:

attr: Indicates the symbolic name of the attributes object, in the form $aattribute_number.
obj_addr: Indicates the address of the attributes object.
type: Indicates the type of the attributes object; this can be thr, mutex, or cond for user threads, mutexes, and condition variables respectively.
state: Indicates the state of the attributes object. This can be valid or invalid.
stack: Indicates the stacksize attribute of a thread attributes object.
scope: Indicates the scope attribute of a thread attributes object. This determines the contention scope of the thread, and defines the set of threads with which it must contend for processing resources. The value can be sys or pro for system or process contention scope.
prio: Indicates the priority attribute of a thread attributes object.
sched: Indicates the schedpolicy attribute of a thread attributes object. This attribute controls scheduling policy, and can be fifo (first in first out), rr (round robin), or other.
p-shar: Indicates the process-shared attribute of a mutex or condition attribute object. A mutex or condition is process-shared if it can be accessed by threads belonging to different processes. The value can be yes or no.
protocol: Indicates the protocol attribute of a mutex. This attribute determines the effect of holding the mutex on a thread's priority. The value can be no_prio, prio, or protect.

Related to this subcommand are the condition mutex and thread subcommands.

back subcommand (of the pdbx command)

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 subcommand (of the pdbx command)

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 subcommand (of the pdbx command)

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:

default: Varies with the current language.
mixed: Causes symbols to be interpreted as they actually appear.
lower: Causes symbols to be interpreted as lowercase.
upper: Causes symbols to be interpreted as uppercase.

catch subcommand (of the pdbx command)

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 subcommand (of the pdbx command)

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:

cv: Indicates the symbolic name of the condition variable, in the form $ccondition_number.
obj_addr: Indicates the memory address of the condition variable.
num_wait: Indicates the number of threads waiting on the condition variable.
waiters: Lists the user threads which are waiting on the condition variable.

Related to this subcommand are the attribute mutex and thread subcommands.

cont subcommand (of the pdbx command)

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 subcommand (of the pdbx command)

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 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 subcommand (of the pdbx 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 subcommand (of the pdbx command)

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 subcommand (of the pdbx command)

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.

display memory subcommand (of the pdbx command)

<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:

i: print the machine instruction
d: print a short word in decimal
D: print a long word in decimal
o: print a short word in octal
O: print a long word in octal
x: print a short word in hexadecimal
X: print a long word in hexadecimal
b: print a byte in octal
c: print a byte as a character
h: print a byte in hexadecimal
s: print a string (terminated by a null byte)
f: print a single precision real number
g: print a double precision real number
q: print a quad precision real number
lld: print an 8 byte signed decimal number
llu: print an 8 byte unsigned decimal number
llx: print an 8 byte unsigned hexadecimal number
llo: print an 8 byte unsigned octal number

down subcommand (of the pdbx command)

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 subcommand (of the pdbx command)

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 subcommand (of the pdbx command)

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 subcommand (of the pdbx command)

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 subcommand (of the pdbx command)

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 subcommand (of the pdbx command)

gotoi address

The gotoi subcommand changes the program counter address to the address specified by the address parameter.

group subcommand (of the pdbx command)

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.

To create a task group "first" containing task 0, enter:
```
group add first 0
 
```
The pdbx debugger responds with:
```
1 task was added to group "first".
 
```
To create a task group "rest" containing tasks 1 through 4, enter:
```
group add rest 1:4
 
```
The pdbx debugger responds with:
```
4 tasks were added to group "rest".
 
```
To change the name of the default group "all" to "johnny", enter:
```
group change all johnny
 
```
The pdbx debugger responds with:
```
Group "all" has been renamed to "johnny"
 
```

To list all of the groups and the tasks they contain, enter:

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

To delete the group "first", enter:

group delete first

To delete members 1, 2 and 3 from group "rest", enter:

group delete rest 1 2 3

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".

To list all of the groups and the tasks they contain, enter:

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 subcommand (of the pdbx command)

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 application. 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 subcommand (of the pdbx command)

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 subcommand (of the pdbx command)

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.

To reestablish control over task 2 if it has been unhooked, enter:
```
on 2 hook
 
```
or
```
on 2
hook
 
```
To reestablish control over all unhooked tasks in the task group "rest", enter:
```
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 subcommand (of the pdbx command)

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 subcommand (of the pdbx command)

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.

By specifying a procedure using the procedure parameter.
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.
By specifying a starting and ending source line number using the sourceline-expression parameter.
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 subcommand (of the pdbx command)

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 subcommand (of the pdbx 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 subcommand (of the pdbx command)

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 subcommand (of the pdbx command)

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:

mutex: Indicates the symbolic name of the mutex, in the form $mmutex_number.
type: Indicates the type of the mutex: non-rec (nonrecursive), recursi (recursive) or fast.
obj_addr: Indicates the memory address of the mutex.
lock: Indicates the lock state of the mutex: yes if the mutex is locked, no if not.
owner: If the mutex is locked, indicates the symbolic name of the user thread which holds the mutex.

Related to this subcommand are the attribute condition and thread subcommands.

next subcommand (of the pdbx command)

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 subcommand (of the pdbx command)

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 subcommand (of the pdbx command)

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

To add a breakpoint for task 0, enter:
```
on johnny stop at 31
 
```
The pdbx debugger responds with:
```
johnny:[0] stop at "ring.f":31
 
```
To add breakpoints for all of the tasks in the task group "jessica", enter:
```
on jessica stop in ring
 
```
The pdbx debugger responds with:
```
jessica:[0] stop in ring
 
```
To switch the current context to the task group "johnny", enter:
```
on johnny
 
```
The pdbx debugger responds with the prompt:
```
pdbx(johnny)
 
```
To add a conditional breakpoint for all tasks in the current context, enter:
```
stop at 48 if len < 1
 
```
The pdbx debugger responds with:
```
johnny:[1] stop at "ring.f":48 if len < 1
 
```
To view the events that have been set on the task group "jessica", enter:
```
on jessica status
 
```
The pdbx debugger responds with:
```
jessica:[0] stop in ring
 
```
To add a tracepoint for task 2, enter:
```
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
 
```

To view all of the events that have been set, enter:

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 subcommand (of the pdbx command)

print expression ...
print procedure ([parameters])

The print subcommand does either of the following:

Prints the value of a list of expressions, specified by the expression parameters.
Executes a procedure, specified by the procedure parameter, and prints the return value of that procedure. Parameters that are included are passed to the procedure.

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 subcommand (of the pdbx command)

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 subcommand (of the pdbx command)

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:

$r0 through $r31: for the general purpose registers.
$fr0 through $fr31: for the floating point registers.
$sp, $iar, $cr, $link: for, respectively, the stack pointer, program counter, condition register, and link register.

By default, the floating-point registers are not displayed. To display the floating-point registers, use the unset $noflregs command.

Notes:

The register value may be set to the 0xdeadbeef hexadecimal value. The 0xdeadbeef hexadecimal value is an initialization value assigned to general purpose registers at process initialization.
The registers command cannot display registers if the current thread is in kernel mode.

return subcommand (of the pdbx command)

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.

search subcommand (of the pdbx command)

/<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 subcommand (of the pdbx command)

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 subcommand (of the pdbx command)

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 subcommand (of the pdbx command)

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 subcommand (of the pdbx command)

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 subcommand (of the pdbx command)

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 subcommand (of the pdbx command)

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 subcommand (of the pdbx command)

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 subcommand (of the pdbx command)

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).

Specify the <condition> argument using the syntax described by "Specifying expressions".

Notes:

The pdbx debugger will not attempt to set a breakpoint at a line number when in a group context if the group members (tasks) have different current source files.
When specifying variable names as arguments to the stop subcommand, fully qualified names should be used. This should be done because, when a stop subcommand is issued, a parallel application could be in a different function on each node. This may result in ambiguity in variable name resolution. Use the which subcommand to get the fully qualified name for a variable.

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 subcommand (of the pdbx command)

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 subcommand (of the pdbx command)

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:

thread: Indicates the symbolic name of the user thread, in the form $tthread_number.
state-k: Indicates the state of the kernel thread (if the user thread is attached to a kernel thread). This can be run, wait, susp, or term, for running, waiting, suspended, or terminated.
wchan: Indicates the event on which the kernel thread is waiting or sleeping (if the user thread is attached to a kernel thread).
state-u: Indicates the state of the user thread. Possible states are running, blocked, or terminated.
k-tid: Indicates the kernel thread identifier (if the user thread is attached to a kernel thread).
mode: Indicates the mode (kernel or user) in which the user thread is stopped (if the user thread is attached to a kernel thread).
held: Indicates whether the user thread has been held.
scope: Indicates the contention scope of the user thread; this can be sys or pro for system or process contention scope.
function: Indicates the name of the user thread function.

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 subcommand (of the pdbx command)

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).

Specify the <condition> argument using the syntax described by "Specifying expressions".

Notes:

The pdbx debugger will not attempt to set a tracepoint at a line number when in a group context if the group members (tasks) have different current source files.
When specifying variable names as arguments to the trace subcommand, fully qualified names should be used. This should be done because, when a trace subcommand is issued, a parallel application could be in a different function on each node. This may result in ambiguity in variable name resolution. Use the which subcommand to get the fully qualified name for a variable.

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 subcommand (of the pdbx command)

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 subcommand (of the pdbx command)

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.

To unhook task 2, enter:
```
on 2 unhook
 
```
or
```
on 2
unhook
 
```
To unhook all the tasks in the task group "rest", enter:
```
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 subcommand (of the pdbx command)

unset name

The unset subcommand removes the set variable associated with the specified name.

Related to this subcommand is the set subcommand.

up subcommand (of the pdbx command)

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.

Related to this subcommand are the down, print, dump, func, file, and where subcommands.

use subcommand (of the pdbx command)

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 subcommand (of the pdbx command)

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 subcommand (of the pdbx command)

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 subcommand (of the pdbx command)

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 subcommand (of the pdbx command)

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.

[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]