User Functions

USER FUNCTION NOTES:

NEW OBJECT:

  Script

NEW Parameters:

  '  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

NEW Functions:

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

  Script.SetParameter( parameter_number, _

                       value )                 Use FOR INTEGER & FLOAT Parameters

  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 )               Use FOR a INTEGER & FLOAT RETURN

  Script.SetStringReturnValue( STRING value )  Use FOR a STRING RETURN

  '  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

CREATING & USING A USER FUNCTION:

'   User Functions are created in much the same way as any other blox script is

'   created.  However, there are some steps needed that aren't used with TBB's

'   normal script writing process.

'  

'   To create a User Function, generate a new Blox of any type you want.  TBB

'   does not yet create a standard User Function Blox yet, so you'll need to

'   use one of TBB's normal Blox definitions as your starting point.

'  

'   Once you've named the new Blox, you should remove all the Script sections

'   listed in the new Blox as these won't be used for working with or creating

'   User Functions.  Script section can be removed or added using the Script

'   Menu item in the Coding window by selecting the "Delete" option when the

'   script section you want removed is highlighted.

'  

'   With all the script sections 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.

'  

'   Once you've created the script section, it will open a coding area where

'   you can code the script you want.

'  

'   Enter your code (see example Blox listed above).  With the code entered

'   you can then call this script from anywhere in the system by using the

'   following process:

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

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

                         example Blox listed above).

      PRINT lResult    '  Sends the User Function result to the Log Window

                       '  or the Print Output.csv file.

      Any_Var = lResult   '  Assigns the User Function Result to Any_Var

'   When you call a User Function like this, the calculation results are

'   returned to variable you place on the left side of the calling statement.

'   In this case, the variable "lResult" will hold the User Function

'   calculation value you created in your function script.

'  

'   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 TBB's Print

'   Output.csv file or Log Window.

'   When you create a User Function script, you'll need to assign the

'   calculation results to a script's return property.  This is done by

'   using one of the following methods:

      Script.SetStringReturnValue( AnyText ) '  Assigns a String Value Result

      Script.SetReturnValue( Any_Num )       '  Assigns a numeric Value Result

'   You can call a User Function witout 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 results:

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

  OR

     Any_Text = Script.StringReturnValue '  Use for STRING Return