Readying Your Custom Component
The Component Licensing Function
Calling the Component Licensing Function
Component licensing allows component designers to restrict the use of their custom components to specific PSCAD users, on a per certificate license basis. As such, a custom model can be freely distributed, perhaps even made available for public download, but the actual usage of that component in an EMTDC simulation is blocked, unless a specific user’s certificate license enables its use.
It is important to note that this feature simply restricts a component’s usage in an EMTDC simulation, via modifications to the corresponding source code. It is up to the component designer to ensure that this source code is still compiled into binary (i.e. *.lib or *.dll), to protect intellectual property before being sent off to the client.
In order to ready your component to use this feature, some minor modifications must first be made to the source code of each custom component you intend to license. These are:
Set licensing parameters and provide a call statement to the Component Licensing Function, a C-language method called ‘CHECK_COMPONENT_LICENSE’. Note that if your component source is written in FORTRAN, you will need to define an interface subroutine and call it instead.
Contact the PSCAD Sales Desk (sales@pscad.com) for the component licencing, static library file, to be included as part of your custom component binary file. This library contains the component licensing function, which must be called.
The component licensing static library file is available upon request from the PSCAD Sales Desk (sales@pscad.com).
Multiple static libraries are provided to you in a single zip (*.zip) file, called ComponentLicensing.zip, containing a file built with each FORTRAN compiler supported for use with the PSCAD software, both 32 and 64-bit. It is up to the component designer to ensure that a final binary file is created to support each compiler type.
It is required that you bind and link the custom component source code to the component licensing static library file, to create a single static library file to associate with your component.
Once your custom component model has been readied for licensing, the final step in the process is to contact the PSCAD Sales Desk (sales@pscad.com) to request a modification to your client’s license certificate; following the modification, they will be able to use your model in their EMTDC simulations.
The function that is used to check whether or not a particular component is licensed for use in an EMTDC simulation, is a C-language function called 'CHECK_COMPONENT_LICENSE', which includes four input arguments:
void CHECK_COMPONENT_LICENSE(CHARACTER name, CHARACTER guid, CHARACTER key, INTEGER count)
The arguments are described as follows:
name: This is simply a name string, identifying the custom component.
guid: GUID stands for Globally Unique Identifier. This is an important character string input, as the longer and more random this character string is, the better. We recommend this website as an easy way to generated a GUID for your component: https://www.guidgenerator.com/.
key: The key is essentially a secret password used to verify to the component license. It can be any string. We recommend a strong key, containing capitals, numbers and off-characters. The size limit for this key is 30,000 characters. If you prefer, you can also use another auto generated GUID.
count: This is an integer argument that represents the interval in milliseconds (i.e. 1 = 1 ms real time), in which the licensing function is called during a simulation. Note that each call will momentarily slow the simulation, so we recommend perhaps a 10 second interval (count = 10,000) or greater.
The manner in which the component licensing function is called depends on the language the component is written in. We provide tools/examples for FORTRAN or C.
Regardless of language, the call statement should be placed at the beginning of any function\subroutine that needs to be secured (that should not work if not licensed). This will ensure that none of the component source is executed, without first checking the license validity.
For C-language source, include the ‘ComponentLicensing.h’ file. (This header file will be provided to you as part of a zip file package, as outlined in Procuring the Necessary Files). Call the function: CHECK_COMPONENT_LICENSE, with the following statement. Note that the input arguments must be defined prior to the call:
#include "ComponentLicensing.h";
const char* name = 'my_component';
const char* guid = '7b56f0a5-8f32-410a-836e-90994fa76bc8'; // https://www.guidgenerator.com/
const char* key = '5628c9b3-1716-4824-9fe7-ed1c6c2ba056'; //
const int count = 10000;
CHECK_COMPONENT_LICENSE(name, guid, key, count);
Since the component licensing function is written in C, you cannot call it directly from FORTRAN source. You must instead call it through an interface subroutine provided in ‘ComponentLicensing.f’ (which in turn, calls the component licensing function).
An example subroutine is shown below:
SUBROUTINE MY_SUBROUTINE
USE, INTRINSIC :: ISO_C_BINDING
CHARACTER*(*) NAME, KEY, GID
PARAMETER(NAME = C_CHAR_'my_component'//C_NULL_CHAR)
PARAMETER(GID = C_CHAR_'7b56f0a5-8f32-410a-836e-90994fa76bc8'//C_NULL_CHAR)
PARAMETER(KEY = C_CHAR_'5628c9b3-1716-4824-9fe7-ed1c6c2ba056'//C_NULL_CHAR)
! Call to check component license function.
!
CALL CHECK_COMPONENT_LICENSE_CI(NAME, GID, KEY, 1000)
END SUBROUTINE
Regardless of what you choose to do, you must ensure that the interface subroutine is linked when the final static library (*.lib) file is created.
NOTE: If the call statement is placed in an initialization subroutine (i.e. gets called only once at time equal to zero), then the ‘count’ input above will have no effect. That is, the function will be called only once, regardless of the length of the simulation.
There are two different options available to consider when creating the final binary file: Use a static library (*.lib), or a dynamic link library (*.dll). Of these two, the dynamic link library (*.dll) is the more secure option (i.e. a bit tougher to hack), although both are reasonably secure for most purposes.
Once your custom component source has been modified to include a CALL statement to the CHECK_COMPONENT_LICENSE function (as described above), and your input parameters have been set, then you simply need to bind your source file, with the appropriate ComponentLicensing.lib file, to form a single static library file that you will include with the component.
Two examples are provided as part of the ComponentLicensing.zip file: One which illustrates the usage of a static library (*.lib), and the other the usage of a dynamic link library (*.dll). The second of which being the most secure method.