IBM Support

How to configure a Rational license for a UNIX system using the license map file

Question & Answer


Question

How do you configure the license map file to use an IBM Rational Suite for UNIX system license to open an IBM Rational point product on a UNIX machine?

Answer

Customizing License Usage Order
It is possible to set up a mixed environment where the same license server manages licenses for both a Suite product and individual point products. In this situation, license usage order can be customized by modifying the settings in the License_Map file on a per-component-product basis. For example, when a user starts an application, such as IBM Rational Rose, you can define whether that user claims a Rational Rose license or a Rational Suite license.


The License Map File
When you install Rational Suite, a default file called License_Map is created and stored in the rational_dir/config subdirectory. The following section shows the contents of the default
License_Map file for Rational Suite. The default License_Map file is set to claim an IBM Rational Suite DevelopmentStudio license for all products first. If that fails, it will attempt to check out a Rational Suite DevelopmentStudio RealTime license followed by a standalone (point product) license.

------------------------------------------------------------------------


Default License Map File for Rational Suite
purecov:5.0 DevelopmentStudioUNIX:1.0, DevelopmentStudioUNIXRT:1.0, standalone
purify:5.0 DevelopmentStudioUNIX:1.0, DevelopmentStudioUNIXRT:1.0, standalone
quantify:5.0 DevelopmentStudioUNIX:1.0, DevelopmentStudioUNIXRT:1.0, standalone
Rose98_Unix:6.0 DevelopmentStudioUNIX:1.0, standalone RoseRealTime:6.1 DevelopmentStudioUNIXRT:1.0, standalone ClearQuest:1.1 DevelopmentStudioUNIX:1.0, DevelopmentStudioUNIXRT:1.0, standalone soda:3.0 DevelopmentStudioUNIX:1.0, DevelopmentStudioUNIXRT:1.0, standalone RationalUnifiedProcess:1.0 DevelopmentStudioUNIX:1.0, DevelopmentStudioUNIXRT:1.0, standalone ClearCase_LT:1.0 DevelopmentStudioUNIX:1.0, DevelopmentStudioUNIXRT:1.0, standalone

------------------------------------------------------------------------



The License_Map file ‘maps’ a component product feature and version to a list of features and versions to try in the order given. It contains lines of the following format:component_designator product_designator {, product_designator}

The component_designator is followed by a comma-separated list of product_designators.

A component_designator specifies the FLEXlm feature and version number associated with a given Suite component product and has the following syntax:
feature_name:version_number (for example, purecov:5.0)

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. A product_designator has the following syntax:
feature_name:version_number (for example, DevelopmentStudioUNIX:1.0)

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

Comments introduced by “#” are allowed anywhere in the map file.

Note: If a component product is not named in the license map file, then it defaults to claiming a stand-alone license.
The following are some examples of license map settings and a description of how they are handled.


Example 1
soda:3.0 DevelopmentStudioUNIX:1.0, DevelopmentStudioUNIXRT:1.0, standalone
This line tells IBM Rational SoDA ’s license client subsystem to first attempt to check out a Suite DevelopmentStudio license. If that fails, it will attempt to check out a Suite DevelopmentStudio RealTime license. If a Suite license is unavailable, the client subsystem will attempt to check out a stand-alone license (that is, a license with feature name soda and version 3.0 or greater).


Example 2
soda:3.0 standalone
This line tells SoDA’s license client subsystem to check out a standalone license only (that is, a license with feature name soda and version 3.0 or greater).


Example 3
soda:3.0 DevelopmentStudioUNIXRT:1.0
This line tells SoDA’s license client subsystem to check out a Suite DevelopmentStudio RealTime license only.

Note: You must have a license map file for Suite licenses to take effect. If a Suite
component product cannot find a license map file containing its component name, it assumes that it is a stand-alone installation — that is, it will only try to check out stand-alone licenses, and will fail if none are available. The only way for a product to know that it should use a Suite license is if it finds the Suite license feature name and version in a component mapping specified in a license map file.

Back to top

RSU_LICENSE_MAP


When you run the user environment setup script (rs_setup.csh or rs_setup.ksh), the script checks to see if the environment variable RSU_LICENSE_MAP is set. If the variable is not set, the script sets the path name to the default license map file
(for example, rational_dir/config/License_Map).

Customizing License Usage for All Users
You can create a global license map file that applies to all users by copying the default license map file and modifying it to suit your purposes.

To create a global License_Map file:
  1. Copy the License_Map file (rational_dir/config/License_Map) to another location.

  2. Modify the file by doing the following:
    • To change the file to use a stand-alone license for the product first and a Suite license second, edit the component as shown in the following example:
      Rose98_Unix:6.0 standalone, DevelopmentStudioUNIX:1.0

    • To change the file to use a Suite license for the product first and a stand-alone license second, edit the component as shown in the following example:
      Rose98_Unix:6.0 DevelopmentStudioUNIX:1.0, standalone

    • To change the file to use only a Suite license for the product, edit the component as shown in the following example:
      Rose98_Unix:6.0 DevelopmentStudioUNIX:1.0

      Note: You may choose to omit product designators that do not apply. For example, if you have not installed Rational Suite DevelopmentStudio RealTime, you can delete the entry “DevelopmentStudioUNIXRT:1.0.”

  3. Instruct users to set the RSU_LICENSE_MAP variable to the path name of your customized license map file.

Back to top

Customizing License Usage for Individual Users


You can customize license usage for an individual user by creating a license map file for that particular user. The contents of the user license map file will override the contents of the default or global license map file.

To create a customized License_Map file for individual users:
  1. If the directory does not already exist, create a ~/.Rational directory.

  2. Copy the License_Map to the ~/.Rational directory. If you are using a customized global license map file, be sure to copy that version to the user’s directory and not the default license map file in the config directory.

  3. Only add the component lines for mappings that you want to override:
    • To change the file to use a stand-alone license for the product first and a Suite license second, edit the component as shown in the following example:
      Rose98_Unix:6.0 standalone, DevelopmentStudioUNIX:1.0

    • To change the file to use a Suite license for the product first and a stand-alone license second, edit the component as shown in the following example:
      Rose98_Unix:6.0 DevelopmentStudioUNIX:1.0, standalone

    • To change the file to use only a Suite license for the product, edit the component as shown in the following example:
      Rose98_Unix:6.0 DevelopmentStudioUNIX:1.0

    • To change the file to use only a stand-alone license for the product, edit the component as shown in the following example:
      Rose98_Unix:6.0 standalone

      Note: You may choose to omit product designators that do not apply. For example, if you have not installed Rational Suite DevelopmentStudioRealTime, you can delete the entry “DevelopmentStudioUNIXRT:1.0.”

Back to top

License Server Process


When you run a Rational Suite product, the following occurs:
  1. The product checks to see if the environment variable RSU_LICENSE_MAP is set. If it is set, it reads the license map file to which it points.

  2. The product checks to see if a License_Map file exists in the user’s home directory (~/.Rational/License_Map). If this file exists, its contents are read and the settings override those loaded from the License_Map file indicated by $RSU_LICENSE_MAP as follows:
    • If a component_designator appears only in the RSU_LICENSE_MAP file, then it remains in force.
    • If a component_designator appears in both $RSU_LICENSE_MAP and ~/.Rational/License_Map, then the mapping used is the one specified in ~/.Rational/License_Map.

Back to top

Considerations for Customizing License Usage


Because there is no “one size fits all” solution, consider the following scenarios when defining your license map settings, especially settings that affect all users.

Scenario 1: IBM Rational Rose RealTime set to claim a Suite license first
RoseRealTime:6.0 DevelopmentStudioUNIXRT:1.0, standalone
In this scenario, starting IBM Rational Rose RealTime will consume a Suite license making it unavailable to other users. If the user is unlikely to use other Suite products, you may
want to make a standalone license the default.

Scenario 2: Rational Rose RealTime set to claim a stand-alone license first
RoseRealTime:6.0 standalone, DevelopmentStudioUNIXRT:1.0
If Rose RealTime always tries to check out a stand-alone Rose RealTime license before
attempting to check out a Suite license, another problem is introduced. Now, when the user starts Rose RealTime, a Rose RealTime license is consumed, if one is available. Later, if the user starts another Suite product such as SoDA while their Rose RealTime session is still active, SoDA will check out a Suite license (assuming there are no stand-alone SoDA licenses). At this point, the user is holding two licenses, a Rose RealTime stand-alone license and a Suite license, where the Suite license alone would have sufficed to run both Rose RealTime and SoDA.
It is important to take the time to think about usage profiles. For example, you need to take into account what products users need and how frequently they use them. You need to modify your license map files to best serve these usage profiles.

Back to top

Licensing Diagnostic Messages


Setting the environment variable RSU_LICENSE_DIAG causes the licensing client subsystem to generate diagnostic messages that show you what it is 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.

The default for Rational products is to print licensing diagnostic messages on
standard error. Note that Rational SoDA does not do this.

(The above information regarding the License_Map file is located in the IBM Rational Suite Installation Guide )

=============================================

The following 2 examples show how to set the environment variables for the License_Map:

General Instructions:

  1. Set the following environment variables:
    LM_LICENSE_MAP and LM_LICENSE_FILE
  2. Set the environment variable for LM_LICENSE_MAP to the <path to License_Map>
  3. Set the environment variable LM_LICENSE_FILE to <port>@<hostname>
  4. Set the RSU_LICENSE_MAP to the License_Map file.

    If the License_Map file is not created, then create it by using the following command:
    touch License_Map
  5. Edit the License_Map file using a command such as vi:
    vi License_Map
  6. Add the component lines in the License_Map file in reference to the licenses being used to open the product such as:
    Rose98_Unix:6.0 rose_enterprise_windows:6.0, standalone
  7. Save the file.
  8. Set the RSU_LICENSE_MAP environment variable using the following command:
    setenv RSU_LICENSE_MAP /rational/config/License_Map


This should allow the UNIX client system to use the IBM Rational Rose Enterprise license to open the IBM Rational Rose98 product.

Back to top


Example 1: This example shows how to set the License_Map for IBM Rational ClearQuest:


  1. Create the file License_Map in the /<rational install dir>/ClearQuest/config directory. That file should contain one of the following depending on the Suite license that is to be used:

    ClearQuest:1.1 RationalSuiteEnterprise:1.0, standalone
    ClearQuest:1.1 DevelopmentStudio:1.0, standalone
    ClearQuest:1.1 AnalystStudio:1.0, standalone
    ClearQuest:1.1 UnifyingPlatform:1.0, standalone

    If the DevelopmentStudio is for UNIX then the map file would contain:
    ClearQuest:1.1 DevelopmentStudioUNIX:1.0, standalone

  2. Set the environment variable RSU_LICENSE_MAP to /<rational install dir>/clearquest/config/License_Map

  3. Set the environment variable RSU_TEMPLATE1_INI to /<rational install dir>/clearquest/config/template1.ini

    Note: If you have a template2.ini file then set it to that. The templates2.ini file is located in the sun5/resources/templates2.ini under the top level of the product install under the Rational ClearQuest standalone install. (Ex. RSU_TEMPLATE2_INI /<rational install dir>/clearquest/sun5/resources/templates2.ini)

  4. Set the environment variable LM_LICENSE_FILE to the port@host of the license server (Ex. LM_LICENSE_FILE 27000@server name)

After all environment variables have been set ClearQuest will launch.

Back to top


Example 2: This example uses an IBM Rational Suite DevelopmentStudio for UNIX system license to open an installed point product IBM Rational Rose on a UNIX machine.


Each user is allowed 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.

  1. Determine which license is being used by a product.
    • Set the environment variable:
      setenv RSU_LICENSE_DIAG 1
    • Run Rose
    • Look for the following message:


      RSU Licensing: CLC Version: RSBU_CLC_OMFINAL_002
      RSU Licensing: FLEXlm Client Version: 7.0f
      RSU Licensing: Initializing FLEXlm job...
      RSU Licensing: ...initialized OK
      RSU Licensing: RSU_LICENSE_MAP not set in environment
      RSU Licensing: Reading license map file
      /people/login/.Rational/License_Map
      RSU Licensing: /people/login/.Rational/License_Map not found.
      RSU Licensing: RSU_TEMPLATE_INI not set in environment
      RSU Licensing: RS_License_Claim() called for Rose98_Unix:6.0
      RSU Licensing: Rose98_Unix:6.0 not found in license map, try standalone license
      RSU Licensing: Checking out license for: Rose98_Unix:6.0
      RSU Licensing: ...lc_checkout() OK


      In this example, Rose is using: Rose98_Unix:6.0 license
  2. Configure your license:
    • Here is how the /login/rational/config/License_Map file looks


      % more License_Map
      #!/@(#)$Revision: /main/9 $
      #------------------------------------------------------------------------
      # This is the default License_Map file shipped with Rational Suite
      # DevelopmentStudio for UNIX and the RealTime Edition.
      #------------------------------------------------------------------------
      purecov:5.0 DevelopmentStudioUNIX:1.0, DevelopmentStudioUNIXRT:1.0, standalone
      purify:5.0 DevelopmentStudioUNIX:1.0, DevelopmentStudioUNIXRT:1.0, standalone
      quantify:5.0 DevelopmentStudioUNIX:1.0, DevelopmentStudioUNIXRT:1.0, standalone
      Rose98_Unix:6.0 DevelopmentStudioUNIX:1.0, standalone
      RoseRealTime:6.1 DevelopmentStudioUNIXRT:1.0, standalone
      ClearQuest:1.1 DevelopmentStudioUNIX:1.0, DevelopmentStudioUNIXRT:1.0,
      standalone
      soda:3.0 DevelopmentStudioUNIX:1.0, DevelopmentStudioUNIXRT:1.0, standalone
      RationalUnifiedProcess:1.0 DevelopmentStudioUNIX:1.0,
      DevelopmentStudioUNIXRT:1.0, standalone
      ClearCase_LT:1.0 DevelopmentStudioUNIX:1.0, DevelopmentStudioUNIXRT:1.0,
      standalone

      % setenv RSU_LICENSE_DIAG 1
      % setenv RSU_LICENSE_MAP /login/rational/config/License_Map
      % ./rose
      RSU Licensing: Diagnostic messages enabled
      RSU Licensing: CLC Version: RSBU_CLC_OMFINAL_002
      RSU Licensing: FLEXlm Client Version: 7.0f
      RSU Licensing: Initializing FLEXlm job...
      RSU Licensing: ...initialized OK
      RSU Licensing: Reading license map file /login/rational/config/License_Map
      RSU Licensing: CREATE map for component Rose98_Unix:6.0
      RSU Licensing: ADD product mapping DevelopmentStudioUNIX:1.0 for component
      Rose98_Unix:6.0
      RSU Licensing: ADD product mapping standalone for component Rose98_Unix:6.0
      RSU Licensing: Reading license map file
      /people/login/.Rational/License_Map
      RSU Licensing: /people/login/.Rational/License_Map not found.
      RSU Licensing: RSU_TEMPLATE_INI not set in environment
      RSU Licensing: RS_License_Claim() called for Rose98_Unix:6.0
      RSU Licensing: found in license map: DevelopmentStudioUNIX:1.0
      RSU Licensing: Checking out license for: DevelopmentStudioUNIX:1.0
      RSU Licensing: ...lc_checkout() OK
      RSU Licensing: Increment Line check for vendor
      RSU Licensing: Check that license vendor string includes Rose98_Unix:6.0
      RSU Licensing: Licensed feature is DevelopmentStudioUNIX:1.0
      RSU Licensing: Vendor_string is purecov:5.0 purify:5.0 quantify:5.0
      Rose98_Unix:6.0 soda:3.0 ClearQuest:1.1 RationalUnifiedProcess:1.0
      RSU Licensing: ...OK


      Here Rose is using: DevelopmentStudioUNIX:1.0

Back to top

[{"Product":{"code":"SSTMW6","label":"Rational License Key Server"},"Business Unit":{"code":"BU053","label":"Cloud & Data Platform"},"Component":"Configuration","Platform":[{"code":"PF002","label":"AIX"},{"code":"PF010","label":"HP-UX"},{"code":"PF016","label":"Linux"},{"code":"PF027","label":"Solaris"}],"Version":"2003.06.14;2003.06.15;2003.06.16;7.0;7.0.0.1;7.0.1;7.0.1.1","Edition":"","Line of Business":{"code":"LOB45","label":"Automation"}}]

Document Information

Modified date:
16 June 2018

UID

swg21120664

Page Feedback