Error Handling

An expression fails in one of three ways.

Syntax errors

A syntax error stops the expression from compiling. Nothing in it runs. This line never closes its bracket:

Dim ItemName
ItemName = UCase(%ItemName

VBScript reports "Expected ')'" against the line and position it reached.

IMan compiles the expression when you save the transform and when you run a preview. A syntax error shows up at one of those two points and never affects any data.

Runtime errors

A runtime error happens while the expression runs, on a line that compiled without error. Dividing by a quantity that turns out to be zero raises error 11, "Division by zero":

Dim NetValue
NetValue = %GrossTotal / %Qty
NetValue

The expression is correct for every record where %Qty holds a number above zero, and it fails on the first record where it does not. Runtime errors are the ones that reach production, because the record that triggers one was not in your sample data.

Logic errors

A logic error compiles and runs and returns the wrong answer. The expression below returns 0 on every record. The author meant to subtract the tax and typed the wrong field:

%GrossTotal - %GrossTotal

Nothing reports a logic error. Compare the result against a figure you already know. The transform preview and the audit report both show you the value the expression produced.

What IMan does with an error

IMan catches the failure and names three things in the message: the field, the transaction, and the position in your expression.

Error whilst evaluating expression on for field [NetValue] on transaction [ORD-10432]. Error - Division by zero at Line [2] Position [0]

The line and position count against the expression as you wrote it. IMan wraps the expression in a function before running it, then takes the wrapping back off the position it reports.

A Filter expression that returns something other than True or False fails differently. IMan reports "The evaluated expression […] could not be converted to a True/False value".

An integration setting decides what happens to the run. Two drop-downs on the integration's Audit tab decide it, and both default to Abort:

• Default Action on Transform Error — Abort, or Reject Record. What Reject Record does depends on the transform.
• Action on Transform Failure — Abort, or Continue to run the rest of the integration once a transform has failed.

Trapping an error yourself

On Error Resume Next stops VBScript from raising the error to IMan. Execution carries on at the next line, and the Err object holds what went wrong.

Dim NetValue
On Error Resume Next
NetValue = %GrossTotal / %Qty
If Err.Number <> 0 Then
  NetValue = 0
  Err.Clear
End If
On Error Goto 0
NetValue

• Err.Number is zero when nothing has failed. Division by zero is 11 and a type mismatch is 13.
• Err.Description is the text, such as Division by zero.
• Err.Clear resets both. Clear the error once you have handled it, or the next test sees the old one.
• On Error Goto 0 turns trapping off again. Anything that fails after it reaches IMan as normal.

Failing a record deliberately

Err.Raise fails an expression on purpose. When the expression can see that the data is wrong, raise an error. Do not return a value the target system will accept:

If %CustomerRef = "" Then
  Err.Raise 5000, "Validation", "Order " & %OrderNo & " has no customer reference"
End If

%CustomerRef

IMan handles the raised error like any other. The two Audit tab settings above decide whether IMan rejects the record or stops the transform. The message reports the description you gave it:

Order 10432 has no customer reference at Line [2] Position [2]

The source, Validation here, does not appear in the message.

Always pass a description. Err.Raise 5000 on its own reports "Unknown runtime error", and the audit report then gives no clue what went wrong. Number the errors from 5000 upwards to stay clear of the numbers VBScript uses itself, and put the identifier of the record in the description.

On Error Resume Next hides every error, not the one you had in mind

Between On Error Resume Next and On Error Goto 0, every failing line is skipped with no error raised, and the expression carries on with whatever the variables held before. Turn trapping on immediately before the line that can fail, test Err.Number immediately after it, and turn it off again. An expression that opens with On Error Resume Next and never tests Err returns a wrong answer in place of failing.