Functions

Functions are used to break complex scripting tasks into smaller components. Using functions can enhance the reusability of your scripts by allowing you to build upon a library of routines you have already created, instead of starting over from scratch.

An OScript function takes the following form:

function [functionType] functionName ( [parameterList] )
	...block of code...
end

A function is created by specifying a function declaration, the function body, and an end statement. The function body (the statements within the function) is executed whenever the function is called.

Declaring a Function

A function declaration establishes the name, return type, and parameters passed to the function. An OScript function declaration takes the following form:

function [functionType] functionName ( [parameterList] )

The functionType is optional and specifies the type of value returned by the function. If functionType is not included, the OScript compiler assumes a Dynamic return value. If the function does not return a value, the void keyword can be used to indicate this.

function void myFunction()
	... block of code ...
end

The functionName is required and specifies the name by which the function will be called. It can include letters, numbers, and underscore characters, but the first character must be a letter. It cannot include spaces and must be less than 256 characters long. (If the script is executed as an Object method, the function name is ignored and the object's feature name is used instead.)

The parameterList is optional and specifies the names that will be used, locally, to reference the parameters. Note that the parentheses surrounding the parameter list are not optional. If included, parameter names are separated by commas, can optionally be preceded by a data type specification, and can optionally be followed by a default value assignment.

function Integer myFn( name, Integer height, Integer age = 32 )

If a data type is not specified for a parameter (as in the above example), the compiler assumes the parameter is Dynamic. If a parameter is assigned a default value, all subsequent parameters must also be assigned a default value. If a value is passed in for a defaulted parameter, the passed-in value overrides the default value. Any parameter that does not have a default value is required; any parameter that has a default value is optional. For more information, see the Calling Conventions section.

All parameters passed to a function are passed by value; the function can operate upon the passed-in value, but does not change the value in the calling code. When you pass a reference data type, even though the reference itself is passed by value, modifying it does change the shared contents of the value in the calling code.

Return Value

The return statement can be used to return a value from a function if the function is not declared to return void. The return statement must be placed within the function body (after the declaration but before the end statement) and takes the following form:

return value

The return statement not only returns a value, but causes the function to return (in other words, stop execution) at the point the return statement is encountered.

function Integer addThreeNumbers( Integer a, Integer b, Integer c )
	Integer sum
	Integer product
	sum = a + b + c
	return( sum )
	product = a * b * c// function will never execute this line
end

If no return statement is included, control returns to the calling function when the end statement is encountered. A return statement can return only a single value, however, that value can be of a complex data type, such as an Assoc, List, or Record, which contains many values.

function List MathOperations( Integer a, Integer b, Integer c )
	List listOfValues
	listOfValues[ 1 ] = a + b + c
	listOfValues[ 2 ] = a - b - c
	listOfValues[ 3 ] = a * b * c
	listOfValues[ 4 ] = a / b / c
	return( listOfValues )
end

Calling Conventions

A function call passes execution control from the calling function to the called function. The parameters, if any, are passed by value to the called function. Execution of a return statement or encountering the end statement in the called function returns control and possibly a value to the calling function.

To call a function, call it by name and pass it the appropriate parameters. If you pass a function more parameters or fewer parameters than it accepts, an Error will occur.

List mathList = MathOperations( 10, 34, 16 )

Any parameter that does not have a default value assigned is required; any parameter that has been assigned a default value is optional. You can override the default value assigned to a function parameter by passing it a value. However, to override a defaulted parameter, values must be specified for all parameters preceding it, as well. The call Fn( 1, 2, , 4 ) syntax used in some programming languages is not valid in OScript. For example:

function Integer myFn(String require1,\
		Integer require2,\
		Integer option1 = 3, \
		String who = 'Joe' )

In the above example, the myFn function accepts four parameters, two that are required and two that are optional. You must pass values for require1 and require2, but you do not need to pass a value for option1 or who. However, if you want to pass a value for who, you must also pass a value for option1.

Recursion

OScript functions can be recursive. OScript maintains a limit of 127 levels of recursion.

function Integer calcFactorial( Integer n )
	if n == 1
		return 1
	else
		return n * calcFactorial( n - 1 )
	end
end

In the above example, the OScript calcFactorial function calls itself until it is complete.

Main Function

Every script contains one main function and zero or more additional local functions. The compiler considers the first function in your script to be the main function and all other functions to be local functions. The contents of the main function are determined in one of two ways:

• If the first statement in your script is a function declaration, all lines of that function constitute the explicit main function, regardless of the name of that function.
• If the first statement is not a function declaration (excluding comments), all lines up to, but not including, the first function declaration constitute the implicit main function.

Local OScript functions can only be called by the main function in the same script. You cannot call a local function from another script.

The following examples illustrate explicit and implicit main functions.

// This file contains an explicit main function that
// calls a local function
function void MyMainFunc()
	Echo( "Here I am in main" )
	MyLocalFunc()
end

Function void MyLocalFunc()
	Echo( "here I am in a local function" )
end

In the above example, the explicit main function MyMainFunc calls the local function MyLocalFunc.

// This file contains an implicit main function
// that calls a local function
Echo( "Here I am in main" )
MyLocalFunc()
function void MyLocalFunc()
	Echo( "here I am in a local function" )
end

In the above example, the implicit main function calls the local function MyLocalFunc.

// This file contains an implicit main function with no local 
// functions
Echo( "Here I am in main" )

In the above example, the implicit main function calls no local functions.

The main function is the only function within the script that can be called from another script, however, it is not called by function name, but rather by the name of the method containing it.

For example, in the MyObject object there are two methods: myMethod and yourMethod. For yourMethod to properly call the main function of myMethod, the two methods should be structured as follows:

Contents of myMethod:

function void mainOfMyMethod()
	IntegertheValue
	... block of code ...
end

Contents of yourMethod:

function void mainOfYourMethod( Integer numberOfTimes)
	Integer n
	for n = numberOfTimes downTo 1
		this.myMethod()
	end
end