Statelake Maps are based on a script engine. This scripting engine allows you to create custom code to perform the mapping of data from one field to another. Being script based, the mapping is not limited to any particular processing, but rather is completely configurable by the operator.

Each script is attached to an Event.

The Statelake script engine is based on Object Pascal. This is the same language that is used within the Delphi programming environment, and as such shares many of the same functions as Delphi and is similar in syntax. You will find that the syntax is also very similar to C#.

Within this section you will find information on the scripting engine. You should read through each of the following topics in order to provide an overview to the Statelake scripting. At a later time you can refer back to this section when looking for a function to perform a required task.

However, you can also find relevant information by searching the Internet for terms like "Delphi" or "Object Pascal". For instance to find a string handling function, you could do an internet search for "Delphi copy string".

Script Editor

There are several places within Statelake where you have the opportunity to enter script code through a Script Editor panel - within the Map, creation of Include Files, and custom scripts within an Action.

While slightly different in presentation, all these panels function in exactly the same manner. All are simple text editors with the line numbers displayed on the left margin.

Script Editor within the Maps module
Script Editor within the Include Files module
Script Editor within the Action module

Within the Include File and Actions modules, the top half of the script editor is where you enter your script code. Within the Maps module, the Script Editor pane occupies the lower area of the window. The line number will show at the left hand border.

When you have finished entering your script, you should Test Compile by right-clicking anywhere within the script window, and selecting Test Compile.

When you are satisfied with the script, right-click anywhere within the script window, and select Save Script.

The bottom portion of the editor contains the compiler messages section. This shows any messages regarding the compilation of the script code you entered. If there are errors with your script they will be shown here along with the line and character number.

Fields

Field Name

Description

Source Data

Shows the dataviews of the source Data Definition linked to the script editor. This allows you to navigate the source data and view its dataviews and fields.

Parameters

Any configuration Parameters will display.

Includes

A list of Include Files within the configuration.

Fields List

A list of fields for the selected dataview in the Source Data field.

Edit Pane

The edit window where you type your script code. Click anywhere within the blank window to create the skeleton starting point for the script code.

Results Pane

Shows the results of compiling your script code.

Scripts

The code that is created to perform a function that is attached to an Event is called a Script. For more information regarding Events, please refer to Events.

A Script has an initial skeleton that is provided by the script engine, and you enhance and extend your script code within this skeleton. The following is a typical script skeleton.

procedure ScriptEvent(var Value:variant);
begin
 
 
end;

The first line in the skeleton will indicate the type of that particular section of script code, and in most cases this will be procedure, as above. This first line should not normally be changed.

Entering Script Code

The second and fourth line in the skeleton are the begin…end statement block within which you should enter your script, and should never be removed.

Using the skeleton above, the following is an example of Script code being entered to write the text Marvin ate 3 kilos of sausages! into the Log during execution of the Script.

procedure ScriptEvent(var Value:variant);
begin
LogInfo('Marvin ate 3 kilos of sausages!');
end;

Declaring Variables

Variables can be declared between the first and second lines, by simply creating a new line directly after the first line, and entering your variable declarations into this space. The following is an example of a Integer variable called MyVariable being declared.

procedure ScriptEvent(var Value:variant);
var MyVariable:Integer;
begin
 
 
end;

Variable names are not case sensitive in a script, so that the above variable MyVariable can be referenced as myvariable, but having the upper and lower case combination may make it easier to identify.

For more information about variables and their use, please see Variables.

Highlighting Syntax

Script will be highlighted in different colours and boldness, depending on what is being represented, such as with the following example.

procedure BeforeMapEvent(var Value:Variant); //SALESORD_HDR
var
vSQL, vErrStr, vInfoStr: string;
begin
Global1 := 0.00; // Order total; see SALESORD_LINES AfterMap
vSQL := 'SELECT ACCNO FROM DR_ACCS WHERE BRANCH =';
vSQL := vSQL + M10B2BORDER['POheader_StoreCode'].AsSql;
Global2 := GetSQLValueFromDest(vSQL,0);
if Global2 = null then
begin
vErrStr := 'Account not found for store code "';
vErrStr := vErrStr + M10B2BORDER['POheader_StoreCode'].AsString;
vErrStr := vErrStr + '".Order rejected.';
LogErrorAndContinue(vErrStr);
end
else
begin
vInfoStr := 'Store code "';
vInfoStr := vInfoStr + M10B2BORDER['POheader_StoreCode'].AsString;
vInfoStr := vInfoStr + '"matched to account no. "'+Global2+'".';
LogInfo(vInfoStr);
end;
end;

Error Messages With Test Compile

The Script can be validated at any time by right-clicking and selecting Test Compile. A successful compile will display in the messages section in the lower portion of the window, as will any errors that have been identified. Errors will display the offending line and character number for the error. Click Save to save the Script and exit the editor.

Validating the following code will generate an error because of the typing mistake.

procedure ScriptEvent(var Value:variant);
begin
If Value<10 thne Value:= 10;
end;

The resulting error message would be Compiler: [Error] (3:13): 'THEN' expected. The compiler has identified an unknown word at character position 13 on line 3, and is anticipating that the word THEN is expected.

A similar issue exists with the following code.

procedure ScriptEvent(var Value:variant);
begin
Whlie Value<10 do Value:= Value+1;
end;

Validation of the code results in the error Compiler: [Error] (3:1): Unknown identifier 'whlie'. In this case there is again a spelling mistake at the 1st character on the 3rd line and the compiler does not recognise the word whlie.  

Exception Handling

When writing Script you will invariably at some stage code something that will fail under certain circumstances.

By default, Statelake will handle errors in your Script by logging as much information as possible to the action Log. This is normally enough for most situations - however, occasionally the situation may require that you handle the error yourself and provide custom logic to capture and deal with any future occurrences of the error.

The Try….Except statement can be used to provide custom error handling logic, and can be nested within other Try….Except statements to provide for multiple alternatives when failures occur.

And instead of the standard error message being written to the Log, you can write a custom error message to provide insight or for further clarification.

An alternative solution would be to provide Script to set the field to a different or correct value using a different calculation, rather than just produce an error.

Exceptions functions are used within the Try...Except statement, to capture information about the exception error.