Release notes for Purify version 2003.06.00  Solaris 2


Contents
========

  o Changes from previous releases

  o Supported systems

  o Restrictions and known issues

New in This Release
===================

  - Bug fixes and compatibility with OS patches.

  - New option -merge to merge the data from multiple Purify log 
    files.  For details and usage of the option, please look under 
    "Miscellaneous options" in the online documentation.

  - Support for Solaris 9. 

  - Support for gcc/g++ 3.0.x and 3.1 compiler (32-bit only).

  - Support for 32-bit JNI applications using JDK 1.2.X and 1.3.1. 
    Please refer to the "Restrictions and Known Issues" section for 
    details.

New in Purify 2002a.06.00
=========================

  - Bug fixes and compatibility with OS patches.

  - Modified Support for Change Request Management Systems,
    including Rational's ClearQuest and ClearDDTS. Please
    see the online help for more details.

  - Support for Forte 7 compiler (compiler version 5.4).

  - This release does not support Solaris 2.5.1 (SunOS 5.5.1).

New in Purify 2002.05.00
=========================

  - Bug fixes and compatibility with OS patches.

  - Support for Forte 6 Update 2 compiler (compiler version 5.3).

  - Support for gcc 2.95.3 compiler.

  - This is the last release to support Solaris 2.5.1 (SunOS 5.5.1).

New in Purify 2001a.04.00
=========================

  - Bug fixes and compatibility with OS patches.

  - HTML-based online help system. See the "HTML Help" topic in the 
    Restrictions and Known Issues section.

  - New product versioning system. This release is the successor of:

       Purify 5.3 for Solaris

  - Support for Forte 6 Update 1 compiler (compiler version 5.2).

  - Support for gcc 2.95.2 compiler.


==================================================

Supported systems
=================

  Operating system and Hardware
  -----------------------------

    Purify has been tested with Solaris versions 2.6, 7, 8 and 9 on 
    SPARC platforms.

    Purify has also been tested on V8 and V9 SPARC programs on the 
    UltraSPARC, and supports 64-bit applications.

  Compilers
  ---------

    Purify has been tested with the following compilers:
    - Forte 7 (compiler version 5.4)
    - Forte 6 Update 2 (compiler version 5.3)
    - Forte 6 Update 1 (compiler version 5.2)
    - Forte 6 (compiler version 5.1)
    - Sun Workshop C and C++ 4.2 and 5.0
    - GNU gcc and g++ versions 2.8.1, 2.95.X, 3.0.x, 3.1 (32-bit only)
    - Cygnus GNUpro v.98r

  Threads
  -------

    Purify supports these threads packages:
    - The native Solaris libthread library.
    - The Solaris Pthreads library, libpthread.
    - Transarc DCE threads.

==================================================

Restrictions and Known Issues
=============================

  Java Language Support
  ---------------------
  - To use Purify with JNI applications using JDK 1.2.X, please
    refer to Solution ID 22506 on:
    http://solutions.rational.com/
    or contact Rational Technical Support and reference Solution ID 22506.

  - To use Purify with JNI applications using JDK 1.3.1 or higher, 
    please refer to the Solution ID 134726221 on:
    http://solutions.rational.com/
    or contact Rational Technical Support and reference Solution ID 134726221.

  Licensing Troubleshooting
  -------------------------
  - When Purify is properly installed, a .lm_license_file file is
    created in the product home directory to allow Purify to locate
    your licenses even when LM_LICENSE_FILE is not set appropriately
    in the user's environment. If you get a message such as:

      Error: Unable to open /product_home/.lm_license_file.
      Your installation is incomplete. Did you run rs_install? ...

    Check your product home directory to see if .lm_license_file exists
    and is readable by you. If the file does not exist, your installation
    is incomplete. You may need to re-run rs_install or license_setup.
    If the permissions are incorrect, change them so that the file is
    readable by all expected users of Purify.

  - If you manually change the location of your licenses (e.g. without
    using license_setup), the .lm_license_file will not be updated and
    you will not be able to checkout a license unless you set the env
    var LM_LICENSE_FILE to point to the new location. You should always
    use license_setup to make changes to your licenses.

  - Be sure you install the products that correspond to your license(s).
    Do not install PurifyPlus unless you have a PurifyPlus license or 
    another valid license. To check your license, locate the "INCREMENT" 
    line(s) in your license file (*.dat) or license update file (*.upd). 
    The license feature name is the first word on the line after "INCREMENT". 
    For example:

      INCREMENT PurifyPlusUNIX rational 5.0 10-jan-2001 1 1234556789012
                ^^^^^^^^^^^^^^

  HTML Help
  ---------
  This product has an HTML based online help that incorporates all the
  information from the product user manual.

  The following restrictions and notes apply to using the HTML help system:

  - The only supported browser for the HTML based help system is 
    Netscape Navigator, versions 4.7.x. The HTML based help system
    does not work with pre 4.7 versions or with 6.x versions.

  - You may view the help in stand-alone mode by pointing your browser to
    the following:

      product_home/UI/html/punix.htm

    (Where "product_home" is the installation location of Purify. e.g. the 
    result of the -printhomedir option.)

  - Netscape must be on your path when you run your instrumented program. 
    Your path is used to locate the browser.

  - The first time you request help from a viewer, a new netscape session 
    will be started, even if you already have netscape running. This session 
    will be re-used by subsequent help requests unless you re-use the 
    launched browser for another purpose.  If you close the browser, a new 
    browser will be launched upon the next help request.

  - The new help system uses Javascript. On some platforms, the MOZILLA_HOME
    environment variable must be set in order for Javascript based web pages
    to work properly. If you experience Java related problems with the help:

    Make sure your netscape installation directory is on your path and that
    MOZILLA_HOME is either not set at all (we will set it for you) or is set 
    to the same installation directory.

    If MOZILLA_HOME is set but does not point to the same netscape 
    installation as the netscape on your path, the help may not work 
    correctly.

    If MOZILLA_HOME is not set at all, Purify will attempt to set it when
    we start netscape. But we will be unable to set it correctly if the 
    netscape found on your path does not resolve to an actual installation 
    directory. For example, if netscape actually references a wrapper script 
    in /usr/local/bin. In this case, you will need to set MOZILLA_HOME 
    explicitly.

    See the Netscape release notes for more information on MOZILLA_HOME.

  - Use the Help->Help Topics menu item to access the top level of the
    help system. 

  - Context sensitive help is available on leaf menu items and on buttons
    ONLY. For information about a window, use the Help->On Window menu item.

  - PDF versions of the Purify Quick Reference card is available in the
    doc/pdf section of your installation, if you have installed PDF
    documentation. Otherwise, see the corresponding area of your
    installation CD.

  64-bit Development
  ------------------
  - Purify supports both 32-bit and 64-bit application development, and 
    will select the correct mode of operation automatically based on inputs. 
    The product banner will report the mode of operation during 
    instrumentation and at runtime. However, the "-version" option will 
    always report 32-bit mode; the product version is the same for both modes.

    The product home directory has been reorganized to support both 
    32 and 64-bit development. This organization should be transparent 
    for all 32-bit users and most 64-bit users. However, the location of 
    the Purify stubs library is different for 64-bit applications:

    32-bit libraries have been moved to the lib32 sub-directory:

       purifyhome/lib32/purify_stubs.a
       purifyhome/lib32/libpurify_stubs.a

    To preserve backward compatibility, the following links are provided 
    in purifyhome:

       purifyhome/purify_stubs.a
       purifyhome/libpurify_stubs.a

    32-bit API users are encouraged to use the libraries from the lib32 
    sub-directory, and not from purifyhome.

    64-bit API users must link against the equivalent library in the 
    lib64 sub-directory:

       purifyhome/lib64/purify_stubs.a
       purifyhome/lib64/libpurify_stubs.a

    The API header file has not moved and is shared for both development 
    modes.

  - If you use 'purify -printhomedir' to prefix internal product libraries
    such as libinternal, you must qualify the library path with the 
    appropriate lib sub-directory:

    `purify -printhomedir`/lib32/solaris2_threads.so
    `purify -printhomedir`/lib64/solaris2_threads.so

    Reference to these libraries is rarely necessary.

  - The "full" code size model is not supported - object files and 
    libraries must be addressable within 32-bits. The address range 
    spanned by all instructions in a single object module should
    be less than 2GB. There are no limitations on the size of data.


  General
  -------
  - Purify sometimes does not display line numbers for error messages 
    accurately if the code is compiled with both debug and optimization 
    flags.

  - If Purify is run in "/tmp" or "/usr/tmp" or "/var/tmp" the generated 
    instrumented *.o files are deleted in these directories.  Please do 
    not use commands such as:
    purify cc -nolink ld file.o
    in "/tmp" or "/usr/tmp" or "/var/tmp" . 
    However there is a work-around for this , You can use the option 
    "-save-tmp-files" to tell Purify not to delete the generated objects. 
    So using:
      purify -save-tmp-files cc -nolink ld file.o
    will generate the instrumented file_pure_*.o in "/tmp" or "/usr/tmp" 
    or "/var/tmp". Otherwise you can use -always-use-cache-dir so that 
    the generated file_pure*.o is generated in cache-dir where it is not 
    deleted (Note: if cache-directory is installed in "/tmp","/usr/tmp",
    "/var/tmp" the generated *_pure_*.o in cache are not deleted, so you 
    can have the cache-directory safely in "/tmp","/usr/tmp","/var/tmp").

  - Archive libraries containing both 32-bit and 64-bit libraries are 
    not supported.  All components of a link must be of the same file type.

  - Because of operating system differences, programs instrumented on one 
    version of Solaris may crash or generate incorrect results if run on 
    a different version of the operating system.

  - Purify does not support use of the LD_PRELOAD environment variable.

  - The SPARCWorks incremental linker, ild, is automatically disabled by 
    Purify due to an incompatibility with file naming conventions.

  - Static data checking is not supported with the Forte 6 and Sun One 
    Studio 7 compilers.

  - If you are running your application on a different machine from the one
    on which it was built, please ensure that both the machines have the 
    same operating system. Further, the system libraries on the two machines
    should be identical. Otherwise, Purify might generate a warning message.
    For more details on how to build and run on different machines, please 
    please see Solution ID 5829 at:

      http://eservice.rational.com/solutions

    Or contact Rational Technical Support and reference Solution ID 5829.


  User Interface
  --------------

  - If a large number of items are selected, "Expand all" followed by 
    "Collapse all" can crash some unpatched versions of the OpenWindows 
    3.0 server.

  - If you expand or collapse messages while the "Continue" or "Reset" 
    buttons are displayed, the buttons may subsequently be incorrectly 
    positioned.

  - The "Edit" and "Coverage" toolbar items may be slow to respond.


  - The Purify GUI menus and buttons become inaccessible if either the 
    NumLock or ScrollLock key is activated. The workaround is to switch 
    them off, or add the following line(s) to your $HOME/.Xdefaults file.
 
      ! Ignore the NumLock and ScrollLock keys on 
      ! mouse buttons
      Purify*ignoreModifierMask: Mod3|Mod2
 
    This second workaround will take effect for a new Purify viewer after 
    you restart your X-session or run a command like 'xrdb -merge 
    $HOME/.Xdefaults'.

  Compilers
  ---------
  - The Sun Workshop 5.0 C++ compiler generates different function names 
    than previous versions. Specifically, the new (demangled) function names 
    include the return type, and the new demangler returns "unsigned" where 
    the previous version returned "unsigned int".

    If you have suppressions that specify C++ functions, and you switch to 
    Workshop 5, your suppressions will most likely stop working.

    The only way to fix them is to modify the function names in your 
    suppressions to the new style.  In order to use your suppressions with
    both 5.0 and older compilers, you need to include both your old 
    suppressions and the new ones.

    The surest way to determine the correct name to use in your suppression 
    is to add the suppression using the Purify viewer.

  - The GNU gcc extensions are not tested against Purify.  Most gcc 
    extensions will probably work fine.  Known limitations at present 
    include problems with nested functions (e.g.: making a pointer to a 
    nested function and attempting to call through it will not work).

  - GNAT ADA

    The GNAT ADA compiler emits stack management code which causes Purify 
    to report SBR/SBW messages.  These messages are harmless.  Rather than 
    globally suppressing SBR/SBW, these specific messages may be safely
    eliminated by setting the Purify runtime option -mark-partial-rsz.

  Purify'ing X Applications
  -------------------------

  - When running a Purify'd X application, there is a potential for 
    deadlock if your application causes Purify to generate a message while 
    the application is holding the X lock, typically allocated and released
    with the XGrabServer()/XUngrabServer() Xlib API's, since Purify will 
    be unable to generate the message and the application is blocked until 
    the message is delivered.

    To avoid this kind of problem, you should run your application on a 
    different X server than the Purify UI or Purify stderr output, or you
    should use the -log-file= or -view-file= options to specify a file to 
    capture messages for inspection after your application is finished.

    A convenient way to debug on two displays is to pre-start the Purify 
    Viewer on one display ("slave"), and then start the application on
    the other display ("master"):

      % purify -display slave:0 -view a.out.X &
      % a.out.X -display master:0

    The two commands must be executed on the same computer, but it could be 
    the workstation associated with either display, or altogether another 
    computer remote from both displays. The application will connect to the 
    already started Purify Viewer, and messages will not conflict with the 
    X display interactions of the application under test.

  Threads
  -------

  - Call chains describing when memory was malloced or freed do not always 
    include the thread id.

  - The Purify API functions purify_map_pool() and purify_map_pool_id() are 
    not MT safe.

  - Customers using unsupported threads packages should contact Rational 
    Software technical support (support@rational.com) to ensure compatibility.

  Copyright Notice
  ----------------

  The following copyright applies to portions of the ClearQuest
  integration and HTML based help system. 

  Copyright 1996 Netscape Communications Corporation, all rights reserved.
  Created: Jamie Zawinski (jwz@netscape.com), 24-Dec-94.  Permission to
  use, copy, modify, distribute, and sell this software and its
  documentation for any purpose is hereby granted without fee, provided
  that the above copyright notice appear in all copies and that both 
  that copyright notice and this permission notice appear in supporting
  documentation.  No representations are made about the suitability of
  this software for any purpose. It is provided "as is" without express
  or implied warranty.