Creating A User Function

Once the script space area has been created as shown in Creating Custom Scripts that space is where the method needed from a special function can be scripted.  A user's Custom Function can be complex or as simple as adding to numbers of changing the case of a text value.


Values to be used in a user function are sent to the user function by adding parameters to the calling statement of the user function:


Let's assume we wanted to add two numbers together.  We first need to give the function a name.  In this example we'll call the function "AddTwoNumbers" which will also be the Custom Function Script Section name.


To execute that function we need to call that function from another script.  Any other script can call any other script section.  This also included any of the Trading Blox standard script sections.  


For our example we need to pass our function two values.  How we get those values is not important, but they must be valid within the script area from which we call this custom function:

'  Assign a value to each of the two Floating Point BPV values:
AnyRandom1 = Random( 1, 100 )
AnyRandom2 = Random( 1, 100 )

Calling "AddTwoNumbers" needs a statement that will access the created custom script section and pass that section the value of two number:

'  This statement will work
script.execute("AddTwoNumbers", AnyRandom1, AnyRandom2)

Within our custom script section we will use two script properties to access the passed value so we can add them together:

'  Create two local floating point values
VARIABLES: anyValue1, anyValue2, sumValue TYPE: Floating
'  Access the values in each of the numeric
'  parameters passed to this function
anyValue1 = script.parameterList[1]
anyValue2 = script.parameterList[2]
'  Add the numbers together
sumValue = anyValue1 + anyValue2
'  Return the sum of the two values
'  to the calling script section
script.SetReturnValue( sumValue )

If the value of the returned numbers were 1 and 2 the return value will equal 3.


Access to a single return value, multiple values can be returned, is available in three ways:

'  To directly return the results of a called script

'  let the calling statement assign its return value
addedValue = script.execute("AddTwoNumbers", AnyRandom1, AnyRandom2)
'  To access the value returned using a property, place
'  the property assignment after the calling statement
addedValue = script.returnValue
'  To send the returned value to the Print Output.csv file
'  call the custom script statement using the PRINT function.
PRINT script.execute("AddTwoNumbers", AnyRandom1, AnyRandom2)


If more examples are needed, use the Help file's email option or use the static Help file topic in the forum.


Custom script section can provide new functionality, but they share the same dependency and limitations of the the script section from which they are called to execute.  This means the script section that executes the custom script section is a script section that is or can be executed for each instrument in the portfolio without the need for the LoadSymbol function, then the custom script section will share that access.  If the calling script section only executes once each for each test.currentDay, that script section will be required to use the LoadSymbol function to have access to an instrument.


To get a broader understanding of how the script section calling the custom section will condition the custom script section, please read the details on the Instrument topic page were each of the standard script sections are listed as having native instrument access, or are script section that only execute once for each test.currentDate and need special access to instruments.


Custom script section variables share access to the calling script section. This means that variables with the same name in the script section that calls the custom script section will have an impact on the values in the custom script section, and also in the calling script section after the custom script section has completed its execution of its scripts.


This means that it is possible to contaminate or share data between the two script sections.  This is also true when a script section calls another custom script section.  There can either be contamination or sharing of data that may or many not be intended.


To prevent unintended contamination of variables, use variable names in a script section that are not going to be used within any other script.  One simple way is to use a prefix or suffix in the custom script that is added to any of the variable names so as the variable name will be unique to the custom that specific custom script name.


In a custom script section named "Field_Count", all the variable names have a suffix attached to their name using the two primary characters in the custom function name:


'  Determine the Size of the String
String_Length_fc = Len(String_Fields_fc)


It is unlikely that a string_length variable would be created in a standard script section to make it unique because variables can be limited in their data scope reach by how the variables are declared.  Custom script sections by default are limited in data scope reach by how they are declared.  However, that scoping reach includes the script section that calls the custom script because the process of how it is executed once called.  In simple terms, when a custom script is called it is not any different from how the same code would work had the scripting in the custom script section been typed into the script section that executed the custom script.


Why then do we need custom script sections?

Custom script sections allow us to write code that can do a task that we don't have as a normal function.  By creating it as a custom script section we can write the code once and then use it many times.


Once a custom script has been created it can then be used many times because the custom script section can be placed in an Auxiliary module that is easily attached to a system list.  A custom script section can also be Right-Clicked, Copied, and then Pasted into another blox for use in that blox.


How many custom script sections are allowed?

There is no known limit, but there is a restriction when it comes to a custom script section name.  Each custom script section in a system must be different from any other custom script section in that system.  This is necessary because the Script Object's Execute function will search the entire system list looking for the name used by the Execute function.  If you have more than one a custom script with the same name and it isn't exactly the same code, then the results you will get might not be what you wanted because the search process looks and then uses the first custom script section it finds with the name given to the Execute function.


Edit Time: 2/25/2018 10:56:02 AM

Topic ID#: 237


Created with Help & Manual 7 and styled with Premium Pack Version 2.80 © by EC Software