HP OpenVMS systems documentation

When you create a VMSLICENSE data file to be processed by VMSLICENSE.COM, you must follow these rules (refer to Example 4-2):

• Specify all PAK data as parameters in the form of DCL assignment statements. Use the following format:

  parameter = parameter-value ! comment

  
  Table 4-1 lists the parameters allowed in the VMSLICENSE data file. You must use the exact parameter names, or VMSLICENSE ignores the line in the VMSLICENSE data file and returns an error message.

• Separate the end of one license registration from the beginning of another with the following special license data separator:

  <NEXT>

• Precede each comment with an exclamation point; VMSLICENSE ignores everything to the right of an exclamation point when processing the line.
• Separate words in the VMSLICENSE data file with any number of spaces or tabs.
• List parameters in any order in the VMSLICENSE data file.

Table 4-1 Parameters Used with VMSLICENSE.COM

Parameter	Description
ACTIVITY	License unit code that corresponds to a License Unit Requirement Table (LURT) or to a constant value.
AUTHORIZATION	String that, when used with the PAK issuer string, identifies the license you want to register.
AVAILABILITY	License unit code that corresponds to a LURT value or to a constant value.
CHECKSUM	Verification string of 17 characters created by the PAK issuer for each PAK with this format: n-cccc-cccc-cccc-cccc where: n is an integer and c is an alphabetic character from A through P.
DATABASE_FILE	Location of the License Database to be used. The default file specification is defined by the logical LMF$LICENSE, which points to SYS$COMMON:[SYSEXE]LMF$LICENSE.LDB on an unmodified OpenVMS system.
DATE	Product date specifying that the license authorizes use of all product versions released on or before the date.
HARDWARE_ID	Identification number of the hardware on which the product is licensed. On I64 systems, this field is used to specify the number of CPU_SOCKETS. If your PAK does not list CPU_SOCKETS=n in the HARDWARE_ID field, then your license is unlimited.
INCLUDE_NODE	Nodes in an OpenVMS Cluster environment that can access the licensed product. INCLUDE_NODE can specify one or more nodes in a clustered Galaxy.
ISSUER	Company that issued the PAK for this product.
OPTIONS	List of license options from a PAK.
PRODUCER	Company that owns this product.
PRODUCT_NAME	Product with a license to register. Use the product name exactly as it appears on the PAK.
RESERVE_LIST	Users (or activities) allowed to access the product license.
TERMINATION_DATE	Date on which the product license is no longer valid.
TOKEN	Product token string from a PAK.
UNITS	Number of license units from a PAK.
VERSION	Version limits from a PAK of the product for which you have a license.

4.4.4.4 Using VMSLICENSE.COM Default Value Rules

If you do not specify a value for a parameter in a VMSLICENSE data file, VMSLICENSE substitutes default values. The current default values are ISSUER=DEC and PRODUCER=DEC on OpenVMS Alpha and VAX systems and HP on OpenVMS I64 systems. All other license parameters have null values until you specify a value.

After you specify a license parameter in the VMSLICENSE data file, the parameter becomes the new default value until the next occurrence of the parameter sets a new default value. To set or reset the value of a parameter to null, use a line of the following form:

parameter = " "

For example, if the most recent PAK data set the INCLUDE_NODE parameter to a specific node, reset the parameter to null for the current and subsequent PAKs by entering the following:

INCLUDE_NODE = ""

Example 4-2 shows how using default data can eliminate typing for the second PAK listed in the VMSLICENSE data file.

4.4.5 Using the LICENSE REGISTER Command

You can directly register (and load) a license with LICENSE commands. For example:

$ LICENSE REGISTER CRYPTICALMENT /ISSUER=DEC -_$ /AUTHORIZATION=USA126087 /PRODUCER=DEC /UNITS=460 -_$ /VERSION=7.3 /TERMINATION_DATE=31-DEC-2001 /AVAILABILITY=E -_$ /OPTIONS=(MOD_UNITS) /CHECKSUM=1-BGON-IAMA-GNOL-AIKO$ LICENSE LOAD CRYPTICALMENT LICENSE-I-LOADED, DEC CRYPTICALMENT was successfully loaded with 460 units $

After you successfully register a license in the License Database (the default file specification is SYS$COMMON:[SYSEXE]LMF$LICENSE.LDB), you can enter the LICENSE LIST/FULL commandto display the data in the database (see Example 4-3).

Example 4-3 Displaying License Database Information

$ LICENSE LIST /FULL /AUTHORIZATION=USA126087 CRYPTICALMENT

Use CTRL/Z to exit, PF3-PF4 for Previous-Next Screen and Arrow Keys to scroll. License Management Facility V1.2 License Database File: SYS$COMMON:[SYSEXE]LMF$LICENSE.LDB Created on: 28-AUG-2001 Created by user: GRAHAM Created by LMF Version: V1.2 ---------------------------------------------------------- Issuer: DEC Authorization: USA126087 Product Name: CRYPTICALMENT Producer: DEC Units: 460 Version: 7.3 Release Date: (none) PAK Termination Date: 31-DEC-2001 Availability: E (System Integrated Products) Activity: 0 Options: MOD_UNITS Hardware ID: Revision Level: 1 Status: Active Command: REGISTER Modified by user: GRAHAM Modified on: 23-SEP-2001 14:32:23.41

When a license is successfully loaded with VMSLICENSE.COM or the LICENSE LOAD command, LMF displays an informational message.

4.4.6 Displaying License Information

To display information from the License Database about specific licenses, enter the LICENSE LIST command.

To display information in memory about loaded licenses, enter the SHOW LICENSE command. This command displays licenses loaded on the current node, and displays any reservation list associated with each license.

4.5 Loading a License

To allow users to access a product, you must load each registered license. Loading a license transfers data from the on-disk License Database into system memory. The following table shows the methods of license loading for LMF:

License Loading Options
Status of Registered License	Loading Method
Registering with VMSLICENSE.COM	Confirm the load option.
Registered with the LICENSE REGISTER command	Use the LICENSE LOAD command.
Previously registered system starting up	System loads the license automatically.

Figure 4-4 illustrates the license loading process for a standalone system. Whether the license manager enters the LICENSE LOAD command or the system automatically loads all registered licenses during startup, the license information is transferred to the system memory of node ART.

Figure 4-4 Loading a License

In an OpenVMS Cluster environment, multiple nodes load licenses from a single common database. LMF provides this capability to let you share licenses as well as control access to a product on a node-by-node basis (provided this is allowed by the terms and conditions of the license).

Typically, any node can load a license registered in the common License Database.For predictability, security, performance, or economic reasons, you can limit which nodes can access a product license intended to be shared among nodes. In an OpenVMS Cluster environment, you control access by modifying the license's include list. Use the LICENSE MODIFY command and either the /INCLUDE or /EXCLUDE qualifier to specify which cluster nodes can load the license. By changing the include list, you can create the effect of moving a product from node to node. Section 4.6.2 describes the process in detail. Note that you cannot share licenses that have the NO_SHARE option. They must be assigned to a single node.

You can also control which users in an OpenVMS Cluster environment can access a product license. Control access by modifying the license's reservation list. Use the LICENSE MODIFY command with the /RESERVE qualifier to specify which users can access the license.

In an OpenVMS Cluster environment, license loading involves transferring, or loading, license information from the on-disk License Database into system memory of the current node. The number and combination of licenses for an OpenVMS Cluster environment can be complex, which in turn makes the loading process complex and sometimes confusing. The general rule is that nodes specified on include lists or not specified on exclude lists of the LICENSE MODIFY command can load a registered license. As each system starts up, it loads any licenses to which it has access. If you need to load a license for all assigned nodes of a running cluster, you can use the OpenVMS System Management utility (SYSMAN), which is described in the HP OpenVMS System Manager's Manual.Figure 4-5 illustrates the loading process in an OpenVMS Cluster environment.

Figure 4-5 Loading a License in an OpenVMS Cluster Environment

See Section 4.6.2 for further details of license loading.

4.6 Managing Licenses After Registration

After you register licenses, you can manage them. While system managers can perform these tasks, managers of cluster environments and large multiple-user systems may also have an interest in managing products and product licenses.

For example, a cluster manager can use LMF to control which nodes can access a database product using important data (see Section 4.6.2). All system managers, however, may want to monitor license data using LICENSE commands.

VMSLICENSE.COM, LICENSE commands, and the DCL command SHOW LICENSE can perform most license management tasks, including:

• Listing registered licenses
• Showing loaded licenses
• Making loaded licenses unavailable --- either permanently or temporarily
• Transferring licenses from one database to another
• Modifying licenses --- such as termination dates or reservation lists

4.6.1 Restricting Product Use

The quickest method to restrict access to products registered in the License Database is to unload the license with a LICENSE UNLOAD command. The product becomes unavailable to new users and unavailable to all users when the last process using the product finishes. The product remains inaccessible until either you or the system reloads the license.

Although LICENSE UNLOAD is fast, it is not permanent. Typically, at system startup, LMF loads all the licenses registered in the License Database. In addition, a license that is loaded remains loaded until either the system is shut down or you intervene.

4.6.1.2 For Inactive Licenses

The following commands control license loading, which restricts product access. However, they do not unload loaded licenses or alter in-memory license data. For loaded licenses, use LICENSE UNLOAD.

• LICENSE DISABLE
  Prevents the specified license from being loaded until you enter a LICENSE ENABLE command.
• LICENSE MODIFY/INCLUDE, LICENSE MODIFY/EXCLUDE
  Makes the named nodes in an OpenVMS Cluster environment available or unavailable for license loading.
• LICENSE MODIFY/UNITS=number
  Limits access when you set the unit number to be less than that required by your processor or cluster.
  Use if your license has the MOD_UNITS option. Not all licenses have a specific number of units. Some licenses provide zero units, which is equivalent to unlimited units.
• LICENSE MODIFY/RESERVE=user-name
  Makes the product available only to the users named in the reservation list. You must use this method if your license has the RESERVE_UNITS option.
• LICENSE COPY
  Automatically disables a license as you reregister it in another License Database.
  This command is similar in effect to LICENSE DISABLE except that it also registers the license in the other database.
• LICENSE ISSUE
  Automatically disables a license so that you can then reregister it in another database.
  This command is similar in effect to LICENSE DISABLE except that it also produces a PAK replica to be registered elsewhere.

For more permanent access restrictions, issue one of the following commands:

• LICENSE DELETE
  Permanently deletes one or more licenses from a database, disallowing further license use. Use this command to eliminate terminated or unused licenses.
• LICENSE MOVE
  Automatically deletes a license as you reregister the license in another License Database.
  This command is similar in effect to LICENSE DELETE except that it also registers the license in the other database.

In an OpenVMS Cluster environment, you can control which nodes have access to a product. Some product licenses require you to control access by creating include or exclude lists with the LICENSE MODIFY command.

In an OpenVMS Cluster environment, license units are available to all nodes by default. If you need to control which nodes in a cluster have access to a product license, you must use the LICENSE MODIFY command with the/INCLUDE or /EXCLUDE qualifiers. These qualifiers take an argument list of System Communications Services (SCS) node names. SCS node names are system parameters set with the System Generation utility (SYSGEN). For example, if your cluster includes nodes MUSIC, ART, DANCE, and THEATR, you can specify that nodes MUSIC and ART have access to the software products registered in the License Database, while nodes DANCE and THEATR do not have access. The following command allows two nodes access to Pascal:

$ LICENSE MODIFY/INCLUDE=(MUSIC,ART) PASCAL

You can perform the same task by using the /EXCLUDE qualifier. The following command specifies the same product access as the previous command:

$ LICENSE MODIFY/EXCLUDE=(DANCE,THEATR) PASCAL

If a license does not provide enough license units forfull availability across the cluster, use LICENSE MODIFY and one of these qualifiers. Otherwise, product availability is unpredictable. Products are authorized for use on nodes in the order in which they load the licenses. Unless you use an include list to control which nodes can load a product, the authorization to use a product can move from processor to processor during a series of system shutdowns and startups.When you shut down a system, LMF automatically unloads all loaded licenses on that system. If another cluster member boots before the first system reboots, the second system, referring to the common License Database, can automatically load the same license. Although this can be helpful, it may not be your intention.

You can use the /INCLUDE and /EXCLUDE qualifiers with the LICENSE MODIFY command to determine who has access to the pool of units created by LMF when it loads combinable licenses. However, note the following:

• LMF combines units from combinable licenses (licenses with the same product name and type) into a single pool from which all authorized nodes may draw. By default, all nodes are authorized. To restrict the nodes that are authorized, assign an include or exclude list to each license for the product.
• Adding the NO_SHARE option to PAKs prevents license units from being shared. You can use this option to reserve all the units on a PAK for a particular node in an OpenVMS Cluster.
• LMF unionizes all the include and exclude lists associated with combinable licenses. The resulting master list is all-inclusive; when combining licenses, a less restrictive list always overrides a more restrictive list.
• Assigning an include list to a license does not reserve the license units for the nodes in the list.

For example, if you assign an include list to four out of five combinable licenses, the default---all nodes are authorized---is in effect for the fifth license, and it overrides the lists on the other licenses. All nodes then have access to the product despite the include lists. Units for the product are allocated on a first-come, first-served basis as the nodes in the cluster are booted, until the pool of units is depleted.

To ensure access exactly as you intend it, assign the same include or exclude list to each license. Purchasing more license units to fulfill requirements to run across the cluster is another option.

4.6.2.1 Effect of the NO_SHARE Option

Some licenses, such as OpenVMS operating system licenses, have the NO_SHARE option; they cannot be shared in a cluster environment. If you are using a common License Database, you must register a separate license for each cluster node and modify each to establish which node can load it.

To ensure that LMF can load a NO_SHARE license in a cluster environment, you have two choices, as follows:

• When you register with VMSLICENSE.COM, you are prompted for a node name. Enter the correct SCS node name at the prompt.
• If you use LICENSE REGISTER, you must follow up by entering a LICENSE MODIFY/INCLUDE=node-name command.

A cluster environment typically uses a single License Database, which should include one OpenVMS license for each cluster node. You can change the association of license and node as long as the number, type, and size of the licenses match the processors present. For example, the cluster environment with nodes ART, MUSIC, DANCE, and THEATR should have four licenses, each one designated for a specific node. If you remove node THEATR and replace it with a node named CRAFTS, you must modify the license intended for THEATR to specify node CRAFTS.

Because an OpenVMS Cluster License Database often contains multiple licenses with the identical product name and producer, you should use the /AUTHORIZATION qualifier with LICENSE commands to uniquely identify a specific license. For example:

$ LICENSE MODIFY/INCLUDE=THEATR BASIC /AUTHORIZATION=USA123456.. . $ LICENSE MODIFY/INCLUDE=CRAFTS COBOL %LICENSE-E-AMBIG, information provided was ambiguous; multiple licenses were found$ LICENSE MODIFY/INCLUDE=CRAFTS COBOL /AUTHORIZATION=USA123456

4.6.2.2 Editing Include and Exclude Lists

Each time you enter a LICENSE MODIFY command with an /INCLUDE or /EXCLUDE qualifier, LMF creates a new list. To edit an existing list, use the /ADD or /REMOVE qualifier in your command line. The following example illustrates the required syntax without using the /ADD or /REMOVE qualifier:

$ LICENSE MODIFY/INCLUDE=(ART,MUSIC,DANCE,THEATR) BASIC -_$ /AUTHORIZATION=USA123456...$ LICENSE MODIFY/INCLUDE=(ART,MUSIC,DANCE,CRAFTS) BASIC -_$ /AUTHORIZATION=USA123456$ LICENSE UNLOAD BASIC %LICENSE-I-LOADED, DEC BASIC was successfully loaded with 400 units

You can also use the following commands:

$ LICENSE MODIFY/INCLUDE=(ART,MUSIC,DANCE,THEATR) BASIC -_$ /AUTHORIZATION=USA123456...$ LICENSE MODIFY/REMOVE/INCLUDE=(THEATR) BASIC /AUTHORIZATION=USA123456$ LICENSE MODIFY/ADD/INCLUDE=(CRAFTS) BASIC /AUTHORIZATION=USA123456

If your license uses the MOD_UNITS option, you can also modify the size of a license in a cluster environment. To change the size of the license, enter a LICENSE MODIFY/UNITS=number command that specifies a number sufficient for your needs and allowed by your license agreement. For example, to change a license registered with 1000 license units to a 1500-unit license, enter:

$ LICENSE MODIFY/UNITS=1500 BASIC$ LICENSE LOAD BASIC