Creating & Calling User Functions

 

User Created Functions expand the extensibility of the Trading Blox Basic language and facilitate a user’s ability to create a unique functions or methods.  This is made possible by using Trading Blox's Script Object that are explained later in this page.

 

All user functions can have any combination of numeric (Integer, or Floating), String, series, or no parameters.  They can return a numeric, string, series, or no value.  They work just like inherent Trading Blox Functions, but user functions must be loaded or present in one of the Blox in the system being tested.  If the user functions are not loaded into the system an error will result.

 

Any other Blox script can call a user created function.  These user created scripts are not processed like other standard Blox script sections.  Normal Blox scripts are executed automatically in a predetermined location in the sequence controlled by data processing loop. Instead user functions are only processed when the Blox containing the user function calling code request them.

 

This ability to call methods that perform specific operations by providing numeric or string data as parameters removes the need for ordering the sequence in which a Blox section is processed.  User Functions also make the process of re-using code modules easier because they can be created as a generic script section that will be available to any Blox.  User Functions called by a standard Blox script will be able to have access the same data that the Blox section calling the user function has at the time the user function is called.

 

A good practice is to create an Auxiliary block with all the custom functions, and include in a Global Suite System. In this way, all the custom functions will be available to all systems in the suite.

 

Creating User Functions

User Functions are created in the Blox Editor by using the Script menu New Custom menu item. Start by creating an Auxiliary Block with no default scripts, and add custom functions as needed. The name of the script will be used to call the script using the script.execute function.

 

Script sections can be removed or added using the Blox Editor script menu item by selecting the Delete option when the script section you want removed is highlighted.  With all the script sections you don't want removed, click on the Scripts Menu item and then select New Custom.  This selection brings up a dialog where you can enter the name of your new User Function.  The name you give to the user functions will be displayed as a script section in the same way that Trading Blox regular script sections show names.

 

Calling User Functions

Once you've created the script section, it will open a coding area where you can code the script you want. This script code window will be no different than any of the other script coding windows.    

 

Start by entering the code you will need to achieve the user function's goal.  With your code entered, and assuming there is no parsing errors being reported at the bottom of the code window, you can then call this script from anywhere in the system by using the following process:

 

lResult = Script.Execute( "User_Function_Name", [parameterlist...] )

 

[parameterlist...]  This is where you pass values to your new function.

 

To obtain the value passed back from your user function to the variable lResult, you can use Blox Basic's PRINT function, or use the value contained in the lResult variable in another calculation.

Print lResult

Any_Var = lResult

 

When you execute a user function on the right side of an equals sign '=', the user function will assign the function's result to the variable on the left side of the equal sign.  In this case the value contained in lResult will be placed in the variable Any_Var.

 

You can call a User Function to print directly to a PRINT statement:

 

Print Script.Execute( "User_Function_Name", [parameterlist...] )

 

In this method the function's result will print directly to Trading Blox Builder default Print Output.csv file and Log Window.

 

When you writing the code for a User Function script, you will need to assign the user function's calculation results to a script's return property.  Placing one of the following methods in the user function code will assign the output value you select in the user function so that it is returned to the calling Blox:

 

Script.SetReturnValue( Any_Num or Any_String ) ' Sets the string or number return value.

If the SetReturnValue function is called more than once, the last call will determine the returned value.

 

You can call a User Function without assigning a value to capture its return result.  To do it that way, the calling statement would look like this:

Script.Execute( "User_Function_Name", [parameterlist...] )

 

In this case you would need to use one of the following properties to access the user function's results in the calling Blox section where you call the user function:

lResult = Script.ReturnValue ' Use for INTEGER OR FLOAT Returns

Or

Any_Text = Script.StringReturnValue ' Use for STRING Return

 

Script Methods & Properties:

In Trading Blox Builder's standard Blox scripts, the code within the Blox is self contained for the most part.  Access to information used within a Blox is determined by location that Blox is called within the code processing loop.  For the most part, data is passed to each Blox through the use of BPV, or IPV variables that have obtained data elsewhere, and in the case of BPV variables a Blox can assign values to BPV and variables declared within the Blox.

 

Data can also be assigned and obtained from BPV series created using the functions:

Any_Name.LoadSymbol

Or

Another_Name.LoadExternalData

 

Parameter values are primarily passed to a user function using the the following properties:

'  Variable Containers of Passed Values to User Created Functions

Script.ParameterList[]             '  Use For Integer & FLOAT values

Script.StringParameterList[]       '  Use For String values

 

'  Quantity Count of Passed Parameter Variables in User Function

Script.ParameterCount               '  Count of Integer & FLOAT Variables

Script.StringParameterCount         '  Count of String Variables

 

'  Return Variable Container Of Last User Function Result

Script.ReturnValue                 '  Use For Integer Or FLOAT Returns

Script.StringReturnValue           '  Use For String Return

 

User scripts do have access to any data that the calling Blox has access to at the time the User Function is called.  This means that if all the data you need to use in the user function is contained of the IPV or BPV variables available to the calling Blox, then you might not need to pass any new information to the user function:

'  Subroutine Processes for Setting a Specific Parameter Value in Active Function

Script.SetParameter( parameter_number, _

                    value )               '  Use For Integer & FLOAT Parameters

script.SetReturnValue(

Script.SetStringParameter( parameter number, _
                          String value ) '  Use For String Parameters

 

'  These are Subrountine Processes for Setting the User Function's RETURN value

Script.SetReturnValue( value or String ) '  Use For a Integer, FLOAT and String Returns

Script.SetStringReturnValue()  No Longer Used See Above

 

'  This is Subroutine Calling Process to Execute a User Created Function

Script.Execute( scriptName, [parameterlist...] )

 

NOTE:

'   Each Parameter List TYPE IS parsed into each OF the following variable

'   containers based upon the LEFT TO RIGHT sequence IN which the parameter

'   value IS listed when it IS called, AND also the TYPE OF variable being

'   passed:

Script.ParameterList[]       '  Use For Integer Or FLOAT parameters

Or

Script.StringParameterList[] '  Use For String parameters

 

To pass in a Series, use the GetReference function

script.Execute( "MyCustomFunction", 10, "hello", 20, "world", GetReference( instrument.averageTrueRange ) )

 

To then access values from the series, use the GetReference function:

PRINT script.GetSeriesValue( 1, index )

 

---