The SYSTEM.License class provides an interface to the InterSystems IRIS License API. More...

Inheritance diagram for License:

Collaboration diagram for License:

Static Public Member Functions
_.Library.Integer	ActiveServerCount (_.Library.Status Status)
	The SYSTEM.License class provides an interface to the InterSystems IRIS License API. More...

_.Library.Integer	ApplicationServerLogin (_.Library.String AppName, _.Library.String Keyword, _.Library.Status Status)

	CKEY ()
	Display the active license key to the current device. More...

_.Library.Integer	CSPGrace ()
	$SYSTEM.License.CSPGrace() returns the current number of CSP sessions in the grace period.

_.Library.Integer	CSPUsers ()
	$SYSTEM.License.CSPUsers() returns the current number of CSP users.

_.Library.String	CheckAppLicenseUsed (_.Library.String AppName, _.Library.String FeatureKeyword)
	$SYSTEM.License.CheckAppLicenseUsed(AppName,Keyword) iterates through the internal license use tables counting the number of times an application license keyword has been taken. More...

_.Library.Boolean	CheckKeyForUpgrade (_.Library.String NewKeyFile, Reductions, _.Library.Status Status)
	$SYSTEM.License.CheckKeyForUpgrade(NewKeyFile,.Reductions,.Status) compares the active license key with More...

_.Library.Integer	CheckNewKey ()
	Signal the License Monitor (^LMFMON) to check for a new key from the License Server,. More...

_.Library.List	ClearDurationCounts ()
	$SYSTEM.License.ClearDurationCounts() sets the collection area of the LoginDuration query to all zeros and returns the counts prior to change. More...

_.Library.Integer	ConnectionCount (_.Library.String UserIdentifier)
	$SYSTEM.License.ConnectionCount() returns the number of connections currently associated with the given UserIdentifier. More...

	Decode ()
	Decode and display the capabilities encoded in the AuthorizationKey field of the active License Key. More...

	DecodeAuth (_.Library.String key)
	Decode and display the capabilities encoded in the AuthorizationKey field of a License Key provided as the 'key' argument.

_.Library.Integer	DeferUserIdentification (_.Library.Integer usage)
	Specify Deferred (usage=1) or automatic (usage=0) license login for the local InterSystems IRIS instance.

_.Library.Status	DistributedMaxReset (_.Library.String Counter)
	Reset distributed peak levels on the License Server for this Instance and it's license key. More...

	DumpKey ()
	Dump the License Server view of key utilization for the active key. More...

	DumpKeys ()
	Dump the License Server view of key utilization for all keys. More...

_.Library.String	DumpLocalAll (_.Library.String filename)
	Dump all the local InterSystems IRIS instance's license table entries to 'filename' in the sequential file output directory. More...

_.Library.String	DumpLocalInUse (_.Library.String filename)
	Dump the local InterSystems IRIS instance's active license table entries to 'filename' in the sequential file output directory. More...

_.Library.String	DumpLocalPID (_.Library.String filename)
	Dump license use by process Id to 'filename' in the sequential file output directory. More...

	DumpServer ()
	Dump License Server database for this server. More...

	DumpServers ()
	Dump License Server database for all servers. More...

_.Library.String	GetAppLicense (_.Library.String AppName, _.Library.Integer GetValues)
	$SYSTEM.License.GetAppLicense(AppName) retrieves the application license for the named application as a string of Keyword=Value pairs separated by $c(0), terminated by an empty $C(0) piece. More...

_.Library.String	GetAppLicenseFree (_.Library.String AppName, _.Library.String FeatureKeyword)
	$SYSTEM.License.GetAppLicenseFree(AppName,Keyword) retrieves the number of free license units associated with an application license feature keyword. More...

_.Library.String	GetAppLicenseMaxUsed (_.Library.String AppName, _.Library.String FeatureKeyword)
	$SYSTEM.License.GetAppLicenseMaxUsed(AppName,Keyword) retrieves the maximum number of consumed license units associated with an application license keyword, since the license was loaded. More...

_.Library.String	GetAppLicenseMinimum (_.Library.String AppName, _.Library.String FeatureKeyword)
	$SYSTEM.License.GetAppLicenseMinimum(AppName,Keyword) retrieves the minimum number of free license units associated with an application license keyword. More...

_.Library.String	GetAppLicenseUsed (_.Library.String AppName, _.Library.String FeatureKeyword)
	$SYSTEM.License.GetAppLicenseUsed(AppName,Keyword) retrieves the number of consumed license units associated with an application license keyword. More...

_.Library.String	GetAppLicenseValue (_.Library.String AppName, _.Library.String FeatureKeyword)
	$SYSTEM.License.GetAppLicenseValue(AppName,Keyword) retrieves the value associated with an application license keyword. More...

_.Library.List	GetAppNames (_.Library.String AppTypes)
	$SYSTEM.License.GetAppNames(AppTypes) returns a list of licensed applications. More...

_.Library.Integer	GetConnectionLimit ()
	$SYSTEM.License.GetConnectionLimit() returns the maximum number of connections permitted per user on this instance. More...

_.Library.Integer	GetFeature ()
	$SYSTEM.License.GetFeature(n) returns 1 if extended license feature n is authorized by the license key, 0 if it is not. More...

	GetKeyInvalidReason ()
	Fetch string describing the reason the key is invalid or in a troubled state.

	GetKeyStatus ()
	Fetch license key status: Valid, Invalid, or Troubled (expiring).

_.Library.List	GetProcessAppsTaken (_.Library.String PID, _.Library.String AppName)
	$SYSTEM.License.GetProcessAppsTaken(AppName,Keyword) retrieves a $List of application license types taken for the Process PID or "" for none. More...

_.Library.String	GetUserId (_.Library.String PID, _.Library.String JobNumber)
	$SYSTEM.License.GetUserId() returns the License User Identifier (if any) associated More...

_.Library.Integer	GetUserLimit ()
	$SYSTEM.License.GetUserLimit() returns the maximum number of license units the current instance will permit to be consumed. More...

	InstanceConnections ()
	$System.License.InstanceConnections() - return current count of connections to instance.

	InstanceConnectionsMax ()
	$System.License.InstanceConnectionsMax() - return maximum concurrent connections to instance since it restarted or the maximum was reset.

_.Library.Integer	IsAppLicensed (_.Library.String AppName, _.Library.String FeatureKeyword)

_.Library.Integer	IsPendingActivation ()
	Answers the question: Is a there a valid license key in the mgr directory that is not loaded. More...

_.Library.Status	IsValidKey (_.Library.String PathAndFileName, _.Library.Integer RequiresRestart, _.Library.String RestartReason, _.Library.String Permit)
	Determine whether the input license key file is valid and if an instance restart will be required to activate it. More...

_.Library.String	KeyAuthorizationKey ()
	$SYSTEM.License.KeyAuthorizationKey() returns the AuthorizationKey field in the active key.

_.Library.Integer	KeyCPUsEnforced ()
	$SYSTEM.License.KeyCPUsEnforced() returns the licensed CPUs code enforced by the active key. More...

_.Library.Integer	KeyCPUsLicensed ()
	$SYSTEM.License.KeyCPUsLicensed() returns the licensed CPUs code authorized by the active key. More...

_.Library.Integer	KeyCoresEnforced ()
	$SYSTEM.License.KeyCoresEnforced() returns the number of Cores enforced by the active key. More...

_.Library.Integer	KeyCoresLicensed ()
	$SYSTEM.License.KeyCoresLicensed() returns the number of Cores authorized by the active key. More...

_.Library.String	KeyCustomerName ()
	$SYSTEM.License.KeyCustomerName() returns the active key CustomerName field.

_.Library.Integer	KeyEnforcedUnits ()
	$SYSTEM.License.KeyEnforcedUnits() returns the number of license units enforced by the active key.

_.Library.Integer	KeyExpirationDate ()
	$SYSTEM.License.KeyExpirationDate() returns the active key expiration date as an integer, $H date value. More...

_.Library.String	KeyFeatures ()
	$SYSTEM.License.KeyFeatures() returns the Features portion of the Authorization field in the active key.

_.Library.String	KeyFileType (_.Library.Integer IncludeKeyword)
	$SYSTEM.License.KeyFileType(IncludeKeyword) returns the FileType property of the [ConfigFile] section of the loaded license key. More...

_.Library.String	KeyLicenseCapacity ()
	$SYSTEM.License.KeyLicenseCapacity() returns the active key LicenseCapacity field.

_.Library.String	KeyLicenseType ()
	$SYSTEM.License.KeyLicenseType() returns the active key license type (example: Concurrent User).

_.Library.Integer	KeyLicenseUnits ()
	$SYSTEM.License.KeyLicenseUnits() returns the number of license units authorized by the active key.

_.Library.String	KeyMachineID ()
	$SYSTEM.License.KeyMachineID() returns the contents of the MachineID field in the active key.

_.Library.Integer	KeyOrderNumber ()
	$SYSTEM.License.KeyOrderNumber() returns the active key order number.

_.Library.String	KeyPlatform ()
	$SYSTEM.License.KeyPlatform() returns the active key licensed platform.

_.Library.String	KeyProduct ()
	$SYSTEM.License.KeyProduct() returns the active key product (example: Enterprise).

_.Library.String	KeyServer ()
	$SYSTEM.License.KeyServer() returns the active key server type licensed (Single or Multi).

_.Library.String	KeyVersion ()
	$SYSTEM.License.KeyVersion() returns the version from the FileType property of the [ConfigFile] section of the loaded license key. More...

_.Library.Integer	LUAvailable ()
	$SYSTEM.License.LUAvailable() returns number of license units currently available at the local InterSystems IRIS instance.

_.Library.Integer	LUConsumed ()
	$SYSTEM.License.LUConsumed() returns number of license units currently consumed at the local InterSystems IRIS instance.

_.Library.Integer	LUMaxConsumed ()
	$SYSTEM.License.LUMaxConsumed() returns the maximum number of license units consumed at the local InterSystems IRIS instance since it started. More...

_.Library.Integer	LUMaxConsumedReset ()
	$SYSTEM.License.LUMaxConsumedReset([Argument]) resets the recorded peak levels of various measures of license use by setting the internal counters to the current usage level and returns the previously recorded maximum count. More...

_.Library.Integer	LUMinAvailable ()
	$SYSTEM.License.LUMinAvailable() returns the minimum number of license units available at the local InterSystems IRIS instance since it started. More...

_.Library.Integer	LicenseCount (_.Library.String UserIdentifier)
	$SYSTEM.License.LicenseCount() returns the number of License Units currently consumed on the local instance by the given UserIdentifier. More...

_.Library.Integer	LoadAppLicenseFile (_.Library.String FileName, _.Library.String AppName)
	$SYSTEM.License.LoadAppLicenseFile(FileName,SectionName) More...

_.Library.Integer	Login (_.Library.String UserIdentifier)
	$SYSTEM.License.Login(UserIdentifier) performs a license login. More...

_.Library.Integer	MaxBufferPool ()
	$$SYSTEM.License.MaxBufferPool() returns the maximum buffer pool size authorized by the active license key. More...

_.Library.Integer	MaxCSPGrace ()
	$SYSTEM.License.MaxCSPGrace() returns the maximum number of CSP sessions in the grace period at any time since the instance started or the CSPGrace maximum counter was reset.

_.Library.Integer	MaxCSPUsers ()
	$SYSTEM.License.MaxCSPUsers() returns the maximum number of concurrent CSP users since the instance started or the CSPUsers maximum counter was reset.

_.Library.Integer	MaxConnections ()
	$SYSTEM.License.MaxConnections() returns the maximum number of connections a user can make while consuming one license unit.

_.Library.Integer	MaxDB (_.Library.Boolean UserOnly)
	$SYSTEM.License.MaxDB() returns the maximum number of Databases authorized by the active license key. More...

_.Library.Integer	MaxECPServers ()
	$SYSTEM.License.MaxECPServers() returns the maximum number of ECP servers authorized by the active license key.

_.Library.Integer	NetworkEnabled ()
	$SYSTEM.License.NetworkEnabled() returns 1 if the InterSystems IRIS license key enables ECP, 0 if it doesn't.

_.Library.Integer	ProcAvailable ()
	$SYSTEM.License.ProcAvailable returns the number of additional InterSystems IRIS User process licenses available on this InterSystems IRIS instance. More...

_.Library.Integer	ProcConsumed ()
	$SYSTEM.License.ProcConsumed returns the number of InterSystems IRIS User process licenses currently in use on this InterSystems IRIS instance. More...

_.Library.Integer	ProcMaxConsumed ()
	$SYSTEM.License.ProcMaxConsumed returns the maximum number of InterSystems IRIS User processes running concurrently since the instance started.

_.Library.Integer	ProcMinAvailable ()
	$SYSTEM.License.ProcMinAvailable returns the minimum number of additional processes available at any time since the instance started. More...

_.Library.Integer	PublicWebAppUser ()
	$SYSTEM.License.PublicWebAppUser declares an application to be a public web application for the purpose of a Web Add-on license. More...

_.Library.Integer	PublicWebAppUserCount ()
	$SYSTEM.License.PublicWebAppUserCount returns the current number of public web application connections active.

_.Library.Integer	PublicWebAppUsersMax ()
	$SYSTEM.License.PublicWebAppUsersMax() returns the maximum number of public web application connections active at any one time.

_.Library.List	ReadDurationCounts ()
	$SYSTEM.License.ReadDurationCounts() returns the number of times a logout occurred within the time indicated by the corresponding ReadDurationValues. More...

_.Library.List	ReadDurationValues ()
	$SYSTEM.License.ReadDurationValues() returns the upper limit in seconds each histogram bucket represents. More...

_.Library.Status	ReturnAllCSPApps (_.CSP.Session session)
	$System.License.ReturnAllCSPApps(SessionId) Called by the CSP Daemon when it deletes a session object.

_.Library.Status	ReturnApplicationLicense (_.Library.String AppName, _.Library.String FeatureKeyword, _.Library.Integer Released, _.CSP.Session session)
	$SYSTEM.License.ReturnApplicationLicense(AppName,FeatureKeyword,.released,session) More...

_.Library.Integer	SetConnectionLimit (_.Library.Integer MaxCon)
	$SYSTEM.License.SetConnectionLimit establishes the maximum number of connections permitted per user on this instance. More...

_.Library.Integer	SetUserLimit (_.Library.Integer MaxLU)
	$SYSTEM.License.SetUserLimit establishes the maximum number of license units that this InterSystems IRIS instance will consume. More...

	ShowCounts ()
	Display Local view of license use. More...

	ShowServer ()
	Display current active license Server address and port. More...

	ShowSummary ()
	Display Summary of License Server Database. More...

_.Library.Status	TakeApplicationLicense (_.Library.String AppName, _.Library.String FeatureKeyword, _.Library.Integer Count, _.CSP.Session session)
	$SYSTEM.License.TakeApplicationLicense(AppName,FeatureKeyword,.count,session) More...

_.Library.String	Upgrade ()
	Upgrade to a license (iris.key file) that has been copied to the mgr directory. More...

_.Library.Integer	UserNameLicensing (_.Library.Integer OnOffState)
	Modify how the License User Identifier is specified. More...

Static Public Member Functions inherited from Help
_.Library.String	Help (_.Library.String method)
	This is a helper class that is used by the various SYSTEM classes to provide a Help method. More...

Detailed Description

The SYSTEM.License class provides an interface to the InterSystems IRIS License API.

Some class methods are implemented in the special $system object and can be accessed with the $SYSTEM.License.Method() syntax. The system object methods are identified in the method documentation as $SYSTEM.License.XXX.

Example: Set Success=$SYSTEM.License.Login(UserIdentifier)

Other methods are implemented as class methods of the SYSTEM.License class and can be accessed by the usual

class(%SYSTEM.License).ClassMethodName() syntax. The special $system object methods can also be accessed in this way.

Example: Do ##class(SYSTEM.License).ShowSummary()

The SYSTEM.License class includes a number of license usage reports and queries.
The data source is either the local instance or the license server, or in some cases both. The data source is identified in the individual query descriptions.

Comparing data from the license server with data from an individual InterSystems IRIS instance can sometimes lead to apparent inconsistencies. These inconsistencies can be explained by understanding the operation of the license server. Each InterSystems IRIS instance maintains a database of its license use and independently controls connections to itself. When multiple instances share a InterSystems IRIS license key, the license server coordinates the counting of license usage among all instances sharing the license key. Each instance periodically sends messages to the license server describing any changes that have occurred to the local license database since the previous message. Each instance controls logins and logouts locally and can continue to permit connections if communication with the license server should be interrupted. The license server coordinates the activity of the participating instances by preventing them from collectively exceeding the authorized license count.

The periodic nature of license server updates is one source of temporary inconsistency between the license server's view of license use and an individual InterSystems IRIS instance's view.
License server and InterSystems IRIS instance counts of license usage will be temporarily out of sync if a number of logins or logouts have not yet been sent to the license server at the time usage reports are requested from the license server and from the local instance. This inconsistency is short lived because updates are sent to the license server about every 15 seconds.

It is also possible for the active license server to be stopped, perhaps because the host on which it is running has shut down or because the instance that started it is being upgraded. In this case, the replacement license server's view of license use will be incomplete until all participating instances have reported their license use.

Member Function Documentation

◆ ActiveServerCount()

_.Library.Integer ActiveServerCount ( _.Library.Status Status )

static

The SYSTEM.License class provides an interface to the InterSystems IRIS License API.

Some class methods are implemented in the special $system object and can be accessed with the $SYSTEM.License.Method() syntax. The system object methods are identified in the method documentation as $SYSTEM.License.XXX.

Example: Set Success=$SYSTEM.License.Login(UserIdentifier)

Other methods are implemented as class methods of the SYSTEM.License class and can be accessed by the usual

class(%SYSTEM.License).ClassMethodName() syntax. The special $system object methods can also be accessed in this way.

Example: Do ##class(SYSTEM.License).ShowSummary()

The SYSTEM.License class includes a number of license usage reports and queries.
The data source is either the local instance or the license server, or in some cases both. The data source is identified in the individual query descriptions.

Comparing data from the license server with data from an individual InterSystems IRIS instance can sometimes lead to apparent inconsistencies. These inconsistencies can be explained by understanding the operation of the license server. Each InterSystems IRIS instance maintains a database of its license use and independently controls connections to itself. When multiple instances share a InterSystems IRIS license key, the license server coordinates the counting of license usage among all instances sharing the license key. Each instance periodically sends messages to the license server describing any changes that have occurred to the local license database since the previous message. Each instance controls logins and logouts locally and can continue to permit connections if communication with the license server should be interrupted. The license server coordinates the activity of the participating instances by preventing them from collectively exceeding the authorized license count.

The periodic nature of license server updates is one source of temporary inconsistency between the license server's view of license use and an individual InterSystems IRIS instance's view.
License server and InterSystems IRIS instance counts of license usage will be temporarily out of sync if a number of logins or logouts have not yet been sent to the license server at the time usage reports are requested from the license server and from the local instance. This inconsistency is short lived because updates are sent to the license server about every 15 seconds.

It is also possible for the active license server to be stopped, perhaps because the host on which it is running has shut down or because the instance that started it is being upgraded. In this case, the replacement license server's view of license use will be incomplete until all participating instances have reported their license use.

$SYSTEM.License.ActiveServerCount() returns the number of instances (including the current instance) currently using the active license key.

It executes the $SYSTEM.License.KeyOrderNumber() query and counts the number of instances using a license with the same OrderNumber value as the active license key on the current instance. Error status is returned by reference in the Status argument.

◆ ApplicationServerLogin()

_.Library.Integer ApplicationServerLogin	(	_.Library.String	AppName,
		_.Library.String	Keyword,
		_.Library.Status	Status
	)

static

Class(%SYSTEM.License).ApplicationServerLogin(AppName, Keyword, Status) returns 1 if the number of instances using the

active license key used by this instance (including this instance) does not exceed the number authorized by the "Keyword" item in the "AppName" application license section. Error status is returned by reference in the Status argument.

◆ CKEY()

CKEY ( )

static

Display the active license key to the current device.

The fields of the [License] section of the installed license file are displayed followed by a brief accounting of license usage, including:

License units currently available.
Minimum number of license units available at any time since the instance started.
Maximum number of license units available.

License usage levels are obtained from the current InterSystems IRIS instance.
This report is identical to those produced by CKEY^SYS.LICENSE and ^CKEY.

◆ CheckAppLicenseUsed()

_.Library.String CheckAppLicenseUsed	(	_.Library.String	AppName,
		_.Library.String	FeatureKeyword
	)

static

$SYSTEM.License.CheckAppLicenseUsed(AppName,Keyword) iterates through the internal license use tables counting the number of times an application license keyword has been taken.

The resulting count is compared to the internal usage count maintained for the application license keyword. The internal count is adjusted if it does not agree with the counted value.
The return value is a string containing "CountedUsage,InternalUsageCountBeforeAdjustment,AppLicensesRecovered"
Throws an "INVALID ARGUMENT" error if AppName is not licensed. Returns "" if FeatureKeyword is not licensed. Returns "" if the application/keyword license value is not a number because only numeric application features can be taken and released. AppName is of the form Company.Application for protected application license sections or Application for unprotected application license sections.

Example: $SYSTEM.License.CheckAppLicenseUsed("MyCompany.MyApp","MyAppFeature")

◆ CheckKeyForUpgrade()

_.Library.Boolean CheckKeyForUpgrade	(	_.Library.String	NewKeyFile,
			Reductions,
		_.Library.Status	Status
	)

static

$SYSTEM.License.CheckKeyForUpgrade(NewKeyFile,.Reductions,.Status) compares the active license key with

the key in file NewKeyFile to determine if the new license key authorizes less capability than the active license. It returns TRUE (1) if any capabilities authorized by the active key are absent in the new key or of lessor capacity. It returns FALSE (0) if all capabilities of the active license are equaled or exceeded by the license in NewKeyFile.

Arguments:

NewKeyFile (input): full path and file name of new license key file.
Reductions (output by reference): an array of capabilities that are smaller in the new key than in the active key.
Status (output by reference): an error status returned by IsValidKey when it was called to examine the new license file.

The Reductions array can contain the following elements:

Reductions("Cores")=$lb(OldCores,NewCores)
Reductions("Server")=$lb(OldServerValue,NewServerValue)
Reductions("Users")=$lb(OldUsers,NewUsers)
Reductions("Product")=$lb(OldProduct,NewProduct)
Reductions("LicenseType")=$lb(OldType,NewType)

Reductions in licensed features will be indicated by Reductions("Feature", FeatureName)=$lb(OldFeatureValue,NewFeatureValue). License parameters which have not changed or which have increased in capability will not be shown.

◆ CheckNewKey()

_.Library.Integer CheckNewKey ( )

static

Signal the License Monitor (^LMFMON) to check for a new key from the License Server,.

and download and upgrade to that key if there is one. This is normally done every 5 minutes by the Monitor, but this method can make it check immediately.
A return of -1 means that no LicenseID was found.
A return of 1 means the signal was successful, a return of 0 means the signal was not successful.
The latest key downloaded can be checked in the Portal License Key page.

◆ ClearDurationCounts()

_.Library.List ClearDurationCounts ( )

static

$SYSTEM.License.ClearDurationCounts() sets the collection area of the LoginDuration query to all zeros and returns the counts prior to change.

Requires the Manager role.

◆ ConnectionCount()

_.Library.Integer ConnectionCount ( _.Library.String UserIdentifier )

static

$SYSTEM.License.ConnectionCount() returns the number of connections currently associated with the given UserIdentifier.

The range of return values is normally 0 through MAXCONNECTIONS.
If the value exceeds MAXCONNECTIONS then more than the allowable number of concurrent connections were attempted for a given ID and the system has transitioned to a mode of one connection per license for this UserIdentifier.

◆ Decode()

Decode ( )

static

Decode and display the capabilities encoded in the AuthorizationKey field of the active License Key.

◆ DistributedMaxReset()

_.Library.Status DistributedMaxReset ( _.Library.String Counter )

static

Reset distributed peak levels on the License Server for this Instance and it's license key.

This is similar to $SYSTEM.License.LUMaxConsumedReset method, but resets the distributed values. 'Counter' may be either 'Users' or 'Connections'. If 'Counter' is null, both are reset

◆ DumpKey()

DumpKey ( )

static

Dump the License Server view of key utilization for the active key.

Note: Not applicable with a Single-Server key.

This report displays license utilization for the key loaded by the current InterSystems IRIS instance. The report is produced by the license server and may reside on a remote host. The location (host and directory) of the output file will be displayed on the terminal when the report is complete. The report shows the license server's view of license use by all InterSystems IRIS instances which share a license key and which are configured to use the same license server (as is required when sharing a key).

License use by each client (License Id) connected to each InterSystems IRIS instance is reported in these columns:

Client: License Id for the connection from a client to this InterSystems IRIS instance.
LU: Number of license units consumed by connections from this client to this InterSystems IRIS instance.
Connections: Number of connections from this client to this InterSystems IRIS instance.
Server: Address of host where the InterSystems IRIS instance is running.
Instance: Name of the InterSystems IRIS instance to which the client is connected.

The report displays the fields of the license key and summarizes the number of servers (InterSystems IRIS instances) using the key, authorized license units, and the current and maximum number of license units in use. This summary information represents the license server's view of license use. This report is identical to the report produced by dumpkey^SYS.LICENSE.

◆ DumpKeys()

DumpKeys ( )

static

Dump the License Server view of key utilization for all keys.

Note: Not applicable with a Single-Server key.

This report displays license utilization for every key controlled by the license server. The report is produced by the license server and may reside on a remote host. The location (host and directory) of the output file will be displayed on the terminal when the report is complete. The report shows the license server's view of license usage by all InterSystems IRIS instances which share each license key under the license server's control. For true reporting and as a requirement of the InterSystems IRIS license agreement, each InterSystems IRIS instance that uses a key must configure the same set of license servers.

License use by each client (License Id) connected to each InterSystems IRIS instance is reported in these columns:

Client: License Id for the connection from a client to this InterSystems IRIS instance.
LU: Number of license units consumed by connections from this client to this InterSystems IRIS instance.
Connections: Number of connections from this client to this InterSystems IRIS instance.
Server: Address of host where the InterSystems IRIS instance is running.
Instance: Name of the InterSystems IRIS instance to which the client is connected.

The report displays the fields of each license key and summarizes the number of servers (InterSystems IRIS instances) using the key, authorized license units, and the current and maximum number of license units in use. This summary information represents the license server's view of license use for each license key. This report is identical to the report produced by dumpkeys^SYS.LICENSE.

◆ DumpLocalAll()

_.Library.String DumpLocalAll ( _.Library.String filename )

static

Dump all the local InterSystems IRIS instance's license table entries to 'filename' in the sequential file output directory.

A file named all.dmp is created if the filename argument is not supplied.

The report displays the following columns:

UserId: the license user identifier consuming each license table entry.
Type: License login type (User, CSP, or Mixed)
Connections: Number of connections to this instance by this user.
MaxCon: Maximum number of connections to this instance by this user.
CSPCon: Number of CSP connections by this user.
LU: Number of license units consumed. If more than one, the maximum connection count is or was exceeded by this user and the user is now consuming one license unit per connection.
Active: Time in seconds the user has been active.
Grace: Number of seconds remaining in the grace period for a CSP user who has disconnected.

This report shows license use at the local instance and is identical to the report produced by ldumpall^SYS.LICENSE. It presents the results of the SYSTEM.License.UserListAll query.

◆ DumpLocalInUse()

_.Library.String DumpLocalInUse ( _.Library.String filename )

static

Dump the local InterSystems IRIS instance's active license table entries to 'filename' in the sequential file output directory.

A file named inuse.dmp is created if the filename argument is not supplied.

The report displays the following columns:

UserId: the license user identifier consuming each license table entry.
Type: License login type (User, CSP, or Mixed)
Connections: Number of connections to this instance by this user.
MaxCon: Maximum number of connections to this instance by this user.
CSPCon: Number of CSP connections by this user.
LU: Number of license units consumed. If more than one, the maximum connection count is or was exceeded by this user and the user is now consuming one license unit per connection.
Active: Time in seconds the user has been active.
Grace: Number of seconds remaining in the grace period for a CSP user who has disconnected.

This report shows license use at the local instance and is identical to the report produced by ldumpinuse^SYS.LICENSE. It presents the results of the SYSTEM.License.UserList query.

◆ DumpLocalPID()

_.Library.String DumpLocalPID ( _.Library.String filename )

static

Dump license use by process Id to 'filename' in the sequential file output directory.

A file named piduse.dmp is created if the filename argument is not supplied.

The report displays the following columns:

PID: Process Id.
Display PID: Process Id in display format (hex on VMS).
Process: Process type (System, User, CSP, Diagnostic, Server, Pending).
LID: The license user identifier for which a license unit is being consumed.
Type: License login type (User, CSP, or Mixed)
Con: Number of connections to this instance by this user.
MaxCon: Maximum number of connections to this instance by this user.
CSPCon: Number of CSP connections by this user.
LU: Number of license units consumed. If more than one, the maximum connection count is or was exceeded by this user and the user is now consuming one license unit per connection.
Active: Time in seconds the user has been active.
Grace: Number of seconds remaining in the grace period for a CSP user who has disconnected.

This report shows license use at the local instance and is identical to the report produced by ldumppid^SYS.LICENSE. Summing the columns of this report is meaningless.
This report is identical to ldumppid^SYS.LICENSE. It presents the results of the SYSTEM.License.ProcessList query.

◆ DumpServer()

DumpServer ( )

static

Dump License Server database for this server.

Note: Not applicable with a Single-Server key. This report presents license usage by the current InterSystems IRIS instance recorded at the license server. The report is produced by the license server and may reside on a remote host. The location (host and directory) of the report output file will be reported to the terminal when the report is complete." License use by client (License Id) is reported in these columns:

Connections: Number of connections for this client.
License Units: Number of license units consumed by this client on this server.
Client: License Id consuming the license unit or units.

The report summarizes total connections and license units consumed by clients attached to this InterSystems IRIS instance and the total number of license units shared by clients on this the InterSystems IRIS server instance with connections by the same client to other the InterSystems IRIS server instances. This report is identical to that produced by dumpserver^SYS.LICENSE.

◆ DumpServers()

DumpServers ( )

static

Dump License Server database for all servers.

Note: Not applicable with a Single-Server key.

This report presents license usage by each InterSystems IRIS instance served by the license server. The report is produced by the license server and may reside on a remote host. The location (host and directory) of the output file will be displayed on the terminal when the report is complete. License use by client (License Id) is reported in these columns:

Connections: Number of connections for this client.
License Units: Number of license units consumed by this client on this server.
Client: License Id consuming the license unit or units.

The report summarizes total connections and license units consumed by clients connected to each InterSystems IRIS instance and the number of license units shared by clients connected to this the InterSystems IRIS server instance with connections from the same client to other the InterSystems IRIS server instances. A combined grand total of connections and license units consumed by all the InterSystems IRIS server instances served by the license server is reported. This report is identical to that produced by dumpservers^SYS.LICENSE.

◆ GetAppLicense()

_.Library.String GetAppLicense	(	_.Library.String	AppName,
		_.Library.Integer	GetValues
	)

static

$SYSTEM.License.GetAppLicense(AppName) retrieves the application license for the named application as a string of Keyword=Value pairs separated by $c(0), terminated by an empty $C(0) piece.

AppName is of the form Company.Application for protected application license sections or Application for unprotected application license sections or the TrakCare application.
If GetValues is zero, only the keyword names are returned. If GetValues is not zero, a sequence of kw=value are returned.

Example: $SYSTEM.License.GetAppLicense("MyCompany.MyApp",1)

Example return value: "kw1=value1"_$c(0)_"kw2=value2"_$c(0)_..._"kwN=valueN"_$c(0)_$c(0)

◆ GetAppLicenseFree()

_.Library.String GetAppLicenseFree	(	_.Library.String	AppName,
		_.Library.String	FeatureKeyword
	)

static

$SYSTEM.License.GetAppLicenseFree(AppName,Keyword) retrieves the number of free license units associated with an application license feature keyword.

AppName is of the form Company.Application for protected application license sections or Application for unprotected application license sections. Keyword is the keyword of the application feature.
GetAppLicenseFree() is only meaningful where the value associated with the keyword is numeric.
An INVALID ARGUMENT error is returned if no application license is loaded for "AppName". An empty string is returned if "Keyword" is not a feature of "AppName".

Example: $SYSTEM.License.GetAppLicenseFree("MyCompany.MyApp","MyAppFeature")

◆ GetAppLicenseMaxUsed()

_.Library.String GetAppLicenseMaxUsed	(	_.Library.String	AppName,
		_.Library.String	FeatureKeyword
	)

static

$SYSTEM.License.GetAppLicenseMaxUsed(AppName,Keyword) retrieves the maximum number of consumed license units associated with an application license keyword, since the license was loaded.

AppName is of the form Company.Application for protected application license sections or Application for unprotected application license sections. Keyword is the keyword of the application feature.
GetAppLicenseMaxUsed() is only meaningful where the value associated with the keyword is numeric.
An INVALID ARGUMENT error is returned if no application license is loaded for "AppName". An empty string is returned if "Keyword" is not a feature of "AppName".

Example: $SYSTEM.License.GetAppLicenseMaxUsed("MyCompany.MyApp","MyAppFeature")

◆ GetAppLicenseMinimum()

_.Library.String GetAppLicenseMinimum	(	_.Library.String	AppName,
		_.Library.String	FeatureKeyword
	)

static

$SYSTEM.License.GetAppLicenseMinimum(AppName,Keyword) retrieves the minimum number of free license units associated with an application license keyword.

AppName is of the form Company.Application for protected application license sections or Application for unprotected application license sections. Keyword is the keyword of the application feature.
GetAppLicenseMinimum() is only meaningful where the value associated with the keyword is numeric.
An INVALID ARGUMENT error is returned if no application license is loaded for "AppName". An empty string is returned if "Keyword" is not a feature of "AppName".

Example: $SYSTEM.License.GetAppLicenseMinimum("MyCompany.MyApp","MyAppFeature")

◆ GetAppLicenseUsed()

_.Library.String GetAppLicenseUsed	(	_.Library.String	AppName,
		_.Library.String	FeatureKeyword
	)

static

$SYSTEM.License.GetAppLicenseUsed(AppName,Keyword) retrieves the number of consumed license units associated with an application license keyword.

AppName is of the form Company.Application for protected application license sections or Application for unprotected application license sections. Keyword is the keyword of the application feature.
GetAppLicenseUsed() is only meaningful where the value associated with the keyword is numeric.
An INVALID ARGUMENT error is returned if no application license is loaded for "AppName". An empty string is returned if "Keyword" is not a feature of "AppName".

Example: $SYSTEM.License.GetAppLicenseUsed("MyCompany.MyApp","MyAppFeature")

◆ GetAppLicenseValue()

_.Library.String GetAppLicenseValue	(	_.Library.String	AppName,
		_.Library.String	FeatureKeyword
	)

static

$SYSTEM.License.GetAppLicenseValue(AppName,Keyword) retrieves the value associated with an application license keyword.

AppName is of the form Company.Application for protected application license sections or Application for unprotected application license sections. Keyword is the keyword of the application feature.
An INVALID ARGUMENT error is returned if no application license is loaded for "AppName". An empty string is returned if "Keyword" is not a feature of "AppName".

Example: $SYSTEM.License.GetAppLicenseValue("MyCompany.MyApp","MyAppFeature")

◆ GetAppNames()

_.Library.List GetAppNames ( _.Library.String AppTypes )

static

$SYSTEM.License.GetAppNames(AppTypes) returns a list of licensed applications.

AppTypes is a string containing the type[s] of licensed applications which should be returned.

"I": Return InterSystems supplied applications.
"P": Return protected applications loaded from the license file.
"U": Return unprotected applications loaded with the $SYSTEM.License.LoadAppLicenseFile() method.

Set Applications=$SYSTEM.License.GetAppNames("PU") ;Fetch all non InterSystems licensed application names.

◆ GetConnectionLimit()

_.Library.Integer GetConnectionLimit ( )

static

$SYSTEM.License.GetConnectionLimit() returns the maximum number of connections permitted per user on this instance.

The limit is established by calling $SYSTEM.License.SetConnectionLimit(). A zero return value means no limit has been set.

◆ GetFeature()

_.Library.Integer GetFeature ( )

static

$SYSTEM.License.GetFeature(n) returns 1 if extended license feature n is authorized by the license key, 0 if it is not.

Current values of n are:
0) Web Add-on
1) Interoperability
2) Shadowing
3) BI User (runtime)
4) BI Development
5) HealthShare
6) TrakCare
7) IP Address Neutral
8) Analytics Run
9) Analytics Analyzer
10) Analytics Architect
11) NLP
12) HealthShare Foundation
13) C-Type License
14) Analytics VR Execute
15) ExtremeNoUserLimit
16) Analytics VR Format
17) Analytics VR Data Define
18) Sharding
19) IntegratedML
20) InterSystems IRIS
21) API Management
22) Compatibility
23) Security Waiver
24) FHIR Repository
25) Columnar Storage
26) FHIR SQL Builder
27) Foreign Tables
28) Vector Search

◆ GetProcessAppsTaken()

_.Library.List GetProcessAppsTaken	(	_.Library.String	PID,
		_.Library.String	AppName
	)

static

$SYSTEM.License.GetProcessAppsTaken(AppName,Keyword) retrieves a $List of application license types taken for the Process PID or "" for none.

PID specifies the process. AppName is of the form Company.Application for protected application license sections or Application for unprotected application license sections.
An INVALID ARGUMENT error is returned if no application license is loaded for "AppName".

Example: $SYSTEM.License.GetProcessAppsTaken($J,"MyCompany.MyApp")

◆ GetUserId()

_.Library.String GetUserId	(	_.Library.String	PID,
		_.Library.String	JobNumber
	)

static

$SYSTEM.License.GetUserId() returns the License User Identifier (if any) associated

with the currently executing session/process.

With a Core Capacity license, this method returns the empty string ("") because InterSystems IRIS does not track license user identifiers. With a user-based license, if this method returns an empty string, that indicates that the session/process is running in a degraded state (as will be the case when no license has been taken out automatically for the session/process).

This method also allows a second argument of JobNumber (the index into the job table), e.g. $SYSTEM.License.GetUserId("",JobNumber). This can be faster than using Process Id if you already have the JobNumber (repeated calls for a single process), or are sequentially accessing all the processes on the system. Note the first argument must be "", and is ignored in this case.

◆ GetUserLimit()

_.Library.Integer GetUserLimit ( )

static

$SYSTEM.License.GetUserLimit() returns the maximum number of license units the current instance will permit to be consumed.

This is the limit established by a prior call to $SYSTEM.License.SetUserLimit(maxusers) or the number of license units authorized by the license key if no reduced limit has been established.

◆ IsAppLicensed()

_.Library.Integer IsAppLicensed	(	_.Library.String	AppName,
		_.Library.String	FeatureKeyword
	)

static

class(%SYSTEM.License).IsAppLicensed(AppName) returns 1 if the application named AppName is licensed, otherwise 0.

class(%SYSTEM.License).IsAppLicensed(AppName,FeatureKeyword) returns 1 if the feature named FeatureKeyword is licensed for the application named AppName, otherwise 0.

AppName is of the form Company.Application for protected application license sections or Application for unprotected application license sections. The license may have been loaded as part of the iris.key file or separately using $system.License.LoadAppLicenseFile()

Example: $SYSTEM.License.IsAppLicensed("MyCompany.MyApp","MyAppFeature")

◆ IsPendingActivation()

_.Library.Integer IsPendingActivation ( )

static

Answers the question: Is a there a valid license key in the mgr directory that is not loaded.

Restart may or may not be required.

class(%SYSTEM.License).IsPendingActivation() returns 1 if the iris.key file in the "mgr" directory is valid but is not the active license key.

class(%SYSTEM.License).IsPendingActivation() returns 0 if the iris.key file in the "mgr" directory is the active license key or if no iris.key file exists in the "mgr" directory or if the key in "mgr" is invalid.

◆ IsValidKey()

_.Library.Status IsValidKey	(	_.Library.String	PathAndFileName,
		_.Library.Integer	RequiresRestart,
		_.Library.String	RestartReason,
		_.Library.String	Permit
	)

static

Determine whether the input license key file is valid and if an instance restart will be required to activate it.

Arguments:
PathAndFileName: (In) Full path to license file.
RequiresRestart: (Out) 1 if instance restart is required to activate key, 0 if not.
RestartReason: (Out) Reason restart is required, or "" if restart is not required.

Permit: (In) For internal use only. Return value:
$$$OK - key is valid for this platform.
Or, error status with explanation of why the key is not valid for this platform.

◆ KeyCPUsEnforced()

_.Library.Integer KeyCPUsEnforced ( )

static

$SYSTEM.License.KeyCPUsEnforced() returns the licensed CPUs code enforced by the active key.

This CPU code is converted to an authorized core count by an algorithim that depends on other aspects of the licensed product. This number may be higher than the CPUs licensed code if an adjustment has been made in the license key to accomodate a CPU counting issue.

◆ KeyCPUsLicensed()

_.Library.Integer KeyCPUsLicensed ( )

static

$SYSTEM.License.KeyCPUsLicensed() returns the licensed CPUs code authorized by the active key.

This CPU code is converted to an authorized core count by an algorithim that depends on other aspects of the licensed product.

◆ KeyCoresEnforced()

_.Library.Integer KeyCoresEnforced ( )

static

$SYSTEM.License.KeyCoresEnforced() returns the number of Cores enforced by the active key.

This may be higher than the number of Cores licensed if an adjustment has been made in the license key.

◆ KeyCoresLicensed()

_.Library.Integer KeyCoresLicensed ( )

static

$SYSTEM.License.KeyCoresLicensed() returns the number of Cores authorized by the active key.

InterSystems IRIS will not accept a key with a given Cores authorization when running on a host with more cores.

◆ KeyExpirationDate()

_.Library.Integer KeyExpirationDate ( )

static

$SYSTEM.License.KeyExpirationDate() returns the active key expiration date as an integer, $H date value.

Use $ZDATE to convert this to readable form.

◆ KeyFileType()

_.Library.String KeyFileType ( _.Library.Integer IncludeKeyword )

static

$SYSTEM.License.KeyFileType(IncludeKeyword) returns the FileType property of the [ConfigFile] section of the loaded license key.

If the IncludeKeyword argument is 1, the property keyword (FileType=) is included. If IncludeKeyword is 0, the property keyword is not included. For example, $SYSTEM.License.KeyFileType(1) might return "FileType=InterSystems License Rev-A.1" while $SYSTEM.License.KeyFileType(0) would return "InterSystems License Rev-A.1". The default value of IncludeKeyword is 0.

◆ KeyVersion()

_.Library.String KeyVersion ( )

static

$SYSTEM.License.KeyVersion() returns the version from the FileType property of the [ConfigFile] section of the loaded license key.

For example, if the [ConfigFile] section containes "FileType=License 2013.1", $SYSTEM.License.KeyVersion() returns 2013.1.

◆ LUMaxConsumed()

_.Library.Integer LUMaxConsumed ( )

static

$SYSTEM.License.LUMaxConsumed() returns the maximum number of license units consumed at the local InterSystems IRIS instance since it started.

This value is the high water mark of license consumption on the local InterSystems IRIS instance.

◆ LUMaxConsumedReset()

_.Library.Integer LUMaxConsumedReset ( )

static

$SYSTEM.License.LUMaxConsumedReset([Argument]) resets the recorded peak levels of various measures of license use by setting the internal counters to the current usage level and returns the previously recorded maximum count.

The usage counts are local to the InterSystems IRIS instance and represent maximum usage since the instance started or the counter was last reset.

Arguments

No Argument: Resets maximum license units consumed as returned by $SYSTEM.License.LUMaxConsumed() and the maximum connection count as returned by $SYSTEM.License.MaxConnections() to the current usage levels. The previously recorded $SYSTEM.License.LUMaxConsumed() value is returned.
Argument = "Users": Resets maximum license units consumed as returned by $SYSTEM.License.LUMaxConsumed() to the current usage level. The previously recorded $SYSTEM.License.LUMaxConsumed() count is returned.
Argument = "Connections": Resets maximum concurrent connections, as returned by $SYSTEM.License.InstanceConnectionsMax() to the current usage level. The previously recorded $SYSTEM.License.InstanceConnectionsMax() is returned.
Argument = "CSPUsers": Resets maximum concurrent CSP Users, as returned by $SYSTEM.License.MaxCSPUsers() to the current usage level. The previously recorded $SYSTEM.License.MaxCSPUsers() is returned.
Argument = "Processes": Resets maximum concurrent licensed process count, as returned by $SYSTEM.License.ProcMaxConsumed() to the current usage level. The previously recorded $SYSTEM.License.ProcMacConsumed() is returned.
Argument = "CSPGrace": Resets maximum concurrent number of CSP sessions in the "grace" period, as returned by $SYSTEM.License.MaxCSPGrace() to the current usage level. The previously recorded $SYSTEM.License.MaxCSPGrace() is returned.
Argument = "*": Resets all maximum license use counts to the current usage counts. The previously recorded $SYSTEM.License.LUMaxConsumed() is returned.

◆ LUMinAvailable()

_.Library.Integer LUMinAvailable ( )

static

$SYSTEM.License.LUMinAvailable() returns the minimum number of license units available at the local InterSystems IRIS instance since it started.

This value is the low water mark of license availability on the local InterSystems IRIS instance.

◆ LicenseCount()

_.Library.Integer LicenseCount ( _.Library.String UserIdentifier )

static

$SYSTEM.License.LicenseCount() returns the number of License Units currently consumed on the local instance by the given UserIdentifier.

The return value is usually 0 if the UserIdentifier is not licensed or 1 if it is.
However, if the maximum number of connections has ever exceeded MAXCONNECTIONS (the maximum allowed number of concurrent connections for a single license) for this UserIdentifier, the system has transitioned to a mode of one license per connection for this UserIdentifier and the return value will be the current number of connections by UserIdentifier.

◆ LoadAppLicenseFile()

_.Library.Integer LoadAppLicenseFile	(	_.Library.String	FileName,
		_.Library.String	AppName
	)

static

$SYSTEM.License.LoadAppLicenseFile(FileName,SectionName)

Load a license for the named application into instance memory. The file is in standard .ini file format and the application license is contained in a section beginning with [SectionName], where 'SectionName' is the name of the application licensed by the section. The SectionName value is case sensitive and can contain as many as 47 alphanumeric characters. It cannot contain a period. Features licensed are authorized by properties in the application section represented as keyword=value pairs.
Keywords are case sensitive and can contain as many as 47 alphanumeric characters. The total length of keyword=value cannot exceed 1024 characters. Licensed items with a numeric value are counted by the license software (see TakeApplicationLicense() and ReturnApplicationLicense()). Licensed items with a text value can be retrieved with GetAppLicenseValue(AppName,FeatureKeyword). The entire application license can be retrieved with GetAppLicense(AppName,getvalues). An application license section can contain 16536 characters including a terminating NULL character appended internally to each keyword=value line.

Example application license section:

[MyApplication]
Concurrent Users=50
LabTech=20
Supervisor=3
Nurse=50
Modules=Lab, Radiology, Billing, Pharmacy 
Arguments:
FileName: file name, including path. Max 1024 characters.
AppName: application name, the section name containing the application license. Max 47 characters.

Return Values:
0 = success
1 = no file or no section or section is empty or malformed
2 = profile section too large
4 = cannot allocate (shared) memory for table;
5 = keyword or value too long
6 = Application name too long.

Example: $SYSTEM.License.LoadAppLicenseFile("c:\InterSystems\Licenses\MyIRIS.key","MyApplication")

◆ Login()

_.Library.Integer Login ( _.Library.String UserIdentifier )

static

$SYSTEM.License.Login(UserIdentifier) performs a license login.

To acquire a license for a particular connection, provide a UserIdentifier (String).
UserIdentifier can be an arbitrary identifier determined by the application, but it must uniquely identify the user connecting to InterSystems IRIS. The client IP address will be appended to the identifier provided separated by an "@" sign to form the complete license identifier. If the input string contains an '@' character, the string will be truncated and the client IP address wil be appended following the first '@' character. The UserIdentifier cannot contain the '|' character. If the '|' character is found, it will be replaced with the forward slash ('/') character. The total length of UserIdentifier can be no more than 64 characters including the '@' character and the IP address appended by the system. If the input UserIdentifier exceeds 64 characters, $SYSTEM.License.Login will return an ILLEGAL VALUE error.

This function will relinquish a license if the session/process is already holding one under a different identifier and it will obtain a new one on the behalf of the user ID provided.

If the MAXCONNECTIONS connection limit per user is exceeded, the usual transition to one-license-unit-per-connection will apply to this user identifier.

If a failure occurs because no additional license units are available, the session/process will revert to the original license state and the function will return 0. If the call is successful it will return a positive integer which is the number of connections currently associated with "UserIdentifier@ClientIP" (including the one just consumed).

◆ MaxBufferPool()

_.Library.Integer MaxBufferPool ( )

static

$$SYSTEM.License.MaxBufferPool() returns the maximum buffer pool size authorized by the active license key.

Zero indicates unlimited.

◆ MaxDB()

_.Library.Integer MaxDB ( _.Library.Boolean UserOnly )

static

$SYSTEM.License.MaxDB() returns the maximum number of Databases authorized by the active license key.

Zero indicates unlimited.

Passing 'UserOnly' = 1 will return the nuber of non-system Databases authorized (system "overhead" is subtracted).

◆ ProcAvailable()

_.Library.Integer ProcAvailable ( )

static

$SYSTEM.License.ProcAvailable returns the number of additional InterSystems IRIS User process licenses available on this InterSystems IRIS instance.

(Applicable only for license types that restrict the number of processes, i.e. 'Real Time' licenses.)

◆ ProcConsumed()

_.Library.Integer ProcConsumed ( )

static

$SYSTEM.License.ProcConsumed returns the number of InterSystems IRIS User process licenses currently in use on this InterSystems IRIS instance.

(Applicable only for license types that restrict the number of processes, i.e. 'Real Time' licenses.)

◆ ProcMinAvailable()

_.Library.Integer ProcMinAvailable ( )

static

$SYSTEM.License.ProcMinAvailable returns the minimum number of additional processes available at any time since the instance started.

(Applicable only with license types that restrict the number of processes.)

◆ PublicWebAppUser()

_.Library.Integer PublicWebAppUser ( )

static

$SYSTEM.License.PublicWebAppUser declares an application to be a public web application for the purpose of a Web Add-on license.

This system method requires that the active license key be a Real Time license or have the Web Add-on feature enabled. The return value is 1 on success, 0 on failure. Failure indicates the license key does not support this option. The PublicWebAppUser system method must be called from the OnStartSession method of the Session Events class defined for the CSP application as follows:

1) Create a subclass of the CSP.SessionEvents class and define a method to handle the OnStartSession event. Call $system.License.PublicWebAppUser() in the OnStartSession class method.

2) Define this class as the Event Class for the CSP application.

Management Portal -> System Administration -> Security -> Applications -> Web Applications

Enter the CSP.SessionEvents subclass in the " Event Class:" box.

3) Insure that "Unauthenticated" is checked for "Allowed Authentication Methods".

Example: The following code could be placed in ClassMethod OnStartSession of the class extending CSP.SessionEvents that acts as the session event handler for the public application.

try { s x=$system.License.PublicWebAppUser() } catch { /* log error */ } q $$$OK

◆ ReadDurationCounts()

_.Library.List ReadDurationCounts ( )

static

$SYSTEM.License.ReadDurationCounts() returns the number of times a logout occurred within the time indicated by the corresponding ReadDurationValues.

The values are returned as a list. $ListLength is currently 6.

◆ ReadDurationValues()

_.Library.List ReadDurationValues ( )

static

$SYSTEM.License.ReadDurationValues() returns the upper limit in seconds each histogram bucket represents.

The values are returned as a list with 5 elements. The sixth value is not provided because there is no upper limit. Returning time bucket values in a list permits the number of buckets and their values to be changed in the future with little impact on the code.

◆ ReturnApplicationLicense()

_.Library.Status ReturnApplicationLicense	(	_.Library.String	AppName,
		_.Library.String	FeatureKeyword,
		_.Library.Integer	Released,
		_.CSP.Session	session
	)

static

$SYSTEM.License.ReturnApplicationLicense(AppName,FeatureKeyword,.released,session)

Return (release) a license unit for an application license and feature. The license feature value must be numeric in the application license section. Releases the license resource associated with the licensed user Id of the current process, or the session license Id in the case of CSP.

Arguments:
AppName: The 'Company.Application' value from the section name in iris.key for protected application license sections, or the name of the unprotected application license section loaded with LoadAppLicenseFile().

FeatureKeyword: The application feature keyword being released. If the FeatureKeyword is omitted, the default value is "Concurrent Users".

Released: Returns 1 if the license was released, 0 if the license was not held.

session: The CSP session Id this application license should be taken for if the application license is being taken for a session, not the current process. If this argument is not present and session is defined and is a CSP.Session object, then the application license will be taken for the session object. If neither the session argument nor the session variable is defined, the license is taken for the current process.

Return value: $$$OK, or error status.
An error status containing an INVALID ARGUMENT error will be returned if no license has been loaded for AppName.

Example: $SYSTEM.License.ReturnApplicationLicense("MyCompany.MyApp","MyAppFeature"[[,.Released[, session]])

◆ SetConnectionLimit()

_.Library.Integer SetConnectionLimit ( _.Library.Integer MaxCon )

static

$SYSTEM.License.SetConnectionLimit establishes the maximum number of connections permitted per user on this instance.

This enables a system administrator to prevent a user from making so many connections to a InterSystems IRIS instance that they consume all available license units. Calling $SYSTEM.License.SetConnectionLimit($SYSTEM.License.MaxConnections()) permits a user to make the maximum connections permitted but prevent transitioning to the license unit per connection state, insuring the user will consume no more than one license unit. A zero argument removes the limit. The failure to obtain a license will be indicated in the normal way. For example, a call to $system.License.Login() will return zero (0) while a failure to log in to a new terminal connection will receive a <LICENSE LIMIT EXCEEDED> error. However, these license failures will not be reported in the console log. The method returns the former maximum value.

The limit applies only to the local instance. If an InterSystems IRIS license is shared among several instances it is still possible to exceed $SYSTEM.License.MaxConnections() over all instances. This can be avoided by setting the limit low enough on each instance that the combined connections to all instances will be unlikely to exceed $SYSTEM.License.MaxConnections().

$SYSTEM.License.SetConnectionLimit reqires access to the Admin Manage resource. It is suggested that customers call this API from SYSTEM^ZSTART.

◆ SetUserLimit()

_.Library.Integer SetUserLimit ( _.Library.Integer MaxLU )

static

$SYSTEM.License.SetUserLimit establishes the maximum number of license units that this InterSystems IRIS instance will consume.

This permits a system manager to prevent a InterSystems IRIS instance from consuming all the license units in a key shared among multiple InterSystems IRIS instances. The Method returns the former maximum value. In the absence of a call to $SYSTEM.License.SetUserLimit(max) a InterSystems IRIS instance may consume all available license units.

Reqires access to the Admin Manage resource.

◆ ShowCounts()

ShowCounts ( )

static

Display Local view of license use.

This report summarizes information derived from the current InterSystems IRIS instance's local license utilization database.

Total Authorized LU: license units authorized by the installed license file.
Current Available LU: License units available at the local InterSystems IRIS instance.
Minimum Available LU: Minimum number of license units availible since the local instance started.
Current Users active: Number of distinct users logged in to the local instance. May be less than the difference between total authorized and current available license units if one or more users have exceeded MaxConnections.
Maximum Users active: Maximum number of distinct users logged in to the local instance at any time since it started.
Current CSP Users active: Current number of CSP sessions consuming license units at the local InterSystems IRIS instance.
Maximum CSP Users active: Maximum number of CSP sessions consuming license units at any time since the local InterSystems IRIS instance started.
Current CSP Sessions in grace period: Current number of CSP sessions in grace period on the local InterSystems IRIS instance.
Maximum CSP Sessions in grace period: Maximum number of CSP sessions in grace period at any time since the local InterSystems IRIS instance started.

This report is identical to the report produced by counts^SYS.LICENSE. It presents the results of the SYSTEM.License.Counts query.

◆ ShowServer()

ShowServer ( )

static

Display current active license Server address and port.

Note: Not applicable with a Single-Server key.
This report is identical to the report produced by ShowServer^SYS.LICENSE.

◆ ShowSummary()

ShowSummary ( )

static

Display Summary of License Server Database.

Note: Not applicable with a Single-Server key.

Displays a summary of license use for the current InterSystems IRIS instance's active license key. The report displays license usage data obtained both from the license server and from the local InterSystems IRIS instance.

The distributed license use section summarizes license use by all InterSystems IRIS instances that share the key. The license server is the source of this information.

Current License Units Used: current number of license consumed by all InterSystems IRIS instances sharing this key.
Maximum License Units Used: maximum number of license consumed by all InterSystems IRIS instances sharing this key at any time since the license server started.
License Units Authorized: number of license units authorized by the installed license key file.

The local license use section summarizes license use by the InterSystems IRIS instance where the report is run. The source of this section is the local InterSystems IRIS instance's internal license use tables.

Current Connections: The current number of connections (license logins) to the local InterSystems IRIS instance.
Maximum Connections: The maximum number of connections (license logins) to the local InterSystems IRIS instance since it started.
Current Users: The current number of license units consumed on the local InterSystems IRIS instance. Note that this item displays license units, not distict users.
Maximum Users: The maximum number of license units consumed on the local InterSystems IRIS instance since it started.

This report is identical to the report produced by ShowSummary^SYS.LICENSE. It presents the results of the SYSTEM.License.ShowSummary query.

◆ TakeApplicationLicense()

_.Library.Status TakeApplicationLicense	(	_.Library.String	AppName,
		_.Library.String	FeatureKeyword,
		_.Library.Integer	Count,
		_.CSP.Session	session
	)

static

$SYSTEM.License.TakeApplicationLicense(AppName,FeatureKeyword,.count,session)

Take (consume) a license unit for a named application and feature. The license feature value must be numeric in the loaded application license section. The InterSystems IRIS license user Id of the current process (or in the case of CSP, the session license Id) will be the user identifier associated with the application license consumed.

Arguments:

AppName: The 'Company.Application' value from the section name in iris.key for protected application license sections, or the name of the unprotected application license section loaded with LoadAppLicenseFile().

FeatureKeyword: The application keyword being consumed. If the FeatureKeyword is omitted, the default value is "Concurrent Users".

Count: ByRef argument to receive count of the number of times this user has now taken this application/keyword license.

session: The CSP session Id this application license should be taken for if the application license is being taken for a session, not the current process. If this argument is not present, a session variable is defined and is a CSP.Session object, then the application license will be taken for the session object. If neither the session argument nor the session variable is defined, the license is taken for the current process.

Return value: $$$OK, or error status.
An error status containing an INVALID ARGUMENT error will be returned if AppName is not licensed.
An error status, ERROR #5915: Cannot allocate a license, if the feature is not licensed or its capacity is exhausted.

An application license can be returned with the $SYSTEM.License.ReturnApplicationLicense(AppName, FeatureKeyword[[, .Count[, session]]) method. All application licenses taken for a process or a CSP session will be returned automatically when the process exits or the CSP session terminates.

Example: $SYSTEM.License.TakeApplicationLicense("MyCompany.MyApp","MyAppFeature",.NewCountTaken)

◆ Upgrade()

_.Library.String Upgrade ( )

static

Upgrade to a license (iris.key file) that has been copied to the mgr directory.

In some cases the license key will not be upgraded or may be incompletely upgraded. Upgrades may not activate all additional license units if they are unable to allocate sufficient memory from the shared memory heap. Upgrades to a key with fewer license units will be deferred until the InterSystems IRIS instance is restarted. Upgrades to or from a "Power Unit" key will be deferred until the InterSystems IRIS instance is restarted.
Return value is 1 on success, "0|Reason for failure" on failure.
The failure message may refer you to messages.log for additional information.

◆ UserNameLicensing()

_.Library.Integer UserNameLicensing ( _.Library.Integer OnOffState )

static

Modify how the License User Identifier is specified.

By default, the client IP address is used to identify a user to the InterSystems IRIS license tracking subsystem. If InterSystems IRIS is installed with the normal security level, each process will be have a user identity ($username).
The $SYSTEM.License.UserNameLicensing system method can be called to make the InterSystems IRIS license subsystem use $username as the license user identifier. The client IP address will be appended to $Username separated by an "@" sign to form the complete license identifier.

$SYSTEM.License.UserNameLicensing modifies the system state. It can be called from SYSTEM^ZSTART to enable user name licensing at instance startup.

$SYSTEM.License.UserNameLicensing(1) enables $username based licensing and returns the previous state.
$SYSTEM.License.UserNameLicensing(0) disables $username based licensing and returns the previous state.
$SYSTEM.License.UserNameLicensing() returns the current state.

$SYSTEM.License.UserNameLicensing(0) returns an UNLICENSED error if called with RealTime or Web Add-On keys, because these license types require UserNameLicensing.

$SYSTEM.License.UserNameLicensing(1) returns an UNLICENSED error if called with a 'Core Capacity' License Type, as this combination is invalid.

Static Public Member Functions

Detailed Description

class(%SYSTEM.License).ClassMethodName() syntax. The special $system object methods can also be accessed in this way.

Member Function Documentation

◆ ActiveServerCount()

class(%SYSTEM.License).ClassMethodName() syntax. The special $system object methods can also be accessed in this way.

◆ ApplicationServerLogin()

Class(%SYSTEM.License).ApplicationServerLogin(AppName, Keyword, Status) returns 1 if the number of instances using the

◆ CKEY()

◆ CheckAppLicenseUsed()

◆ CheckKeyForUpgrade()

◆ CheckNewKey()

◆ ClearDurationCounts()

◆ ConnectionCount()

◆ Decode()

◆ DistributedMaxReset()

◆ DumpKey()

◆ DumpKeys()

◆ DumpLocalAll()

◆ DumpLocalInUse()

◆ DumpLocalPID()

◆ DumpServer()

◆ DumpServers()

◆ GetAppLicense()

◆ GetAppLicenseFree()

◆ GetAppLicenseMaxUsed()

◆ GetAppLicenseMinimum()

◆ GetAppLicenseUsed()

◆ GetAppLicenseValue()

◆ GetAppNames()

◆ GetConnectionLimit()

◆ GetFeature()

◆ GetProcessAppsTaken()

◆ GetUserId()

◆ GetUserLimit()

◆ IsAppLicensed()

class(%SYSTEM.License).IsAppLicensed(AppName) returns 1 if the application named AppName is licensed, otherwise 0.<br>

class(%SYSTEM.License).IsAppLicensed(AppName,FeatureKeyword) returns 1 if the feature named FeatureKeyword is licensed for the application named AppName, otherwise 0.<br>

◆ IsPendingActivation()

class(%SYSTEM.License).IsPendingActivation() returns 1 if the iris.key file in the "mgr" directory is valid but is not the active license key.<br><br>

class(%SYSTEM.License).IsPendingActivation() returns 0 if the iris.key file in the "mgr" directory is the active license key or if no iris.key file exists in the "mgr" directory or if the key in "mgr" is invalid.

◆ IsValidKey()

◆ KeyCPUsEnforced()

◆ KeyCPUsLicensed()

◆ KeyCoresEnforced()

◆ KeyCoresLicensed()

◆ KeyExpirationDate()

◆ KeyFileType()

◆ KeyVersion()

◆ LUMaxConsumed()

◆ LUMaxConsumedReset()

◆ LUMinAvailable()

◆ LicenseCount()

◆ LoadAppLicenseFile()

◆ Login()

◆ MaxBufferPool()

◆ MaxDB()

◆ ProcAvailable()

◆ ProcConsumed()

◆ ProcMinAvailable()

◆ PublicWebAppUser()

◆ ReadDurationCounts()

◆ ReadDurationValues()

◆ ReturnApplicationLicense()

◆ SetConnectionLimit()

◆ SetUserLimit()

◆ ShowCounts()

◆ ShowServer()

◆ ShowSummary()

◆ TakeApplicationLicense()

◆ Upgrade()

◆ UserNameLicensing()