Skip to content

IMan (VB)Script Language Reference

IMan evaluates expressions in VBScript. The language appears in the Map, Filter and Aggregate transforms, in the Script Task, and in every setup field that takes an evaluated expression, such as a file name or a URL.

IMan adds two things to the language:

  • Field references. An expression reads the dataset through the % syntax, described under Field references below.
  • Its own functions. Mid, Replace and InStr are standard VBScript. Lookup, Sum and Count are IMan's. The VBScript Function Reference lists both.

Everything else is VBScript:

  • The language is dynamically typed. Every variable is a Variant, and nothing declares a String, an Integer or a Boolean.
  • An expression carries no Function and no End Function line. IMan writes both.
  • You do not declare the result. The last line of the expression is the result.

Components of the language

  • Syntax — statements, comments, line breaks and the words an expression cannot use.
  • Variables — holding a value while the expression runs, constants and objects, and how Empty and Null differ.
  • Operators — arithmetic, comparison, logical and concatenation.
  • Decisions — If, ElseIf and Select Case.
  • Loops — For, For Each, Do and While.
  • Arrays — declaring and resizing a set of values held in one variable.
  • Functions — calling a function, and writing your own in Common Functions.
  • Error handling — what IMan does when an expression fails, and how to trap an error yourself.

What an expression is

An expression is a piece of script that returns a value. It may be a single line or many lines.

The three kinds

  • Field expression. Sets the value of one field. The Map and Aggregate transforms hold these. Write it over as many lines as you need, and declare local variables in it.
  • Record evaluation expression. Applies to a whole record rather than to one field, and decides something about it. The Filter transform holds these, and so does the Aggregate transform's grouping. Write it over as many lines as you need, and declare local variables in it.
  • Inline expression. Generates one value for a setup field, such as the file name a Writer transform will write to. An inline expression is a single line. It cannot declare a variable.

A Filter's record evaluation expression must return True or False. IMan converts the result, and reports "The evaluated expression […] could not be converted to a True/False value" when it cannot.

The last line is the result

IMan wraps your expression in a function and assigns the function's result from the last line.

The last line must be an expression. IMan writes the assignment onto the front of that line. The line has to be something with a value.

Dim NetValue
NetValue = %GrossTotal - %TaxTotal
NetValue

%GrossTotal of 1200 and %TaxTotal of 400 make the result 800. The bare NetValue on the last line returns it.

IMan ignores a trailing blank line. It walks back from the end of the expression past any line that is blank or holds only spaces, and uses the last line that has something on it. Leave as much white space at the foot of the expression as you like.

A continued statement keeps its result. Where the last line continues from the one above with an underscore, IMan puts the assignment on the first line of the statement rather than on the fragment at the end:

Dim NetValue
NetValue = %GrossTotal - %TaxTotal
"Net " & _
CStr(NetValue)

An assignment on the last line returns False

IMan prepends its own assignment to the last line. Where that line is already an assignment, VBScript reads the second equals sign as a comparison rather than as a second assignment.

Dim NetValue
NetValue = %GrossTotal - %TaxTotal

This does not return 800. NetValue never receives a value, and the expression compares the empty variable against 800 and returns False. Put the bare variable on a line of its own, or drop the variable and write the calculation as one line:

%GrossTotal - %TaxTotal

A Dim on the last line will not compile. VBScript reports "Expected statement", because IMan has written an assignment onto the front of a declaration.

Field references

A field reference reads a value out of the IMan dataset. Write a per cent sign followed by the field name:

%GrossTotal

or, with the name in square brackets:

%[Gross Total]

Use the brackets when the name is not a plain word. Without them IMan ends the field name at the first character that could start something else — a space, a comma, a quote, a bracket, a backslash, or any of > < = & + - * /. A name holding one of those needs the brackets. A dotted path does not need them. A full stop is not on that list, and %Orders.OrderNo and %[Orders.OrderNo] read the same field.

Write two per cent signs for a literal one. IMan turns %% into a single % and does not treat it as a reference. Write %% in a LIKE pattern and in an encoded URL.

A reference with nothing after it fails with "Empty field identifier.", and an opening bracket with no closing one fails with "Unclosed field name.".

Two fields in one expression

Dim NetValue
NetValue = %GrossTotal - %TaxTotal
NetValue

The same expression with both names bracketed:

Dim NetValue
NetValue = %[GrossTotal] - %[TaxTotal]
NetValue

When an expression fails

IMan reports the line and the position of a failure against the expression as you wrote it. It takes the wrapping function back off, subtracts the assignment it added to the last line, and allows for each field reference being longer or shorter than the variable name IMan put in its place. Count to that line in the editor to find the failure.

Error handling covers what happens to the run, and how to trap an error rather than let it stop the integration.