Functions and Subroutines

FRED's scripting language is a version of BASIC called WinWrap, developed by Polar Engineering and Consulting ( http://www.winwrap.com/web2/).  The implementation combines a powerful Integrated Development Environment (IDE) with a fully extendable language that allows for creation of classes, methods, script libraries and automation with other applications using COM.

Raytrace and analysis tasks can be automated entirely through FRED's scripting language, providing a powerful complement to the ease of model creation using FRED's GUI.  Scripts, when executed, start in the Main() subroutine, but custom subroutines and functions can also be added.  Rather than placing all of the scripting code into the Main() subroutine, breaking the code down into a smaller collection of subroutines and functions can facilitate script extension, readability and debugging.

What is a Subroutine?

A subroutine is a collection of code that performs a task but does not return a value after it executes.  The collection of code in a subroutine is enclosed by the Sub and End Sub keywords and can be declared in the following way.

Sub DoStuff( ByVal argument1 As Long, ByVal argument2 As Double )      

'Here we implement some code that uses argument1 and argument2

End Sub

In this example, we have declared a subroutine called DoStuff that requires two input arguments when the subroutine gets called, and the two arguments would be used to implement the task being performed by the subroutine.

What is a Function?

A function is similar to a subroutine except that it returns a value to the calling object after it executes.  The collection of code in a function is enclosed by the Function and End Function keywords and can be declared in the following way:

Function Add2( ByVal arg1 As Double, ByVal arg2 As Double, ByRef sum As Double ) As Boolean

	sum = arg1 + arg2      
	Return True

End Function

In the example above, three arguments are passed into the function call, and the function returns a Boolean value.  Inside the function, the first two arguments are added together, and the result is assigned to the variable sum, which was passed in as the third argument (more on this below).  The function then returns True value, which may be used as an indication that the function executed successfully.  There is no requirement that the return value be a Boolean; it can be any valid data type.

What are ByVal and ByRef?

In our example subroutine above, the first argument, argument1, is passed into the subroutine ByVal (pass by value), meaning that the argument acts like a local variable to the subroutine.  The subroutine can modify the value of argument1 and the object that called this subroutine will not see any of the modifications.  Passing an argument ByVal should be used when the value of the argument should be preserved both before and after the subroutine or function execution.

In the example function above, the third argument, sum, is passed into the function ByRef (pass by reference), meaning that the function can modify the value of the argument AND the changes will be seen by the calling function.  In other words, you can pass in an argument by reference and after the function executes the variable may have a modified value.  In this way, arguments passed by reference can act like return values.  The Add2 example effectively has two return values; the function call itself returns a Boolean and the third argument was passed by reference and then modified by the function.

Example Usage in a FRED Script

The above examples and description apply generically to BASIC, but how might we use them when writing scripts in the context of FRED itself?

The example FRED file (link below) contains 9 source nodes and an embedded script called, "Subroutines and Functions".  The intention of the script is to demonstrate how a custom Subroutine and custom Function can be used to facilitate the following tasks:

1. Retrieve the node numbers for all sources in the model.
2. For each source with ray positions type, "Random Plane", update the source ray counts.

Associated FRED file:  FRED Scripting Functions and Subroutines