Writing your own error handler

The normal place for this statement is at the top of the routing script, but you can use it elsewhere too if you want to handle errors differently at different parts of the interview.

Any valid routing or mrScriptBasic statements that you want to execute when a run-time error occurs. The most common statements are those that write information to a log file, but you may also want to display an explanatory message for the respondent or interviewer.

You can define more than one error handler as long as each one has a unique label. You can put them anywhere in the routing section, although at the start or end of the section are the most usual places.

If you put the error handling code at the start of the routing section, you'll also need a statement that skips over the code to the first instruction in the interview itself. The way to do this is to mark the start of the interview with a label and jump to that. For example:

Since the error handling section will either terminate the interview with an error message or end with Resume Next to continue with the next question, there is no need to include a statement that specifically marks the end of this section. However, if the error handler does not use Resume Next, it is good practise to mark the end of the error handler with an Exit statement to ensure that the interviewing program stops when it reaches the end of this code.

When the error handler is at the end of the routing section, you need to mark the end of the main interviewing section so that the interviewing program stops when it reaches this statement. The statement you use is Exit:

Here’s an example of an error handler that writes a message to the log file and also displays a message for the respondent or interviewer. The text of the message that the respondent or interviewer sees is defined in the metadata section of the script as follows (the message is spread over a number lines for readability, but must be typed all on one line in the script):

ErrorDisplay "A processing error has occurred. If you have a
moment to spare, please help us to resolve the error by clicking
  <a "mailto:_helpdesk@unicomsi.com?subject=Error in survey
  {ProjectName} &body=Please enter any details about what
  happened here:%0A%0A Technical details:%0ATime of error (UTC) =
  {TimeStamp}%0A Project = {ProjectName}%0ARecord identifiers =
  {Serial}, {RespId}%0A {ErrorDetails}"">here</a> to send an
  email description of the problem. <br/><br/>Please return later
  to try again. Thank you for your help."
info;

The texts in curly braces are the names of variables whose values are set in the routing section (they are called Inserts), and the %0A strings generate new lines in the text when it is displayed in the email window.

ErrorHandler2:
Dim err_msg
' Write message to log file
err_msg = "Error executing script (line " + _
CText(Err.LineNumber) + "): " + Err.Description + " (" + _
CText(Hex(Err.Number)) + ")"
Debug.Log(err_msg, logLevels.LOGLEVEL_ERROR)
' Populate inserts for user message
ErrorDisplay.Label.Inserts["TimeStamp"].Text = Now("UTC")
ErrorDisplay.Label.Inserts["ProjectName"].Text = IOM.ProjectName
ErrorDisplay.Label.Inserts["Serial"].Text = CText(IOM.Info.Serial)
If (IOM.Info.RespondentID = "") Then
ErrorDisplay.Label.Inserts["RespId"].Text = "Unavailable"
Else
ErrorDisplay.Label.Inserts["RespId"].Text = IOM.Info.RespondentID
End If
ErrorDisplay.Label.Inserts["ErrorDetails"].Text = err_msg
' Display message
IOM.Texts.InterviewStopped = ErrorDisplay.Label
' Terminate interview and flag as failed due to script error
IOM.Terminate(Signals.sigError)

All the statements that mention the Inserts property are placing information about the interview in variables that are part of the message that the respondent or interviewer sees. See Programmatically inserting text into labels for further information about Inserts.

IOM.Text.InterviewStopped is the standard text that is displayed when an interview stops for any reason. Our script sets it to be the same as the message text that is written to the log file.