Functions¶

A function takes zero or more values, does something with them and returns a result. An expression calls functions to do most of its work.

Three sets of functions are available:

The VBScript functions, such as Left, Mid, Replace and InStr.
IMan's own functions, such as Lookup, Sum and Count. The VBScript Function Reference documents both sets.
Your own, written once in Common Functions and called from any transform or task that takes VBScript.

Calling a function¶

Write the name of the function and put its arguments in brackets, separated by commas:

Left(%ItemName, 7)

Call a function that takes no arguments by its bare name:

Now

Always write the brackets. An expression uses the value a function returns, and VBScript needs the brackets to read the call that way. Left %ItemName, 7 fails with "Expected end of statement".

Arguments¶

A comma separates each argument from the next, and the order decides which is which. Left takes the string first and the number of characters second:

Dim ItemPrefix
ItemPrefix = Left("IC-1000-BLUE", 7)
ItemPrefix

The expression returns IC-1000.

Optional arguments¶

Some functions take an argument you may leave out. Leaving it out selects a different behaviour rather than passing nothing.

Mid takes the string and the position to start at, and optionally the number of characters to take. Without the third argument it takes everything from the starting position to the end:

Mid("My Parsed String", 11)

That returns String. With the third argument it takes that many characters:

Mid("My Parsed String", 11, 3)

That returns Str.

An optional argument can usually only be left off the end. To pass a later one, pass every argument before it. InStr is the exception. Its optional start position comes first, and InStr("IC-1000", "-") searches from the first character and returns 3.

Writing your own function¶

Put the function in Common Functions and any transform or task that takes VBScript can call it, including the single-line setup fields that accept no Dim of their own. A function has three parts:

The header. The word Function, the name, and the arguments in brackets.
The result. An assignment to the function's own name.
The end. The words End Function.

Function ItemPrefix(ItemCode)

  ItemPrefix = Left(ItemCode, 7)

End Function

An expression then calls it like any other function:

ItemPrefix(%ItemCode)

Assigning the result¶

A function assigns its own result explicitly. An expression returns its last line. A function returns whatever was last assigned to its name, wherever in the body that assignment happened. Each branch can therefore set its own result:

Function SizeBand(Qty)

  If Qty > 10 Then
    SizeBand = "large"
  Else
    SizeBand = "small"
  End If

End Function

A function that never assigns its name returns Empty. No error is raised, and the calling expression carries on with the empty value. Give every branch an assignment, or assign a default at the top of the function and let a branch overwrite it.

Leaving early¶

Exit Function ends the function at once. The result is whatever the function's name held at that point:

Function SizeBand(Qty)

  SizeBand = "small"
  If Qty <= 10 Then Exit Function

  SizeBand = "large"

End Function

Changing an argument¶

A function can change the caller's variable. VBScript passes each argument by reference unless told otherwise. An assignment to the argument inside the function reaches the variable the caller passed:

Function CleanCode(Code)

  Code = UCase(Trim(Code))
  CleanCode = Code

End Function

An expression that calls CleanCode(Raw) finds Raw changed as well. Write ByVal in the header, Function CleanCode(ByVal Code), to give the function its own copy. ByRef spells out the default.

Sub¶

A Common Function can also be a Sub. A Sub does its work and returns no value. Call one on a line of its own, either with Call and brackets or bare without them:

Call TidyCode(Raw)
TidyCode Raw

Brackets without Call pass a copy

TidyCode(Raw) compiles, and VBScript reads the brackets as part of the argument. It passes a copy of Raw, and the change the Sub makes never reaches it. With two arguments, TidyCode(Raw, 10) fails to compile with "Cannot use parentheses when calling a Sub".

A Sub has no result to use, and Code = TidyCode(Raw) raises "Type mismatch". Call runs a function too, and discards its result.