======================================================================== * IBM(R) IBM Debugger for AIX, Version 6.1 * COPYRIGHT International Business Machines Corp. 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. ======================================================================== README - IBM Debugger for AIX, Version 6.1 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. The IBM Debugger for AIX consists of two components: An AIX debug engine program (irmtdbgc) that is used to control and debug a C/C++ application on AIX Version 5. The debug engine runs on the same machine as the application to be debugged. The debug engine interacts with the application under debug control. A user interface client (idebug) that communicates with the engine and allows you to debug your application. A version of idebug for both AIX and Windows is provided. The user interface client can run on the same AIX machine as the debug engine. This document contains the following sections: 1) Prerequisite software 2) Installing the IBM Debugger for AIX 3) Uninstalling the IBM Debugger for AIX 4) What's New in the IBM Debugger for AIX, Version 6.1 5) Starting a debug session 6) Accessing IBM Debugger for AIX documentation 7) IBM Debugger for AIX Limitations 1) Prerequisite software ----------------------------------------------------------------------------------------------------------------------------------------- AIX client installation The AIX client requires AIX v5.1 (AIX 5100-08 or later), AIX v5.2 (AIX 5200-07 or later), AIX v5.3 (AIX 5300-03 or later) or AIX v6.1.0.0 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 2) 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: Fileset Description ibmdebugger Top-level fileset that contains set-up and installation information. Contains the debug engine components, client UI components, and online help components for AIX. ibmdebugger.ui IBM Debugger for AIX user interface. ibmdebugger.engine IBM Debugger for AIX engine for compiled language debugging. ibmdebugger.engine.msg.LANG IBM Debugger for AIX engine national language filesets. Contains message files, where LANG is one of: pt_BR, zh_CN, zh_TW, de_DE, es_ES, fr_FR, it_IT, ja_JP, or ko_KR. ibmdebugger.jre Java Runtime Environment (JRE) used with the IBM Debugger for AIX. 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* After installing the IBM Debugger components on AIX, run the following command to add the IBM Debugger executables to your PATH: export PATH=/usr/idebug:/usr/idebug/engine/bin:$PATH Installing the user interface client (idebug) for Windows To install the user interface client for Windows: Open a command prompt and navigate to the IBMdebugger\windows\ directory on the product CD. Run the program, IBMdebugger\windows\setup.exe, on the product CD and then follow the on-screen prompts to install the user interface client. 3) 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: Open a command prompt. 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. Change directory (with the cd command) to _jvm\bin. Enter the following command: java -jar ..\..\_uninst\uninstall.jar 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* 4) What's New in the IBM Debugger for AIX, Version 6.1 ----------------------------------------------------------------------------------------------------------------------------------------- Launch of a local AIX application from the idebug command line Restart of a remote AIX application 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) 5) 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: Start the user interface client. Click the down arrow beside the daemon icon in the Debug view. Enter a range of ports that the user interface client can attempt to use (ranges are entered, for example, as 8001-8009). The user interface client will use the first available port in the range. If the debug engine is launched from the user interface client, it will use the port that the user interface client found available. 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): From the AIX client, select File -> New Launch -> Load a program. 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=:] where: 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= 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). is the full path to the program you wish to debug. 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(). 6) 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. 7) 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