Open topic with navigation

You are here: Surpac Concepts > Macros > SCL > System and Misc > SclLicenseManager
GEOVIA Surpac

SclLicenseManager

Overview

GEOVIA software products are protected using a sophisticated licensing system. The SclLicenseManager licensing commands can be useful for protecting third-party complex Tcl scripts. Developers of complex suites of TCL and SCL scripts can use this licensing system to register user licences for their third-party scripts with the GEOVIA licencing system. The SclLicenseManager licensing commands can be useful for protecting third-party complex Tcl scripts.

Synopsis

SclLicenseManager <sub option><optional parameters>

Description

The following sub functions are currently available.

SclLicenseManager getLicenseType
SclLicenseManager getSentinelId
SclLicenseManager getSSILMVersion
SclLicenseManager getVersion
SclLicenseManager isSecurityClassEnabled <optional parameters>
SclLicenseManager registerUserLicense <optional parameters>
SclLicenseManager unregisterUserLicense <optional parameters>

Synopsis

SclLicenseManager <getLicenseType>

Description

getLicenseType queries the software to determine the type of licensing system being used. This can be either local, network, or none.

Arguments

  • <getLicenseType>

    • A literal string to identify the sub function

Returns

The word "local", "network", or "none".

Examples

set licenseType [SclLicenseManager getLicenseType]
puts "You are using a $licenseType license type"

Synopsis

SclLicenseManager <getSentinelId>

Description

getSentinelId will return the unique identifier of the sentinel or computer host ID as an integer value. A sentinel number or host ID is returned for local sentinels (connected to the parallel or USB port) or for a Licence Manager (SSILM) installation. Note that for SSILM installations, an updated version of the ssilm.exe program is required to ensure the correct information is returned from the licence manager. The ssilm.exe must be from a Surpac, or related product, after V4.1-F.

If the ssilm.exe is from an earlier version the value returned by this SCL command will be 0. Script authors should treat this value as an error condition and write appropriate error handling code.

Arguments

  • <getSentinelId>

    • A literal string to identify the sub function

Returns

The sentinel Id as an integer value or 0 if using a SSILM license earlier than version 4.1-F.

If an error condition occurs the function will throw a Tcl error which can be caught using the Tcl catch command.

Examples

if {[catch {SclLicenseManager getSentinelId} sentinelId]} {
  puts "ERROR: cannot determine sentinel number"
} else {
  if {$sentinelId == 0} {
    puts "ERROR: cannot correctly determine sentinel number"
    puts "Try updating your software to at least version 4.1-f"
  } else {
    puts "Your sentinel ID is $sentinelId"
  }
}

Synopsis

SclLicenseManager <getSSILMVersion>

Description

getSSILMVersion queries the license manager to determine the version of the network licensing system (SSILM) being used.

Note that this sub function is only valid when the license type is network. See getLicenseType

Arguments

  • <getSSLIMVersion>

    • A literal string to identify the sub function

Returns

The version number of the SSILM being used or a null string if no SSLIM is being used. If an error condition occurs the function will throw a Tcl error which can be caught using the Tcl catch command.

Examples

set licenseType [SclLicenseManager getLicenseType]
if {"$licenseType" == "network"} {
  if {[catch {SclLicenseManager getSSILMVersion} versionNo]} {
    puts "ERROR: Cannot determine the SSILM version"
  } else {
    puts "The network license manager version is $versionNo"
  }
} else {
  puts "INFORMATION: Not using a network license manager"
}

Synopsis

SclLicenseManager <getVersion>

Description

getVersion queries the license manager to determine the identifier string of the client software (for example, Surpac). The returned identifier string takes the form of:

<product name> x.y.z <optional release type> <(x64)>

where

  • <product name>

    • Is a descriptive name for the product. This may include spaces.

  • x

    • Is the major version number.

  • y

    • Is the minor version number.

  • z

    • Is the maintenance version number.

  • <optional release type>

    • Is optional and, if present, may be either alpha, beta or special.

  • (x64)

    • Is appended to the version number for 64-bit versions of Surpac.

Arguments

  • <getVersion>

    • A literal string to identify the sub function

Returns

The version identifer as described above.

Examples

puts "[SclLicenseManger getVersion]"

Synopsis

SclLicenseManager <isSecurityClassEnabled><security class name>

Description

isSecurityClassEnabled returns 1 if the requested security class is enabled in the software product or 0 if it is not enabled.

Names for the security classes encapsulated in any GEOVIA product can be found by using the UPDATE LICENCE function.

Arguments

  • <IsSecurityClassEnabled>

    • A literal string to identify the sub function

  • <security class name>

    • A quoted string that identifies the security class to check. Names for the security classes encapsulated in any GEOVIA product can be found by using the UPDATE LICENCE function

Returns

If the security class name is unknown or is not licensed then a value of 0 is returned. If the security class is licensed a value of 1 is returned.

Examples

set enabled [SclLicenseManager isSecurityClassEnabled "Core Modules"]
if {$enabled != $SCL_ERROR} {
  if {$enabled} {
    puts "You are licensed to use the core modules"
  } else {
    puts "You are not licensed to use the core modules"
  }
} else {
  puts "ERROR: cannot determine license state for class Core Modules"
}

Synopsis

SclLicenseManager <registerUserLicense><user license><hostid><max users><sequence>

Description

registerUserLicense increments the number of running sessions of a third-party licensed product in the SSILM network license manager. If there is not a current registration for the license string identified by <user license> then one is created and set to one.

When registering a user license type the <hostid>, maximum user count <max users> for the user license must be submitted along with a <sequence> number that identifies the license.

The <hostid> must be given such that the correct SSILM server processes the registration in the event that more than one SSILM may be running on the network.

The <max users> count for the license is used by the SSILM to determine if a license can be granted. If by registering a user licenses the <max users> count would be exceeded then the request is denied and a Tcl error is thrown.

The <sequence> number is used to identify a particular issue of a user license. Due to the nature of the network licensing model it is possible that a license may be registered on the SSILM from different locations and it is also possible that these licenses may also be different. For example the vendor may have issued a new license that allowed a higher number of network users than the original license. In this case the <sequence> number for the new license should be higher so the SSILM can recognise this fact and update the <max users> count for the license.

It is up to to the third-party vendor to manage the <sequence> number as part of their licensing model. An acceptable scheme for the sequence number would be to use the date of license issue as follows 030211 which would mean 11 February 2003 or just an incrementing number starting at one for the first issue of a license.

Note that when ever a successful <registerUserLicense> call is made a corresponding call to <unregisterUserLicense> should also be made to ensure the count of current sessions in the SSILM is decremented. See unregisterUserLicense

It is the responsibility of the third-party developer to manage product security in their code. This function only allows a third-party developer the ability to track the total number of running sessions of their product over a SSILM installation.

Due to the network protocol used to implement this function it is possible that the message to the license manager server and/or the reply message back to the client will be lost. It is unlikely this will occur on a reasonable network but a short retry loop should be coded to handle this situation.

In the event of an abnormal termination of the software the registered license will be cleared from the SSILM count.

Note that this sub function is only valid when the license type is network. See getLicenseType

Arguments

  • <registerUserLicense>

    • A literal string to identify the sub function

  • <user license name>

    • A quoted string to identify the name of the license class, ie "Tailings"

  • <hostid>

    • The host id of the SSILM that is to be used to process the user registration request.

  • <max users>

    • The total number of permitted sessions for this user license class

  • <sequence>

    • A sequence number used to identify the latest license information with respect to the max user count. A request with a higher sequence number will cause the max users information to be updated. As an example sequence number use the date of license issue as follows 30124 which represents 24-Jan-2003.

Returns

The current number of running session of the user license including the new request by the call to registerUserLicense. If the maximum user count would be exceed by this call then a Tcl error is thrown. If another error condition occurs then a Tcl error is thrown

Examples

set licenseType [SclLicenseManager getLicenseType]
if {"$licenseType" == "network"} {
  for {set i 0} {$i < 3} {incr i} {
    if {[catch {SclLicenseManager registerUserLicense "MY PRODUCT" 2852192599 2 30325 } currentSessions]} {
      puts "ERROR: Cannot register license ... retrying"
      set currentSessions -1
    } else {
      break
    }
  }
  if {$currentSessions < 0} {
    puts "ERROR: Could not get a network license"
  } else {
    puts "Successful license registration"
    puts "There are $currentSessions current users"
  }
} else {
  puts "INFORMATION: Not using a network license manager"
}

Synopsis

SclLicenseManager <unregisterUserLicense><user license name><hostid>

Description

unregisterUserLicense decrements the number of running sessions of a third-party licensed product in the SSILM network license manager. If there is not a current registration for the license string then nothing is done.

Note that this sub function is only valid when the license type is network. See getLicenseType

Arguments

  • <unregisterUserLicense>

    • A literal string to identify the sub function

  • <user license name>

    • A quoted string to identify the name of the license class, ie "Tailings"

  • <hostid>

    • The host id of the SSILM that is to be used to process the user unregistration request.

Returns

If an error condition occurs then a Tcl error is thrown

Examples

set licenseType [SclLicenseManager getLicenseType]
if {"$licenseType" == "network"} {
 if {[catch {SclLicenseManager unregisterUserLicense "MY PRODUCT" 2852192599}]} {
   puts "ERROR: cannot unregister user license"
 }
}

Open topic with navigation