1

Installing the products

The basic steps

Note: Rational® PurifyPlus is a Rational product that includes Rational® Purify®, PureCoverage®, and Quantify®, and provides a unified procedure for installing all three applications on your system at the same time.

To install Rational PurifyPlus, Purify, PureCoverage, or Quantify:

1. If you have purchased a permanent license or a term license agreement (TLA) from Rational Software, obtain a .upd file with license information from the AccountLink page on Rational Software's website.

   If you are installing the product with a startup or evaluation key, skip this step.

   Note: A permanent key allows the use of the product without time limits. A TLA key allows the use of the product for a specific period of time. A startup license key gets you up and running as soon as you receive your Rational product, but you will have to enter a permanent or TLA key later to continue using the product. An evaluation license key is valid for a limited time, but again you will have to enter a permanent or TLA key later to ensure continued use of your Rational product.

2. Install the product on your system using the rs_install program.

This chapter tells you how to gather the information you need to perform these steps, as well as instructions to get you started using AccountLink and the rs_install program. It also contains information about post-installation tasks (such as uninstalling) and administering the GLOBEtrotter FLEXlm® Software License Manager that is included with your Rational Software product.

Information you need for AccountLink

In addition to contact information, you will need to provide the following to obtain a .upd file with licensing information:

Data for AccountLink	Notes	Your Entry
Your Rational account number	Source: your Rational license key certificate.
License Type	Permanent and TLA licenses for PurifyPlus can be either Floating licenses or Named User licenses. Permanent and TLA licenses for Purify, PureCoverage, and Quantify are always Named User licenses. For further information, see Maintaining the rational.opt options file.
Rational Product Line		DEVELOPER TOOLS
Product Name	Source: your Rational license key certificate.	PurifyPlus for UNIX, Purify for UNIX, PureCoverage for UNIX, or Quantify for UNIX
Quantity	Source: your Rational license key certificate. This is the number of named-user licenses that you have purchased.
Host Name and hostid	This is the name and hostid of the machine that you intend to use as your license server host. If the license server host is different from the installation machine, you must have remote shell access from the installation machine to the license server host.  In addition, the installation directory must be accessible from the license server host. If you do not know the hostid of your license server host, download the tool gethostinfo.sh from AccountLink, and run it on your system.

Obtaining a .upd file using AccountLink

Access AccountLink at http://www.rational.com/accountlink/.

When you supply the required information to AccountLink, you will receive by return email a file named license_for_<server name>.upd. Save this file in a location that is accessible from the installation machine. If you are installing a permanent or TLA license, you need this file before you proceed with the next step, running rs_install.

Information you need for rs_install

You need all the information in the following table to install your Rational product, unless you have previously set up a FLEXlm license for the product. If you have set up a FLEXlm license, all the data you need is already available to the rs_install program.

Data for rs_install	Notes	Your Entry
The full pathname to the installation location (referred to in this chapter as Rational).	This is the directory for installing all Rational Software products. You must have 20 megabytes of free disk space for each installation of Purify, Quantify, and PureCoverage. You must have 60 megabytes for a complete installation of PurifyPlus. The directory must be accessible from every machine on which you plan to run the Rational products-both the machines on which users instrument their applications, and the machines on which users run their applications. It must be the same for each machine, so you cannot use a local automount path like /tmp_mnt/rational. If Rational does not already exist, the installation program will create it when you enter the full pathname. If you are installing on a read-only file system, or if you want to create this directory manually, see Supplemental notes. This section also shows you the structure of the directory after installation.
License key type.	Source: your Rational license key certificate. Note: To enter a permanent or TLA license key after you've been using a startup or evaluation license, see Entering a permanent or TLA license key after initial installation.	permanent, TLA, startup, or evaluation
Host name or IP address of the host machine on which the license server is to run (the "license server host").	This data is required only if you are setting up a permanent or TLA license and cannot import the license_for_<server name>.upd file. If the license server host is different from the installation machine, you should have remote shell access from the installation machine to the license server host. If you do you have remote shell access, the rs_install program provides instructions for how to proceed. In addition, the installation directory must be accessible from the license server host.
License server port number.	This data is required only if you are setting up a permanent or TLA license and cannot import the license_for_<server name>.upd file. This is the port at which the license server listens for license requests. Default is 27000. You can use any port number that is not already in use. The /etc/services file on the license host lists all ports in use by most commonly used services, but other ports may be in use on your system as well. FLEXlm reserves ports 27000-27009 for its use; these ports are ordinarily available unless a different FLEXlm server on the license host is using them. The rs_install program checks to make sure that the license server port number does not conflict with entries in the /etc/services file on the license server host, or with NIS services.
License quantity.	This data is required only if you are setting up a permanent or TLA license and cannot import the license_for_<server name>.upd file. Source: your Rational license key certificate.
Expiration date.	This data is required only if you are setting up an evaluation or startup license. Source: your Rational license key certificate or email from Rational Software. If you have a startup or evaluation license, enter the date in the dd-mmm-yyyy format. The field is not case sensitive.
Note: If you are installing a permanent or TLA Named User license, you must supply user names for each individual who will be using the product. You must include your user name in order to perform the post-installation selt-test successfully. User names are recorded in the FLEXlm options file, rational.opt. For information about the options file, see Maintaining the rational.opt options file. You do not need this information if you are installing a Floating license for PurifyPlus. To input User names, you need the data in A or B below, or the data in A supplemented with the data in B.
A. Path of the PureLA directory containing the file users.purela (available only if you licensed an earlier version of the product using PureLA License Advisor).	If you are currently running the product under a PureLA license, you have the option of importing the user names from the PureLA database instead of entering them manually. The PureLA directory is located in the same parent directory as the previous product installation, which you can find with the command <product>-printhomedir. You can modify the list of imported user names, either while you're running  rs_install or afterwards. If the number of user names is not the same as the number of licenses you bought, rs_install will help you correct the list.
B. user names (all names; or some or none, in combination with an option to generate dummy names).	You can enter all user names. The number of names you enter must match the number of licenses you purchased. You can enter some user names, and then enter -n to populate the rest of the options file with dummy names as placeholders that you can replace later. Or you can just enter -n to enter nothing but dummy names, and update the options file later.
Name for the Rational license file (<server name>.dat), including full pathname.	This name is required only if you are setting up a permanent or TLA license. The rs_install program, which creates this file when it runs, will suggest <server name>.dat as a default. If you want to use an existing Rational license .dat file, enter its name, including full pathname, instead of the default. The rs_install program makes a backup of the existing license file before it processes the file with the new data. For information, see The Rational license file.

Installing the products using rs_install

For information about specific product and operating system versions, see the README file in the DeveloperTools.<version> directory. For information about rs_install, run rs_help, which opens a Help file in a Netscape browser.

To install the products:

1. Make the product available for installation.

   If you are installing the product from the Rational Software product CD-ROM and need instructions, see Mounting the CD-ROM.

2. Run the rs_install program

   The rs_install program is a complete installer that guides you through the following processes:

• Setting up the license server
• Installing product licenses
• Installing the selected product
  Note: Your users can get online help only if you install the html documentation.
• Performing the post-installation tasks

To run the rs_install program, go to the directory where you mounted the CD-ROM. (You should not be root when you run rs_install.) For example:

# exit
% cd /cdrom
% ./rs_install

The rs_install program prompts you through the installation, providing detailed instructions along with default settings. The defaults appear in brackets, for example [2]. To accept the default, press Enter.

Note: After you install your license key, the rs_install program reminds you that you must configure your server to automatically restart the license server when it reboots. The rs_install program gives you instructions for doing this.

3. When installation is complete, go to After you install: Post-installation tasks and perform any necessary post-installation procedures.

Answers to questions about rs_install

Below are the answers to some common questions about the rs_install program.

• Can I rerun parts of the installation?
  Yes. The rs_install program provides commands that enable you to rerun specific sections of the installation as needed. See Using rs_install commands.
• Do I have to reenter my license server information each time I install a product?
  No. You only need to enter this information once. The rs_install program saves the information you enter about yourself and about the machine to be used as the license server for your Rational Software product licenses in two text files: an rs_install.defaults file that contains information about you and your license server, and a file such as rs_install.DeveloperTools.5.2 that records product-specific information. The rs_install program reports the location of these files when you quit the program. The next time you run rs_install, the program uses the saved configuration information.
• Do I need to install all my licenses on one server?
  No. You are not required to use all of your allowed licenses for a single license server. You might want to install a product at another site and configure a license server at that site to serve the remaining licenses in your Rational Software account.
• Which type of product license key should I install?
  If you already have your permanent ro TLA license key, you can install it right away. You can also request a permanent license key at www.rational.com/accountlink. Otherwise, select the startup or evaluation license to get started using the product.

  Note: To ensure uninterrupted use of your Rational Software product, you should install your permanent or TLA license key as soon as possible.

• Can I import existing user names from an earlier installation of the product installed with Named User licensing?
  Yes. If you installed the product previously under FLEXlm, the user names are imported automatically when you run rs_install. If you installed the product under PureLA License Administrator, rs_install asks you if you want to import the existing users.purela file, and also permits you to edit the imported user names. You can also edit the user names after installation; see Maintaining the rational.opt options file.
• How do I proceed if I already have other Rational product licenses installed on my server?
  You must add the new licenses to your current Rational product license file. To do this, specify the current Rational license file as the license file name instead of using the default.
• How do I get updates for the rs_install program and for the Rational products?
  You can get updates from within the rs_install program, though you must be running the program on a machine that has network access. The rs_install program's Licensing Options screen lets you select an item to download the latest version of rs_install (in which case rs_install replaces itself and restarts using the new version) or get product updates.

After you install: Post-installation tasks

For Rational PurifyPlus

The single post-installation task for Rational PurifyPlus is to notify all users of the product that they must source either purifyplus_setup.csh or purifyplus_setup.sh, depending on the shell they are using. Sourcing these files makes the product license available to the user and updates their command search path and man page path.

These files can be found in the Rational directory

For Rational PurifyPlus

The post-installation tasks depend on the individual products. The rs_install program performs these tasks for you if possible, or tells you how to perform them from outside of the installation program. Post-installation tasks can include:

• Installing on a read-only file system
• Making the manual pages available
• Making the products available to all users

Note: You can rerun the post-installation at any time. See Using rs_install commands.

Installing on a read-only file system

Purify, PureCoverage, and Quantify work by creating and monitoring special instrumented versions of object files and libraries. They must be able to write these instrumented files to a cache directory, which by default is Rational/releases/<producthome>/cache.

For this reason, if you install any of the products on a file system that is mounted read-only by client machines, you must create symbolic links to a writable file system. The rs_install program guides you through the process of selecting a shared directory that is mounted read/write on client machines and linking the cache directory to this publicly writable directory.

If there is no writable shared directory mounted on client machines, have all users make a cache subdirectory in their home directory and set the product's -cache-dir option to this directory. For example:

% mkdir $HOME/cache
% echo $PUREOPTIONS

If the PUREOPTIONS environment variable is already set, have users specify the -cache-dir option:

csh % setenv PUREOPTIONS "-cache-dir=$HOME/cache \
     $PUREOPTIONS"
sh, ksh $ PUREOPTIONS="-cache-dir=$HOME/cache \
     $PUREOPTIONS"; export PUREOPTIONS

If the PUREOPTIONS environment variable is not set, have users specify:

csh % setenv PUREOPTIONS "-cache-dir=$HOME/cache"
sh, ksh $ PUREOPTIONS="-cache-dir=$HOME/cache"; export \
     PUREOPTIONS

Have all users add this same specification to their local or central .cshrc file, or its equivalent.

Making the manual pages available

The rs_install program installs the product manual pages in Rational/releases/<producthome>/man. To make them available, do one of the following:

• Set your MANPATH environment variable to include Rational/releases/<producthome>/man.
• Copy the manual pages for the product into your man directory.
  If necessary, log in as root to do this.

Making the products available to all users

Note: If you are using Named User licensing, users must be listed in the rational.opt file in order to use Purify, PureCoverage, and Quantify; to add users to the options file, see Maintaining the rational.opt options file.

To make the products available to all users listed in rational.opt, add the full Rational/releases/<producthome> pathname to each user's PATH environment variable, or specify the full pathname in makefiles.

As an alternative to modifying your PATH environment variable, you can create a symbolic link to <producthome>/<product> from a directory such as /usr/local/bin. Make sure this is a symbolic link, not a copy or a hard link. Create symbolic links for each product you install, as in the following examples:

• For Purify:

  % rm /usr/local/bin/purify
  % ln -s Rational/releases/\
     <producthome>/purify /usr/local/bin
  

• For PureCoverage:

  % rm /usr/local/bin/purecov
  % ln -s Rational/releases/\
     <producthome>/purecov /usr/local/bin
  

  For PureCoverage, you also need to create symbolic links to the pc_* script files:

  % rm -i /usr/local/bin/pc_*
  % ln -s Rational/releases/\
    <purecovhome>/scripts/pc_* /usr/local/bin
  

  For more information on the pc_* scripts, see the PureCoverage online help system.

• For Quantify:

  % rm /usr/local/bin/quantify
  % ln -s Rational/releases/\
    <producthome>/quantify /usr/local/bin
  

  For Quantify, you also need to create symbolic links to the qv program and to the qx script files:

  % rm /usr/local/bin/qv
  % rm -i /usr/local/bin/qx*
  % ln -s Rational/releases/\
     <quantifyhome>/qv /usr/local/bin
  % ln -s Rational/releases/\
     <quantifyhome>/qx* /usr/local/bin
  

  For more information on the qv program and on the qx scripts, see the Quantify online help system.

• Create symbolic links for debugger scripts on HP-UX:

  On HP-UX, Purify, PureCoverage, and Quantify include three scripts that enable you to start instrumented programs under a debugger. You need to create symbolic links to these scripts. For example, for Purify:

  % rm /usr/local/bin/purify_dde 
  % rm /usr/local/bin/purify_xdb
  % rm /usr/local/bin/purify_softdebug
  % ln -s <purifyhome>/purify_dde /usr/local/bin
  % ln -s <purifyhome>/purify_xdb /usr/local/bin
  % ln -s <purifyhome>/purify_softdebug /usr/local/bin
  

  For PureCoverage and Quantify, create the same symbolic links, substituting purecov or quantify for purify.

The installation is now complete. To add names to the options file, see Maintaining the rational.opt options file. To remove previous versions of the products, see Removing a previous product release.

Maintaining the rational.opt options file

Named User licensing is always used with Purify, PureCoverage, and Quantify, and is available for use with PurifyPlus. Under Named User licensing, the user names of all users who are authorized to run Purify, PureCoverage, and Quantify must be listed in the rational.opt options file. The number of user names in the file must match the number of licenses you have installed.

Users who are identified in the file can use all features of the product, including instrumenting applications, running instrumented applications, and viewing saved data files in the product's user interface. A user can run as many concurrent sessions as desired on a single host machine; this consumes a single license. The same user can run the product on additional host machines, but consumes another license for each additional machine.

The options file is created when you run the rs_install program. By default, this file is Rational/config/rational.opt. You can relocate the file yourself after installation, provided that you edit the license file DAEMON line to specify the new path:

DAEMON rational /etc/rational /mydir/rational.opt

During installation, rs_install asks you to supply user names, one for each license you purchased. You don't have to enter all user names during installation; rs_install will generate dummy names to bring the total up to the number of licenses you purchased. Your entries-real names, automatically generated dummy names, or both-are recorded in the options file.

The user names are recorded in the options file in GROUP directives. An INCLUDE directive follows each GROUP directive, specifying one product that the users in the group are authorized to use:

GROUP <group name> <user1> <user2> . . . <usern>
INCLUDE <product>:KEY=<license key> GROUP <group name>

For example, in the following, alice, tom, and harry can use Purify, but only alice and harry can use Quantify:

GROUP DevTools1 alice tom harry
INCLUDE purify:KEY=456778982 GROUP DevTools1
GROUP DevTools2 alice harry
INCLUDE quantify:KEY=12345778654 GROUP DevTools2

The KEY is the license key that you receive from Rational Software in the .dat license file.

Modifying the list of user names

Note: If you modify the options file while the license vendor daemon is running, you must restart the license server.

You can add, change, or delete user names by running the options_setup script. You can also add, change, or delete user names in the options file using any text editor.

The number of users listed for each product must always match the number of licenses that you purchased. The license server must be restarted before the changes can take effect; the options_setup script restarts the license server for you.

For additional information about the options file, refer to your FLEXlm user's manual.

Removing a previous product release

Note: Only the installer of the product can uninstall it.

After you install the latest version of Purify, PureCoverage, or Quantify, and after all users have switched to the new version, you can remove the old release to reclaim disk space.

To remove a previous release of Purify, PureCoverage, or Quantify, go to the Rational directory and run the uninstall script:

% cd Rational
% config/uninstall

Running the uninstall script with no command-line arguments causes it to display the list of products in the releases directory. The script prompts you for the product you want to remove.

Requesting and installing the permanent or TLA license key

When you purchase Purify, PureCoverage, or Quantify, you purchase a specific number of licenses for each product. Rational Software issues you a license key for the product that corresponds to the type and number of licenses you purchased. You need this license key to use the software.

Purify, PureCoverage, and Quantify come with a startup license that you can use to get started using the product. You then request a permanent or TLA license key from Rational Software at http://www.rational.com/accountlink/ and install it to ensure continued use of the product. The startup license key and other licensing information is available from the License Key Certificate included in the product packaging.

Purify, PureCoverage, and Quantify use the FLEXlm Software License Manager from GLOBEtrotter Software, Inc. to manage product licenses. For more information on FLEXlm, see Using the FLEXlm Software License Manager.

Requesting your permanent or TLA license key

To request a permanent or TLA license key, go to http://www.rational.com/accountlink/ and follow the instructions provided there.

Entering a permanent or TLA license key after initial installation

To enter your permanent or TLA license key after you have installed your Rational Software product and exited the rs_install program:

1. Go to the Rational/releases/DeveloperTools.<version> directory and run the license_setup program. For instructions, see Using rs_install commands.
2. For the licensing option, select the option for setting up a permanent license.

   Note: The program tells you how to update your license server machine so that it restarts the license server when it reboots. You need root permission to perform the update.

Supplemental notes

Creating an installation directory manually

You need a publicly readable directory for the installation of Purify, PureCoverage, and Quantify. If one does not already exist, you can create it when you run rs_install. You can also create it manually before you start rs_install.

1. Log into a UNIX workstation that provides access to the CD-ROM drive and that mounts the file system(s) into which you want to load the products.
2. Create a Rational directory. For example:

   % mkdir /opt/Rational
   

The Rational directory must be visible on all machines that are to run this product. The NFS name for Rational must be the same on all machines. (If you are installing the product for your use only, you can install it in your home directory.)

After the installation, the Rational directory is structured like this:

Note: Purify, PureCoverage, and Quantify must be able to write instrumented files to a cache subdirectory of the <producthome> directory. If you install on a read-only file system, you must create symbolic links to a writable file system. See Installing on a read-only file system.

Mounting the CD-ROM

The following instructions refer to specific operating systems.

To determine your operating system, type:

% uname -a

Note: Before you begin, make sure you know the device name of your CD-ROM drive. If you do not know the device name, consult your system administrator.

On Solaris and IRIX systems with Volume Management, load the CD-ROM and then go to Step 5. (On these systems, the CD-ROM automatically mounts on the /cdrom directory. To determine whether you have Volume Management, check to see if the Solaris vold daemon or the IRIX mediad daemon is running on your system.)

To mount the CD-ROM:

1. Load the CD-ROM into the drive.
2. Log in as root:

   % su root
   

3. If you do not already have one, create a cdrom directory to be the mount point for the CD-ROM drive:

   # mkdir /cdrom
   

4. Mount the CD-ROM: On Solaris systems without Volume Management:

   # /etc/mount -r -F hsfs <cdrom-device-name> /cdrom
   

   If your HP-UX system is configured to mount the CD-ROM at /cdrom:

   # /etc/mount /cdrom
   

   If your HP-UX system is not configured to mount the CD-ROM at /cdrom, use the following command:

   # /etc/mount -r -F cdfs <cdrom-device-name> /cdrom
   

   On IRIX 6.x:

   # /etc/mount -r -t iso9660 <cdrom-device-name> /CDROM
   

5. To verify that the CD-ROM is mounted, use the ls command to list the files:

   # ls -R /cdrom
   

Ejecting the CD-ROM

After you complete the installation, eject the CD-ROM.

On Solaris with Volume Management, type:

% eject cdrom

On Solaris without Volume Management, type:

% su root
# umount /cdrom
# eject cdrom 
# exit

On HP-UX, type:

% su root
# umount /cdrom
# exit

Press the eject button on the CD-ROM drive.

On IRIX, type:

% eject /CDROM

Using rs_install commands

The rs_install program includes four commands that you can use to rerun specific sections of the rs_install program without actually reinstalling any products: license_setup, license_check, post_install, and options_setup.

To use these commands, go to the DeveloperTools.<version> directory. For example:

% cd Rational/releases/DeveloperTools.<version>
% ./license_setup

• Use the license_setup command to rerun the license setup phase of the installation. Use license_setup to import your permanent or TLA license keys and whenever you want to change your licensing information.
• Use the license_check command to check your license server and the license file to make sure your license information is correct.
• Use the post_install command to rerun the post-installation phase of the installation. For more information, see After you install: Post-installation tasks.
• Use options_setup to modify the list of users allowed to use the Rational Software product. For more information, see Modifying the list of user names.

Using the FLEXlm Software License Manager

The FLEXlm Software License Manager monitors license access, simultaneous usage, idle time, and so on. It includes the following components:

• A vendor daemon named rational that dispenses Purify, PureCoverage, and Quantify licenses. The rational daemon is used for all licensed Rational Software products. If you have products from other vendors that also use FLEXlm, they will include their own vendor daemons.
• A license manager daemon named lmgrd that is used by all licensed products from all vendors that use FLEXlm. The lmgrd daemon does not process requests on its own, but forwards requests to the appropriate vendor daemon.
• A Rational license file that specifies your license servers, vendor daemons, and product licenses.

The Rational license file

The Rational license file is a text file that is automatically created when you run the rs_install or license_setup programs.

The file for startup and evaluation licenses is:

Rational/config/Temporary.dat

The default file for permanent or TLA licenses is:

Rational/config/<license server name>.dat

Note: For best results, use the Rational license file only for Rational Software product licenses.

The rs_install program saves the license path to <producthome>/.lm_license_file. This is the path that Purify, PureCoverage, and Quantify use to locate the license file. You can override the location in .lm_license_file by setting the LM_LICENSE_FILE environment variable. The full path searched is equivalent to $LM_LICENSE_FILE: 'cat.lm_license_file'.

Verifying that FLEXlm is working

To verify that your FLEXlm License Manager is operational and that the daemons are running, type the following commands on your license server:

% ps axww | grep -v grep | egrep "lmgrd|rational"

or

% ps -e | grep -v grep | egrep "lmgrd|rational"

The output should include lines similar to the following (your pathnames will vary):

538 ?? S 0:03.50
/rational/base/cots/flexlm.6.0i/platform/lmgrd
      -c /rational/config/servername.dat
      -l /rational/config/servername.log
539 ?? I 0:00.90 rational -T servername 6.0 3 -c ...

Using FLEXlm commands

The FLEXlm License Manager supports the following commands for system administration:

Use this command	To
lmdiag	Diagnose problems when you cannot check out a license
lmdown	Shut down the license and vendor daemons
lmhostid	Report the license manager host ID of a workstation
lmreread	Reread the license file and start new vendor daemons
lmstat	Report status on daemons and feature usage
exinstal	Report on licenses in the license file you specify on the command line

Learning more about FLEXlm

For more information about the FLEXlm Software License Manager, see the FLEXlm End User Manual that is included on your Rational Software CD-ROM.

The FLEXlm End User Manual, along with answers to frequently asked questions about FLEXlm, is also available at http://www.globetrotter.com/manual.htm.

Copyright© 1999, 2001 Rational Software Corporation. All rights reserved.

---