========================================================================
* IBM(R) IBM Debugger for AIX, Version 6.1
* (C) COPYRIGHT International Business Machines Corp. 2006, 2008
* All Rights Reserved
* Licensed Materials - Property of IBM
*
* US Government Users Restricted Rights - Use, duplication or
* disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
* AIX and IBM are trademarks of IBM Corp.
*
* Other company, product, and service names may be trademarks or service
* marks of others.
========================================================================

The IBM Debugger for AIX, Version 6.1 supports local and remote debugging for C/C++ applications that are running on AIX Version 5. Applications running on an AIX machine can be debugged from the debugger user interface running on the same machine or remotely from another AIX or Windows machine.

This document contains the following sections:

• Prerequisite software
• Installing the IBM Debugger for AIX
• Uninstalling the IBM Debugger for AIX
• What's New in the IBM Debugger for AIX, Version 6.1
• Starting a debug session
• Accessing IBM Debugger for AIX documentation
• IBM Debugger for AIX Limitations

Prerequisite software

AIX client installation

The AIX client requires AIX v5.1 (AIX 5100-08 or later) or AIX v5.2 (AIX 5200-07 or later) or AIX v5.3 (AIX 5300-03 or later).

To test whether this install platform is supported, at the system prompt type lscfg -p | fgrep Architecture. You should receive the reply Model Architecture: chrp. Only Common Hardware Reference Platform (chrp) systems are supported.

Debugging of the following features is only supported if the corresponding features are present in the hardware or operating system:

• Thread Local Storage (TLS)
• Decimal Floating Point (DFP)
• Vector types
• POWER5 and POWER6 Hardware features

Installing the IBM Debugger for AIX

If you installed all filesets when installing the XL C/C++ compilers, as described in the default installation procedure in the "IBM XL C/C++ Enterprise Edition for AIX, V9.0 Installation Guide", all the IBM Debugger components for AIX (client and engine) are already installed.

If you did not install all filesets when installing the XL C/C++ compilers, or used the non-default installation procedure, you will need to install the IBM Debugger components for AIX separately. For instructions, see "Installing the debug engine (irmtdbgc) and user interface client (idebug) for AIX" below.

If you want to use the IBM Debugger user interface client on Windows, you will need to follow the procedure in "Installing the user interface client (idebug) for Windows" below.

If you are installing a full product version and not an Interim Fix, it is recommended that you uninstall any previous version of the IBM Debugger before installing this version of the IBM Debugger for AIX (see Uninstalling the IBM Debugger for AIX).

Installing the debug engine (irmtdbgc) and user interface client (idebug) for AIX

The IBM Debugger for AIX is packaged in the following filesets:

To install the IBM Debugger components on AIX, as well as the appropriate message filesets that your system currently supports, issue the following commands:

installp -aXgd . -e /tmp/ibmdebugger.install.log ibmdebugger*

Installing the user interface client (idebug) for Windows

To install the user interface client for Windows:

1. Open a command prompt and navigate to the IBMdebugger\windows\ directory on the product CD.
2. Run the program, IBMdebugger\windows\setup.exe, on the product CD and then follow the on-screen prompts to install the user interface client.

Uninstalling the IBM Debugger for AIX

Uninstalling on Windows

To uninstall the IBM Debugger for AIX Windows client, open the Windows Control Panel and choose Add or Remove Programs. Locate and select IBM Debugger for AIX. Click Remove to start the uninstallation process.

If uninstall fails, the following steps can be followed to manually start the uninstall program:

1. Open a command prompt.
2. Change directory (with the cd command) to the IBM Debugger for AIX install directory. The default installation directory is C:\Program Files\IBM\IBM Debugger for AIX.
3. Change directory (with the cd command) to _jvm\bin.
4. Enter the following command: java -jar ..\..\_uninst\uninstall.jar
5. The uninstall program will start.

Uninstalling on AIX

To uninstall the IBM Debugger for AIX engine/client on AIX, issue this command when logged on as the root user:

installp -u ibmdebugger*

What's New in the IBM Debugger for AIX, Version 6.1

• Support for:
  • POWER6 hardware
  • AltiVec registers
  • Decimal Floating Point (DFP)
  • Thread Local Storage
• Local variable filtering
• show_self function, which allows you to display the contents of a C++ object in a meaningful way
• C/C++ function evaluation for functions with C linkage
• Expression evaluation for assignment expressions
• One-line aggregate display support
• Support for national language characters in C/C++ source
• Cast-to-Template support
• Improved monitoring of local variables
• A new Debug Console view (Technical Preview only)

Starting a debug session

Before you debug a program, be sure that you have compiled the program with debug information by using the -g compiler option.

To start a debugging session, you first start the IBM Debugger client on either a local or remote AIX machine or remote Windows machine. Then you launch the debug session locally or remotely.

Starting the IBM Debugger client

To start the IBM Debugger client on Windows, go to the Windows Start menu and select Programs > IBM > IBM Debugger for AIX > IBM Debugger for AIX.

To start the IBM Debugger client on AIX, execute the idebug command. In a multiuser environment (more than one user running the user interface client on the same AIX machine), each user must select a unique daemon port number. To do this, specify a range of daemon ports in the user interface client:

1. Start the user interface client.
2. Click the down arrow beside the daemon icon in the Debug view.
3. Enter a range of ports that the user interface client can attempt to use (ranges are entered, for example, as 8001-8009).
4. The user interface client will use the first available port in the range.
5. If the debug engine is launched from the user interface client, it will use the port that the user interface client found available.
6. If you are launching the debug engine directly, you must specify the port that the user interface client obtained.

Launching the IBM Debugger engine

To debug a program locally, you can launch the engine from the AIX client, or from the command line. To debug a program remotely, you must launch the engine from the AIX command line.

To launch the engine from the AIX client (local debugging only):

1. From the AIX client, select File -> New Launch -> Load a program.
2. Provide the necessary information to locate and launch your program. At a minimum, you must specify the name of the executable. If the program cannot be found in your current PATH environment variable, include the full path to the program.

Your application will be loaded and execution will suspend at main().

To launch the engine from the command line (local or remote debugging), execute the following command:

irmtdbgc [-qhost=<hostname>:<uidaemonport>] <executable><executable parameters>

where:

• <uidaemonport> is the TCP/IP port number on the client machine that is specified in the daemon preferences. The default daemon port number is 8001. The port specified for the engine must be one of the ports that the user interface is listening on.
• -qhost=<hostname> is the name of the host machine on which the client is running. You can omit this option if the client is running on the same machine, or if you have specified the client machine and port with the DER_DBG_ADDR environment variable (see the Debugger engine section of IBM Debugger for AIX Limitations).
• <executable> is the full path to the program you wish to debug.
• <executable parameters> are the parameters passed to the program that you want to debug.

The engine will then connect to the client, load your program, and suspend it when it reaches main().

Accessing IBM Debugger for AIX documentation

Complete documentation for the IBM Debugger for AIX is provided in an online information center which is launched from the IBM Debugger client.

To view the help system: From the Windows or AIX client, select Help > Help Contents.

IBM Debugger for AIX Limitations

General limitations:

• When applying an Interim Fix through a Windows client, there is an uncaught SWT exception written to the log file when you replace the current configuration with another one. This exception can be ignored and you can safely proceed to use the workbench with the replaced configuration.
• When using the AIX client, when a rendering is added in the Memory View, the rendering may not position to the base address of the memory block. To work around this problem, right-click in the rendering and select Reset to Base Address. This will take the rendering to the base address of the memory block.
• When using the AIX client, the help system may fail to start if a non-working Web browser is on your path. To ensure that the help system functions, remove non-working Web browsers from your path.
• The IBM Debugger for AIX does not support passing the program name as a parameter to the idebug command.
• When using the Monitor Local Variable or Monitor Memory action on child nodes of an array or struct, the results may not be as expected. Either action will attempt to monitor the top node rather than the selected child node. A fix for this problem is being considered for a future release.

Debugger engine:

• The DER_DBG_PORT debug engine environment variable has been deprecated. The host address and port should be specified as DER_DBG_ADDR=host:port.
• The DER_DBG_DEEP_STEP_DEBUG environment variable has been deprecated. This environment variable has been replaced by DER_DBG_STEP_DEBUG = [SHALLOW | DEEP] [INCLUDE | NOINCLUDE], where:
  • SHALLOW or DEEP controls whether the step-debug function only checks the immediate subroutine for debug information (SHALLOW) or keeps going until a location with debug information is found (DEEP). The default is SHALLOW. Deep step-debug can be slow if you have large amounts of code with no debug information.
  • INCLUDE or NO_INCLUDE determines whether code in included files is treated as having debug information when performing a step-debug. The default is INCLUDE.
• The following environment variables have been added:
  • DER_DBG_BACKGROUND_READ - The default value is YES. Setting this to NO will prevent the debugger from reading debug information while it is otherwise idle. For applications with extremely large amounts of debug data, it may be necessary to set this to NO to prevent the debugger from running out of heap space.
  • DER_DBG_POWER_STEP - If set to Y or YES, the debugger will ignore breakpoints when stepping. The default setting is NO.
  • DER_DBG_CICS_STEP - This is a special environment variable to be used when debugging under CICS. It causes the debugger to step normally through code that calls routines via CICS.
• The DER_DBG_ NO_LIBPTHDEBUG environment variable is no longer supported.

Documentation Infocenter

• HTTP Status 500 error or visible HTML code in Help search results: If you search the online documentation in the Help window (Help > Help Contents) and encounter one of the following problems:
  • HTTP Status 500 error, with the description, "The server encountered an internal error () that prevented it from fulfilling this request."
  • visible HTML tags at the top or bottom of the search results list, such as <a class="link" id="a113" href="...
  Try running the same search again in the Dynamic Help view: click Help > Dynamic Help or select the keyboard F1 key and then click the Search link at the bottom of the view. The Dynamic Help search will display the results under the Local Help category.
• Clicking a Help search result displays XML code: If you search the online documentation in the Help window (Help > Help Contents) and click one of the results, and the content frame displays an XML source file rather than something readable, then run your search again in the Dynamic Help view. Click Help > Dynamic Help and click the Search link at the bottom of the view. The Dynamic Help search will display the results under the Local Help twistie. If you have selected the Show result categories button, then the result you are looking for will be shown under a category such as Welcome (these are some of the categories that display correctly only in the Dynamic Help view).

National language limitations:

• Using the irmtdbgc command, you cannot load a program whose name or parameters include characters with UCS codepoints above 255. Such programs can be loaded locally with the AIX client File > New Launch > Load a program action.
• Bidirectional (BIDI/BiDi) language limitations:
  • The Debugger editor, Variables view, Monitors view, and Memory view may display words composed of BIDI characters and numerals incorrectly. The position of the numerals and BIDI characters in the word may be incorrect.
  • The Arabic Lam Aleph (or Lam Alef) characters do not display correctly in the EBCDIC rendering in the Memory view when using CP420. CP420S can be used instead.
  • Editing a string variable so that it contains Arabic characters with tails may not set the value correctly if the tail character does not have an adjacent space. The tail character may be lost.
  • Hindi numerals cannot be entered into edit fields in the Variables, Monitors, and Memory views.
• User interface text that is added to the product as the result of an Interim Fix is English-only.