Class Reference
%SYSTEM.License
| Server:basexml |
| Instance:SOAXML |
| User:UnknownUser |
 |
|||
| Private Storage | |||
The %SYSTEM.License class provides an interface to the Cache 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 Cache instance can sometimes lead to apparent inconsistencies.
These inconsistencies can be explained by understanding the operation of the license server.
Each Cache instance maintains a database of its license use and independently controls connections to itself.
When multiple instances share a Cache 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 Cache instance's view.
License server and Cache 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.
|
|
|
|
|
|
Display the active license key to the current device.
The fields of the [License] section of the installed cache.key file are displayed followed by a brief accounting of license usage, including:
License usage levels are obtained from the current Cache instance.
- 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.
$SYSTEM.License.CSPGrace() returns the current number of CSP sessions in the grace period.
$SYSTEM.License.CSPUsers() returns the current number of CSP users.
$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.
$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 and display the capabilities encoded in the AuthorizationKey field of the active License Key.
Decode and display the capabilities encoded in the AuthorizationKey field of a License Key provided as the 'key' argument.
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 Cache 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 Cache 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 Cache instance is reported in these columns:
The report displays the fields of the license key and summarizes the number of servers (Cache 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.
- Client: License Id for the connection from a client to this Cache instance.
- LU: Number of license units consumed by connections from this client to this Cache instance.
- Connections: Number of connections from this client to this Cache instance.
- Server: Address of host where the Cache instance is running.
- Instance: Name of the Cache instance to which the client is connected.
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 Cache instances which share each license key under the license server's control. For true reporting and as a requirement of the Cache license agreement, each Cache instance that uses a key must configure the same set of license servers.
License use by each client (License Id) connected to each Cache instance is reported in these columns:
The report displays the fields of each license key and summarizes the number of servers (Cache 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.
- Client: License Id for the connection from a client to this Cache instance.
- LU: Number of license units consumed by connections from this client to this Cache instance.
- Connections: Number of connections from this client to this Cache instance.
- Server: Address of host where the Cache instance is running.
- Instance: Name of the Cache instance to which the client is connected.
Dump all the local Cache 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:
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.
- 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.
Dump the local Cache 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:
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.
- 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.
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:
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.
- 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.
Dump License Server database for this server.
Note: Not applicable with a Single-Server key. This report presents license usage by the current Cache 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:
The report summarizes total connections and license units consumed by clients attached to this Cache instance and the total number of license units shared by clients on this Cache server instance with connections by the same client to other Cache server instances. This report is identical to that produced by dumpserver^%SYS.LICENSE.
- 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.
Dump License Server database for all servers.
Note: Not applicable with a Single-Server key.
This report presents license usage by each Cache 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:
The report summarizes total connections and license units consumed by clients connected to each Cache instance and the number of license units shared by clients connected to this Cache server instance with connections from the same client to other Cache server instances. A combined grand total of connections and license units consumed by all Cache server instances served by the license server is reported. This report is identical to that produced by dumpservers^%SYS.LICENSE.
- 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.
$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.
Example: "kw1=value1"_$c(0)_"kw2=value2"_$c(0)_..._"kwN=valueN"_$c(0)_$c(0)
$SYSTEM.License.GetAppLicenseFree(AppName,Keyword) retrieves the number of free license units associated with an application license feature keyword. GetAppLicenseFree() is only meaningful where the value associated with the keyword is numeric.
Example: $SYSTEM.License.GetAppLicenseFree("MyApp","MyAppFeature")
$SYSTEM.License.GetAppLicenseMin(AppName,Keyword) retrieves the minimum number of free license units associated with an application license keyword. GetAppLicenseMin() is only meaningful where the value associated with the keyword is numeric.
Example: $SYSTEM.License.GetAppLicenseMin("MyApp","MyAppFeature")
$SYSTEM.License.GetAppLicenseValue(AppName,Keyword) retrieves the value associated with an application license keyword.
Example: $SYSTEM.License.GetAppLicenseValue("MyApp","MyAppFeature")
$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 license
1) Ensemble
2) Shadow add on
3) BI user (runtime)
4) BI development
5) HealthShare
6) BitTrakCare
7) IPNeutral
8) DeepSeeRun
9) DeepSeeAnalyze
10) DeepSeeModel
11) iKnow
12) HealthShare Foundation
13) C-Type license
14) DeepSee Visual Reporting Execute
15) ExtremeNoUserLimit
16) DeepSee Visual Reporting Format Definition
17) DeepSee Visual Reporting Data Definition
Fetch string describing the reason the key is invalid or in a troubled state.
Fetch license key status: Valid, Invalid, or Troubled (expiring).
$SYSTEM.License.GetUserId() returns the License User Identifier (if any) associated with the currently executing session/process. It is possible that the value of UserIdentifier is "", which indicates that the session/process is running in degraded state (as will be the case when no license has been taken out automatically for the session/process by Caché).
$SYSTEM.License.GetUserId(PID) ) returns the License User Identifier associated with the process with the input Process Id.
$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.
$System.License.LIC_InstanceConnections() - return current count of connections to instance.
$System.License.LIC_InstanceConnectionsMax() - return maximum concurrent connections to instance since it restarted or the maximum was reset.
##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.
The license may have been loaded as part of the cache.key file or separately using $system.License.LoadAppLicenseFile()
$SYSTEM.License.KeyAuthorizationKey() returns the AuthorizationKey field in the active key.
$SYSTEM.License.KeyCPUsEnforced() 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.
$SYSTEM.License.KeyCPUsLicensed() returns the number of Cores authorized by the active key.
$SYSTEM.License.KeyCustomerName() returns the active key CustomerName field.
$SYSTEM.License.KeyEnforcedUnits() returns the number of license units enforced by the active key.
$SYSTEM.License.KeyExpirationDate() returns the active key expiration date as an integer, $H date value. Use $ZDATE to convert this to readable form.
$SYSTEM.License.KeyFeatures() returns the Features portion of the Authorization field in the active key.
$SYSTEM.License.KeyLicenseCapacity() returns the active key LicenseCapacity field.
$SYSTEM.License.KeyLicenseType() returns the active key license type (example: Concurrent User).
$SYSTEM.License.KeyLicenseUnits() returns the number of license units authorized by the active key.
$SYSTEM.License.KeyMachineID() returns the contents of the MachineID field in the active key.
$SYSTEM.License.KeyOrderNumber() returns the active key order number.
$SYSTEM.License.KeyPlatform() returns the active key licensed platform.
$SYSTEM.License.KeyProduct() returns the active key product (example: Enterprise).
$SYSTEM.License.KeyServer() returns the active key server type licensed (Single or Multi).
$SYSTEM.License.LUAvailable() returns number of license units currently available at the local Cache instance.
$SYSTEM.License.LUConsumed() returns number of license units currently consumed at the local Cache instance.
$SYSTEM.License.LUMaxConsumed() returns the maximum number of license units consumed at the local Cache instance since it started. This value is the high water mark of license consumption on the local Cache instance.
$SYSTEM.License.LUMaxConsumedReset() Resets the maximum number of license units consumed so it is equal to the current number of license units consumed and returns the previous maximum number of license units consumed at the local Cache instance since it started or the counter was last reset.
Arguments
- No Argument: Maximum License units, LUMaxConsumed(), and connection counts, MaxConnections() are reset to current counts. LUMaxConsumed() is returned.
- Augument = "Users": Maximum License units consumed, as returned by LUMaxConsumed(), is reset to current use count. LUMaxConsumed() is returned.
- Augument = "Connections": Maximum concurrent connections, as returned by InstanceConnectionsMax(), is reset to current connection count. InstanceConnectionsMax() is returned.
- Augument = "CSPUsers": Maximum concurrent CSP Users, as returned by MaxCSPUsers(), is reset to current CSP user count. MaxCSPUsers() is returned.
- Augument = "Processes": Maximum concurrent licensed process count, as returned by ProcMaxConsumed(), is reset to current process count. ProcMacConsumed() is returned.
- Augument = "CSPGrace": Maximum concurrent number of CSP sessions in "grace" period, as returned by MaxCSPGrace(), is reset to current process count. MaxCSPGrace() is returned.
- Augument = "*": All maximum license counts are reset to the current counts. LUMaxConsumed() is returned.
$SYSTEM.License.LUMinAvailable() returns the minimum number of license units available at the local Cache instance since it started. This value is the low water mark of license availability on the local Cache instance.
$SYSTEM.License.LoadAppLicenseFile(FileName,AppName)
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 [appname]. The AppName value is case sensitive and can contain as many as 47 alphanumeric characters. Items licensed are contained in the section in keyword=value pairs. Keywords are case sensitive and can contain as many as 47 alphanumeric characters. Use of licensed items with a numeric value can be 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:
[YourApplication]
Concurrent Users=50
LabTech=20
Supervisor=3
Nurse=50
Modules=Lab, Radiology, Billing, Pharmacy
Arguments:
file: file name, including path. Max 1024 characters.
appnaname: application name>. Max 47 characters.
$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 Cache. 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 total length of UserIdentifier and the appended IP address can be no more than 64 characters. If it is out of this range $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).
$$SYSTEM.License.MaxBufferPool() returns the maximum buffer pool size authorized by the active license key. Zero indicates unlimited.
$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.
$SYSTEM.License.MaxCSPUsers() returns the maximum number of concurrent CSP users since the instance started or the CSPUsers maximum counter was reset.
$SYSTEM.License.MaxConnections() returns the maximum number of connections a user can make while consuming one license unit.
$SYSTEM.License.MaxDB() returns the maximum number of non-system Databases authorized by the active license key. Zero indicates unlimited.
$SYSTEM.License.MaxECPServers() returns the maximum number of ECP servers authorized by the active license key.
$SYSTEM.License.NetworkEnabled() returns 1 if the Cache license key enables ECP, 0 if it doesn't.
$SYSTEM.License.ProcAvailable returns the number of additional processes that are authorized to be started in the current Cache instance. (Applicable only with license types that restrict the number of processes.)
$SYSTEM.License.ProcConsumed returns the number of Cache User processes currantly running in the current Cache instance.
$SYSTEM.License.ProcMaxConsumed returns the maxumum number of Cache User processes running concurrently since the instance started.
$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.)
$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 have the Web Add-on feature enabled. 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.
SMP -> Home > CSP Applications > Edit CSP Application
Enter the %CSP.SessionEvents in the " Event Class:" box.
3) Insure that "Unauthenticated" is checked for "Allowed Authentication Methods".
Example implementation:Class Sample.SessionEvents Extends %CSP.SessionEvents { ClassMethod OnStartSession() { d $zu(9,"","OnStartSession()") ;debug statement try { s x=$system.License.PublicWebAppUser() } catch { /* log error */ } q $$$OK } }
$SYSTEM.License.PublicWebAppUserCount returns the current number of public web application connections active.
$SYSTEM.License.PublicWebAppUsersMax() returns the maximum number of public web application connections active at any one time.
$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.
$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.
$System.License.ReturnAllCSPApps(SessionId)
$SYSTEM.License.ReturnApplicationLicense(AppName,FeatureKeyword)
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 name of the 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.
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.
$SYSTEM.License.SetUserLimit establishes the maximum number of license units that this Cache instance will consume. This permits a system manager to prevent a Cache instance from consuming all the license units in a MultiServer key shared among multiple Cache instances. The Method returns the former maximum value. In the absence of a call to $SYSTEM.License.SetUserLimit(max) a Cache instance may consume all available license units.
Reqires access to the %Admin Manage resource.
Display Local view of license use.
This report summarizes information derived from the current Cache instance's local license utilization database.
- Total Authorized LU: license units authorized by the installed cache.key file.
- Current Available LU: License units available at the local Cache 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 Cache instance.
- Maximum CSP Users active: Maximum number of CSP sessions consuming license units at any time since the local Cache instance started.
- Current CSP Sessions in grace period: Current number of CSP sessions in grace period on the local Cache instance.
- Maximum CSP Sessions in grace period: Maximum number of CSP sessions in grace period at any time since the local Cache instance started.
This report is identical to the report produced by counts^%SYS.LICENSE. It presents the results of the %SYSTEM.License.Counts query.
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.
Display Summary of License Server Database.
Note: Not applicable with a Single-Server key.
Displays a summary of license use for the current Cache instance's active license key. The report displays license usage data obtained both from the license server and from the local Cache instance.
The distributed license use section summarizes license use by all Cache instances that share the key. The license server is the source of this information.The local license use section summarizes license use by the Cache instance where the report is run. The source of this section is the local Cache instance's internal license use tables.
- Current License Units Used: current number of license consumed by all Cache instances sharing this key.
- Maximum License Units Used: maximum number of license consumed by all Cache 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.
This report is identical to the report produced by ShowSummary^%SYS.LICENSE. It presents the results of the %SYSTEM.License.ShowSummary query.
- Current Connections: The current number of connections (license logins) to the local Cache instance.
- Maximum Connections: The maximum number of connections (license logins) to the local Cache instance since it started.
- Current Users: The current number of license units consumed on the local Cache instance. Note that this item displays license units, not distict users.
- Maximum Users: The maximum number of license units consumed on the local Cache instance since it started.
$SYSTEM.License.TakeApplicationLicense(AppName,FeatureKeyword)
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 Cache 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 name of the 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 license.
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) 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.
Upgrade to a license (cache.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 Cache instance is restarted. Upgrades to or from a "Power Unit" key will be deferred until the Cache instance is restarted.
Return value is 1 on success, "0|Reason for failure" on failure.
The failure message may refer you to cconsole.log for additional information.
Modify how the License User Identifier is specified. By default, the client IP address is used to identify a user to the Cache license tracking subsystem. If the Cache 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 Cache 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() returns anerror if called with an argument with RealTime or Web Add-On keys because these license types use special login rules.
|
|
Selects Address As%String , InstanceName As%String , OrderNumber As%String
The ActiveServerList query returns all Active Cache instances served by the license server.
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.
Selects UserId As%String , LicenseUnits As%String , Connections As%String , ServerIP As%String , Instance As%String , OrderNumber As%String
The AllKeyConnectionList query returns a list of active connections consuming license units from all keys maintained by 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 Cache server.
The ServerIP field contains the address of the Cache server to which the connection was made.
The Instance field contains the name of the Cache instance to which the connection was made.
The data source is the license server.
Selects UserId As%String , Type As%String , Connects As%Integer , MaxCon As%Integer , CSPCon As%Integer , LU As%Integer , Active As%Integer , Grace As%Integer , AppLicenses As%List
This query is similar to the UserList query, but it returns the Application license usage in an additional column as a list.
The UserId field contains the License Login UserId. The Type field contains the login type and is one of the following:
Connects is the number of connections to this Cache instance by the user represented by UserId.
- 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 Cache instance by the user represented by UserId.
CSPCon is the number of CSP sessions open to this Cache instance by the user represented by UserId.
LU is the number of License Units consumed on this Cache instance by the user represented by the UserId.
Active is the time in seconds the UserId has been logged in to this Cache 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 Cache instance.
Selects UserId As%String , LicenseUnits As%String , Connections As%String , ServerIP As%String , Instance As%String
The ConnectionList query returns a list of active connections consuming license units from the current key.
The data source is 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 Cache server.
- The ServerIP field contains the address of the Cache server to which the connection was made.
- The Instance field contains the name of the Cache instance to which the connection was made.
Selects InstanceLicenseUse As%String , License Units As%String
Query returns data displayed by ##class(%SYSTEM.License).ShowCounts()The data source is the local Cache instance.
- Instance License Use: Text describing meaning of row data.
- License Units: Value (count) described by text.
Selects CapacityField As%String , Value As%String
Decodes the license capacity fields of the License Authorization field of the license key.The data source is the local Cache instance.
- Capacity Field: Licensed capacity name.
- License Units: Licensed capacity value.
Selects Field As%String , Value As%String
This query returns the fields of the active license key.
The value of the Sections argument filters what is returned.
- 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.
The name of each application license section enclosed in square brackets will begin each section in the "Field" field with the "Value" field empty.
- 1 Return main license section [License].
- 2 Return application license sections.
- 3 Return all license sections.
The data source is the local Cache instance.
Selects AddressPort As%String , Value As%String
Returns the IP address and port of the active License Server. This information is not applicable for Single Server keys.
Note: Not applicable with a Single-Server key.
The data source is the local Cache instance.
Selects LicenseCapacity As%String , CustomerName As%String , OrderNumber As%String , ExpirationDate As%String , AuthorizationKey As%String , MachineId As%String
The LicenseServerKeyList query returns all license keys maintained by the license server.
The data source is the license server.
- 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.
Selects Duration As%String , Count As%String
The LoginDuration query returns a histogram of the durations license unit consumption on the local instance.
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 Cache 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
Selects PID As%Integer , DisplayPID As%String , Process As%String , LID As%String , Type As%String , Con As%Integer , MaxCon As%Integer , CSPCon As%Integer , LU As%Integer , Active As%Integer , Grace As%Integer
This query returns license usage for this Cache instance by Process.
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:
The LID field contains the License Login UserId for this process.
- 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 Cache 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:
Con is the number of connections to this Cache instance by the user represented by LID.
- 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 Cache instance by the user represented by UserId.
CSPCon is the number of CSP sessions open to this Cache instance by the user represented by UserId.
LU is the number of License Units consumed on this Cache instance by the user represented by the UserId.
Active is the time in seconds the UserId has been logged in to this Cache 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 Cache instance.
Selects LicenseUnitUse As%String , Local As%String , Distributed As%String
Query returns license usage summary as displayed by $System.License.ShowSummary
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 Cache instance are returned.
Note: Not applicable with a Single-Server key.
The data source is both the local Cache 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
Selects UserId As%String , Type As%String , Connects As%Integer , MaxCon As%Integer , CSPCon As%Integer , LU As%Integer , Active As%Integer , Grace As%Integer
This query returns license use by User Id
The UserId field contains the License Login UserId. The Type field contains the login type and is one of the following:
Connects is the number of connections to this Cache instance by the user represented by UserId.
- 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 Cache instance by the user represented by UserId.
CSPCon is the number of CSP sessions open to this Cache instance by the user represented by UserId.
LU is the number of License Units consumed on this Cache instance by the user represented by the UserId.
Active is the time in seconds the UserId has been logged in to this Cache 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 Cache instance.
Selects UserId As%String , Type As%String , Connects As%Integer , MaxCon As%Integer , CSPCon As%Integer , LU As%Integer , Active As%Integer , Grace As%Integer
This query returns all license slots by User Id, or free.
The UserId field contains the License Login UserId. The Type field contains the login type and is one of the following:
Connects is the number of connections to this Cache instance by the user represented by UserId.
- 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 Cache instance by the user represented by UserId.
CSPCon is the number of CSP sessions open to this Cache instance by the user represented by UserId.
LU is the number of License Units consumed on this Cache instance by the user represented by the UserId.
Active is the time in seconds the UserId has been logged in to this Cache 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 Cache instance.