%SYSTEM.License
abstract class %SYSTEM.License extends %SYSTEM.Help [ Final ]
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.
Method Inventory
- ActiveServerCount()
- ApplicationServerLogin()
- CKEY()
- CSPGrace()
- CSPUsers()
- CheckAppLicenseUsed()
- CheckKeyForUpgrade()
- CheckNewKey()
- ClearDurationCounts()
- ConnectionCount()
- Decode()
- DecodeAuth()
- DeferUserIdentification()
- DistributedMaxReset()
- DumpKey()
- DumpKeys()
- DumpLocalAll()
- DumpLocalInUse()
- DumpLocalPID()
- DumpServer()
- DumpServers()
- GetAppLicense()
- GetAppLicenseFree()
- GetAppLicenseMaxUsed()
- GetAppLicenseMinimum()
- GetAppLicenseUsed()
- GetAppLicenseValue()
- GetAppNames()
- GetConnectionLimit()
- GetFeature()
- GetKeyInvalidReason()
- GetKeyStatus()
- GetProcessAppsTaken()
- GetUserId()
- GetUserLimit()
- InstanceConnections()
- InstanceConnectionsMax()
- IsAppLicensed()
- IsPendingActivation()
- IsValidKey()
- KeyAuthorizationKey()
- KeyCPUsEnforced()
- KeyCPUsLicensed()
- KeyCoresEnforced()
- KeyCoresLicensed()
- KeyCustomerName()
- KeyEnforcedUnits()
- KeyExpirationDate()
- KeyFeatures()
- KeyFileType()
- KeyLicenseCapacity()
- KeyLicenseType()
- KeyLicenseUnits()
- KeyMachineID()
- KeyOrderNumber()
- KeyPlatform()
- KeyProduct()
- KeyServer()
- KeyVersion()
- LUAvailable()
- LUConsumed()
- LUMaxConsumed()
- LUMaxConsumedReset()
- LUMinAvailable()
- LicenseCount()
- LoadAppLicenseFile()
- Login()
- MaxBufferPool()
- MaxCSPGrace()
- MaxCSPUsers()
- MaxConnections()
- MaxDB()
- MaxECPServers()
- NetworkEnabled()
- ProcAvailable()
- ProcConsumed()
- ProcMaxConsumed()
- ProcMinAvailable()
- PublicWebAppUser()
- PublicWebAppUserCount()
- PublicWebAppUsersMax()
- ReadDurationCounts()
- ReadDurationValues()
- ReturnAllCSPApps()
- ReturnApplicationLicense()
- SetConnectionLimit()
- SetUserLimit()
- ShowCounts()
- ShowServer()
- ShowSummary()
- TakeApplicationLicense()
- Upgrade()
- UserNameLicensing()
Methods
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.
This report is identical to those produced by CKEY^%SYS.LICENSE and ^CKEY.
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")
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.
- 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)
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.
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.
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 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.
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.
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 is identical to ldumppid^%SYS.LICENSE. It presents the results of the %SYSTEM.License.ProcessList query.
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.
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.
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() 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")
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() 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")
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")
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")
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.
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
An INVALID ARGUMENT error is returned if no application license is loaded for "AppName".
Example: $SYSTEM.License.GetProcessAppsTaken($J,"MyCompany.MyApp")
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.
##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")
##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.
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.
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.
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")
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).
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
Called by the CSP Daemon when it deletes a session object.
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]])
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.
Reqires access to the %Admin Manage resource.
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.
Note: Not applicable with a Single-Server key.
This report is identical to the report produced by ShowServer^%SYS.LICENSE.
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.
- 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.
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)
Return value is 1 on success, "0|Reason for failure" on failure.
The failure message may refer you to messages.log for additional information.
$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.
Queries
The Address field contains the IP address of the host where the instance is running.
The Instance field contains the instance name.
The OrderNumber field contains the OrderNumber field of the License key the Instance is using.
The data source is the license server, and this query will open a TCP port to receive data from the license server.
The UserId field contains the License User Id of the entity consuming one or more license units.
The LicenseUnits field contains the number of license units consumed. This can be a number, or the string "shr", indicating that the connection shares a license unit with another connection by the same License UserId.
The Connections field contains the number of connections the UserId entity has made to the the InterSystems IRIS server.
The ServerIP field contains the address of the the InterSystems IRIS server to which the connection was made.
The Instance field contains the name of the InterSystems IRIS instance to which the connection was made.
The data source is the license server, and this query will open a TCP port to receive data from the license server.
It accepts two parameters:
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().
ShowCounts: If 1, the taken keywords will be returned as KeywordName=TimesTaken in the AppLicenses field. If zero, only the KeywordName will be returned for taken keywords.
The UserId field contains the License Login UserId. The Type field contains the login type and is one of the following:
- User - Regular user login
- CSP - Cache Server Page login
- Mixed - Regular user plus Cache Server Page login
- Grace - Logged out CSP session waiting for grace period to expire.
MaxCon is the maximum number of concurrent connections to this InterSystems IRIS instance by the user represented by UserId.
CSPCon is the number of CSP sessions open to this InterSystems IRIS instance by the user represented by UserId.
LU is the number of License Units consumed on this InterSystems IRIS instance by the user represented by the UserId.
Active is the time in seconds the UserId has been logged in to this InterSystems IRIS instance.
Grace is the amount of time this license unit will remain in the grace period if all connections were closed immediately.
AppLicenses is a list of Application license features held by the UserId. The data source is the local InterSystems IRIS instance.
- The UserId field contains the License User Id of the entity consuming one or more license units.
- The LicenseUnits field contains the number of license units consumed. This can be a number, or the string "shr", indicating that the connection shares a license unit with another connection by the same License UserId.
- The Connections field contains the number of connections the UserId entity has made to the the InterSystems IRIS server.
- The ServerIP field contains the address of the the InterSystems IRIS server to which the connection was made.
- The Instance field contains the name of the InterSystems IRIS instance to which the connection was made.
- The ApplicationUse field contains the applications taken by the connection formatted as AppName,Feature;AppName,Feature;...;AppName,Feature.
- The UserId field contains the License User Id of the entity consuming one or more license units.
- The LicenseUnits field contains the number of license units consumed. This can be a number, or the string "shr", indicating that the connection shares a license unit with another connection by the same License UserId.
- The Connections field contains the number of connections the UserId entity has made to the the InterSystems IRIS server.
- The ServerIP field contains the address of the the InterSystems IRIS server to which the connection was made.
- The Instance field contains the name of the InterSystems IRIS instance to which the connection was made.
- Instance License Use: Text describing meaning of row data.
- License Units: Value (count) described by text.
- Capacity Field: Licensed capacity name.
- License Units: Licensed capacity value.
The 'flag' argument is for internal use only.
- Field: Text to the left of the '=' sign in the [License] section of the license key file.
- Value: Value to the right of the '=' sign.
- 1 Return main license section [License].
- 2 Return application license sections.
- 3 Return all license sections.
The data source is the local InterSystems IRIS instance.
Note: Not applicable with a Single-Server key.
The data source is the local InterSystems IRIS instance.
- The LicenseCapacity field is the data to the right of "LicenseCapacity=" in the key file.
- The CustomerName field is the data to the right of "CustomerName=" in the key file.
- The OrderNumber field is the data to the right of "OrderNumber=" in the key file.
- The ExpirationDate field is the data to the right of "ExpirationDate" in the key file.
- The AuthorizationKey field is the data to the right of "AuthorizationKey" in the key file.
- The MachineID field is the data to the right of "MachineID=" in the key file.
- The LicenseID field is the data to the right of "LicenseID=" in the key file.
The Duration field contains a duration of license unit consumption in seconds. The duration field is text suitable for display, not a number. The final row will be prefixed with a ">" sign to indicate that the duration of the row has no upper limit
The Count field contains the number of times a license unit was consumed for less than the corresponding Duration field. The Count field is not cumulative.
The data source is the local InterSystems IRIS instance.
Example:
;1) run query %SYSTEM.License.LoginDuration ;2) write the results to the current output device. Set rset=##class(%Library.ResultSet).%New("%SYSTEM.License:LoginDuration") If rset="" Write !,"Create Query failed" d DisplayError^%apiOBJ(%objlasterror) Quit Set status=rset.Execute() If $$$ISERR(status) Write !,"Execute Query failed:" Do DisplayError^%apiOBJ(status) Quit Set colcnt=rset.GetColumnCount() For i=1:1:colcnt Set colname(i)=rset.GetColumnName(i) Write !! For i=1:1:colcnt Write $j(colname(i),15)," " while rset.Next() { Write ! For i=1:1:colcnt Write $j(rset.GetData(i),15)," " } ;Results look like this: ; ;Testing %SYSTEM.License.LoginDuration query. ; Duration Count ; 1 0 ; 15 7548 ; 60 7261 ; 900 260 ; 3600 0 ; > 3600 0
The PID is the operating system Process Identifier.
The DisplayPID is display form for PID, it is hexadecimal value in VMS.
The Process field is one of the following process login types:
- System - system processes that do not consume a license unit.
- User - Regular user (terminal, ODBC, Cache Direct) login.
- CSP - Cache Server Pages server process. A CSP server process does not maintain an association with an internal license table entry. The association is rather with the session. For this reason, information regarding number of connections, and license units is not available for CSP processes. Use the UserList query to obtain this information for CSP sessions.
- Diagnostic - Process is logged in to InterSystems IRIS with the "-B" command line argument and is using the diagnostic license unit.
- Server - A server process (eg the COMMCTRL process) which does not consume a license unit, but which creates jobs which do consume license units.
- Pending - A process for which license acquisition is pending. Can occur when deferred license acquisition is in effect.
The Type field contains the License login type and is one of the following:
- User - Regular user login
- CSP - Cache Server Page login
- Mixed - Regular user plus Cache Server Page login
- Grace - Logged out CSP session waiting for grace period to expire.
MaxCon is the maximum number of concurrent connections to this InterSystems IRIS instance by the user represented by UserId.
CSPCon is the number of CSP sessions open to this InterSystems IRIS instance by the user represented by UserId.
LU is the number of License Units consumed on this InterSystems IRIS instance by the user represented by the UserId.
Active is the time in seconds the UserId has been logged in to this InterSystems IRIS instance.
Grace is the amount of time this license unit will remain in the grace period if all connections were closed immediately.
The data source is the local InterSystems IRIS instance.
This represents the view of distributed and local license use maintained by the license server. Local and distributed Authorized, Current, and Maximum license unit usage levels are returned. Current and Maximum connections to the local InterSystems IRIS instance are returned.
Note: Not applicable with a Single-Server key.
The data source is both the local InterSystems IRIS instance and the license server.
Example:
;1) run query %SYSTEM.License.Summary and place results in: ; headings(c) = heading_text for column c ; data(r,c) = data for row r, column c ;2) write the results to the current output device. s Rset=##class(%ResultSet).%New("%SYSTEM.License.Summary") if 'Rset s status="Could not form query %SYSTEM.License.Summary." w !,status q s r=Rset.Execute() if r { s ncol=Rset.GetColumnCount() f i=1:1:ncol s headings(i)=Rset.GetColumnName(i) s nrec=0 While (Rset.Next()) { s nrec=nrec+1 s ncol=Rset.GetColumnCount() f i=1:1:ncol s data(nrec,i)=Rset.GetData(i) } d Rset.Close() s status=nrec_" entries added to array" } i 'r s status="Could not execute query %SYSTEM.License.Summary." w !,status q w !!,headings(1),?40,headings(2),?60,headings(3),! for i=1:1:nrec w !,data(i,1),?40,data(i,2),?60,data(i,3) q
The UserId field contains the License Login UserId. The Type field contains the login type and is one of the following:
- User - Regular user login
- CSP - Cache Server Page login
- Mixed - Regular user plus Cache Server Page login
- Grace - Logged out CSP session waiting for grace period to expire.
MaxCon is the maximum number of concurrent connections to this InterSystems IRIS instance by the user represented by UserId.
CSPCon is the number of CSP sessions open to this InterSystems IRIS instance by the user represented by UserId.
LU is the number of License Units consumed on this InterSystems IRIS instance by the user represented by the UserId.
Active is the time in seconds the UserId has been logged in to this InterSystems IRIS instance.
Grace is the amount of time this license unit will remain in the grace period if all connections were closed immediately.
The data source is the local InterSystems IRIS instance.
The UserId field contains the License Login UserId. The Type field contains the login type and is one of the following:
- User - Regular user login
- CSP - Cache Server Page login
- Mixed - Regular user plus Cache Server Page login
- Grace - Logged out CSP session waiting for grace period to expire.
MaxCon is the maximum number of concurrent connections to this InterSystems IRIS instance by the user represented by UserId.
CSPCon is the number of CSP sessions open to this InterSystems IRIS instance by the user represented by UserId.
LU is the number of License Units consumed on this InterSystems IRIS instance by the user represented by the UserId.
Active is the time in seconds the UserId has been logged in to this InterSystems IRIS instance.
Grace is the amount of time this license unit will remain in the grace period if all connections were closed immediately.
The data source is the local InterSystems IRIS instance.