
                Installation Instructions                                      
                Visual Threads Version 2.2

This document contains the information you need to install 
Visual Threads Version 2.2 on a Compaq Tru64 UNIXR system. 
You must read this document before installing Visual Threads.


Visual Threads Kit Summary

Product Name: Visual Threads Version 2.2

Operating System: Compaq Tru64 UNIX Version 4.0D or higher 
for Alpha Systems (patch kit required for V4 systems)

License: Compaq Developers' Toolkit for Compaq Tru64 UNIX  
license (OSF-DEV Product Authorization Key [PAK])


Required Hardware

You need an Alpha system and a workstation monitor or terminal.
If you are installing from a CD-ROM, you also need a CD-ROM
drive.


Required Software

The following table shows the Visual Threads subsets and 
disk space required:

Visual Threads Subset Name and Size

Contents          Subset Name    Disk Space in   Status
                                 /usr/opt

Visual Threads    DVTBASE220     20,000 KB       Required
Base Components

Java Runtime      JAVJRE118      4,000 KB        Required
Environment


Required Tru64 UNIX Software

Required Tru64 UNIX Subsets

Contents                         Subset Name

Compaq Tru64 UNIX Base System.   OSFBASE425 or higher*

Standard Programmer Commands     OSFPGMR425 or higher
(Software Development).

Static Libraries (Software       OSFLIBA425 or higher
Development).  This is
required only if you make 
use of any Visual Threads
features requiring
instrumentation.

* See also "Information about Tru64 UNIX Versions 4.0D, 4.0E
and 4.0F" for patch kit requirements.


Required Java Software

You should install the JAVJRE118 subset included with the 
Visual Threads kit since Visual Threads has been validated 
with this Java Runtime Environment.  It can coexist with 
any existing JAVA (JRE or JDK) you have installed, and does 
not supercede them in any way.


TruCluster Support

Visual Threads can be run in a TruCluster environment.
During installation, a Visual Threads configuration step
will be performed on each member of the cluster.


Information About Tru64 UNIX Versions 4.0D, 4.0E and 4.0F

In order to analyze threaded applications, Visual Threads 
requires a debugging-enhanced version of several system
libraries (libpthreads.so, libpthreadsdebug.so, 
libpthread.so, libcmalib.so, libc.so, and libexc.so).   
These enhanced libraries are included in Patch Kit 4 (or 
later) for Tru64 UNIX Version 4.0D, in Patch Kit 2 (or 
later) for Tru64 UNIX Version 4.0E,a nd Patch Kit 4 (or
later) for Tru64 UNIX Version 4.0F.  With this version of 
Visual Threads, you must install one of these patch kits 
before installing Visual Threads.


Making Ladebug Accessible

The Ladebug image has "set user ID" mode (the SUID bit is 
set) to enable remote debugging.  Thread-specific debugging 
commands may not work from within Visual Threads if you're 
using Tru64 UNIX Versions 4.0D or 4.0E.

To eliminate this problem, the set user ID mode must be
removed.  Log in as root and enter the following commands:

% chmod -s /usr/opt/LDBnnn/bin/ladebug
% chmod +r /usr/opt/LDBnnn/bin/ladebug

For example, for Ladebug Version 4.0-48, enter:

% chmod -s /usr/opt/LDB448/bin/ladebug
% chmod +r /usr/opt/LDB448/bin/ladebug

Note that as long as these changes are in effect, remote 
debugging may not work correctly for Ladebug at your site.


Atom Software

The Visual Threads Instrumentation tool (VTI) works best 
with versions of Atom that fully support the -gp,
-Xnodisable, and -Xfork options.  During installation and
during instrumentation, warning messages are generated if
the version of Atom doesn't support all of these options.
See the Visual Threads Release Notes for details.

Note that an appropriate version of Atom is supplied with 
Tru64 UNIX Versions 4.0F and greater and with the Compaq 
Developers' Toolkit Supplement for Compaq Tru64 UNIX, but 
not with Tru64 UNIX Versions 4.0D or 4.0E.

If you receive installation or instrumentation warnings
regarding Atom, you may consider getting a newer version
of Atom from the Compaq Developers' Toolkit Supplement for 
Compaq Tru64 UNIX.  See the Release Notes for details.


Installation Steps

Perform the following steps to install Visual Threads:

1. Back up your system disk before installing any software.
   For details on performing a system disk backup, refer
   to your system documentation.

2. Access the files, depending on the type of installation 
   you are doing:

   If you are performing a download from the Visual 
   Threads Web site at http://www.compaq.com/visualthreads/,
   copy the DVT220.tar file to a temporary area on your
   system.  Expand the file by using the following command:
   tar -xvf DVT220.tar.

   If you are performing a CD-ROM installation, mount the 
   CD-ROM containing the Visual Threads kit.

   If you are installing Visual Threads subsets from a 
   Remote Installation Services (RIS) server area of a 
   remote system to your local system, first check with 
   your site system administrator to make sure that:

    A Visual Threads kit is installed in the RIS 
     server area and is available for use.

    Your system is registered as a RIS client.

   If the Visual Threads subsets are available on a RIS 
   server system, you need the name of that system to start 
   the installation procedure.

   See "Installing into a RIS Server Area" on page 8. 

3. Log in as superuser (login name root) to the system 
   where you are installing Visual Threads.

4. Determine if you have enough available disk space for 
   the installation and add more if necessary.  (See 
   "Increasing Disk Space for the Visual Threads
   Installation" on page 6.)

5. Make sure /usr/tmp and /tmp have read and write
   permissions for all Visual Threads users. Without
   read and write permissions on these directories,
   Visual Threads will not start.

6. If necessary, delete old Visual Threads kits.  Use the 
   setld -i command to list the subsets installed on your 
   system and check for the presence of any subset with a 
   name that starts with DVT.  For example:

   # /usr/sbin/setld -i | grep DVT | grep installed

   If any of these subsets exist, they are old versions 
   that must be deleted. To delete a subset, use the setld 
   -d command. For example, to delete the Version 1.1 base 
   subset, enter the following command:
   # /usr/sbin/setld -d DVTBASE110

7. Use the setld -l command to install the Visual Threads 
   files.

   If you mounted the CD-ROM, specify the full path name of 
   the directory on the CD-ROM containing the Visual 
   Threads software:

   # /usr/sbin/setld -l `directory-name'

   If you downloaded the files from the Web site, set your 
   working directory to the kit subdirectory and then use 
   the following command:

   # /usr/sbin/setld -l .

8. The installation script lists the subset choices:

   The following subsets are mandatory and will be 
   installed automatically unless you choose to exit
   without installing any subsets:

      * Java 1.1.8-10 Standalone Runtime Environment
      * Visual Threads Base Components

   You may choose one of the following options:

     1) ALL of the above
     2) CANCEL selections and redisplay menus
     3) EXIT without installing any subsets

   Estimated free diskspace (MB) in root:284.4 usr:1257.0

   Enter your choices or press RETURN to redisplay menus.

   Choices (for example, 1 2 3-5): 1

   Enter the numbers of the subsets to install and press 
   Return.

9. The installation script prompts you to confirm your 
   subset selections. Enter y and press Return to confirm.

10. The installation script installs the software and
   displays messages describing the installation.

   If you see a warning message about the installed
   version of libpthreads, see "Information About Tru64
   UNIX Versions 4.0D and 4.0E".

   If you see a warning message about DECthreads being 
   unable to generate timestamps, see "DECthreads Library 
   Warning About Timestamps" on page 7.

   If you see a warning message about the Atom version, see 
   "Atom Software" on page 3.  Also see additional
   information in the Visual Threads Release Notes.

11. Run the Installation Verification Procedure.  (See 
   "Verifying the Visual Threads Installation" on page 5.)

12. If you want to update the whatis database of keywords, 
   use the following command: 

   # /usr/sbin/setld -c DVTBASE220 WHATIS


Verifying the Visual Threads Installation

After you install Visual Threads, you should run the
Installation Verification Procedure (IVP).  Before running 
it, make sure that /usr/tmp has at least 7 MB of available 
disk space.

To verify the Visual Threads base subset, enter the following
command:

# /usr/sbin/setld -v DVTBASE220

The Installation Verification Procedure (IVP) runs and
displays information on your terminal.  The IVP should end
with the following text:

Installation Verification Procedure Successful


Reading the Release Notes

Before you use Visual Threads, be sure to read the release 
notes.  If you are upgrading from an earlier version, be 
sure to read the section called "User Interface Changes 
from Previous Release."


Registering an OSF-DEV License to Use Visual Threads

You must have the Compaq Developers' Toolkit Supplement for 
Compaq Tru64 UNIX license (the OSF-DEV PAK) loaded to run 
Visual Threads.  If you do not have this PAK, contact your 
local authorized Compaq sales representative or visit the 
software licensing Web site at
http://www.compaq.com/products/software/info/ for information.


Using Visual Threads After Installation

Running Visual Threads

You can run Visual Threads in several ways:

  o From an icon on a Tru64 UNIX system.  Use the CDE folder 
    Application_Manager, which points to 
    Developers_Toolkit, where the Visual Threads icon 
    resides.

  o From the command line on a Tru64 UNIX system. After
    setting your DISPLAY environment variable, invoke 
    dxthreads or VisualThreads. 


Using the Online Help

All the documentation for Visual Threads is contained in 
the online Help.  (There is also a manpage called dxthreads 
and related manpages called vti and vttrace.)

Before you start using Visual Threads, you should choose 
Help: Contents from the Control Panel.  Then read all the 
topics in the online book "Getting Started" for a quick
introduction that will save you time in learning Visual 
Threads.


Increasing Disk Space for the Visual Threads Installation

To determine the current amount of free space for a
directory path:

1. Log in to the system where you plan to install Visual 
   Threads.

2. Check which file systems are mounted and where they are 
   by displaying the /etc/fstab file. For example:

   # more /etc/fstab

   /dev/rd0a:/:rw:1:1:ufs::
   /dev/rd0g:/usr:rw:1:2:ufs::
   /usr/staff/r1/leslie@bigsys:/usr/staff/r1/leslie:rw:0:0:nfs
   /usr/man@bigsys:/usr/man:ro:0:0:nfs:bg:

   In this example, /usr (mounted to /dev/rd0g) is the 
   only mount point that affects where Visual Threads 
   files will reside; the system has only one local disk 
   drive and the /usr file system resides in the g
   partition of the disk on that drive.

3. Enter the df command to determine total space and free 
   space for the file system where Visual Threads files 
   will reside. Based on the preceding display of the
   /etc/fstab file, which shows that only /usr is a mount 
   point, you will need to inspect free space only in the
   /usr file system.

   # df -k /usr

   Filesystem Total   kbytes  kbytes %
   node       kbytes  used    free   used    Mounted On

   /dev/rd0g  122598  54447   55892   49%     /usr

   This display indicates that there are 55,892 KB free.

The Visual Threads installation procedure creates the
directory /usr/opt/DVT220, if it does not already exist,
and loads files into subordinate directories.  If you
have insufficient disk space for the Visual Threads
subsets and know that you have additional space on
alternative disks or disk partitions for your system,
you can take the following steps before installing
Visual Threads:

1. Log in as superuser (login name  root).

2. Create the directory /usr/opt/DVT220.

3. Specify in the /etc/fstab file that the newly created 
   directory is a mount point to new disk partitions where 
   there is additional space.

4. Enter the mount /usr/opt/DVT220 command to have the new 
   mount point take effect.


DECthreads Library Warning About Timestamps

If you use the DECthreads library directly to generate 
trace files, the library must be able to access the file
/dev/sysdev0.  Without this file, the generated trace files 
contain null timestamps, which makes the threads analysis 
data unusable by Visual Threads.

Typically, you are warned if this problem exists by one or 
more messages, including during installation of Visual 
Threads.

If you have not yet created this file, you can create it 
using the the following command, which you execute as
superuser:

cd /dev
./MAKEDEV sysdev0

Performing this step also provides better performance when 
generating timestamps as Visual Threads processes events.


Stopping the Installation

You can stop the installation procedure at any time by 
pressing Ctrl+C.  However, files created up to that point 
are not deleted.  You must delete these files interactively.


Deinstalling the Software

Use the setld command to deinstall Visual Threads: 

# /usr/sbin/setld -d DVTBASE220


Error Recovery

If errors occur during the installation, the system displays
error messages. If the installation fails due to insufficient
disk (file system) space, the installation procedure displays
the following message:

fitset:
filesystem /usr needs xxx kbytes more to install the
software specified

An error can also occur during the installation if:

1. The operating system version is incorrect.

2. The Networking Utilities subset is not installed.

3. The operating system is V4.0D or V4.0E without an 
   appropriate patch kit installed.

For more information about error messages generated during 
installation, see your system documentation on system messages,
recovery procedures, and software installation. If you are
notified that any errors occurred, take the appropriate action
as described in that documentation.


Visual Threads E-mail Address and Web Page

If you have comments, questions, or feedback about Visual 
Threads that you'd like to send to Compaq, send an e-mail 
message to Visual.Threads@hp.com.

For the latest information, see the Web page at
http://www.compaq.com/visualthreads/.


Installing into a RIS Server Area

You can install Visual Threads with the Remote Installation 
Services (RIS) utility into a RIS server area on a Tru64 
UNIX system. You do not use the setld command for this 
operation. To install Visual Threads from a RIS server to a 
RIS client, you must first install Visual Threads in your 
RIS server environment. See your RIS manager if Visual 
Threads is not already installed on the RIS server.

To install Visual Threads subsets that reside in a
/var/adm/ris distribution area on a remote system, start the
installation procedure as follows:

1. Log in as superuser (login name root) to the system 
   where you are installing Visual Threads.

2. Enter the following command to ensure that you are at 
   the root (/) directory:

   # cd /

3. Enter a setld command that requests the load function 
   and identifies the system where the Visual Threads subsets
   are located.

   For example, if you are loading Visual Threads subsets 
   from a RIS distribution area on node bigsys, enter the 
   following command:

   # setld -l bigsys:

   RIS then displays a menu that lists all the software 
   subsets available to you and prompts you to enter the 
   numbers of those you want to load.

   Note that the numbers of the Visual Threads subsets 
   vary from system to system, depending on which products 
   are available in the RIS area and how many subsets each 
   has.

4. Enter the numbers of the Visual Threads subsets that 
   you want to install and press Return. The setld utility 
   installs Visual Threads on the client machine.


RIS Disk Space Requirements

If you are installing Visual Threads into a RIS server area, 
you do not create Visual Threads file systems, but instead 
use the RIS utility to extract files from media.  Visual 
Threads files are compressed during the extraction process 
and require the following amounts of disk space to be
available in the RIS server area:

Visual Threads Version 2.2 - 16,000 KB


Sample RIS Installation

The following sample session describes how to add Visual 
Threads to the ris0.alpha area:

1. Log in as superuser (login name root).

2. Enter the following command to invoke the RIS utility:

   # /usr/sbin/ris

3. Select the Install Software option from the RIS main 
   menu by entering i at the prompt:

   *** RIS Utility Main Menu ***

   a) ADD a client
   d) DELETE software products
   i) INSTALL software products
   l) LIST registered clients
   m) MODIFY a client
   r) REMOVE a client
   s) SHOW software products in remote installation environments
   x) EXIT

   Enter your choice: i

4. Choose option 2 from the RIS Software Installation Menu:

   RIS Software Installation Menu:

   1) Install software into a new area
   2) Add software into an existing area
   3) Return to previous menu
 
   Enter your choice: 2

5. A list of available environments appears from which you 
   might select ris0.alpha:

   You have chosen to add a new product into an
   existing environment.

   Select the remote installation environment:

   1 /usr/var/adm/ris/ris0.alpha

   (list of available products for environment)
    .
    .
    .

   Enter your choice: 1

6. The installation procedure then prompts you for an 
   input device name:

   Enter the device special name or mount point of
   the distribution media, for example, /dev/rmt0h:
   /dev/rmt0h

7. After the subsets are installed, the following message 
   appears:

   Media extraction complete.

8. When the RIS main menu appears, choose the m menu item 
   (Modify Client) to add Visual Threads to the list of 
   products that RIS clients can install.


Copyright 2002 Compaq Information Technologies Group, L.P.
