1

Installing the products

Overview

The Rational® PurifyPlus for UNIX product family includes:

• Rational PurifyPlus
• Rational Purify®
• Rational PureCoverage®
• Rational Quantify®

PurifyPlus provides a license that allows you to use Purify, PureCoverage, and Quantify, as well as a unified procedure for installing all three applications on your system at the same time. Individual product licenses are also available.

Installing each product includes three steps, though depending on your situation you may be able to skip one or more of them:

1. Obtaining a license for the product.
2. Installing the product using the rs_install program.
3. Performing any necessary post-installation configuration procedures.

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

Note: You may be able to complete licensing and installation without gathering any information at all. If you are 1) using a startup or evaluation license, or a permanent license that has not expired, and 2) not setting up a new ClearQuest integration, just go ahead and run the rs_install program. The program will find existing licenses and perform a typical installation (an installation of all the products for which you have a license, on the system where you're logged in) without requiring you to supply any information. Read Installing the products using rs_install

Step 1: Obtaining a license for your Rational product

About licenses

When you purchase PurifyPlus, Purify, PureCoverage, or Quantify, you purchase a specific number of licenses for each product. The license key can be either a permanent license key, which has no expiration date, or a term license agreement (TLA) license key. Rational Software issues you a license key for the product that corresponds to the number and type of licenses you purchased. You need this license key to use the software.

The products also come with a startup license that you can use to get started using the product if, at the time of installation, you don't have the key your purchased. You can then request your key from AccountLink, Rational Software's license management web tool, 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.

Evaluation licenses for the products are also available. These permit you to try the products for a limited period, ordinarily two weeks, so that you can see the benefits of using them.

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.

The following table provides definitions of license types, and helps you determine whether you need to perform Step 1, based on the type of license you are setting up.

License Type	Description	Instructions
Permanent	Allows the use of the product without time limits.	If you are upgrading from an earlier version of the product and still have a valid permanent or TLA license, go right to Step 2: Installing your Rational product. If you do not yet have a valid permanent or TLA license set up, gather the information specified in Information you need to obtain a license and then request a license from AccountLink, Rational Software's license management web tool. This applies if you are a first-time purchaser of the Rational PurifyPlus products. 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.
Term License Agreement (TLA)	Allows the use of the product for a specific period of time.
Startup	Is provided to get you up and running as soon as you receive your Rational product, if your permanent or TLA license key is not available. Note that you will have to enter a permanent or TLA key later to continue using the product, ordinarily within 90 days.	Go right to Step 2: Installing your Rational product. When you receive your permanent or TLA license, see Entering a permanent or TLA license key after initial installation.
Evaluation	Allows you to try out the product before purchasing for a limited time, ordinarily two weeks. Note that you will have to enter a permanent or TLA key later to continue using the product.

Information you need to obtain a license

In addition to contact information, you will need to provide the following information to AccountLink, Rational Software's license management web tool, in order to obtain a .upd import file. The .upd file contains licensing information and you will use it later in the licensing procedure.

Data for AccountLink	Notes	Your Entry
Your Rational account number	Source: your Rational license key certificate.
License Type	Source: your Rational license key certificate. 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.
Rational Product Line	Source: your Rational license key certificate.	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 Floating licenses or Named User licenses that you intend to install. This cannot be greater than the number of licenses you purchased.
Host Name and hostid	This is the name and hostid of the machine that you intend to use as your license server host during installation. 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, you can download and run the tool get_hostinfo.sh after you have begun your license request on AccountLink. Go to Obtaining a .upd import file using AccountLink.

Obtaining a .upd import file using AccountLink

Access AccountLink at http://www.rational.com/accountlink/. The AccountLink website provides instructions for requesting licenses.

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.

Go on to Step 2: Installing your Rational product.

Step 2: Installing your Rational product

Install your product using the script rs_install.

 

Information you need for rs_install

The information you need to supply to the rs_install script depends on what type of license you have, and on how you are setting it up:

• If you already have a valid license or are using a temporary or evaluation license, and if you are not setting up a new ClearQuest integration, and if you intend to perform a Typical installation (with the product or products installed on the same system as the system where you are logged in), you do not need to gather any additional information. Click

 
• If you are installing a new permanent or TLA license, and you have a .upd file that you can use to import licensing data, click

 
• If you are installing a new permanent or TLA license, and you do not have a .upd file that you can use to import licensing data, click

 
• If you already have a permanent or TLA license set up, but are not performing a Typical installation, click

 
• If you are installing a temporary or evaluation license, but are not performing a Typical installation, click

If you are installing a new permanent or TLA license and are importing a .upd file

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. Note that these are per-platform figures. 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. The directory 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 want to create this directory manually, see Supplemental notes. This section also shows the structure of the directory after installation.
Note: If you are installing a 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 self-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 user names 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, where <product> is purify, purecov, or quantify. 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.	The rs_install program, which creates this file when it runs, will suggest <server name>.dat as a default. See The Rational license file for information about the file.
Note: If you have installed Rational ClearQuest, Rational Software's change request management system, it is possible for Purify and PureCoverage users to file change requests from within the Purify and PureCoverage graphical interface. To configure this integration between the products: You as the installer can provide rs_install with site-wide default values. Note that individual users can override the default values if they have different requirements, following the instructions in the Purify and PureCoverage online help systems. (See "ClearQuest" in the online help index.) Alternatively, you can choose not to enter default values. In this case, users must enter their own values in order to use the integration. The source for the following configuration values is your ClearQuest system administrator.
ClearQuest client interface.	If you are installing on a Solaris or HP-UX platform, you can specify the default ClearQuest client for your users: X for the ClearQuest native X client web for the ClearQuest web client All other platforms support only the web client. Users must have ClearQuest on their path in order to use the native X client.
Name of the default ClearQuest database.	Enter the name of a site-wide default ClearQuest database for your users who access ClearQuest through the native X client. Even if you have chosen web as your default interface, you may want to enter a value here for users who prefer to use the ClearQuest native X client. Source: ClearQuest system administrator.
URL for the ClearQuest web client.	Specify the URL if you selected web as your default ClearQuest client interface. Even if you have chosen X as your default interface, you may want to enter a value here for users who prefer to use the web interface. Source: ClearQuest system administrator.

When you have gathered the information you need, go on to Installing the products using rs_install.

If you are installing a new permanent or TLA license without importing a .upd file

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. Note that these are per-platform figures. 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.
Host name or IP address of the host machine on which the license server is to run (the "license server host").	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 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.	Source: your Rational license key certificate.
Note: If you are installing a 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 self-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 user names 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, where <product> is purify, purecov, or quantify. 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.	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.
Note: If you have installed Rational ClearQuest, Rational Software's change request management system, it is possible for Purify and PureCoverage users to file change requests from within the Purify and PureCoverage graphical interface. To configure this integration between the products: You as the installer can provide rs_install with site-wide default values. Note that individual users can override the default values if they have different requirements, following the instructions in the Purify and PureCoverage online help systems. (See "ClearQuest" in the online help index.) Alternatively, you can choose not to enter default values. In this case, users must enter their own values in order to use the integration. The source for the following configuration values is your ClearQuest system administrator.
ClearQuest client interface.	If you are installing on a Solaris or HP-UX platform, you can specify the default ClearQuest client for your users: X for the ClearQuest native X client web for the ClearQuest web client All other platforms support only the web client. Users must have ClearQuest on their path in order to use the native X client.
Name of the default ClearQuest database.	Enter the name of a site-wide default ClearQuest database for your users who access ClearQuest through the native X client. Even if you have chosen web as your default interface, you may want to enter a value here for users who prefer to use the ClearQuest native X client. Source: ClearQuest system administrator.
URL for the ClearQuest web client.	Specify the URL if you selected web as your default ClearQuest client interface. Even if you have chosen X as your default interface, you may want to enter a value here for users who prefer to use the web interface. Source: ClearQuest system administrator.

When you have gathered the information you need, go on to Installing the products using rs_install.

If you already have a permanent or TLA license set up

If you are upgrading from an earlier version of the product and still have a valid permanent license, most of the information you need is already available in your system.

Gather the information specified in the following table:

Data for rs_install	Notes	Your Entry
Full pathname of your license file, <server name>.dat.	Alternatively, you can supply the host name or IP address of the host machine on which the license server is running (the "license server host") and the license server port number.
The full pathname to the current installation location, or to the new installation location (referred to in this chapter as Rational).	This is the directory for installing all Rational Software products. You can use your existing installation; but if you use a new directory, it must meet the following requirements: 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. Note that these are per-platform figures. 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 the directory you specify 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.
Note: If you have installed Rational ClearQuest, Rational Software's change request management system, it is possible for Purify and PureCoverage users to file change requests from within the Purify and PureCoverage graphical interface. To configure this integration between the products: You as the installer can provide rs_install with site-wide default values. Note that individual users can override the default values if they have different requirements, following the instructions in the Purify and PureCoverage online help systems. (See "ClearQuest" in the online help index.) Alternatively, you can choose not to enter default values. In this case, users must enter their own values in order to use the integration. The source for the following configuration values is your ClearQuest system administrator.
ClearQuest client interface.	If you are installing on a Solaris or HP-UX platform, you can specify the default ClearQuest client for your users: X for the ClearQuest native X client web for the ClearQuest web client All other platforms support only the web client. Users must have ClearQuest on their path in order to use the native X client.
Name of the default ClearQuest database.	Enter the name of a site-wide default ClearQuest database for your users who access ClearQuest through the native X client. Even if you have chosen web as your default interface, you may want to enter a value here for users who prefer to use the ClearQuest native X client. Source: ClearQuest system administrator.
URL for the ClearQuest web client.	Specify the URL if you selected web as your default ClearQuest client interface. Even if you have chosen X as your default interface, you may want to enter a value here for users who prefer to use the web interface. Source: ClearQuest system administrator.

When you have gathered the information you need, go on to Installing the products using rs_install .

If you are installing a temporary or evaluation license

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. Note that these are per-platform figures. 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 or email from Rational Software.	startup or evaluation
Expiration date.	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 (for example, 31-dec-2003). The field is not case sensitive.
Note: If you have installed Rational ClearQuest, Rational Software's change request management system, it is possible for Purify and PureCoverage users to file change requests from within the Purify and PureCoverage graphical interface. To configure this integration between the products: You as the installer can provide rs_install with site-wide default values. Note that individual users can override the default values if they have different requirements, following the instructions in the Purify and PureCoverage online help systems. (See "ClearQuest" in the online help index.) Alternatively, you can choose not to enter default values. In this case, users must enter their own values in order to use the integration. The source for the following configuration values is your ClearQuest system administrator.
ClearQuest client interface.	If you are installing on a Solaris or HP-UX platform, you can specify the default ClearQuest client for your users: X for the ClearQuest native X client web for the ClearQuest web client All other platforms support only the web client. Users must have ClearQuest on their path in order to use the native X client.
Name of the default ClearQuest database.	Enter the name of a site-wide default ClearQuest database for your users who access ClearQuest through the native X client. Even if you have chosen web as your default interface, you may want to enter a value here for users who prefer to use the ClearQuest native X client. Source: ClearQuest system administrator.
URL for the ClearQuest web client.	Specify the URL if you selected web as your default ClearQuest client interface. Even if you have chosen X as your default interface, you may want to enter a value here for users who prefer to use the web interface. Source: ClearQuest system administrator.

When you have gathered the information you need, go on to Installing the products using rs_install.

Installing the products using rs_install

For information about specific product and operating system versions, see the README file on your CD-ROM or in the directory that results when you unpack the tar file from Rational Software.

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 for mounting a CD-DOM, click

   If you have obtained the products from a web or FTP download, unpack the compressed tar file. The directory that is created is equivalent to the top level of the CD-ROM.

2. Run the rs_install program.

   The rs_install program is a complete installer that guides you through whichever of the following processes are necessary:

   • Setting up the license server.
   
   
   • Installing product licenses.
   
   
   • Installing the selected product and documentation.
     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 or unpacked your tar file. (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.

   If you select Typical as your installation type within rs_install, the entire installation, including the post-installation tasks, proceeds automatically. A typical installation installs all the products for which you have a license on the system you're logged into.

   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 Step 3: Post-installation configuration 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.

• What's the easiest way to use rs_install?
  Choose Typical when the rs_install program prompts you for the type of installation to perform. The program then proceeds to complete installation and post-installation tasks without further intervention from you. If you have special requirements, such as the need to install a Solaris version of the product on an HP-UX machine, or if you are setting up a new ClearQuest integration, you have to choose Custom instead of Typical; this requires you to input a small amount of additional information.
• 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 a text file called rs_install.PurifyPlus.<version>. 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.
  To change your license server, use the license_setup command. See Using rs_install commands.
• 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 or 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 under PureLA License Administrator with Named User licensing?
  Yes. The rs_install script 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.
• The host I want to use as the license server for my new products is already the license server for other Rational products. How do I share the server?
  You must add the new licenses to your current Rational .dat license file. To do this, specify the current Rational .dat 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 internet 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.
• How do I report problems or make suggestions for the rs_install program?
  You can submit comments by running the rs_install command with the -report option. This option helps you organize installation and licensing information and e-mail it to Rational technical support. You can, of course, also call or e-mail Rational technical support without this option.

Step 3: Post-installation configuration tasks

Configuration tasks include tasks that the rs_install program performs (or helps you perform) and tasks that you must complete manually.

The rs_install program performs its configuration tasks by callling the <product>.configure command for the product your are installing; <product> is purify, purecov, or quantify. You can also rerun the <product>.configure command at any time to check or to adjust your configuration; refer to Checking and adjusting your configuration.

The tasks that <product>.configure performs include:

• Configuring the cache directory.
• Setting up the online help system.
• Integrating Rational ClearQuest (for PurifyPlus, Purify, and PureCoverage).
• Running <product>_test to validate setup.

The tasks that you must perform manually include:

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

Note that the <producthome> directory is the home directory of Purify, PureCoverage, or Quantify.

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.

Checking and adjusting your configuration

You can run the script <product>.configure (where <product> is purify, purecov, or quantify) at any time to check that your configuration is correct and to make adjustments. To use the script go to the product home directory. For example, for Purify, type:

% cd `purify -printhomedir`

To check your configuration and licensing, type:

% ./purify.configure -check

To run the script in interactive mode, type:

% ./purify.configure

You can also run the script in batch mode, specifying the parameters you want changed as arguments to options. For a list and description of batch mode options, type:

% ./purify.configure -help

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, but you must edit the DAEMON line in the license file 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 in your .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

If you installed your product with a startup or evaluation license key, you have to enter a permanent or TLA license key before the startup or evaluation license key expires. This allows you to continue uninterrupted use of the product.

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/PurifyPlusFamily.<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 your product if it is to run on multiple machines. 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 product files to be installed and that mounts the file system(s) into which you want to load the product.
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

Before you begin, make sure you know the device name of your CD-ROM drive. Ask your system administrator for this information.

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 PurifyPlusFamily.<version> directory. For example:

% cd Rational/releases/PurifyPlusFamily.<version>

% ./license_setup

Use these commands as follows:

• 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 .dat license file to make sure your license information is correct.
• Use the post_install command to rerun the post-installation phase of the installation. One of the actions this command performs is to call the <product>.configure command; see Step 3: Post-installation configuration 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 .dat license file is a text file that is automatically created when you run the rs_install or license_setup programs. The .dat license file is based on data from the .upd file that you receive from AccountLink.

The file for startup and evaluation licenses is:

Rational/config/Temporary.dat

The default file for permanent or TLA licenses is:

Rational/config/<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:

% /bin/ps -e | egrep "lmgrd|rational"

The output should include lines similar to the following:

/bin/ps -e | egrep "lmgrd|rational"

    351 ? 0:00 rational

    345 ? 0:01 lmgrd

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 © 1992-2003 Rational Software Corporation. All rights reserved.

---