Chapter 6

The following topics are covered in this section:

• "How Licenses Work"
• "The License Manager"
• "License Manager Commands"
• "The License File"
• "Obtaining Licenses"

When you buy Apex or Summit, you purchase some number of floating licenses. Floating licenses allow anyone on your network to use Apex or Summit as long as a license is available. Thus, the number of licenses that you purchase determines the maximum number of users who can use Apex or Summit simultaneously.

For example, if you purchased five Apex licenses and three users are currently using Apex, then two more users can use Apex.

Licenses are controlled by a license manager (FLEXlm software delivered as part of Apex) that runs on a license server (one of your workstations). The license manager monitors license access, simultaneous usage, idle time, and so on.

When you start Apex or Summit, you are initially unlicensed. If a license is available, the license manager gives you a license and you retain it as long as you keep using Apex or Summit. When you exit, your license is returned to the license manager and becomes available for another user.

If no license is available, you are unable to use Apex or Summit until a license is returned by another user.

Apex uses the Flexible License Manager, FLEXlm, from Globetrotter Software, Inc. Apex and Summit require FLEXlm . The license manager includes the following components:

• A vendor daemon named rational that dispenses Apex and Summit licenses.

  The rational daemon is used for all of Rational's licensed products. If you have other products from other vendors that also use FLEXlm, they will include their own vendor daemons.

• A license daemon named lmgrd.

  The same license daemon 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 license file that you maintain.

  It specifies your license servers, vendor daemons, and product restrictions.

Once the daemons and license file are in place, all that remains is to start the license daemon, which in turn will start the vendor daemons, each time the license server boots. The license daemon can be conveniently started from:

Digital Unix:	/sbin/init.d/SlmRational.sh
HP-UX:	/sbin/init.d/SlmRational.sh
IRIX:	/etc/init.d/SlmRational.sh
AIX:	/etc/inittab
Solaris:	/etc/rc2.d/SlmRational.sh

Apex provides installation scripts to guide you through this setup. They are described in "Installation Quick Start."

To verify that your license manager is operational, you can enter these commands on your license server to see if its daemons are running:

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

or

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

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

1719-S  0:00/vendor/rational/apex/base/cots/flexlm.6.0i/platform/lmgrd
                            -c /vendor/rational/config/license.dat
10424 - S 0:13 rational -T garcon 4
                            -c /vendor/rational/config/license.dat

The license manager supports several system-administration commands.

Command	Description
lmdiag	Allows you to diagnose problems when you cannot checkout a license.
lmdown	Shuts down license and vendor daemons
lmhostid	Reports license manager host ID of workstation
lmremove	Returns specific licenses to license pool (for example, after a workstation crashes)
lmreread	Rereads license file, starts new vendor daemons
lmstat	Reports status on daemons and feature usage
exinstal	Reports on licenses in license file you specify on the command line.

For more information on these commands, you can view the FLEXlm on-line documentation from any Apex window by selecting the Help:Manuals:Other Manuals:FLEXlm End-User Manual menu.These commands are documented in the "License Administration Tools" chapter.

The default Rational license file is rational_dir/config/license.dat. As you install Rational products, you can merge the Rational license data into another license file that you have already set up for another product.

When users start Apex or Summit, apexinit and summitinit automatically define the environment variable LM_LICENSE_FILE for them. FLEXlm uses this variable to locate the license file.

The license file is a text file that you can edit with any text editor. Your license file will contain lines similar to:

SERVER garcon 1874350 1706
DAEMON rational /vendor/rational/base/cots/flexlm.6.0i/platform
FEATURE env_base.sun4 rational 3.2 1-jan-00 6 x5B0AFAAC15C896694511 ""
FEATURE summit_cm.sun4 rational 3.2 1-jan-00 6 0B6A4AECE9F92961F6D0 ""
FEATURE ada.sun4 rational 3.2 1-jan-00 6 DB0ADADC11ABCC8BF7EF ""

In general, one or three server lines are followed by one or more vendor daemon lines, which are followed by one or more feature or increment lines. Each server line contains, in order, the:

• Keyword SERVER
• Host name of the license server, from hostname
• License manager host ID of the license server, from lmhostid
• TCP port number to use

Each vendor daemon line contains, in order, the:

• Keyword DAEMON
• Name of the vendor daemon (always rational for Apex)
• Pathname to the directory that contains the executable code for this daemon (which defaults to rational_dir/base/cots/flexlm.6.0i/platform
• Pathname to your options file for this daemon (optional-see the "Options" section below)

Each feature and increment line contains, in order, the:

• Keyword FEATURE or INCREMENT
• Name of the license. The first 3 are required for all Apex and Summit products:
  • env_base.host for the base product on host
  • summit_base.host for the base product on host
  • summit_cm.host for Summit CM on host
  • summit_tm.host for Summit TM on host
  • ada.host for the Ada 95 and Ada 83 compilers on host
  • ada83.host for the Ada 83 compiler only on host
  • rci.host for The RCI
  • asis for Rational ASIS
  • apex.target.self_target.c++ for the C/C++ compiler for target

  The host (and target) parameters can take on the values of:

  • sun4 (sun4) (Solaris)
  • hppa (hp) (HP-UX)
  • alpha (axp) (Digital Unix)
  • mips (sgi) (SGI/IRIX)
  • rs6k (ibm) (AIX)
  • any for any O/S

  Normally, you will not use the any keys. If you are unsure, please contact your Rational account representative. You must be contractually authorize to use any keys.

• Name of the vendor daemon, previously defined on a DAEMON line, that serves this feature (always rational for Rational products)
• Latest (highest numbered) version of this feature that is supported (3.000 for the current release of Apex and Summit)
• Expiration date. This is specified as dd-mmm-yy or as dd-mmm-yyyy, where yy is the last 2 digits of the year and yyyy is the unabbreviated year. You must specify 4 digits for the year 2000 and beyond. You must specify `00' to indicate a license which does not expire.
• Number of licenses
• Encryption code (obtained from Rational)
• Vendor string, enclosed in double quotes (usually null)
• License manager host ID, supplied only when this feature is bound to a specific host, also known as node-locked (never supplied for floating Apex or Summit licenses)

The tokens on each line can be separated by any amount of white space (spaces or tabs). You can edit only four kinds of tokens in the license file:

• Host names on SERVER lines
• TCP port numbers on SERVER lines
• Pathnames to vendor daemons on DAEMON lines
• Pathnames to options files on DAEMON lines

All other tokens are included as input to the encryption algorithm that produces the encryption codes on the FEATURE lines.

You can customize license access by:

1. Creating an options file for the rational daemon

2. Adding the pathname of the options file as the fourth field on the DAEMON line for the rational daemon

An options file allows you to:

• Reserve licenses for specified users or groups of users
• Allow or disallow licenses for certain users

For Apex, lines in the options file have this format:

GROUP name list_of_users
RESERVE number apex {USER | HOST | DISPLAY | GROUP} name
INCLUDE apex {USER | HOST | DISPLAY | GROUP} name
EXCLUDE apex {USER | HOST | DISPLAY | GROUP} name

The following table shows several examples:

Objective:	Example line(s) added to your options file:
To use Purify, PureCoverage or Quantify with Apex, and you purchased USER-BASED keys, it is required that you have an INCLUDE for each user of each product in your options file	INCLUDE purifyapex USER ace INCLUDE purecovapex USER ace INCLUDE quantifyapex USER ace
To make sure a key developer named Ace never has to wait for a license	RESERVE 1 USER ace
To allow access from only one workstation named loner	INCLUDE HOST loner
To disallow access to three stooges	GROUP stooges <larry curly moe> EXCLUDE GROUP stooges

Even if you already have existing Rational licenses, you will need new license codes to move to the current version from versions earlier than Apex 2.2.2.

If you are installing Rational Apex for the first time, or are adding licenses, contact Rational to obtain the encryption code for your Apex installation.

Please be prepared to supply the host name and ID number of your Apex license server, the number of licensed users, and the licensing version of your Apex release. The get_license_info installation script will help you gather them. The information gathered is put in the LICENSE_INFORMATION file.

Rational Software Corporation will provide your encryption code and its expiration date. The code will be a 20-digit hexadecimal string--for example: 4B868981DB6D7295573E. The date will be in a dd-mmm-yyyy format--for example: 31-dec-2001. The day can be expressed as one or two digits and the year can be expressed as two or four digits--for example: 01-jan-98 or 1-jan-1998. If you express the year as two digits (yy) instead of four digits (yyyy), it is interpreted as 19yy. If your encryption code never expires, the year (yy) in your expiration date will be 00.