Automate encompasses a VBA-compatible engine designed to extend the functionality available in AML (Automate Markup Language), the primary internal language used by Automate. It allows multi-line BASIC scripts to be included in a task with the use of the BASIC Script action and allows all built-in Visual Basic functions to be used as an expression in any step of a task. Furthermore, Automate also includes a large collection of additional functions that extend the functionality of the Automate Scripting Engine beyond the capabilities of what the basic VBA-compatible engine provides. These functions are collectively referred to as "Automate Extended Functions."
This article will discuss functions, how they are used in Automate, and how they can add more intelligence to a task, thus, broadening the functionality of Automate.
Functions – General Overview
In computer programming, a function is essentially a predefined formula which automatically generates various kinds of output. Its main purpose is to accept certain input from the user and return a value which is passed on to the main program to finish the execution. Most programming languages such as VBScript come with a pre-written, built-in range of functions that perform various procedures or routines. For example, some pre-written VBScript functions include date and time functions (i.e. add a time interval to a date, display the current month and day, countdown to year 3000), string related functions (i.e. return a specified number of characters from the left or right side of a string, replace characters in a string), format functions (i.e. returns an expression formatted as a date or time, returns an expression formatted as a currency value) and much more.
Detailed information regarding a complete list of built in VBScript functions can be found in the Automate Help document under Reference -> BASIC Scripting -> Functions. Help on each function can also be accessed from the Expression Builder 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 popup menu that appears.
Automate extended functions can be extremely useful because they provide added functionality to a given task. The extended functions are capable of providing multiple attributes in regards to the task currently being executed, such as returning the path and filename of the currently running task, returning the amount of time the task or particular step within the task took to execute in minutes, seconds or milliseconds or returning the last error generated by a task step. They can supply system information, such as returning the computer name that Automate is running on, returning the IP address of the specified host name or local machine or returning the amount of space remaining on a specific drive. The extended functions can perform extensive date/time and file related procedures as well, such as returning the first or last day of the specified month, quarter or year, returning the number of files found in the specified folder or extracting the file name or the path within a particular string. Detailed information regarding all available Automate extended functions can be found in the Automate Help document under Reference -> BASIC Scripting -> Extended Functions.
Function Syntax
Most functions require other parameters in order to properly complete a procedure or routine. The general format of a function is its name followed by any arguments contained in between parenthesis:
FunctionName (arguments)
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.
Certain functions may not need arguments to properly perform its duty. For example, the Date() function returns the current system date and the Now() function returns the current date along with the time. For instance, if this was entered:
Date()
The returned result would be the current date value such as 1/1/2010.
If this was entered:
Now()
The returned result would be the current date and time value such as 1/1/2010 12:00:59 AM.
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. So, if this was entered:
Len(“Hello”)
The returned value would be 5.
Another example is the Automate extended function, ExtractFileName(), which requires a path and filename. So, if the following was entered:
ExtractFileName("c:\foldername\filename.txt")
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. So, 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 Automate extended function can be found in the Automate Help document.
Using Functions in Automate
Built-in VBScript functions along with Automate extended functions can be used to return data inside any action parameter that accepts expressions by surrounding the function with percent signs. Let’s use the Len() function as an example. This function can be used with a single ‘Message Box’ action by simply entering %Len(“Hello”)% in this action’s General tab properties under the Message to display parameter as shown in Figure 1-1 below.
Figure 1-1: Len(“Hello”) used in ‘Message Box’ action
When this task runs, the function will perform its procedure and return the results in a message dialog, as illustrated in Figure 1-2 below.
Figure 1-2 : Results of Len(“Hello”)
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, let’s assume that a variable named theFile is populated with the string value c:\foldername\filename.txt. In order to extract the filename from this string and view the results in a message dialog, the proper syntax to enter in a ‘Message Box’ step would be %ExtractFileName(theFile)% as shown in Figure 1-3.
Figure 1-3: ExtractFileName(theFile) used in ‘Message Box’ action
During task execution, a message dialog will display the properly extracted filename as shown in Figure 1-4.
Figure 1-4: Results of function ExtractFileName(theFile)
Now, let’s examine how a function and variable can be used as arguments inside another function. For instance, let’s assume that a variable named theFile is populated with the string value filename.txt. Suppose we need to strip the file extension from this filename. This can be accomplished by using the Left() and InStr() functions. The proper syntax to enter in a ‘Message Box’ step is %Left(theFile, InStr(theFile, ".")-1)% as shown in Figure 1-5 below.
Figure 1-5: Left(theFile, InStr(theFile, ".")-1) used in a ‘Message Box’ action.
The InStr() function residing inside the Left() function will first be evaluated. As we know, the InStr() function returns the position of the first occurrence of one string within another, therefore, this function will return the value 9 because “.” is the ninth character in filename.txt.
TheLeft() function is evaluated next. As previously noted, this function returns a specified number of characters from the left side of a string. As a result, this function will determine the first 9 characters contained in filename.txt subtracted by 1. The value that appears in a message dialog is filename, as illustrated in Figure 1-6 below.
Figure 1-6: Results of function Left(theFile, InStr(theFile, ".")-1)
Conclusion
Functions are normally associated with computer programming and therefore are often depicted by non programmers and novice Automate users as being too complicated to use. This is certainly not the case. The fact that Automate encompasses a Basic Script engine allows the ability to use functions in any task step parameter in the same manner as other expressions, such as variables or constants, without resorting to writing code. Additionally, for those that require more information about functions or wish to familiarize themselves with the internal workings of Automate, an array of information is documented in the Automate Help file by simply selecting Contents… from the Help menu.
Applies to: Automate 10
