The license management system has been reconstructed in Caché 5. It reflects changes to the way Caché is licensed. This new licensing system meets a primary objective of making license management more robust than earlier implementations of Caché.
Important:
InterSystems Terms and Conditions govern how you may use the licensed Caché software. Occasionally, the implementation may be less lenient. Verify that any license-related code you write conforms to these terms and conditions.
How Caché Logins Work
This section covers the following topics:
Identifying Users
The Caché license management system attempts to identify distinct users and to charge one license unit per user. A user is identified by a license user ID, which can be an IP address, a username, a CSP session ID, or some other identifier depending on how the user connects.
Multiple processes started by or for a single user, share a license unit up to a maximum limit of processes per user. The $System.License.MaxConnections() method returns the maximum value (maxconn) for the current implementation.
 Set maxconn=$System.License.MaxConnections()
 Write "Maximum connections = ",maxconn
If the number of processes exceeds this maximum, a transition occurs and Caché begins charging one license unit per process for that user ID. The system presumes that if more than maxconn connections are associated with a user ID, multiple users are accessing Caché through an intermediary, (for example, a firewall system) so additional license units are required. Therefore, when the (maxconn + 1) process starts, the number of license units charged to that user ID changes from one to (maxconn + 1). Processes started by the Job command are charged against the process limit of the user ID invoking the Job command.
InterSystems expects that most applications are moving to identify their users by name, eliminating problems associated with using a default user ID based on client IP address, CSP session ID, or other connection-derived user ID. For example, when firewall or terminal server software is used, Caché cannot differentiate among connecting users, so it falls back on the maximum-connection transition rule. Using mixed connections, such as CSP and Caché Direct, from the same client also makes it impossible to count users appropriately using automatic ID creation.
When the username serves as the license identifier, these problems disappear. The importance of accurate user identification is expected to grow as organizations implement new access and audit requirements. Using the user identity to control license compliance is a natural corollary to this trend.
License Logins
There are two modes of license login: automatic and explicit. Automatic login remains the default in Caché 5. The licensing system attempts to identify the IP address of the client and uses it as the license user ID. This works well when clients connect directly to the server using IP. It does not work well if a firewall intervenes between the client and the server; all clients appear to have the same IP address. When a terminal server is used with the telnet protocol, automatic login cannot differentiate among users because Caché sees a single IP address for all terminal server ports. Since all connections originate from the same address, all connections have the same user ID. If users connect through a firewall or use the telnet transport from terminal servers, use explicit logins.
When IP is not used as the network transport, the IP address is not available for use as a license user ID. In these cases, the licensing system uses a variety of other sources as the license user ID. When connections originate from a terminal server using the LAT protocol, the terminal server name and port name (obtained from $ZIO) are combined to form a user ID. Hence, a user with multiple sessions from a terminal server port is charged a single license unit. Batch processes started by the at daemon on UNIX or from a batch queue on OpenVMS pose another special case. Such processes do not share a license unit because they are not associated with a user. For these processes, the process ID is used as the license identifier.
When explicit login is selected, no automatic detection of a user ID is attempted. The application must explicitly call the $System.License.Login(UserIdentifier) method to supply the license user ID and acquire a license.
Explicit login is enabled by calling the $System.License.DeferUserIdentification([0 or 1]) function. This call can be made from the ^%ZSTART routine at system startup. If the argument value is 1, license acquisition is deferred at login, so an explicit login can be performed. If the argument value is 0, license acquisition is automatic at process startup.
When login is deferred, the customer must call the license login method immediately. A process that has not performed a license login pauses for 15 seconds after each 1000 lines of Caché ObjectScript code.
Use an explicit login for any case that automatic login does not handle. It is important to remember that, even if automatic login is configured, it is always possible to call $System.License.Login(UserIdentifier) to use explicit user identification for licensing purposes.
CSP Connections
CSP connections are a special case for logins. We strongly recommend that CSP applications use the %CSP.Session equivalent method, %CSP.Session.Login, to identify a user for licensing purposes. If they do not, the CSP session ID is used as the license user ID. Each session consumes a license unit, which in many cases is unsuitable. For example, a user can have several browser windows open concurrently. Alternatively, a user can connect via several pathways (CSP, a terminal window, and a Caché Direct connection from a Visual Basic client). In this case, you can use the %CSP.Session class method, %CSP.Session.Login(UserId,Password,[0 or 1]) to perform an explicit license login for the session.
Processes started by the user start routine (^%ZSTART or the older ^ZSTU) are another special case. The process running ^%ZSTART has no parent process. Therefore, a login is performed for the user ID, User Startup, before ^%ZSTART is called. Processes started by the Job command from ^%ZSTART have this user ID. If you prefer, call $System.License.Login(UserId) from ^%ZSTART to change the user ID. This procedure means that ^%ZSTART can start as many as one less than maxconn background processes and only consume one license. If, according to the license terms and conditions, these processes should have a separate license (for example if they drive a piece of laboratory equipment that requires a separate license), then you are required to call $System.License.Login(UserId) to obtain a license for an appropriate user ID.
Finally, it is important to understand that Caché 5 no longer tries to distinguish background processes and count them differently. If a user process starts another process, that child process counts as one more against the user’s overall maximum limit of processes.
Configuring Caché 5 Licensing
The major difference between Caché 5 and earlier versions of Caché is that each configuration maintains an independent local view of its license capacity and current use. Each configuration requires access to the key; therefore a cache.key file must be installed on every configuration. Multiserver keys can be shared among cooperating configurations, either on the same machine or on different machines. Please note that Enterprise keys are not automatically sharable as they were in earlier versions. Sharing is permitted only with multiserver keys.
Sharing multiserver keys requires coordination among configurations using the key. Caché 5 introduces a license manager that replaces the license server in version 4.1 and earlier versions of Caché. When multiserver keys are shared, a license manager must be configured. The license manager coordinates the views of license use maintained locally in every configuration. One license manager can handle multiple configurations. The license manager is not a Caché process; it is unaffected if a Caché configuration shuts down. This avoids past problems when the license server became unreachable if a configuration shut down or paused during backup. The license manager communicates with configurations via UDP messages on a configurable port. The default port is 4001.
License managers are defined in the Caché Configuration Manager in the License section of the Advanced tab. You can configure redundant license managers. This is much less critical than with previous Caché versions for two reasons. First, the configuration can continue running with users logging in and out in the absence of the license manager. Second, the license manager continues running after configuration shutdown when it is supporting more than one configuration. When configuring license managers, decide which server or servers you want to host the license manager. You can configure it to run on as many hosts as you want, but more than three is excessive. Since the license manager is started by a running configuration, it should be configured to run on systems where you expect a Caché configuration to be running consistently. If you configure redundant license managers there is no need to use different port numbers as was necessary with license servers.
Upgrading a License
A license key can be upgraded by placing it in the appropriate directory on the Caché server, or by using the license wizard in the Caché Configuration Manager. When the wizard enters and saves the key, the working version of the key is automatically updated and activated. If upgrading manually, invoke the $System.License.Upgrade method from the %SYS namespace. In general there is no need to restart the configuration.
There are constraints when upgrading a license type. Automatic activation of the new key does not occur if you change license types from Power Unit to any other type; this should be a rare event. Most license upgrades are expected to just increase the number of license units or change from single-server to multiserver licenses.
Another constraint is the amount of memory the license upgrade consumes from the generic memory heap (gmheap) space. If gmheap space is not available, the number of license table entries cannot be expanded. There is also a limit to the amount of gmheap space (10 pages) that a license upgrade consumes. This limit permits a maximum of slightly more than 7,000 additional license units to be activated. This is the incremental count, not the total, so if you have a 30,000 Concurrent User key, you can upgrade it to slightly more than 37,000 license units without restarting the configuration. If you upgrade your license by purchasing more than 7,000 additional license units, approximately 7,000 additional license units are activated, but a restart is necessary to activate the rest.
Determining License Capacity
How does one know how many licenses have been used, and by whom? The %SYSTEM.License class provides an interface to the Caché license application programming interface (API) and presents a large number of methods that can be used to query license capacity and current use. You can run these class methods using the special $System object; they are described in the Caché Class Reference. Invoke the following class methods to display information or dump the license database to a file:
$System.License.CKEY displays the key. This subroutine is called by the ^CKEY program which is retained for compatibility:
 Do $System.License.CKEY()
$System.License.ShowCounts summarizes license use tracked in shared memory on the local system:
 Do $System.License.ShowCounts()
$System.License.ShowManager displays the active license manager address and port:
 Do $System.License.ShowManager()
Methods to Show Local License Information
The subroutines listed below dump the contents of license tables contained locally in configuration-shared memory. In general, they identify the client:
$System.License.DumpLocalAll dumps all local license table entries to the all.dmp file in the current directory:
 Do $System.License.DumpLocalAll()
An example of the contents of the all.dmp file:
License Capacity = 5, Current use = 2, Units Remaining = 3

   0)  User ID = 127.0.0.1, Connections = 2, CSP Count = 0, Time active = 90
   1)  User ID = 192.9.202.81, Connections = 1, CSP Count = 0, Time active = 49
   2)  free
   3)  free
   4)  free
$System.License.DumpLocalInUse dumps all local license table entries in use to the inuse.dmp file in the current directory:
 Do $System.License.DumpLocalInUse()
An example of the contents of the inuse.dmp file:
License Capacity = 5, Current use = 2, Units Remaining = 3
$System.License.DumpLocalPID dumps local license table use by process ID to the piduse.dmp file in the current directory:
 Do $System.License.DumpLocalPID()
An example of the contents of the piduse.dmp file:
License Capacity = 5, Current use = 2, Units Remaining = 3
Methods to Show License Manager Information
The following subroutines dump the contents of license tables maintained by the license manager. The output files are in the indicated directory on the host where the active license manager is running.
$System.License.ShowSummary displays a summary of license information at the license manager. The Distributed license use section presents a collective view of license use for all Caché configurations currently supported by the license manager. The Local license use section presents a view of license use for the single Caché configuration in which the program is run:
 Do $System.License.ShowSummary()
$System.License.DumpServer dumps the license manager database information relating to the server from which you run this routine to the file, dumpserver.txt, on the host running the license manager:
 Do $System.License.DumpServer()
$System.License.DumpServers dumps the license manager database information for all known servers to the file, dumpservers.txt, on the host running the license manager:
 Do $System.License.DumpServers()
$System.License.DumpKey dumps the key used by this configuration and configurations that share it to the file, dumpkey.txt, on the host running the license manager:
 Do $System.License.DumpKey()
$System.License.DumpKeys dumps all keys, showing the configurations and clients using them to the file, dumpkeys.txt, on the host running the license manager:
 Do $System.License.DumpKeys()
Note:
Be aware that the information displayed by the local license methods is more up-to-date than the information shown by the license manager methods; the license manager is only updated periodically, while the local data is real time.