Using the Old-Style KBC Licence Tester

This page describes the use of the "old-style" License Tester. For a more general discussion and for details about the newer version of the tester, look here. If the lay-out of your Tester differs from the image below, you will have the newer version.

Before getting started, make sure you understand how licensing for KBC software has been implemented at your site. Next, run the Basic Check to get started. Then carefully read through the diagnostics, to pinpoint the cause.

Basic Check

  • Start the License Tester from the Start menu. Its location will depend on the version you have:
Start > All Programs > KBC > KBC License Tester
or
Start > All Programs > KBC Profimatics > KBC License Tester
or even
Start > All Programs > Net Admin Tools > KBC License Tester
  • When the program has started, click the Initialize button.
  • Select the desired item from the Feature dropdown box.
  • Click the Check License button.

You should now have enough information to start working out the cause.

Let's take an example of what happens with a working license on a network system. You should see something similar to this:

The key information is in the Info box at the top of the screen and in the diagnostic text window at the bottom. We can tell from the Info box that licenses are being served from a network computer named CalgaryMaker. The diagnostics tell us that we were granted a license which will expire in 382 days time and that the license server is running version 8.1.0.0 of the license server software. This is a working license: what happens with a failed license?

Info Box

Most often, just looking at the Info box is enough to spot the problem.

LSHOST, LSFORCEHOST and KBCLicServers can all be used to direct the licensing system to the correct license.

LSHOST - An environmental variable. This points the license server to a list of places where it can look for a license. Valid entries are either the network name (or IP address) of the license server for network licenses, or "no-net" for stand-alone licenses. The license system is free to look elsewhere for the license, so it is unlikely that any entry here will be the cause of the problem.

LSFORCEHOST - Another environmental variable. This will force the license system only to look in the specified location. As above, this can either be the network name of the license server or "no-net" for a stand-alone license.

The security technology underpinning KBC Software is licensed from Safe-Net Inc. The same core technology is used by many other products and vendors. LSHOST and LSFORCEHOST are not used exclusively by KBC software, so we added a new KBC-specific method to aid license detection... the KBCLicServers file:

Using KBCLicServers - this line only appears if the KBCLicServers file is found and it contains a server name. KBCLicServers.kbclic is a text file that directs KBC software to the license location. The last line of the file should either be the name of the license server or "no-net" for a stand-alone license. The contents of a KBCLicServers.kbclic file used to direct the system to a license server named MyServer are shown below.

#this file contains KBC license server name(s), if there is more than
#one server, please use colon(:) as separator, eg servera:serverb
#kbc software can take up to 10 license servers here.
#the server name(s) in this file has to be the last line of this file.
MyServer

The file can contain multiple server names separated by a colon character and can use the word no-net to mean stand-alone or local licensing on the current PC. When you are using this file, local licenses are searched first. You can override this behaviour by using a ~ character as the first non-blank character of the server name line.

KBCLicServers.kbclic must be placed in the common-files folder used for stand-alone license files. For English versions of Windows this is "c:\program files\common files\kbc".

"Stand-alone license file found" or "No stand-alone license file found" – means what it says.

Security Key Found or No Security Key Found – detects any hardware key (dongle) and displays the lock code.

Understanding the diagnostics

The License Tester diagnostics will trace the actions taken by the Tester and report results. The information you see varies between Tester versions, with all examples on this page using the version that ships with SIM Suite 4.0. The first few lines report some basics about the system. For example: 

 Windows OS = Microsoft Windows XP (Build 2600 CSD Service Pack 3)
 Common Files location = C:\Program Files\Common Files
 You are running with admin rights.
 Initialisation completed in  300 milliseconds
 SLM Initialised successfully

The first two lines report the Windows version and the Common Files location, using information retrieved from the operating system. The Common Files location sets where various files will be located, such as any standalone license file, license.kbclic and the kbclicservers.kbclic file. KBC software looks for these files in a "KBC" sub-folder of the Common Files folder.

The third line reports your current administrator status. You do not need administrator rights to use the Tester, but you probably will need those rights to install stand-alone license files on versions of Windows after "XP". Your status will be rechecked as part of any license install. There are three responses you may see:

  • You are running with admin rights - means your current user account has Administrator rights on the PC and the License Tester is being run as administrator.
  • You are not running with admin rights - means your current user account has Administrator rights on the PC, but the License Tester is being run in normal mode, without elevated Administrator rights. You will see this response on Windows Vista and Windows 7 where you have just launched the License Tester normally.
  • You do not have Admin rights - means your current user account is not an Administrator account and you may not be able to install license files as a consequence.

The final diagnostic line shown above reports the initialisation status of the application. It very rarely fails. Any error usually indicates an installation error for the Tester itself. Once initialised, the Tester will check for any stand-alone license file on your PC and make sure its locking mechanism matches that PC or any security key plugged into it. The following example shows a typical response for a license locked against a PC's hard-disk ID: 

 Standalone license:
 License file C:\Program Files\Common Files\KBC\license.kbclic
 matches machine fingerprint of 26DAD004

Any mismatch will be clearly reported.

The last test run is to validate the LSHOST environment variable, which is used as a list of license servers to search for licenses. The validation looks only for syntax, checking the server names are separated by colon characters (:) and not semi-colons or commas. It does not verify that those servers exist. The following is an invalid LSHOST string: 

 MyLicenseServer ; MySecondLicenseServer

and this is the valid version: 

 MyLicenseServer : MySecondLicenseServer

Spaces are optional and are used only to make the text more readable.

Further diagnostic text will be generated as you perform tests.

Example for working standalone license

 Requesting license for KBC_PFPRO_Process (version 1.0)
 Request time = 906 milliseconds
 ...license granted to Standalone:KBC\Calgary\CalgaryTestMachine1
 ...license has 497 days remaining before expiry
 ... from server no-net

The feature names you see in the drop-down list are more human-readable forms of the actual names used by KBC software and reported in the diagnostics. Here, the KBC_PFPRO_Process feature corresponds to the Petro-SIM:Petro-SIM Full Base License item in the Feature dropdown list. The information in this diagnostic tells us:

  • that the license was successfully granted
  • that it comes from a license issued to a KBC Calgary computer named CalgaryTestMachine1
  • that it expires in 479 days
  • and that it was a standalone license (this is the meaning of no-net).

Example for working network license

 Requesting license for KBC_PFPRO_Process (version 1.0)
 Request time = 500 milliseconds
 ...license granted to Network: KBC\Calgary\CalgaryTestServer
 ...license has 328 days remaining before expiry
 ... from server CalgaryTestServer (Version 8.1.0.0)

This tells us we have been granted a license from the pool held by the network license server CalgaryTestServer, which is running version 8.1.0.0 of the Sentinel RMS License Manager.

Example for failed license

As the next section explains, licenses can come from multiple sources and the license system will search all its sources until it finds a license. When it fails, the system can usually only give you a general error message. The Tester attempts to do better and pinpoint a specific cause by cycling through the known servers, testing each in turn and giving you information about the failure. Remember that the Sentinel RMS system supports many different commonly used products and your site may well be running multiple license servers, reserving a different server for each vendors packages. The License Tester will not be able to find licenses for KBC products on servers solely supporting other vendor products.

How licenses are found

The license system searches for licenses in several locations, allowing you to mix standalone and network licenses and to have multiple license servers. The search order is as follows, with the search stopping once a valid license is found:

  • Use servers listed in KBCLicServers.kbclic
  • Use any LSFORCEHOST server - search will stop here if the variable is set
  • Use any standalone license file
  • Use servers list in the LSHOST variable
  • Search any license servers found on the local IP subnet

Having the system search as far as it can for licenses can be convenient, but it can also cause confusion when no licenses are found. Suppose you have three seats of Petro-SIM licensed on a corporate server and you also have other license servers for non-KBC products on the same subnet. If those three seats are in use when you try to get a license, the system will carry on and search all the other servers it can find. It will fail and give you a generic message saying no license could be found. If instead you force the system to limit its search solely to the license server hosting KBC licenses, you will get a clear message telling you all the seats are in use. Using the KBCLicServers.kbclic file helps limit the search and we recommend its use for network licenses.

Testing a Specific Server

In some situations you know where your licenses are coming from and want to limit the License Tester to look only on that server. How do you do this?

You use the Connect to Server box shown here and enter the server name or IP address. Use no-net to mean stand-alone licenses on your PC. Click the Set button when ready.

License Tester Reference

Main Buttons

  • Initialize button - this initialises the license tester, carrying out basic tests on license system set-up on the PC.
  • Install License File - installs any .kbclic file to its correct location. This mechanism can handle the KBCLicServers.kbclic file, standalone license files and network license files.
    • Standalone license files - here the install process will check for any existing file you may have and attempt to merge the new features with the old. It will report any conflicts it finds.
    • Network license files - the install process will use your settings to guide you through selecting the target server. It then installs the licenses to that server, replacing any existing licenses of the same name.
  • Check Key Match - helps you check which license file goes with which key and is useful when you have many standalone licenses and keys to manage. Plug in a key, start the tester and then use Check Key Match, to browse for a license file to test against the key.
  • Check Servers - searches for license servers on the local subnet, reporting a list in the diagnostic window of those it finds.
  • Clear Messages - clears the diagnostic window
  • Check License - probably the most useful function! This checks whether it can get a license for your selected feature. If you are using the KBCLicServers file to limit the search, it will attempt to get detailed diagnostics for any failure. Licenses are only checked out for a millisecond or so before being returned.

Features group

This is where you select a feature for analysis. The listbox shows you features you can check, where the list will often contain many more entries than your license supports. What you see in the dropdown list is controlled by check boxes:

  • List all features - shows all possible features in the list
  • SIM Suite only (checked by default) - limits the features to those used by the KBC SIM Suite package
  • Energy only - limits the features to those used by the KBC Energy products including Persimmon, ProSteam, SuperTarget, and WaterTarget

You will see a much shorter list if you launch the KBC License Tester from a Diagnostics button in Petro-SIM. The list will then contain only features that have failed in Petro-SIM.

Trace Settings group

The controls here help you with more detailed diagnosis. The most useful function is the Connect To Server box, which lets you limit the test to a specific license server you enter in the box and set. Use this option when you are trying to work out why a license is failing and all you get is a generic message.

  • The drop-down box provides access to a detailed trace of the internal workings of the system and is rarely needed.
  • The Popup message on errors box can be used in conjunction with the trace dropdown box and again is rarely needed.
  • Connected Server reports the current license server being used by the tester.
  • The Verbose Trace on Check All box is used together with the Check All button to generate very detailed diagnostics about the process.

Advanced group

This group provides access to less frequently used options that you may need to diagnose specific situations.

  • Check Out checks out the selected feature, holding on to it until you check it back in using the Check In button.
  • Check In returns a checked-out license
  • Validate validates that your checked-out license is still valid
  • Check All will test all the features shown in the features drop down list, one at a time. It is a quick way of verifying which licenses work and which do not. Remember that you may not be licensed for all the features and so some might legitimately fail.
  • List All Features lists all the features available on the connected or available servers
  • Init SA System initializes the license system on a PC. This is only done to resolve infrequent problems caused by initialisation not completing properly during software installation.
  • Run Cleanup Tool may be used by KBC, as a last resort to reset license servers and the client's PC, mainly to resolve infrequent issues with "commuter licenses".
  • Feature Exists checks to see if the selected feature exists on your system. Use to help you identify license errors caused by a feature being in use by others versus not being available in your license.

Further Help

Please contact the KBC software helpdesk for more information, giving as much information as you can about your problem.