Functions & Extended Functions

In computer programming, a function is predefined code which can generate various kinds of values depending on certain input from the user. Most programming languages such as VBScript come with a pre-written, built-in range of functions that perform various procedures or routines. Functions can be used as an expression in any task step, thus, adding more intelligence to a task and further broadening the functionality. Additionally, contains an extensive collection of additional functions that increase the functionality of the Scripting Engine which are called extended functions.

Function Syntax

Most functions require other parameters to properly complete a procedure or routine. The general format of a function is its name followed by any arguments contained in between parenthesis. An argument (sometimes referred to as parameters) is a value sent to the function when it is called upon. By passing an argument to a function, the function is given information to work on. A basic function would look like this:

FunctionName(arguments)

Certain functions may not need arguments to properly perform its duty. A function without arguments must include an empty set of parentheses (). For example, the Date() function returns the current system date and the Now() function returns the current date along with the time. These functions require no arguments or parameters in which they need to perform any procedures on, therefore the proper syntax are simply the functions themselves, with nothing entered in between the parenthesis. For instance, if the following syntax was entered:

Date()

The returned result would be the current date value such as 1/1/2010.

An example of a function which requires arguments is the Len() function, which returns the number of characters in a string. The syntax for this function is Len(“string”) which requires a string to be entered inside the parenthesis in which it will perform calculations on. For example, if this was entered:

Len(“Hello”)

The returned value would be 5.

Another example is the extended function, ExtractFileName(), which requires a path and filename in between the parenthesis in which it will extract the file name from. So, if the following was entered:

ExtractFileName(c:\

The returned value would be filename.txt.

An example of a function requiring more elaborate arguments is the Left() function, which returns a specified number of characters from the left side of a string. The syntax for this function is Left(“string”, length) which requires a valid string followed by the amount of characters to return inside the parenthesis. If the following was entered:

Left("AutoMate", 4)

The return value would be Auto.

Another example is the InsStr()function which returns the position of the first occurrence of one string within another. The search begins at the first character of the string. The syntax for this function is InStr(“string1”,“String2”). So, if the following was entered:

InStr(Hello,o)

The return value would be 5 signifying that the letter “o” is the fifth character in the word “Hello”.

NOTE: Sample syntax for each function and extended functions can be found in the Help document.

Using Functions

Built-in VBScript functions along with extended functions can be used to return data inside any action parameter of a task that accepts expressions by surrounding the function with percent signs. This tells that the contents in between the percent signs should not be taken literally, but used as an expression instead. For example, the Len() function can be used within Message dialog activity by simply entering the following syntax in the Message to display parameter (highlighted below):

%Len(“Hello”)%

As previously mentioned, the Len() function returns the number of characters in a string. When the task runs, the Len() function will be performed and a message dialog displaying the results will appear, as illustrated below.

Expressions such as variables, constants or other functions can be used as arguments or parameters entered inside the parenthesis of a function. In such cases, the specified expression needs to be entered by itself (omitting any percent signs, quotes or other characters). For example, assume that a variable named %theFile% is populated with the string value c:\folderName\fileName.txt. to extract only the filename from this string and view the results in a message dialog, the proper syntax to enter in a Message Dialog step would be:

%ExtractFileName(theFile)%

As shown below.

During task execution, a message dialog will display the properly extracted filename as shown below.

Using Expression Builder

The Expression Builder is a valuable tool used to assist in the creation and examination of expressions. When using the Expression Builder, help regarding each function can be accessed by first selecting the Functions folder from the lower left pane, then selecting the desired function from the lower right pane and pressing the F1 key or by right-clicking the function and selecting Help from the pop-up menu that appears.

See Expression Builder for more details.