Carmenta Engine 5 Runtime Licenses
This article describes how to use a Carmenta Engine 5 runtime license when an applications is being developed or deployed.
Carmenta Engine license keys
Carmenta Engine has three different types of license keys:
SDK
An SDK license is required to use the development tools in an SDK installation, like Carmenta Studio and Carmenta Explorer. A license file is installed in the file system. An SDK license can be used during development and testing of applications on the development machine.
An SDK license requires an activation procedure, which locks it to a specific machine. It can not be used as an SDK license on a different machine. An SDK license can only be used as a runtime license on a different machine while developing, and an evaluation text and marker will be displayed in all map windows.Evaluation
An evaluation license is similar to an SDK license, and is installed in the same way. It does not have to be activated however, and is usually valid only for a limited time. An evaluation text and marker is displayed in all map windows.Runtime
A runtime license allows an application to use the Carmenta Engine runtime. The application is required to deploy and manage the runtime key, and supply it to the Carmenta Engine runtime in the Runtime.Initialize call, see the example below.
When running Linux applications on Windows using WSL, the license key needs to be installed in C:\ProgramData\Carmenta\License.carmentakey for it to be found.
The available functionality in the SDK and the Runtime is controlled by the license keys, i.e. certain classes may be excluded. Which functionality that is available in the license keys depends of which Carmenta Engine Extensions that have been licensed.
To acquire Carmenta Engine license keys, please contact Support.
Initializing Carmenta Engine 5 with a runtime license
In a deployed Carmenta Engine application, the application can supply a runtime license key in the Runtime.Initialize call. When calling Runtime.Initialize without a key, Carmenta Engine will first look for a license in the Carmenta Engine data directory and, if no license key is found, look for an installed SDK license. Runtime license keys are received from Carmenta as text files.
Depending on your license agreement with Carmenta, you might either have been issued individual runtime license keys for each separate deployment, or a single runtime license key that is valid for all your deployments.
If you have a single runtime license key that is valid for all your deployments, the easiest is to embed the license file as a string resource in your application. If not, it is better to let the application read the license key from an external text file that can be deployed separately.
The following examples shows how the license key can be read from a file.
// Read contents of the license file into a string.
string licenseKey = File.ReadAllText("runtime.carmentakey");
try
{
// Initialize Carmenta Engine with the key.
Runtime.Initialize(licenseKey);
}
catch (Exception ex)
{
// Display error message from exception.
MessageBox.Show(
ex.Message,
"Error",
MessageBoxButton.OK,
MessageBoxImage.Error);
}
// Read contents of the license file into a string.
std::ifstream license_file("runtime.carmentakey");
std::string license_key;
std::copy(std::istreambuf_iterator<char>(license_file),
std::istreambuf_iterator<char>(), std::back_inserter(license_key));
try
{
// Initialize Carmenta Engine with the key.
Carmenta::Engine::Runtime::initialize(license_key.c_str());
}
catch (const Carmenta::Engine::EngineException& ex)
{
// Display error message from exception.
std::fprintf(stderr, "%s\n", ex.message().c_str());
}
// Read contents of the license file into a string.
FileInputStream licenseFile = new FileInputStream("runtime.carmentakey");
String licenseKey = new Scanner(licenseFile, "UTF-8").useDelimiter("\\A").next();
try {
// Initialize Carmenta Engine with the key.
com.carmenta.engine.core.Runtime.initialize(licenseKey);
} catch (Exception ex) {
// Display error message from exception.
JOptionPane.showMessageDialog(null,
ex.getMessage(),
"Error",
JOptionPane.ERROR_MESSAGE);
}
In the early stages of development, it may be easier to ignore the runtime license, and just call the Runtime.Initialize without a key. When run, the SDK license key will be found, so it will work to develop, test and debug as usual.
However, it is recommended to test the application with a proper runtime key as soon as possible, to ensure that the runtime license key covers all the modules used by the application. If the runtime key is supplied to Runtime.Initialize as described above, that key will be used, even if an SDK key is available.
Managing Carmenta Engine runtime licenses
Procedures for deploying Carmenta Engine applications with individual runtime license keys for each separate deployment are described below.
The application needs to be designed so that the runtime license is loaded from a file since every target machine is going to have its own unique license key. To generate the unique license keys you can use the Runtime.GenerateLicenseActivationRequest method in the Carmenta Engine API from your application or you can use the Carmenta Runtime License Key Manager command line utility included in the Carmenta Engine SDK.
Example instructions that uses the Carmenta Runtime License Key Manager command line utility:
For every target machine a non-activated (NA) installation license key file will be provided from Carmenta. Using this key file you create an activation request with the Carmenta Runtime License Key Manager utility. Run it on the target machine to create the activation request (AR) file.
Example of the command to run: RuntimeLicenseKeyManager.exe request_activation 1234_1_NA_CarmentaEngine.carmentakey 1234_1_AR_CarmentaEngine.carmentakey On Linux use carmenta-runtime-license-key-manager instead of RuntimeLicenseKeyManager.exe.
Send the activation request file (1234_1_AR_CarmentaEngine.carmentakey in the example above) to support@carmenta.com.
When you receive the corresponding activated license file, install it on the correct target machine by copying it to the folder the application requires.
Be sure to keep track of which target machine each license key belongs to, since they can only be used for that specific machine.