Implement the plugin
- Last UpdatedApr 24, 2025
- 3 minute read
-
Create a C++ source file that implements the C++ Entry Function.
-
Map your function to a lpackalg enumeration in order to add it as a selectable option for linepack calculation in Advanced Database Editor (ADE).
-
(Optional) Extend the RealTime database (RTDB) schema if necessary.
You can create multiple linepack functions, but their names must be unique. They must follow the signature so it can be discovered, loaded, and used externally. The function is a void type and accepts two parameters—the pipelineslot and pipeline*. The first parameter is the slot number of the pipeline record (that is, ptnum). The second parameter is the pointer to the locked pipeline record in the RealTime database (RTDB).
extern "C" OAS_EXPORT void do_custom_linepack(
pipelineslot pipeline_slot,
pipeline * pPipeline
)
For a full sample implementation, refer to C:\dev\RealTime\source\Pipeline.Linepack.Extension.Example\pipelineLinepack.cpp.
In our example code, we illustrate how to set the linepack value of each pipe segment as follows:
pipe_segment* pPipe = static_cast<pipe_segment*>(bt_get_rec(DATABASE_PIPE_SEGMENT,pipe_slot);
pPipe->linepack = pPipe->capacity * 2;
Map the Custom lpackalg_enum Value to Your Plugin / Extending lpackalg enumeration
Each function corresponds to a unique lpackalg enumeration value. With each function created, you must create a corresponding value in the lpackalg enumeration by extending the enum in the schema. Refer to the following lpackalg_enum_override example.
{
"name": "lpackalg",
"description": "Algorithm selection for linepack",
"values": [
{
"name": "AT_LINEPACK_PLUGIN_METHOD_1",
"description": "Custom Linepack Plugin Method 1",
"value": 10
},
{
"name": "AT_LINEPACK_PLUGIN_METHOD_2",
"description": "Custom Linepack Plugin Method 2",
"value": 11
},
{
"name": "AT_LINEPACK_PLUGIN_METHOD_3",
"description": "Custom Linepack Plugin Method 3",
"value": 12
}
]
}
Once ready, the file is placed in %DNADataRoot%\RealTime\database\schema\enumerations\your_lpackalg_enum_override.json.
Note: The name of the file does not matter if it does not conflict with an existing file in the same directory.
When deciding on the value of your custom lpackalg enumeration, make sure it does not conflict with any values in the baseline schema.
We recommend you start with enumeration values of 10 and above to leave space for baseline options to be added in the future without conflicting with your custom options.
Applying the schema extensions
Once the schema extensions are included, they are applied by executing %DNAInstallRoot%\RealTime\bin\SchemaConverter.exe with RealTime shut down. Once applied, execute the following Advanced Database Editor (ADE) initialization commands in order to see the new enumeration values in ADE:
dbeditdisplayschemamerge -v -f schema
dnatreelayoutschemamerge -p ADE -f schema
Extending LMS.RealTime.json
To map your custom lpackalg value to your plugin function, you need to add a settings file that links the custom lpackalg to the unique function that implements the desired linepack calculation. Place the settings file in the %DNADataRoot%\RealTime\config\Settings\ directory. Refer to the following LMS_Extensions_BatchTracking_Linepack_Map.json example.
{
"RealTime": {
"LMS": {
"BatchTracking": {
"LinepackFunctionNameToEnumMap": {
"AT_LINEPACK_PLUGIN_METHOD_1": {
"EnumValue": "10",
"FunctionName": "do_custom_linepack"
},
"AT_LINEPACK_PLUGIN_METHOD_2": {
"EnumValue": "11",
"FunctionName": "do_custom_linepack2"
},
"AT_LINEPACK_PLUGIN_METHOD_3": {
"EnumValue": "12",
"FunctionName": "do_custom_linepack3"
}
}
}
}
}
}
In the above example, we are mapping function "do_custom_linepack" to lpackalg enumeration value 10, which has the name "AT_LINEPACK_PLUGIN_METHOD_1". This step is critical because, later in ADE, when you select the linepack option as "AT_LINEPACK_PLUGIN_METHOD_1", the Batch Tracking application knows to look for the function "do_custom_linepack". If you forget to map your function with a custom lpackalg enum value, the Batch Tracking application will error-out and default to using the baseline LINEAR option for the linepack calculation. If the function name here does not align with the C++ entry function name, the lookup will also fail and the application will error-out and default to using the baseline LINEAR option.
The key (for example, AT_LINEPACK_PLUGIN_METHOD_1), and the EnumValue (10), should match the definition in lpackalg_enum_override.json. Duplicates will be rejected.
Note: The name of the file does not matter if it does not conflict with an existing file in the same directory.
Applying the changes
After extending LMS.RealTime.json and LMS_Extensions.json, restart the RealTime service for changes to take effect.
Extend the schema
Your plugin may require additional RealTime database (RTDB) fields to store temperature or pressure readings for your linepack calculation. Also, your formula may require additional RTDB fields to store the processed result. One solution is to extend the RTDB database schema for the necessary Batch Tracking tables.
Applying the schema extensions
After you have included your schema extensions, follow the procedure below to apply your schema extensions.
-
If necessary, shut down the RealTime service.
-
Open a Windows Command Prompt.
-
Execute the following command:
%DNAInstallRoot%\RealTime\bin\SchemaConverter.exe