Operation and Use, Volume 2

Starting the pdbx debugger

You can start the pdbx debugger in either normal mode or attach mode. In normal mode your program runs under the control of the debugger. In attach mode you attach to a program that is already running. Certain options and functions are only available in one of the two modes. Since pdbx is a source code debugger, some files need to be compiled with the -g option so that the compiler provides debug symbols, source line numbers, and data type information.

When the application is started using pdbx in normal mode, debugger control of the application is given to the user by default at the first executable source line within the main routine. This is function main in C code or the routine defined by the program statement in Fortran. In Fortran, if there is no program statement, the program name defaults to main. If the file containing the main routine is not compiled with -g the debugger will exit. The environment variable MP_DEBUG_INITIAL_STOP can be set before starting the debugger to manually set an alternate file name and source line where the user initially receives debugger control of the application. Refer to the appendix on POE environment variables and command-line flags in IBM Parallel Environment for AIX: Operation and Use, Volume 1, Using the Parallel Operating Environment

Normal mode

The way you start the debugger in normal mode depends on whether the program(s) you are debugging follow the SPMD (Single Program Multiple Data) or MPMD (Multiple Program Multiple Data) model of parallel programming. In the SPMD model, the same program runs on each of the nodes in your partition. In the MPMD model, different programs can run on the nodes of your partition.

If you are debugging an SPMD program, you can enter its name on the pdbx command line. It will be loaded on all the nodes of your partition automatically. If you are debugging an MPMD program, you will load the tasks of your partition after the debugger is started. pdbx will look for the program in the current directory unless a relative or absolute pathname is specified.

ENTER

pdbx [program [program_options]] [poe opt ions] [-c command_file] [-d nesting_depth] [-I directory [ -I directory]...] [-F] [-x]

This starts pdbx. If you specified a program, it is loaded on each node of your partition and you see the message:

0031-504  Partition loaded ...

You will then see the pdbx prompt:

pdbx(all)

The prompt shows the command context all. For more information see "Setting command context".

ENTER

pdbx -a poe process id [limited poe options] [-c command_file] [-d nesting_depth] [-I directory [ -I directory]...] [-F] [-x]

This starts pdbx in attach mode. See "Attach mode" for more information.

ENTER

pdbx -h

This writes the pdbx usage to STDERR. It includes pdbx command line syntax and a description of pdbx options.

The options you specify with the pdbx command can be program options, POE options, or pdbx options listed in Table 3. Program options are those that your application program will understand.

You can use the same command-line flags on the pdbx command as you use when invoking a parallel program using the poe command. For example, you can override the MP_PROCS variable by specifying the number of processes with the -procs flag. Or you could use the -hostfile flag to specify the name of a host list file. For more information on the POE command-line flags, see IBM Parallel Environment for AIX: Operation and Use, Volume 1, Using the Parallel Operating Environment

Note:: poe uses the PATH environment variable to find the program, while pdbx does not.

After pdbx initializes, the pdbx command prompt displays to indicate that pdbx is ready for a command.

Table 3. Debugger Option Flags (pdbx)

Use this flag:	To:	For example:
-a	Attach to a running poe job by specifying its process id. This must be executed from the node where the poe job was initiated. When using the debugger in attach mode there are some debugger command line arguments that should not be used. In general, any arguments that control how the partition is set up or specify application names and arguments should not be used.	To attach the pdbx debugger to an already running poe job. ENTER pdbx -a <poe_process_id>
-c	Read pdbx startup commands from the specified commands_file. The commands stored in the specified file are executed before command input is accepted from the keyboard. If the -c flag is not used, the pdbx debug program attempts to read startup commands from the file .pdbxinit. To find this file, it first looks in the current directory, and then in the user's home directory. In a pdbx session, you can also read commands from a file using the source subcommand. Reading subcommands from a command file describes how to use this subcommand in pdbx.	To start the pdbx debugger and read startup commands from a file called start.cmd: ENTER pdbx -c start.cmd
-d	Set the limit for the nesting of program blocks. The default nesting depth limit is 25. This flag is passed to dbx unmodified.	To specify a nesting depth limit: ENTER pdbx -d nesting.depth
-F	This flag can be used to turn off lazy reading mode. Turning lazy reading mode off forces the remote dbx sessions to read all symbol table information at startup time. By default, lazy reading mode is on. 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.	To start the pdbx debugger and read all symbol table information: ENTER pdbx -F
-h	Write the pdbx usage to STDERR then exit. This includes pdbx command line syntax and a description of pdbx options.	ENTER pdbx -h
-I (upper case i)	Specify a directory to be searched for an executable's source files. This flag must be specified multiple times to set multiple paths. (Once pdbx is running, this list can be overridden on a group or single node basis with the use command.)	To add directory1 to the list of directories to be searched when starting the pdbx debugger: ENTER pdbx -I dir1 You can add as many directories as you like to the directory list in this way. For example, to add two directories: ENTER pdbx -I dir1 -I dir2
-x	Prevent the dbx command from stripping _ (trailing underscore ) characters from symbols originating in Fortran source code. This flag allows dbx to distinguish between symbols which are identical except for an underscore character, such as xxx and xxx_.	To prevent trailing underscores from being stripped from symbols in Fortran source code: ENTER pdbx -x

These pdbx flags are closely tied to the flags supported by dbx. For more information on the option flags described in this table, refer to their use with dbx as described in AIX 5L Version 5.1 Commands Reference and AIX 5L Version 5.1 General Programming Concepts: Writing and Debugging Programs.

For a listing of pdbx subcommands, you can also refer to its online manual page. This manual page also appears in Appendix A, Parallel environment tools commands.

Attach mode

The pdbx debugger provides an attach feature, which allows you to attach the debugger to a parallel application that is currently executing. This feature is typically used to debug large, long running, or apparently "hung" applications. The debugger attaches to any subset of tasks without restarting the executing parallel program.

Parallel applications run on the partition managed by poe. For attach mode, you must specify the appropriate process identifier (PID) of the poe job, so the debugger can attach to the correct application processes contained in that particular job. To get the PID of the poe job, enter the following command on the node where poe was started:

$ ps -ef | grep poe

You initiate attach mode by invoking pdbx with the -a flag and the PID of the appropriate poe process:

$ pdbx -a <poe PID>

For example, if the process id of the poe process is 12345 then the command would be:

$ pdbx -a 12345

After you invoke the debugger in attach mode, it displays a list of tasks you can choose. The paging tool used to display the menu will default to pg -e unless another pager is specified by the PAGER environment variable.

pdbx starts by showing a list of task numbers that comprise the parallel job. The debugger obtains this information by reading a configuration file created by poe when it begins a job step. At this point you must choose a subset of that list to attach the debugger. Once you make a selection and the attach debug session starts, you cannot make additions or deletions to the set of tasks attached to. It is possible to attach a different set of tasks by detaching the debugger and attaching again, then selecting a different set of tasks.

The debugger attaches to the specified tasks. The selected executables are stopped wherever their program counters happen to be, and are then under the control of the debugger. The other tasks in the original poe application continue to run. pdbx displays information about the attached tasks using the task numbering of the original poe application partition.

Attach screen

Figure 1 shows a sample pdbx Attach screen.

Figure 1. pdbx Attach screen

+--------------------------------------------------------------------------------+
|ATTENTION: 0029-9049 The following environment variables have been              |
|ignored since they are not valid when starting the debugger                     |
|in attach mode -                                                                |
|  'MP_PROCS'.                                                                   |
|                                                                                |
|To begin debugging in attach mode, select a task or tasks to attach.            |
|                                                                                |
|Task       IP Addr                 Node                 PID     Program         |
|0        9.117.8.62           pe02.kgn.ibm.com         23870      ftoc          |
|1        9.117.8.63           pe03.kgn.ibm.com         14908      ftoc          |
|2        9.117.8.64           pe04.kgn.ibm.com         14400      ftoc          |
|3        9.117.8.65           pe05.kgn.ibm.com         13114      ftoc          |
|4        9.117.8.66           pe06.kgn.ibm.com         11330      ftoc          |
|5        9.117.8.67           pe07.kgn.ibm.com         19784      ftoc          |
|6        9.117.8.68           pe08.kgn.ibm.com         19524      ftoc          |
|7        9.117.8.69           pe09.kgn.ibm.com         22086      ftoc          |
|                                                                                |
|At the pdbx prompt enter the "attach" command followed by a                     |
|list of tasks or "all".  (ex. "attach 2 4 5-7" or "attach all")                 |
|You may also type "help" for more information or "quit" to exit                 |
|the debugger without attaching.                                                 |
|                                                                                |
|pdbx(none)                                                                      |
|                                                                                |
+--------------------------------------------------------------------------------+

The pdbx Attach screen contains a list of tasks and, for each task, the following information:

Task - the task number
IP - the ip address of the node on which the task/application is running
Node - the name of the node on which the task/application is running, if available
PID - the process identifier of the task/application
Program - the name of the application and arguments, if any.

After initiating attach mode, you can select a set of tasks to attach to. At the command prompt:

ENTER: attach all
OR
ENTER: attach followed by the task_list (see "Syntax for task_list" for the correct syntax).

It is also possible to use the quit or help command at this prompt. Any other command will produce an error message. The quit command will not kill the application at this point, since the debugger has not been attached as of yet.

Note:: When debugging in attach mode, the load subcommand is not available. An error message is displayed if an attempt is made to use it.

Other compiling options

pdbx provides substantial information when debugging an executable compiled with the -g option. However, you may find it useful to attach to an application not compiled with -g. pdbx allows you to attach to an application not compiled with -g, however, the information provided is limited to a stack trace.

You can also attach pdbx to an application compiled with both the -g and optimization flags. However, the optimized code can cause some confusion when debugging. For example, when stepping through code, you may notice the line marker points to different source lines than you would expect. The optimization causes this re-mapping of instructions to line numbers.

Command line arguments

You should not use certain command line arguments when debugging in attach mode. If you do, the debugger will not start, and you will receive a message saying the debugger will not start. In general, do not use any arguments that control how the debugger partition is set up or that specify application names and arguments. You do not need information about the application, since it is already running and the debugger uses the PID of the poe process to attach. Other information the debugger needs to set up its own partition, such as node names and PIDs, comes from the configuration file and the set of tasks you select. See Appendix B, Command line flags for normal or attach mode for a list of command line flags showing which ones are valid in normal and in attach debugging mode.

The information in the appendix is also true for the corresponding environment variables, however pdbx ignores the invalid setting. The debugger displays a message containing a list of the variables it ignores, and continues.

For example, if you had MP_PROCS set, when the debugger starts in attach mode it ignores the setting. It displays a message saying it ignored MP_PROCS, and continues initializing the debug session.

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