Functions

A function is a reusable block of code that accomplishes a certain task. Any time you need that task, you can use the function in your script. This saves you the time and effort required to add code for that task to your script each time you need it. It also keeps your scripts cleaner and less cluttered by reducing the amount of code in the script.

Functions can: 

• Take data from the script, manipulate it in some way, and then return the results back to the script.
• Perform an action or series of actions and pass the resulting data to the script.

Some functions are built in to Studio for use in your scripts. You don't need to add anything to your script to use a built-in function. When you want to use one, you can simply call it.

You can also create your own custom functions to use in a script. This is helpful when you have code you use frequently in your script. Rather than adding it to your script every time you need it, you can create a function that contains the code. Then when you need that code, you can call the function.

Syntax

Function names have a set of open and closed parentheses at the end of it: functionName().

Any text inside the parentheses are parameters, which define data that's passed between the function and the script: functionName(param1,param2).

To create a custom function, use this syntax: 

FUNCTION <name><([parameter], [...])> <{ ... [RETURN [data]]}>

In this syntax: 

• FUNCTION is the required keyword that begins all custom function statements.
• <name> is the name of the function.
• ([<parameter>] [...]) defines any parameters that the function requires.
• { ... } contains the code of the function.
• [RETURN <data>] is the statement to include to pass data from the function to the main script.

You can name your custom functions anything as long as you follow these guidelines: 

• Use alpha-numeric characters (a-z, A-Z, 0-9).

• The first character in the name must be a letter.
• Use the underscore character ( _ ) and the dollar sign ( $ ) anywhere in the name.
• Do not use reserved words or the names of built-in functions.

The syntax for a RETURN statement is:

RETURN or RETURN <var>

When calling a function, use one of the following syntaxes: 

<functionName><([parameter], [parameter], [...])>

<{<varName>.<functionName><([parameter], [parameter], [...])>}>

Parameters and Arguments

Many functions need to use data from the script. You can do this using parameters and arguments.

Parameters are defined when a function is created. A parameter is a variable name that appears in the parentheses that follow the name of the function. A function can have more than one parameter. Each parameter is separated by a comma. You can include a space if you want, but it's not required. For example, the function logn(value, base) has two parameters, value and base.

The specific data that the script passes into the function via the parameters are called arguments. The following example shows using the built-in function abs(value) in a script. In this example,  -42 is the argument that's passed into the value parameter.  

ASSIGN abVal = abs(-42)

In Studio, all parameters are required. If a function is defined with a parameter, you must pass a value in when you call the function. The number of arguments passed into the function must match the number of defined parameters.

The script doesn't check to make sure that the arguments are the right type or format. However, if the argument isn't the type or format that the function expects, the function may not complete successfully, or the results may not be accurate.

If too many or too few arguments are passed into the function, it causes a compile error when you run the script. This can happen for built-in functions and custom functions.

Argument Formatting

When calling a function that requires parameters, you must include the arguments you're passing into the function. Follow these guidelines for formatting the arguments:

• If the argument is numeric or a variable, you don't need to enclose it in single or double quotes.
• If the argument is a variable, you don't need to enclose it in curly braces.
• If the argument is alphanumeric and not a variable, enclose it in single or double quotes.

For example, the dateadd() function requires three parameters, unit, date, and value.

Unit defines the part of the date you want the function to change, such as the year or the month. Date is the original date you want to modify. And value is how much you want the function to increase the specified unit of the original date. The following example shows how each part is formatted:

ASSIGN NewDateYearNumeric = dateadd('year', MyDateTime, 1)

The unit is an alphanumeric string, so it's formatted with single quotes. The date in this example is a variable, so it doesn't have quotes. If you passed in a string date, it would require quotes. The value is not formatted because it's numeric.

RETURN Statements

A RETURN statement terminates a function and passes control back to the script. It can also pass data back to the script.

RETURN statements can only pass data to the script as a variable value or an array. They cannot pass multiple values, unless those values are part of an array or an object. They cannot pass objects, unless the objects are first converted to JSON. If necessary, you can convert it back to an object in the script.

The syntax for a RETURN statement is:

RETURN or RETURN <var>

All built-in functions that return a value to the script contain a RETURN statement. In custom functions that you create, RETURN statements are optional. If there isn't a RETURN statement, the function cannot pass any values back to the script. The only way you can use a function that doesn't have a RETURN statement is by calling it like a statement.

If you include a RETURN statement in a function, it must be the last line in the function.

Variable Visibility

The default behavior is that all values in the function are available and usable only within the function. When the function ends, all values in the function are lost. If the function contains a RETURN statement that passes a variable value back to the script, only the values passed through the RETURN statement are available outside of the function.

If you include variables in a custom function that exist in the main script, those variables have global scope. This means these values are available outside of the function without using a RETURN statement. Similarly, if you declare a variable within the function as global, its value is available in the main script. This is similar to the behavior seen in subscripts.

When you use a function in an expression or as the value of a variable, it follows the default behavior. However, if you call a function as a statement, all values in the function have global scope and are available for use outside of the function. For functions without a RETURN, this is the only way they can be used.

Create Custom Functions

You can create custom functions when you have code you want to be able to use in multiple places in your script. A custom function is only available within the script where you create it. If you want to use a custom function in a different script, you must copy the function definition code into that script.

You can create a function in one Snippet action in your script, then call it from other Snippet actions in the same script. If you debug the snippet containing the function definition, it's included in the debug. However, the function won't be included when you debug the other snippets.

The syntax to declare a custom function is: 

FUNCTION <name><([parameter], [...])> <{ ... [RETURN [data]]}>

FUNCTION is a keyword that lets the script know that what follows is a custom function. Function names must follow the same naming guidelines as other entities in scripts: 

• Use alpha-numeric characters (a-z, A-Z, 0-9).

• The first character in the name must be a letter.
• Use the underscore character ( _ ) and the dollar sign ( $ ) anywhere in the name.
• Do not use reserved words or the names of built-in functions.

If the function requires parameters, put them between the parentheses at the end of the function name. If there aren't any parameters, the parentheses can be left empty. Separate multiple parameters with commas.

The code that makes up the function goes between the curly braces. The placement of the curly braces is flexible. They can go on the same line as the FUNCTION keyword and name, or they can be on separate lines. For example, both of the following are valid function definitions: 

FUNCTION myFunction() { ASSIGN var = "value" } 

FUNCTION myFunction() 
{ 
	ASSIGN var = "value"
}

If the function includes a RETURN statement, it must be the last statement in the function before the closing curly brace.

You can learn more about creating functions on the Declaration Statements page.

Auto-Completion Help for Custom Functions

You can add auto-completion help for your custom functions. This is tool tip text that pops up when you begin typing the name of the function in the Snippet editor window. This help only appears when calling the function with dot notation.  

You can use these tool tips to give helpful information about the function. For example, you can use it to define the parameters of the function.

To add auto-completion help, add a comment on the same line as the function declaration. For example, to create the tool tip shown in the preceding image, your function declaration would look like this:

FUNCTION MyAppend(a,b) // My function to append the text
{
   RETURN "{a}{b}"
}	

If you add auto-completion help to a function, the curly braces containing the function code must be placed on a separate line from the function definition. The script considers all text after the two forward slashes to be part of the comment. If the curly braces are on the same line, the script includes them in the comment.

Call Functions in a Script

When you want to use a function in your script, you must call it. There are three ways you can call function. Not every option works for all functions. The options available for a given function depend on whether the function returns a value. You can call a function: 

• Alone like a statement. This option works with all functions.
• In a place where you'd use a variable or expression. This option only works with functions that return a value.
• With a variable using dot notation. This option only works with functions that return a value.

Call a Function as a Statement

A statement is a line of code with a command keyword that tells the script what to do. You can use a function as a statement. When you do, you don't need a special command keyword, as with other statements in a snippet. The code in the function tells the script what to do.

You can call any function as a statement. If a function doesn't contain a RETURN statement, this is the only way you can call it. This is because a RETURN statement passes data from the function back into the script. When there isn't a RETURN, being called as a statement is the only way the script has access to the data in the function.

The syntax for calling functions as a statement is: 

<functionName><([parameter], [parameter], [...])>

The following example shows the append() function being called like a statement: 

IF TEST = 1
{
  ASSIGN originalString = "My name"
  ASSIGN originalString2 = "Whose pajamas are these? "
  ASSIGN appendWithEscape = $"They're the cat's pajamas."			
}
originalString.append(" is Inigo Montoya.")
originalString2.append(AppendWithEscape)

Use a Function in Place of a Variable

When a function returns a value, you can use it anywhere you would use a variable or expression. The script can use the value that the function returns as it would the value of the variable or the result of the expression.

The syntaxes for using a function in place of a variable are: 

<functionName><([parameter], [parameter], [...])>

<{<varName>.<functionName><([parameter], [parameter], [...])>}>

If you want the result of the function to be assigned to a variable, you can call the function as part of an ASSIGN statement. For example, ASSIGN var = otherVar.function(). However, there is one case where this does not work, and that is to call a member function of the GetRESTproxy() function.

The following example shows how you use a function that returns a value. This is the example function: 

FUNCTION replaceCharacters(string)
{
	ASSIGN adjustedString = string.replace("&", "and")
	RETURN adjustedString
}			

This is function replaces the ampersand character ( & ) with the word and. In the following example, the replaceCharacters() function is used in placed of a variable in the string value of the stringRes variable. When this code runs, the value of stringRes is updated to My favorite animals are dogs and cats.

ASSIGN testString = "dogs & cats"
ASSIGN stringRes = "My favorite animals are {replaceCharacters(testString)}."

Use a Function with Dot Notation

When functions return a value, you can use them with variables using dot notation. This attaches the function to the variable, like this: variable.function(). When you call a function in this way, the variable's value is passed into the function.  This option only works with functions that return a value.

The syntax for using a function with dot notation: 

<{<varName>.<functionName><([parameter], [parameter], [...])>}>

The following example shows this approach. This is the function: 

FUNCTION MyAppend(a,b)
{
   RETURN "{a}{b}"
}	

This is a FOR loop that uses the MyAppend function with the variable ph:

FOR i=1 TO 9
{
   ph = "{ph.MyAppend(i)}"
}

The result of the FOR loop is: ph="123456789".

When you call a function using dot notation, the value of the variable it's attached to is passed into the function as the argument for the first parameter. In the preceding example, the initial value of ph is passed into the MyAppend() function as the argument for parameter a. This is why the function call includes only one argument when the function definition has two parameters. The initial value of i is passed to the function as the argument for parameter b.

The benefit of calling functions with dot notation is that it allows you to add tool tip help for the function.