clearlicense

Monitors and controls the product license database

APPLICABILITY

ClearCase (administrative command), Attache (administrative command), MultiSite (administrative command)

SYNOPSIS

clearlicense [ -pro·duct product-name ] [ -hos·tid | -rel·ease [ username | user-ID ] ... ]

DESCRIPTION

The clearlicense command reports the status of the ClearCase and Attache user licensing facility. You can also use this command to release users' licenses, making them available to other users.

HOW LICENSING WORKS

ClearCase and Attache implement an active user floating license scheme. To use ClearCase or Attache you must obtain a product-specific license. When you run Attache or any ClearCase program, it attempts to obtain a license for you. If you get one, you can keep it for an extended period: entering any ClearCase or Attache command renews it. If you do not enter any command for a substantial period, another user can take your license.

One or more hosts in the local area network are designated as license server hosts. Each of these hosts has a LicenseKeys value in the Windows NT registry key HKEY_LOCAL_MACHINE\SOFTWARE\Atria\ClearCase\CurrentVersion. The LicenseKeys value (on the Licensing tab in the ClearCase Control Panel on the license server host) stores one or more license entries.

Each license entry defines a specified number of licenses, allowing that number of ClearCase or Attache users to be active at the same time. See the license.db reference page for a description of the license entry format.

NOTE: One or more of your network's license server hosts can be UNIX hosts. A UNIX license server host stores license entries in the file /var/adm/atria/license.db.

License Priorities

Each user can (but need not) be assigned a license priority in the license database. Each user specified in a -user line gets a priority number: the first user gets priority 1 (highest priority), the second user gets priority 2, and so on. All users who are not specified in any -user line share the lowest priority.

Getting a License

(ClearCase only) When you first run a ClearCase tool, or first enter a Windows command to access VOB data though a view, a license-verification request is made.

(Attache only) When you first attempt to connect to the workspace helper, a license-verification request is made. The helper acts as a remote ClearCase user, requesting a ClearCase license on behalf of the Attache client. This license becomes the Attache license; the helper sets flags when it calls on ClearCase so that no new ClearCase license is consumed.

When requesting a license for either ClearCase or Attache, the license-verification check follows this process:

  1. The product software on your host determines the license server host to use; this value is specified on the Licensing tab in the ClearCase Control Panel.
  2. It makes an RPC call to the license server process on that license server host, to verify your right to use the product. (The license server process is actually albd_server, performing these duties in addition to its other tasks.)
  3. The license server process determines your rights and sends back an appropriate message.
  4. Depending on the message sent by the license server, your command either proceeds or fails.

Subsequently, similar license-verification checks are performed on periodically. The sections that follow describe in detail how users get and lose licenses.

In the following cases, you get a license and become an active user:

NOTE: Some commands do not require a license; this is noted in the individual reference pages.

Losing a License

When you get a license, its time-out period is set. As you continue to use ClearCase or Attache commands and data, your license is periodically refreshed. (The time-out period is reset.) If you do nothing with ClearCase or Attache in the time-out period, you lose your license and it becomes available to other users.

NOTE: The time-out period for ClearCase is 60 minutes; a shorter time-out interval can be configured in the license database with the -timeout option. The time-out period for Attache is one week and cannot be changed. See the license.db reference page for more information.

You can also lose your license before the time-out period is over:

It is possible to regain a license immediately after losing it.

NOTE: Applications that periodically browse and/or update file system resources, even when idle, will prevent your license from being released. Such applications include Windows Explorer and Visual C++.

License Expiration

Each license entry can have an expiration date. (The expiration time is at 00:00 hours on that date.) During the 72-hour period before the expiration date, attempts to use a license from that license entry succeed, but a warning message appears. After the expiration time, attempts to use those licenses fail.

THE CLEARLICENSE REPORT

Following is a typical clearlicense report:

License server on host "kronos".
Running since Monday 4/04/99 15:53:13.

LICENSES:
Max-Users       Expires       Password [status]
    19           none          2aae4b60.b4ac4f0f.02 [Valid]

Maximum active users allowed: 19
Current active users: 6
Available licenses: 13

ACTIVE users:
    User            Priority           Time-out in
    rdc                 2              59 minutes (at 10:44:20)
    chris               1              26 minutes (at 10:10:45)
    cheryl           none              23 minutes (at 10:07:27)

License Usage Statistics:
2 licenses revoked today 4/14/99.
0 license requests denied.
0 active users bumped by preferred user.

The following sections explain the parts of this report.

License Server Field

The license server is the albd_server process on the license server host. The report lists the time at which albd_server first processed a license-verification request.

Licenses

The information in this section is gathered from the license entry line(s) on the Licensing tab. Each such -license line generates a separate line in this report. The status can be one of the following:

Valid

The expiration date (if any) for this set of licenses has not yet arrived.

Warning

You are now in the 72-hour period preceding the expiration time.

Expired

This set of licenses has expired.

The "current active users" number summarizes the information in the next section of the report.

Active Users

Each line in this section describes one active user. The priority none indicates that the user is not specified in any -user entry and, thus, has the lowest license priority.

License Usage Statistics

This section lists licensing activity statistics, compiled since the time the license server (albd_server) started execution:

OPTIONS AND ARGUMENTS

Default: A report on licenses and user activity for all products with valid licenses is displayed, in the format described above.

-pro·duct product-name

Specifies the product whose licensing information is to be displayed or changed. product-name must match (including capitalization) the word that follows -license in the product's license entry-for example: ClearCase, Attache, MultiSite, and Attache-MultiSite.
-hos·tid

Displays the machine identifier of the host on which you invoke the command (for ClearCase) or the helper host's machine identifier (for Attache).
To obtain the license-server-host-ID for the License Registration Form (located in the ClearCase and MultiSite Installation and Release Notes; to be used when you want to add licenses to an existing license database or add a license server host), log in to the current or future license server host and run clearlicense -hostid.
-rel·ease [ username | user-ID ] ...

Specifies users (by user name or by numeric user-ID) whose licenses are to be revoked. Using -release without an argument causes your own license to be revoked. To discourage license battles among users, albd_server prevents this option from being used an excessive number of times during any single period (for Attache) or day (for all other products).

LICENSING ERRORS

This section describes errors typically encountered in licensing.

Problems with License Host File

If the Windows registry key value LicenseHost does not exist or is empty, this message appears:

mvfs: ERROR: view view-tag not licensed!

(in Attache, appears on the console of helper host)

command-name: .: Input/Output error

(in Attache, appears in the Command window)

Additional error messages may be displayed or written to the Event Viewer:

Error: You do not have a license to run ClearCase.

Error: Your license server is not specified.

Error: Unable to query value of LicenseKeys in the NT Registry; NT error Windows-NT-status-code.

Error: Unable to read LicenseKeys from the NT Registry; NT error Windows-NT-status-code.

Problems with License Server Host

If the license server host specified on the Licensing tab cannot be contacted, this message appears:

mvfs: ERROR: view view-tag not licensed!

(in Attache, appears on the console of helper host)

command-name: .: I/O error

(in Attache, appears in the Command window)

In addition, error messages are displayed or are logged to the Event Viewer:

Error: Cannot contact license server host "hostname"
defined in HKEY_LOCAL_MACHINE\SOFTWARE\Atria\ClearCase\CurrentVersion\LicenseHost.

Error: You do not have a license to run ClearCase.

Error: Error Windows-NT-status-code reading license server hostname from the NT Registry.

Losing a License

If you lose your license while a view is active, this message appears when you try to use the product:

mvfs: ERROR: view shtest - all licenses in use!

(in Attache, appears on the console of helper host)

SEE ALSO

albd_server, license.db



Feedback on the documentation in this site? We welcome any comments!
Copyright © 1999 by Rational Software Corporation. All rights reserved.