After You Install

This chapter provides an overview of tasks that you must perform after you have installed Rational Suite. The following topics are included:

• Configuring Rational Purify, PureCoverage, and Quantify
• Configuring Rational Rose for UNIX
• Configuring Rational SoDA

---

Configuring Rational Purify, PureCoverage, and Quantify

This section explains how to configure Rational Purify, PureCoverage, and Quantify after you have installed the three products.

The configuration tasks include:

• Installing on a Read-Only File System
• Making the Manual Pages Available
• Making the Product Available to All Users, including:
  • Making Rational Quantify Scripts Available
  • Making Rational PureCoverage Scripts Available
  • Making Debugger Scripts Available on HP-UX

Installing on a Read-Only File System

If you install Rational Purify, PureCoverage, or Quantify on a file system that is mounted read-only by client systems, 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 systems and linking the cache directory to this publicly writable directory.

When There is No Writable File System

If there is no writable shared directory mounted on client systems, 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, specify the -cache-dir option using one of the methods below.

For csh, tcsh, or compatible shells, do the following:

% setenv PUREOPTIONS "-cache-dir=$HOME/cache:$PUREOPTIONS"

For ksh, bash, or other Korn-compatible shells, do the following:

$ PUREOPTIONS="-cache-dir=$HOME/cache $PUREOPTIONS"; \ export 
PUREOPTIONS

If the PUREOPTIONS environment variable is not set, define it using one of the methods below.

For csh, tcsh, or compatible shells, do the following:

% setenv PUREOPTIONS "-cache-dir=$HOME/cache"

For ksh, bash, or other Korn-compatible shells, do the following:

$ PUREOPTIONS="-cache-dir=$HOME/cache"; export PUREOPTIONS

Add this same specification to your local or central .cshrc file, or its equivalent.

Making the Manual Pages Available

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

• Set your MANPATH environment variable to include producthome/man (where producthome is one of purify, quantify, or purecov).
• Copy the manual pages for the product into your man directory. If necessary, log in as root to do this.
• Running rs_setup.csh or rs_setup.ksh adds the locations of these product's manual pages to the MANPATH environment variable automatically.

Making the Product Available to All Users

To make Rational Purify, PureCoverage, and Quantify available to all users, create a symbolic link to producthome/product (where producthome is one of purify, quantify, or purecov) from a directory such as /usr/local/bin. Make sure this is a symbolic link, not a copy or a hard link.

For example:

% rm /usr/local/bin/purify

% ln -s producthome/purify /usr/local/bin

Repeat this procedure for each product you install.

Note: As an alternative, you can add the producthome/product pathname to each user's PATH environment variable, or reference the full path name in your makefile (rs_setup.csh and rs_setup.ksh will do this for you).

Making Rational Quantify Scripts Available

To make Rational Quantify scripts available, you need to create symbolic links to qv and to the qx script files:

% rm /usr/local/bin/qv 

% rm -i /usr/local/bin/qx*

% ln -s quantifyhome/qv /usr/local/bin

% ln -s quantifyhome/qx* /usr/local/bin

For more information on the qx script, see the Quantify online help.

Making Rational PureCoverage Scripts Available

To make Rational PureCoverage scripts available, you need to create symbolic links to the pc_* script files:

% rm -i /usr/local/bin/pc_* 

% ln -s purecovhome/scripts/pc_* /usr/local/bin

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

Making Debugger Scripts Available on HP-UX

On HP-UX, Rational 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 Rational PureCoverage and Quantify, create the same symbolic links, substituting purecov or quantify for purify.

The installation is now complete.

---

Configuring Rational Rose for UNIX

This section details Rational Rose for UNIX configuration, performed after installation. You must complete these steps before using Rational Rose.

The following topics are covered in this section:

• Rose for UNIX Configuration Files
• Rose.ini File Replaced By rose.reg
• Configuring Your Printer
• Using Rose for UNIX
• Initial Runtime Instructions When Upgrading
• Installing and Using Converted Fonts Provided in this Release
• Configuring the Rose/ClearCase Integration

Rose for UNIX Configuration Files

Executing rational_dir/releases/DevelopmentStudioUNIX.2002.05.00/platform/bin/rose (where platform is hppa_hpux or sun4_solaris2) will run the Rose configuration file config.sh before bringing up Rose. The configuration file sets environment information such as the Rose home directory and location of the license file.

Rose.ini File Replaced By rose.reg

Any settings previously in the Rose.ini file are now in the registry file, rose.reg. This new registry file is located in the rational_dir/releases/rose.2002.05.00/registry directory of the release. The settings in this file are entered in your registry, after running rose_cleanup and then rose. Any changes made to the release rose.reg file will apply to all users running rose. If you wish to make changes specific for your environment, a rose.reg.template file is available in rational_dir/releases/rose.2002.05.00/registry. Copy this file to your $HOME directory and name it $USER.reg. Edit this file with the settings you prefer, run rose_cleanup and then rose. Rose will automatically register your $HOME/$USER.reg file and your settings will be available in your Rose session.

Configuring Your Printer

Perform the following steps to configure your printer for use with Rose.

• You may print to your default printer by selecting the appropriate print options within Rose. Rose will print to the printer defined in the PRINTER environment variable.
• You may install a default printer, or redefine or add ports by editing your $HOME/windows/win.ini file as described. Any changes made to your $HOME/windows/win.ini will apply to your personal configuration.

  You may also edit the release win.ini file (rational_dir/releases/rose.2002.05.00/mw/win.ini). In this case, the same change will apply to any new user who runs the release.

  • Specify the default printer under the [windows] section, using the following syntax:

    device=outputdevicename, PSCRIPT, portconnection:
    

    The keyword PSCRIPT (PostScript) is used in place of the devicedriver.

    Rose for UNIX supports PostScript printing only.

  • Specify the UNIX command in the [ports] section. The [ports] section lists available communication and printer ports. The LPTn keywords are mapped to UNIX commands. In the following example, LPT1 and LPT2 are mapped to the print command lp. The print job output is sent to a file. The output file is then sent to the printer. The term "%s" tells the system to substitute the name of the PostScript intermediate output file. The term -dps1700 in the example directs the print job to a UNIX printer named ps1700.

    [ports]
    LPT1:=lp -c "%s"
    LPT2:=lp -c -dps1700 "%s"
    LPT3:=
    

    Note: When using lp, the -c option should always be used.

  • Rose does not use the [PrinterPorts] section. Modifying this section will have no effect.
  • The [devices] section lists the active and inactive output devices that can be accessed by device driver PSCRIPT and specifies ports to which these devices are connected. In the following example, Default Postscript Printer=PSCRIPT,LPT1: specifies that the printer is connected to the PSCRIPT queue that is connected to LPT1:

    [devices]
    Default Postscript Printer=PSCRIPT,LPT1:
    Postscript Printer QMS=PSCRIPT,LPT2:
    

    The devices listed in this section appear in the File > Print dialog, under Name. In this dialog you may select the printer you wish to use.

Using Rose for UNIX

Use the following commands to start Rational Rose products:

Product	Command
Rose for UNIX	rose
Analyzer	analyzer
Rose Model Integrator	modelint

These commands are shell scripts contained in the rational_dir/releases/DevelopmentStudioUNIX.2002.05.00/platform/bin directory (where platform is hppa_hpux or sun4_solaris2)

Initial Runtime Instructions When Upgrading

Any user running an earlier version of Rose, should run rational_dir/releases/DevelopmentStudioUNIX.2002.05.00/platform/bin/rose_cleanup (where platform is hppa_hpux or sun4_solaris2).

It is only necessary to perform this step once - before running Rose.

To run Rose, see Using Rose for UNIX.

Installing and Using Converted Fonts Provided in this Release

Rose includes fonts that are compatible and may be used on both personal computers and UNIX displays. For more information on using these fonts, please see the Rational Rose Release Notes.

Configuring the Rose/ClearCase Integration

It may be necessary to reconfigure an earlier Rose/ClearCase integration set up. Before using the Rose/ClearCase integration with this release, review the following file (located in this release):

rational_dir/releases/rose.2002.05.00/addins/clearcase/README

---

Configuring Rational SoDA

This section describes Rational SoDA configuration options available during installation, and for reconfiguration purposes after installation.

Note: If you are using an earlier release of SoDA, read about upgrading from previous releases in the Rational SoDA Release Notes before installation.

Installation Requirements for Rational SoDA

Note: FrameMaker + SGML is no longer shipped with SoDA. It must now be licensed and installed independently. Rational SoDA 2002.05.00 supports FrameMaker+SGML 5.5 and 6.0.

If you have previously installed version 3.0.1, 3.0.3, or 3.1.0 of Rational SoDA, you can choose to use the installation of FrameMaker+SGML bundled with that release. To do this, copy the entire SoDA directory to a new location and uninstall the previous version of Rational Suite. This way, you do not accidentally remove the previous version of Rational SoDA when you uninstall the Suite.

Note: To optimize disk space by removing the SoDA components and keeping only the FrameMaker+SGML components, refer to Technical Application Note 17972 at the following location: www.rational.com/support/.

SoDA Components

During installation, you will have the option of choosing which SoDA components to load. The following describes these components.

Required Components

You must load the two components that are required for all installations:

• SoDA Common Component, containing document templates, X resources, apiclients file updates, and so on
• SoDA Components for platform, the platform-specific executables

The SoDA installation process is not optimized for heterogeneous networks (more than one UNIX platform). If you need to install more than one version of SoDA, contact Rational Technical Support.

Optional Components

There are additional components that you may need to load, depending on the needs of your project:

• Apex Domain for platform, containing source-domain definitions, executables, and so on for integrating SoDA and Rational Apex. You must load it to use SoDA with Apex.
• TestMate Domain for platform, containing source-domain definitions, executables, and so on for integrating SoDA and TestMate. You must load it to use SoDA with TestMate.
• Rose Domain for platform, containing source-domain definitions, executables, and so on for integrating SoDA and Rational Rose. You must load it to use SoDA with Rose.
• RoseRT Domain for platform, containing source-domain definitions, executables, and so on for integrating SoDA and Rational RoseRT. You must load it to use SoDA with Rose RealTime.
• Ghostscript postscript interpreter for platform, this is public domain software for processing PostScript images. You may install this component for improving the appearance of diagrams generated by the Rose domain. Ghostscript is provided without warranty or support. Use of Ghostscript is subject to the GNU General Public License. See the Rational SoDA Release Notes for more information.
• ClearCase Domain for platform, containing source-domain definitions, executables, and so on for integrating SoDA and Rational ClearCase. You must load it to use SoDA with ClearCase.
• ClearQuest Domain for platform, containing source-domain definitions, executables, and so on for integrating SoDA and Rational ClearQuest. You must load it to use SoDA with ClearQuest.
• SoDA Training, a platform-independent tar file. Load it only if you have SoDA users who are planning to attend Rational's SoDA training class. (Further instructions on completing the installation of the SoDA Training component are provided with the training material.)
• SoDA Demo, a platform-independent component for demonstrating SoDA features. It is intended primarily for use by Rational personnel. Unless requested by your Rational representative, you do not need to load this component.

SoDA Control Options

If you have Rational Apex installed, you will be prompted during installation to provide a control type for use during checkin of a FrameMaker+SGML file. These options are only applicable if you are loading the Apex Domain component. Here are the two options for SoDA control:

• Storage in binary format or MIF (Frame's Maker Interchange Format) upon checkin
• Document locking (Frame's View Only format) upon checkin and document unlocking upon checkout

Storage Formats

You can specify the way in which versions of controlled documents are stored in the CMVC database. The two choices are:

• Binary format, which is the normal format of FrameMaker+SGML documents. This format is more compact and requires less time for FrameMaker+SGML to save and open.
• However, CMVC does not store versions of binary files efficiently. Each version is stored as a full copy of the current binary file. Over time, as many new versions are checked in, the CMVC database will grow very large even if each version contains only minor changes.
• MIF, which is an ASCII representation that fully describes the contents of FrameMaker+SGML documents. MIF can be several times larger than the equivalent binary format and requires more time for FrameMaker+SGML to save and open (because FrameMaker+SGML must convert the MIF from/to binary).

  However, CMVC stores versions of ASCII text files efficiently. Only one version is stored as a full copy of the original file. All other versions are stored as differentials. Over time, as many new versions are checked in, the CMVC database does not grow too large if most versions contain only minor changes.

  Because MIF files are often quite large, calculating the differences between versions can take some time, thereby slowing the checkin.

A Binary Example

For example, a 10 KB document is controlled in binary format, and its initial version takes up 10 KB in the CMVC database.

The document is checked out, additions are made to it, and its size is now 15 KB. The document is checked in, and its two versions use 25 KB (10 KB + 15 KB) in the CMVC database.

The document is checked out again, minor changes are made to it, and its size remains 15 KB. It is checked in again, and its three versions use 40 KB (25 KB + 15 KB) in the CMVC database.

A MIF Example

The same 10 KB document is controlled in MIF, and its initial version uses 30 KB in the CMVC database. (For this document, the MIF was three times larger than the equivalent binary format.)

The document is checked out, additions are made to it, and its size (in binary format) is now 15 KB. The document is checked in, and its two versions use 36 KB (30 KB + 6 KB in differences) in the CMVC database.

The document is checked out again, minor changes are made to it, and its size (in binary format) remains 15 KB. It is checked in again, and its three versions use 37 KB (36 KB + 1 KB in differences) in the CMVC database.

Document Locking

When documents are controlled and checked in, their UNIX file permissions are set to be read-only (r--r--r--). However, there is no easy way to tell if a document is read-only from within FrameMaker+SGML.

You can tell SoDA to lock documents when they are checked in and unlock them when they are checked out. When a document is locked (in FrameMaker+SGML View Only format), it is apparent in FrameMaker+SGML that the document is not editable--you cannot select text or type in the document until it is checked out and unlocked.

Using SoDA with Rational Rose

During installation you may be asked if you want to use SoDA with Rational Rose. If you answer yes, you must also provide the location of your Rose installation. The install process will automatically configure SoDA to use the version of Rational Rose you have specified.

See the release notes for further information about using SoDA with Rational Rose.

Using SoDA with Rational Rose RealTime

During installation you may be asked if you want to use SoDA with Rational RoseRT. If you answer yes, you must also provide the location of your RoseRT installation. The install process will automatically configure SoDA to use your RoseRT installation.

See the release notes for further information about using SoDA with RoseRT.

Using SoDA with Rational Apex

If you are installing SoDA for use with Rational Apex, and if you would like apexinit to automatically start SoDA for all Apex users, use your preferred text editor to adjust the soda.start script in the rational_dir/releases/soda.2002.05.00/share/bin directory. Uncomment the appropriate line as indicated by the instructions in the file.

Normally, it is better not to make this adjustment unless all Apex users will also be regular SoDA users. Usually, only some Apex users are regular SoDA users.

See the release notes for further information about using SoDA with Apex.

Using SoDA with Rational ClearQuest

During installation you may be asked if you want to use SoDA with Rational ClearQuest for UNIX. If you answer yes, you must also provide the location of your ClearQuest installation. The install process will automatically configure SoDA to use the version of Rational ClearQuest you have specified.

See the release notes for further information about using SoDA with ClearQuest.

Reconfiguring SoDA

Sometimes it is necessary to reconfigure SoDA after installation, for example to specify a new Rose installation, or if the SoDA installation is moved. Configuration of SoDA is performed during the post_install phase of rs_install. You may run rs_install using the post_install alias to reconfigure SoDA.

Licensing may also be reconfigured after install by using the license_setup and license_check tools, described earlier in this manual.

Using SoDA

After you have completed the SoDA installation, you may start SoDA by running the soda command. For further information, see the instructions for SoDA users in the "Getting Started" chapter of Using SoDA with Frame.