<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>

<!-- ========================================================================
* 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.
======================================================================== -->

<head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  <title>README - IBM Debugger for AIX, Version 6.1</title>
</head>

<body link="blue" vlink="purple">
<p>
========================================================================<br>
* IBM(R) IBM Debugger for AIX, Version 6.1                              <br>
* (C) COPYRIGHT International Business Machines Corp. 2006, 2008        <br>
* All Rights Reserved                                                   <br>
* Licensed Materials - Property of IBM                                  <br>
*                                                                       <br>
* US Government Users Restricted Rights - Use, duplication or           <br>
* disclosure restricted by GSA ADP Schedule Contract with IBM Corp.     <br>
* AIX and IBM are trademarks of IBM Corp.                               <br>
*                                                                       <br>
* Other company, product, and service names may be trademarks or service<br>
* marks of others.                                                      <br>
========================================================================</p>
<table summary="Readme" border="0" cellspacing="5" cellpadding="2" width="100%">
  <tr>
    <td align="left" valign="middle" colspan="1" bgcolor="#C5CEF5">
      <strong>README - IBM Debugger for AIX, Version 6.1</strong>
    </td>
  </tr>
</table>

<p>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.</p>

<table summary="Readme" border="0" cellspacing="5" cellpadding="2" width="100%">
  <tr>
    <td align="left" valign="middle" colspan="1" bgcolor="#C5CEF5">
      <p>The IBM Debugger for AIX consists of two components:</p>

      <ol>
        <li>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.</li>
        <li>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.</li>
      </ol>
    </td>
  </tr>
</table>

<p>This document contains the following sections:</p>

<ul>
  <li><a href="#prerequisite">Prerequisite software</a></li>
  <li><a href="#install_debug">Installing the IBM Debugger for AIX</a></li>
  <!-- <li><a href="#install_fix">Installing Interim Fixes</a></li> -->
  <li><a href="#uninstall">Uninstalling the IBM Debugger for AIX</a></li>
  <li><a href="#v6_features">What's New in the IBM Debugger for AIX, Version 6.1</a></li>
  <li><a href="#start">Starting a debug session</a></li>
  <li><a href="#docs">Accessing IBM Debugger for AIX documentation</a></li>
  <li><a href="#limitations">IBM Debugger for AIX Limitations</a></li>
</ul>

<h2><a name="prerequisite">Prerequisite software</a></h2>

<h3>AIX client installation</h3>

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

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

<!-- <p>If you are applying an Interim Fix, you must have IBM Debugger for AIX v6.1 installed.</p>

<p>Interim Fixes are cumulative in nature. Applying an Interim Fix on an AIX client will include everything delivered by the previous Interim Fix for this release.</p> -->

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

<ul>
  <li>Thread Local Storage (TLS)</li>
  <li>Decimal Floating Point (DFP)</li>
  <li>Vector types</li>
  <li>POWER5 and POWER6 Hardware features</li>
</ul>

<!-- <h3>Windows client installation</h3>

<p>If you are applying an Interim Fix, you must have IBM Debugger for AIX v6.1 installed.</p>

<p>Interim Fixes are cumulative in nature, however, an Eclipse update error in the IBM Debugger for AIX v5.0.0 product release will prevent the installation of this Interim Fix on the IBM Debugger for AIX v5.0.0 product release. You should apply this Interim Fix to the IBM Debugger for AIX v5.0.0 after installing the IBM Debugger for AIX Version 5.0.0.1 Interim Fix. Alternatively, you can install this Interim Fix if you choose to install all optional features.</p> -->

<h2><a name="install_debug">Installing the IBM Debugger for AIX</a></h2>

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

<p>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 &quot;Installing the debug engine (irmtdbgc) and user interface client (idebug) for AIX&quot; below.</p>

<p>If you want to use the IBM Debugger user interface client on Windows, you will need to follow the procedure in &quot;Installing the user interface client (idebug) for Windows&quot; below.</p>

<p>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 <a href="#uninstall">Uninstalling the IBM Debugger for AIX</a>).</p>

<h3>Installing the debug engine (irmtdbgc) and user interface client (idebug) for AIX</h3>

<p>The IBM Debugger for AIX is packaged in the following filesets:</p>

<table border="1" cellpadding="1" cellspacing="1">
  <tr>
    <th><p align="center">Fileset</th>
    <th><p align="center">Description</th>
  </tr>
  <tr>
    <td>ibmdebugger</td>
    <td>Top-level fileset that contains set-up and installation information. Contains the debug engine components, client UI components, and online help components for AIX.</td>
  </tr>
  <tr>
    <td>ibmdebugger.ui</td>
    <td>IBM Debugger for AIX user interface.</td>
  </tr>
  <tr>
    <td>ibmdebugger.engine</td>
    <td>IBM Debugger for AIX engine for compiled language debugging.</td>
  </tr>
  <tr>
    <td>ibmdebugger.engine.msg.LANG</td>
    <td>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.</td>
  </tr>
  <tr>
    <td>ibmdebugger.jre</td>
    <td>Java Runtime Environment (JRE) used with the IBM Debugger for AIX.</td>
  </tr>
</table>

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

<p><code>installp -aXgd . -e /tmp/ibmdebugger.install.log ibmdebugger*</code></p>

<h3>Installing the user interface client (idebug) for Windows</h3>

<p>To install the user interface client for Windows:</p>

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

<!-- <h2><a name="install_fix">Installing Interim Fixes</a></h2>

<h3>Applying a downloaded Interim Fix to an AIX client</h3>

<p>To apply the Interim fix, you can use smit or installp:</p>

<ol>
  <li>Download and extract the image tar file to a directory on your machine.</li>
  <li>Go to the directory where you extracted the image to and issue the install command. For example, if you are using installp, type <code>installp -X -d /tmp/inst.images ibmdebugger</code>.</li>
  <li>If you use smit, and select 'Install corresponding LANGUAGE filesets? Yes', only the ibmdebugger.msg.lang fileset that matches the LANG environment variable will be installed. To install all language filesets, you must use installp. For example, <code>installp -X -d /tmp/inst.images ibmdebugger.msg.*</code>.</li>
</ol>

<p>If you are using one of the supported non-UTF8 CKJ locales, you must install one of the following filesets:</p>

<p>
X11.fnt.ucs.ttf (for ja_JP or Ja_JP)<br>
X11.fnt.ucs.ttf_CN (for zh_CN or Zh_CN)<br>
X11.fnt.ucs.ttf_KR (for ko_KR)<br>
X11.fnt.ucs.ttf_TW (for zh_TW or Zh_TW)<br>
</p>

<p>The install images are available on AIX v5.2 or higher base CDs, and updates are available from the <a href="http://www.ibm.com/servers/eserver/support/">AIX fix distribution Web site</a>.</p>

<h3>Applying an Interim Fix to a Windows client</h3>

<p>Interim Fixes are installed through the Update Manager capability included in this product. To apply an Interim Fix, complete the following steps:</p>

<ol>
  <li>Select <strong>Help &gt; Software Updates &gt; Find and Install</strong>.</li>
  <li>In the Feature Updates page, click the <strong>Search for updates of the currently installed features</strong> radio button.</li>
  <li>Click <strong>Finish</strong> to contact the Web sites associated with the product's features and discover what versions of those features are available. The potential upgrades are displayed in the Search Results page.</li>
  <li>Select the feature versions that you want to upgrade, and then click <strong>Next</strong>.</li>
  <li>Carefully review the license agreements for the upgraded features. If the terms of all of these licenses are acceptable, select the <strong>I accept the terms in the license agreements</strong> check box, and then click <strong>Next</strong>. Do not proceed to download the features if the license terms are not acceptable.</li>
  <li>In the Optional Features page, click <strong>Next</strong>.</li>
  <li>In the Installation page, click <strong>Finish</strong>.</li>
  <li>Once all of the features and plug-ins have been downloaded successfully and their files installed into the product on the local computer, a new configuration that incorporates these features and plug-ins is formulated. When asked to restart, click <strong>Yes</strong>, and then exit the Workbench for the changes to take effect.</li>
</ol> -->

<h2><a name="uninstall">Uninstalling the IBM Debugger for AIX</a></h2>

<h3>Uninstalling on Windows</h3>

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

<p>If uninstall fails, the following steps can be followed to manually start the uninstall program:</p>

<ol>
  <li>Open a command prompt.</li>
  <li>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.</li>
  <li>Change directory (with the cd command) to _jvm\bin.</li>
  <li>Enter the following command: <code>java -jar ..\..\_uninst\uninstall.jar</code></li>
  <li>The uninstall program will start.</li>
</ol>

<h3>Uninstalling on AIX</h3>

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

<p><code>installp -u ibmdebugger*</code></p>

<h2><a name="v6_features">What's New in the IBM Debugger for AIX, Version 6.1</a></h2>

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

<h2><a name="start">Starting a debug session</a></h2>

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

<p>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.</p>

<h3>Starting the IBM Debugger client</h3>

<p>To start the IBM Debugger client on Windows, go to the Windows Start menu and select <strong>Programs &gt; IBM &gt; IBM Debugger for AIX &gt; IBM Debugger for AIX</strong>.</p>

<p>To start the IBM Debugger client on AIX, execute the <code>idebug</code> 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:</p>

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

<h3>Launching the IBM Debugger engine</h3>

<p>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.</p>

<p>To launch the engine from the AIX client (local debugging only):</p>

<ol>
  <li>From the AIX client, select <strong>File -&gt; New Launch -&gt; Load a program</strong>.</li>
  <li>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.</li>
</ol>

<p>Your application will be loaded and execution will suspend at <code>main()</code>.</p>

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

<p><code>irmtdbgc [-qhost=&lt;hostname&gt;:&lt;uidaemonport&gt;] &lt;executable&gt;&lt;executable parameters&gt;</code></p>

<p>where:</p>

<ul>
  <li><code>&lt;uidaemonport&gt;</code> 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.</li>
  <li><code>-qhost=&lt;hostname&gt;</code> 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 <a href="#limitations">IBM Debugger for AIX Limitations</a>).</li>
  <li><code>&lt;executable&gt;</code> is the full path to the program you wish to debug.</li>
  <li><code>&lt;executable parameters&gt;</code> are the parameters passed to the program that you want to debug.</li>
</ul>

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

<h2><a name="docs">Accessing IBM Debugger for AIX documentation</a></h2>

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

<p>To view the help system: From the Windows or AIX client, select <strong>Help &gt; Help Contents</strong>.</p>

<h2><a name="limitations">IBM Debugger for AIX Limitations</a></h2>

<h3>General limitations:</h3>

<ul>
  <!-- <li>If you apply an Interim Fix for the IBM Debugger for AIX on Windows and then uninstall the debugger, the files that were added during the Interim Fix are not removed. These files can be manually deleted after the uninstall is complete. This problem occurs with IBM Debugger for AIX Windows Client Version 5.0.0.1 and IBM Debugger for AIX Windows Client Version 5.0.0.2.</li> -->
  <!-- <li>When applying an Interim Fix through a Windows client, after clicking <strong>Finish</strong> in the final Installation page, there may be a delay before the progress message appears (indicating the features that are being installed). During this delay, the Install dialog box will close and the workbench will be in the foreground.</li> -->
  <!-- <li>On Windows, after reverting the configuration back to the IBM Debugger for AIX Version 5.0.0 from either the IBM Debugger for AIX Version 5.0.0.1 or the IBM Debugger for AIX Version 5.0.0.2, you may see a warning symbol associated with the resulting configuration. If you open the Properties dialog box for that configuration, the status will contain this message:
    <p>Plug-in: &quot;system.bundle&quot; version: &quot;3.1.0&quot; referenced by this feature is not included at runtime. Runtime includes plug-in version &quot;3.1.2&quot;.</p>
    <p>This message can be ignored and you can safely proceed to use the workbench with the reverted configuration.</p>
  </li> -->
  <li>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.</li>
  <li>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 <strong>Reset to Base Address</strong>. This will take the rendering to the base address of the memory block.</li>
  <li>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.</li>
  <li>The IBM Debugger for AIX does not support passing the program name as a parameter to the <code>idebug</code> command.</li>
  <li>When using the <strong>Monitor Local Variable</strong> or <strong>Monitor Memory</strong> 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.</li>
</ul>

<h3>Debugger engine:</h3>

<ul>
  <li>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.</li>
  <li>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:
    <ul>
      <li>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.</li>
      <li>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.</li>
    </ul>
  </li>
  <li>The following environment variables have been added:
    <ul>
      <li>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.</li>
      <li>DER_DBG_POWER_STEP - If set to Y or YES, the debugger will ignore breakpoints when stepping. The default setting is NO.</li>
      <li>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.</li>
    </ul>
  </li>
  <li>The DER_DBG_ NO_LIBPTHDEBUG environment variable is no longer supported.</li>
</ul>

<h3>Documentation Infocenter</h3>

<ul>
  <li><strong>HTTP Status 500 error or visible HTML code in Help search results:</strong> If you search the online documentation in the Help window (<strong>Help &gt; Help Contents</strong>) and encounter one of the following problems:
    <ul>
      <li>HTTP Status 500 error, with the description, "The server encountered an internal error () that prevented it from fulfilling this request."</li>
      <li>visible HTML tags at the top or bottom of the search results list, such as <code>&lt;a class=&quot;link&quot; id=&quot;a113&quot; href=&quot;...</code></li>
    </ul>
  Try running the same search again in the Dynamic Help view: click <strong>Help &gt; Dynamic Help</strong> 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.
  </li>
  <li><strong>Clicking a Help search result displays XML code:</strong> If you search the online documentation in the Help window (<strong>Help &gt; Help Contents</strong>) 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 <strong>Help &gt; Dynamic Help</strong> 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 <strong>Show result categories</strong> 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).</li>
</ul>

<h3>National language limitations:</h3>

<ul>
  <li>Using the <code>irmtdbgc</code> 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 <strong>File &gt; New Launch &gt; Load a program</strong> action.</li>
  <li>Bidirectional (BIDI/BiDi) language limitations:
    <ul>
      <li>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.</li>
      <li>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.</li>
    <li>Editing a string variable so that it contains Arabic characters with <em>tails</em> may not set the value correctly if the <em>tail</em> character does not have an adjacent space. The <em>tail</em> character may be lost.</li>
      <li>Hindi numerals cannot be entered into edit fields in the Variables, Monitors, and Memory views.</li>
    </ul>
  </li>
  <li>User interface text that is added to the product as the result of an Interim Fix is English-only.</li>
</ul>

<!-- ========================================================================
<p></p>
<h3></h3>
<ol>
  <li></li>
</ol>
<ul>
  <li></li>
</ul>
<code></code>
<table border="1" cellpadding="1" cellspacing="1">
  <tr>
    <th><p align="center"></th>
    <th><p align="center"></th>
  </tr>
  <tr>
    <td></td>
    <td></td>
  </tr>
  <tr>
    <td></td>
    <td></td>
  </tr>
</table>
======================================================================== -->

</body>
</html>
