Implement the plugin

Modify the schema

If you are using this extension to add custom data attributes to profile points, then you must modify the schema as described in this section. If you are only intending to override system-calculated values of existing data attributes, no schema modifications are required.

Profile points are defined in a structure profile_point which is referenced in two places in the baseline schema, both on the pipe_segment record:

• The profile field on pipe_segment is a 40 element array of profile_point structures. These correspond to the static profile points.

• The if_profile field on pipe_segment is a 40-element array of intfc_pnt structures that ultimately use profile_point. These correspond to the dynamic batch interface profile points.

As it is not possible to extend structures that are part of the baseline schema, the following instructions will show you how to create a new structure to host the extended profile fields:

Step 1: Create a new structure to add the custom data attributes

Create a file “profile_point_ extensions.json” and add the new custom data attributes. This file defines a structure that contains the extended profile points. If the fields added are to be retrieved by the bthydplot BLT, then they must be of type "double". Fields that are not of type "double" can be added (for example, if they are helpful in calculating other values), however, they will not be able to be retrieved by the bthydplot BLT.

The example below shows how a data attribute called “ext_fld” of type “double” was added. Make sure to choose a unique name for the extended data attribute that does not match the name of any baseline data attribute. For a list of baseline data attributes, see Understand Hydraulic Profile line types.

{

"name": "profile_point_extensions",

"description": "Extended data for a single profile location",

"fields": [

{

"name": "ext_fld",

"type": "double",

"description": "A custom extension to profile_point”

}

]

}

Place the file in: %DNADataRoot%\RealTime\database\schema\structures.

Step 2: Create a new array type to host the new profile point structure

Create a file “profile_arr_extensions.json” to define the array type that will host the extended profile point structure created in Step 1. This array must have a dimension of 40 and point to the profile_point_extensions structure. The following extract can be copied as is to perform this step.

{

"name": "profile_arr_extensions",

"description": "Array for extended profile points",

"elementType": "profile_point_extensions",

"dimension": 40

}

Place the file in: %DNADataRoot%\RealTime\database\schema\arrays.

Step 3: Add two new fields to the pipe_segment table

Create a file “pipe_segment_table_override.json” to add a new field for static profile points and another field for dynamic profile points. The names of the new fields must be profile_extensions and if_profile_extensions in order for the Hydraulic Plot Business Logic Tier (BLT) (bthydplot) to successfully retrieve extended profile points. Both fields should use the array type created in Step 2. The following extract can be copied as-is to perform this step.

{

"name": "pipe_segment",

"fields": [

{

"name": "profile_extensions",

"type": "profile_arr_extensions",

"description": "Extended static profile points"

},

{

"name": "if_profile_extensions",

"type": "profile_arr_extensions",

"description": "Extended batch interface profile points"

}

]

}

Place the file in: %DNADataRoot%\RealTime\database\schema\tables.

Step 4: Apply the schema changes

Follow the procedure below to apply your schema extensions:

1. If necessary, shut down the RealTime service.

2. Open a Windows Command Prompt.

3. Execute the following command:

%DNAInstallRoot%\RealTime\bin\SchemaConverter.exe

Your plugin code should provide implementation for the following two functions.

void initializeHydraulicProfile(Pipelineslot plslot)

Where:

• plslot is an integer that represents the slot number of the pipeline being processed.

• The initializeHydraulicProfile function entry point is located at the start of hydraulic profile processing. This function allows you to initialize the context at the beginning of the profile calculation for each pipeline.

void extendHydraulicProfile(Pipelineslot plslot, pipe_segmentslt segmentslot)

Where:

• plslot is an integer that represents the slot number of the pipeline being processed.

• segmentslot is an integer that represents the slot number of the pipeline segment being processed.

• The extendHydraulicProfile function entry point is located just after the baseline profile point processing, within the context of the pipeline segment being processed. This is the function you can use to provide the calculation logic of custom data attributes of the profile point or override the system-calculated values of baseline attributes.

Error handling should be included in the plugin code itself. Batch Tracking will catch and log exceptions thrown by the plugin.

Each profile point, static or dynamic, is associated with a milepost. When traversing profile points along a pipeline segment, you can inspect the milepost associated with the profile point and compare it with the mileposts in the profile and if_profile arrays to determine if you are dealing with a static point or a dynamic point. For example, say the following mileposts exist during a particular processing cycle:

If the profile point being inspected has a milepost value of 4.5, then this profile point is part of the static profile array, more specifically profile[1]. If you need to access the extended data attributes, you will need to use profile_extensions[1].

If the profile point being inspected has a milepost value of 2.1, then this profile point is part of the dynamic if_profile array, more specifically if_profile[0]. If you need to access the extended data attributes, you will need to use if_profile_extensions[0].

An example of how to implement this mapping in the plugin code is given in the SDK example and is shown below.