Chapter 2: Installing and Administering Micro Focus Server Licenses

This chapter explains how to run AppTrack and how to use it to install and administer Micro Focus Server licenses.

For the purposes of this chapter, "license unit" means a Micro Focus Server license in the license database, available for use by your application.

Introduction

Before you can run an application that uses Micro Focus Server, your Micro Focus Server licenses must be installed onto your system. They can be installed by using the License Administration utility, AppTrack. The section Installing and Uninstalling Licenses Using AppTrack in this chapter describes how to do this.

All licenses that you install are stored on the license database. We recommend that you set a password on the database to protect it from misuse.

Running AppTrack

You install and administer Micro Focus Server licenses, and monitor the number of users running an application, by using the License Administration utility, AppTrack. The easiest way of starting AppTrack is to run the script mflicense and select option 2.

To ensure that the license details are displayed correctly, use the version of AppTrack supplied with your latest version of Micro Focus Server. If you use the script mflicense to kick off Apptrack, you will automatically use the right version.

Warning To use AppTrack on your system, UNIX must support shared memory allocation and use.

How to

Setting an AppTrack Password

We recommend that you use a password for AppTrack, as this prevents any unauthorized person from tampering with your license system.

All Micro Focus Server licenses that you install are stored on the license database that is created the first time a Micro Focus Server license is installed. Since the password you select is also stored in the license database, there is nowhere to save the password until the database is created. Once you have installed a Micro Focus Server license, and the database is created, then the password is saved. This is so, even if you delete all licenses from the license database. Note that there is only one password for the license database. If other copies of Micro Focus Server are installed on the system and administered by other users, you all share the same password.

How to

Installing and Uninstalling Licenses Using AppTrack

You install Micro Focus Server licenses manually by using AppTrack.

You cannot install the same Micro Focus Server license on more than one machine at a time; to do so would violate the terms of the End User License Agreement. If you want to move a Micro Focus Server license from one system to another, you must first uninstall it from the current system, and then install it on the new system. If you require additional Micro Focus Server licenses, contact your Micro Focus account representative or your Micro Focus authorized supplier for details on purchasing them.

We recommend that you uninstall old Micro Focus Server licenses that you are no longer using. This is because they will still be loaded at startup and could cause your system to run out of shared memory.

How to

64-bit Application Server on AIX

If you install the 64-bit version of Application Server on AIX, you are issued with licenses for the 64-bit version. Any licenses associated with a 32-bit version of Application Server on AIX remain enabled. You cannot use 32-bit licenses with 64-bit Application Server on AIX, nor can you use 64-bit licenses with 32-bit Application Server on AIX.

You can install and uninstall 32-bit licenses at any time, but these have no effect on the 64-bit Application Server.

Monitoring Micro Focus Server License Use

You can monitor the usage of Micro Focus Server licenses by displaying a license report in AppTrack. This shows, among other things, the:

How to

Entries that show Developer Usage refer to Developer Testing Licenses, which are used when developing an application. You may not use them for running applications in production. For details see the chapter Developer Testing Licenses, if this is included in this book.

If you have Enterprise Server, you can also monitor your Micro Focus Server licenses using Enterprise Server License Manager, described in the chapter Running Enterprise Server License Manager.

Viewing Current Users

From AppTrack you can view a list of users who currently have Micro Focus Server license units in use by selecting option 7 (Current Users).

Before using this option you must first enable logging by creating an empty file apptrack.log in var/mfaslmf. The simplest way to do this is by using the touch command:

 touch /var/mfaslmf/apptrack.log

You must give the file general write permissions, otherwise the current users display might be incorrect.

The display is made up of blocks of information, one block for each ASLMF $COBDIR that is active. Each block begins with a display of a $COBDIR value and is followed by a list of records, one record for each user job under that $COBDIR. The details on each record are:

Alternatively, you can redirect output to a file by running the free-standing utility userstat.gnt and using standard redirection. To do this, use the command:

cobrun $COBDIR/aslmf/userstat.gnt

Model 1 Facilities

This section describes the facilities that are available with Model 1 licenses.

Overdraft

If you intend to run more than one copy of your application at the same time, you must ensure that you have sufficient Application Server licenses to cover the number of users accessing the application. During an exceptional period, for example, at year end, you might have more users running your application than usual. You need to purchase sufficient Application Server licenses to cover this situation. However, to help you cope with unexpected fluctuations in use, and to give you time to purchase additional licenses, AppTrack has a built-in time-limited overdraft facility.

You can configure the shell script nolicense to send an email to the person responsible for licensing issues whenever a user receives the response that no more license units are available. The person responsible for licenses should contact your product supplier to resolve any excess license usage issues. See the section Special Action On No-license Condition.

If you have set the ASLMFRETRY environment variable, as described in the section Automatic License Retry, no retry is attempted until all unused overdraft license units (if available) have been used.

The number of additional copies of your application that you can run depends on the number of license units installed for the application:

License units installed Additional license units available
1 0
2 - 9 1
10 - 19 2
20 - 29 3
30 - 39 4

For each further ten license units installed, an additional license unit becomes available.

You can use the extra license unit or units for up to 30 days.

Special Action On No-license Condition

If you have more users trying to run your application than you have Application Server licenses installed, there will be times when some users will receive the response that there are no more license units available at that moment. You can monitor how often this happens, so that you can determine how many additional Application Server licenses you need to purchase.

To help you monitor no-license conditions, AppTrack runs the shell script /var/mfaslmf/nolicense every time that it is unable to satisfy a license unit request. A single parameter is passed to the script; this parameter identifies the directory of the installed Application Server, so that different applications can be separately identified. The script then writes the name of the directory, and the date and time at which the attempt to run failed, to the file /var/mfaslmf/USERLOG.

The supplied nolicense script is a sample and you can edit it to your requirements. For example, the script contains a line that is commented out, that demonstrates how each time the script is invoked, a message could be mailed to a specified user.

If you do not want to use this monitoring facility, you can disable the nolicense script. To do this we recommend you comment out the unwanted lines.

AppTrack executes the nolicense script only if it is owned by root, and has no write permissions for Group or Other. This is to prevent anyone other than the person who is responsible for license administration from editing the script.

Automatic License Retry

Exceptional demands for an application by users might occasionally cause your number of Application Server licenses to be exceeded, although you have enough in normal cicumstances. If this occurs you are advised to set the environment variable ASLMFRETRY.

Note: You can check how many users are using an Application Server license over a period of time using the stats command. See the section Statistics Collection for details.

ASLMFRETRY enables you to set a value that specifies the number of times an application should attempt to get a license unit, and the length of time it should wait between attempts. In effect, the task suspends itself until a license unit becomes free.

The format of ASLMFRETRY is:

ASLMFRETRY=retries[,wait]

where the parameters are:

retries The number of times the task should attempt to obtain a license unit.
wait The time the application should wait, in seconds, between each attempt to obtain a license unit. The default is 10

For example, to enable 100 attempts to use a license unit:

ASLMFRETRY=100
export ASLMFRETRY 

To enable 25 attempts to use a license unit, with a 1 minute wait between each attempt:

ASLMFRETRY=25,60
export ASLMFRETRY 

Note If you set the ASLMFRETRY environment variable, no retry is attempted unless all unused overdraft license units (if available) have been used. See the section Overdraft for details of the overdraft facility.

License Usage Warning

If you would find it useful to receive advance warning of the need to purchase additional Micro Focus Server licenses, and to have some control over when the overdraft is first used, you can arrange to have a user script launched whenever the ASLMF license usage reaches or exceeds a level defined by you.

By default, license usage warning is not enabled.

You specify the license usage level in the text file WATERMARK, which you must create in the $COBDIR directory in which Application Server is installed. License usage warning works per installation of Application Server, so you can turn it on or off for each installation, and use different usage levels for each installation.

The text file WATERMARK contains the license usage level defined in one of the following ways:

When the license usage level is met or exceeded, AppTrack executes the user script /var/mfaslmf/watermark, passing it the following parameters.

You must write the user script /var/mfaslmf/watermark, to take whatever action you would find useful, for example the script could send a warning to you by e-mail.

AppTrack executes the /var/mfaslmf/watermark script only if it is owned by root, and has no write permissions for Group or Other. This is to prevent anyone other than the person who is responsible for license administration from editing the script.

License usage warning is in effect only if the text file $COBDIR/WATERMARK is present. If you want to disable license usage warning, you should remove $COBDIR/WATERMARK, and not simply change the license usage level value to an unattainable value. This is because if the file exists, AppTrack opens it and parses its contents, which takes unnecessary processing time.

Statistics Collection

It can be useful, for statistical purposes, to take a snapshot of license use at regular intervals over a period of time and get an average number of license uses at the end of the data collection. To do this, use the command:

$COBDIR/aslmf/apptrack stats p n 

where the parameters are:

p The period, in seconds, between each statistics collection
n The number of statistics collections to make

For example, the command:

$COBDIR/aslmf/apptrack stats 60 10

takes 10 snapshots, with 60 seconds between each.

By default, the statistics are displayed on the screen. It is usually more useful to direct them into a file; for example:

$COBDIR/aslmf/apptrack stats 60 10 >> userfile

The format of the statistics is similar to that displayed by the AppTrack license summary; see the section Monitoring License Use for details. The differences are that the heading lines are not displayed, and that each snapshot is separated by a dividing line.

Model 2 Facilities

This section describes the facilities that are available with Model 2 licenses for Micro Focus Server.

Sharing Across Installations

Model 2 licenses are shared across all installations of Micro Focus Server on a UNIX machine.

Overdraft

If you intend to run more than one copy of your application at the same time, you must ensure that you have sufficient Micro Focus Server licenses to cover the number of concurrent users. During an exceptional period, for example, at year end, you might need to run more concurrent copies of your application than usual. You need to purchase sufficient Micro Focus Server licenses to cover this situation. However, to help you cope with unexpected fluctuations in use, and to give you time to purchase additional Micro Focus Server licenses, AppTrack has a built-in limited overdraft facility. This takes into account all the Model 2 licenses installed on the UNIX machine.

AppTrack monitors the usage of license units and when it detects usage in excess of the licensed capacity, updates are made to the file overdraft.log, which is in the directory /var/mfaslmf.

You are allowed to exceed the number of Micro Focus Server licenses you are authorized for (your "licensed capacity") by up to 10%.

You are also allowed to exceed the licensed capacity by more than 10% for up to 10 days. Each day that you exceed your licensed capacity by more than 10% is known as an overdraft day. When an overdraft day occurs it is logged in the overdraft file, and the number of overdraft days remaining is reduced by 1. An email is sent to the systems administrator informing them that an overdraft has occurred, and how many overdraft days they have left. On the eleventh overdraft day, any application requesting an overdraft will fail. You must apply to Micro Focus to increase your licensed capacity, then install the extra licenses. Only when you have the extra capacity installed can the overdraft mechanism be reset.

After 10 consecutive days have elapsed during which no overdrafts occur, the overdraft accumulated so far is reset to zero.

Error Messages

Various error messages indicating licensing problems can arise during the running of applications. For details of messages that can be issued when using the base Micro Focus Server, see the topic Micro Focus Server Licensing Messages. For details of messages that can be issued when using Enterprise Server, see the topic Enterprise Server Licensing Messages

When an application using Micro Focus Server terminates because of a license problem, the number of the error message is set into the exit status of the run. Thus even in batch mode, where no-one is monitoring displayed messages, it is still possible to detect failures.

Troubleshooting

If users cannot run an application even though Micro Focus Server licenses are installed, check that the licenses were installed for the correct Micro Focus Server. Start AppTrack and select option 1 (License List).

If the licenses are listed correctly, check that the setting you are using for the Micro Focus Server directory matches the correct application.

If you have installed to the wrong Micro Focus Server, uninstall the licenses, set COBDIR to the correct directory, and reinstall the licenses to the correct Micro Focus Server.

If you are installed to the correct directory, but you still cannot run the application, try selecting option 6 (Reinitialize Licensing) of the license administration utility. If this fails to work, you should contact your application supplier and explain the problem.

If you receive the message "Environment variable COBDIR not set" when you start an application under AppTrack, check that:

Licensing messages are displayed in the following situations:

For Model 2 licenses, a log of license overdraft is stored in the Micro Focus Server installation directory. This file is not human readable, but you might be requested to send it to Micro Focus for analysis. If the file is removed or altered outside the AppTrack interface, AppTrack will prevent applications running.

Recovering from a Corrupt Database

If the license database is deleted or damaged, you can recover it using the utility aslmdbrecover and then reinstall your Micro Focus Server licenses. This utility deletes the license database and any system associated files and recreates the database. It starts the AppTrack utility and prompts you to reinstall the licenses.

To recover from a corrupt database:

  1. Run the utility aslmdbrecover, by entering:
    sh $COBDIR/aslmf/aslmdbrecover 
  2. Reinstall the licenses as described earlier.

If the license database for the development system is damaged, you can recover it using a similar utility lmfdbrecover. See the section Recovering from a Corrupt Database in the chapter Administration Tasks in your Development System Licensing Guide, if this is available.

Problems Running AppTrack

If you enter the command:

$COBDIR/aslmf/apptrack

and a message such as:

/aslmf/apptrack not found

is displayed and nothing else happens, simply logging into the correct user is not sufficient to set up your environment to run AppTrack.

You need to establish where the Micro Focus Server for your application has been installed, and set up the necessary environment variables according to the operating system.

How to

If you don't know the directory in which Micro Focus Server is installed, you can scan your system looking for all directories that contain AppTrack by using the command:

find / -name apptrack -print

The resulting display from this command might contain lines telling you that you do not have access to certain directories. Ignore these. One of the lines output by this command should be:

 cobol-installation-directory/aslmf/apptrack

For example, you might find that the line:

 /usr/lib/cobol/aslmf/apptrack

is displayed. In this case, Micro Focus Server is installed in the directory /usr/lib/cobol/aslmf.

If the output of the find command does not list any directories containing "apptrack", Micro Focus Server is not installed on your system.

If the output of the find command displays more than one directory containing "apptrack", note that only one of these is for your application. The other instances are for applications installed and in use by other users on your system. You can check the date each AppTrack was installed to see which is yours, by using the following command for each directory listed:

ls -l cobol-installation-directory/aslmf/apptrack

If you are still unsure, ask your system administrator which Micro Focus Server directories belong to other users. Other users can find out which Micro Focus Server directories belong to them by running their copy of AppTrack, and entering 2 (License Summary).

Once you have ascertained which Micro Focus Server directory relates to your application, make a note of the directory for future use, and return to the beginning of this section to start AppTrack.


Copyright © 2006 Micro Focus (IP) Ltd. All rights reserved.