The License Map File

The Problem

Suite products introduce a unique licensing problem, because they create the potential for a user to have more than one license feature that can convey a license to run a given product. For instance, if your license file contains both DevelopmentStudioUNIX licenses and standalone Rose licenses, then a license to run Rose could be claimed under either of these features.

Rational Suites give you the ability to control the order in which the Suite component products attempt to claim licenses, because there is no "one size fits all" right answer. To continue with the Rose example, suppose Rose tries first to claim a "DevelopmentStudioUNIX" license. This claim may fail, either because the user does not have any such licenses installed, or because all the licenses are currently checked out. In that case, the user may want Rose to try to claim a Rose license (in fact, greater anticipated use of one component product might have been the reason for purchasing additional standalone licenses in the first place). But trying the licenses in this order may not be what the user wants. Whenever they start up Rose, if a Suite license is available then it will be consumed, and hence be unavailable to other users.

If Rose always tries to check out a standalone Rose license before attempting to check out a Suite license, then this problem goes away, but now there is another problem. Now, when the user starts Rose, it will consume a Rose license if one is available. But if the user later starts another Suite product, such as SoDA, while their Rose session is still active, then SoDA will check out a Suite license (assuming there are no standalone SoDA licenses). At this point, the user is holding two licenses, a Rose standalone license and a Suite license, where the Suite license alone would have sufficed to run both Rose and SoDA.
 

The Solution

Rational Suite solves this problem by allowing each user to specify the order of license feature claim attempts on a per-component-product basis. This is controlled by a configuration file called a license map file. A license map file consists of lines of the following format:
component_designator product_designator {, product_designator}
In other words, the component_designator is followed by a comma-separated list of product_designators. A component_designator or product_designator has the following syntax:
feature_name:version_number
These are the FLEXlm license feature name and version. A component_designator specifies the FLEXlm feature and version number associated with a given Suite component product. A product_designator specifies a FLEXlm feature and version number that the license client subsystem will try to claim on behalf of the component product when that product requests a license for the feature and version specified by the component_designator. The license map file "maps" a component product feature and version to a list of feature/versions to try in the order given.

In addition, the keyword "standalone" in the place of a product_designator denotes a standalone license; it is equivalent to specifying a product_designator that is identical to the component_designator.

Here's an example license map file line:

# An example...
#
SoDA:3.2 DevelopmentStudioUNIX:1.5, standalone # (suite first)
Note that comments introduced by '#' are allowed anywhere in the map file.

This line tells SoDA's license client subsystem to first attempt to check out a DevelopmentStudio for UNIX license. If that fails, it will attempt to check out a standalone license (that is a license with feature name "SoDA" and version 3.2 or greater).

You could also specify only "standalone" or only "DevelopmentStudioUNIX", which would cause the component product to try only the one license specified.

If a component product is not named in the license map file, then it defaults to claiming a standalone license.
 

How Rational Products Find License Map Files

When a Suite component product is launched, it first reads the environment variable RSU_LICENSE_MAP. If this environment is set to a pathname, it reads in the license map file specified.

Next, the product checks for a file called License_Map in a subdirectory called .Rational located in the user's home directory (that is, it looks for ~/.Rational/License_Map). If this file exists, it is read in, and its contents override those of the license map read from $RSU_LICENSE_MAP (if any) as follows:

The Default License Map File

The DevelopmentStudio for UNIX installation includes a default license map file. The file is called License_Map and is located in the config/ subdirectory of the installation.

The DevelopmentStudioUNIX environment script (rs_setup.csh or rs_setup.ksh) checks to see if the RSU_LICENSE_MAP environment variable is set; if not, it's set to the pathname of the default license map file.

To create a common default license map file for users that is different from the default that is shipped with the distribution, just copy config/License_Map to another location and modify it as needed. Then instruct users to set RSU_LICENSE_MAP to the pathname of your customized default license map file. In addition, users can fine-tune the default mapping by creating a ~/.Rational/License_Map file. As described above, they need only include component lines for mappings that they wish to override.

IMPORTANT NOTE: You must have a license map file somewhere for Suite licenses to take effect. If a Suite component product cannot find any license map file containing its component name, it assumes that it is a standalone installation, i.e. it will only try to check out standalone licenses (and will fail if none are available). The only way for a product to know that it is supposed to try a Suite license is if it finds that Suite license feature name and version in a component mapping specified in a license map file.
 

Licensing Diagnostic Messages

Setting the environment variable RSU_LICENSE_DIAG causes the licensing client subsystem to generate diagnostic messages which show you what it's doing when it searches for license map files, reads them in, and performs licensing operations. Since license maps can be found in various places that depend on the user's environment, licensing operations can have unexpected results if you are not careful. In these cases, it is very helpful to set RSU_LICENSE_DIAG and examine the resulting messages, because you can see exactly what is going on.

The default for Rational products is to print licensing diagnostic messages on standard error, but some products deviate from this.

   

techpubs@rational.com
Copyright © 1993-2000, Rational Software Corporation. All rights reserved.