Runtime Error Handling

When developing a Digitise app, you should allow within your Scripts for potential errors which could occur when the app is run.

By default Script errors, such as syntax errors, which arise at runtime will display an error message box which provides information about the type of error, the Script which was running when the error occurred and the line number within the Script at which the error occurred. When the user clicks the OK button to dismiss the message box, the Script is terminated and control returns to the app.

Other errors, such as data and communications errors, errors inserting or updating records in a remote data source or errors pertaining to the operation of controls, do not display in error message boxes and have to be handled within a Script.

The error message box varies slightly from Platform to Platform but contains similar information. For example, in the Windows Desktop Client the dialog box looks like this:

Picture showing the Runtime error dialog box on a Windows device.

and on an Android device it looks like this:

Runtime error dialog box on an Android device.

The title describes the category of error, e.g. Script Error in the examples above. Below this is a user-orientated description of the problem followed by the details section at the bottom, giving more information. When the user clicks on the OK button to close the message box, the current Script will be terminated at the line specified in the details and control returns to the app.

 

The Scripting language includes a number of Statements and Methods which relate to handling potential errors at runtime. These cover turning on and off the use of popup error messages and checking for and obtaining details of any errors, allowing you to include error handling within your Scripts.

If you turn off the display of the popup error messages described above, no message will be displayed to the user in the event that an error occurs whilst the app is being run. You can, however, use the error handling Scripting Methods and Statements to check for data, comms and some other errors within your Scripts and obtain information about any errors. These Methods return the same information as would be displayed in the details section of the error message box and allow you to handle any errors within your Scripts. If you are not displaying the popup error messages for your users, you should incorporate error checking within your apps' Scripts at appropriate points to enable any errors which might occur to be caught and handled gracefully within your Scripts.

  • Syntax errors are not handled by the error handling Scripting Methods and Statements when the display of popup error message boxes is switched off and will cause your Script to terminate without displaying any message.

 

The following error handling Methods and Statements are available:

This Statement hides the popup error message box for all errors.

If certain errors occur during the running of a Script, the Script will automatically move to the next line in the Script and continue running. No error message will be displayed. The types of errors covered here include data and communications errors, errors uploading and downloading data and some errors relating to the operation of controls.

If you are not displaying these errors to your users, you should incorporate error checking within your app at appropriate points to catch any such errors which might occur and allow them to be handled gracefully within your Scripts. You can call the GetLastError, GetLastDataError, GetLastErrorType and GetLastErrorLine Scripting Methods (see below) to obtain information about the last error which occurred.

This Statement has the same effect as the SetDataErrorOff Method described below.

 

This Statement hides the popup error message box for all errors.

If certain errors occur during the running of a Script, the Script will look for the specified label within the Script (see below) and, if found, continue running from there. No error message will be displayed. The types of errors covered here include data and communications errors, errors uploading and downloading data and some errors relating to the operation of controls.

This Statement has a global scope, allowing you to call it anywhere within your Script. Once called it will continue in operation until you recall it specifying a different label to move to or call one of the other error handling Statements or Methods to cancel it.

The <label> specified in the Statement call MUST be located within the Scripting Function in which the error actually occurs, otherwise the Script will terminate without displaying an Error.

For example, you could include the call within the Application OnLoad Event specifying a label of errorhandler and then create a section within each of your individual Scripting Functions headed with the label errorhandler:. In this case, whenever an error occurred, the Script would execute the code within the errorhandler section. However, if you forgot to add the errorhandler section to a particular Function, any errors occurring within that Function would simply cause the Script to stop.

 

This Statement allows you to provide markers within your Scripts to which the Script can be directed to jump to and continue running from there.

To add a labelled section to a Script, simply add a line in the format <label>: before the lines of code you want to include within the section. You can give a label any name you like except for any of the Scripting reserved words.

For example:

[code statements]

errorhandler:

[code statements 2]

In this example, the Script lines represented by [code statements 2] fall within a section called errorhandler.

Note, that you can't include a label within a conditional Statement, i.e. within an If, While or For Statement.

You can use the Statements GoTo <label> or On Error GoTo <label> (see above) to instruct your Script to jump to the specified label within the Script and continue running from there. Any lines of code in between will be ignored.

GoTo <label> jumps immediately to the specified label and the label must be within the same Function as the GoTo call.

On Error GoTo <label> will only jump to the specified label if an error occurs. The labelled section must be within the Function in which the error actually occurs, otherwise the Script will terminate silently.

 

Note that a label doesn't signify the end of the code segment above it. For example, in the following Script:

On Error GoTo errorhandler

[code statements]

errorhandler:

[code statements 2]

confirmexit:

[code statements 3]

an error in [code statements] would cause the Script to jump to the errorhandler section. The Script would execute [code statements 2] and then continue to execute [code statements 3]. Likewise, if no error occurs, the Script will execute all three code segments.

If you want a label to segregate sections of your Script, you will need to provide for this within your Script code, e.g. you could call the Exit Function Statement before a label or include the contents of a labelled section within an If Statement which means the code is only run in the circumstances specified by the If Statement condition.

 

This Statement turns on the display of the popup error message dialog for syntax, data, communications and some control-related errors after it has been turned off by an earlier call to On Error Resume Next, On Error GoTo <label> or SetDataErrorOff(). If one of these types of error occurs, it will be notified to the user in a popup error message and processing of the Script will stop. When the user closes the error message, they will be returned to the app.

This Statement has the same effect as the SetDataErrorOn Method described below.

Other types of error will not display the dialog box.

 

Calling the SetDataErrorOn Method is equivalent to calling the On Error GoTo 0 Statement (see above).

 

Calling the SetDataErrorOff Method is equivalent to calling the On Error Resume Next Statement.

If you are not displaying Data errors for your users, you should incorporate error checking within your app at appropriate points to enable any errors which might occur to be handled gracefully within your Scripts.

 

The GetLastError Method returns a description of the last error which occurred.

 

The GetLastErrorLine Method returns the line number within the Script at which the last error occurred or -1 if no error has occurred.

 

The GetLastErrorType Method returns a string specifying the category of error for the last error which occurred.

 

The GetLastDataError Method returns a description of the last data or communications error that occurred. The description matches the information that would be displayed in the details section of the Error dialog box, if this dialog were displayed.

GetLastDataError has been superseded by the newer GetLastError (see above) and we recommend using GetLastError as it covers a wider range of possible error types than GetLastDataError. However, if you have disabled the newer error handling functionality introduced in Digitise Apps' predecessor MX (v10.3), you must use GetLastDataError; you cannot use GetLastError - see below for more details.

 

  • When running Scripts on Android devices, to improve performance, Scripts generally don't update the screen until the Script finishes, unless a call to a Method, such as MsgBox or GetControlValue, necessitates a screen update. This means you won't see some screen changes until the Script exits.

    However, if you call On Error GoTo <label> or On Error Resume Next, this deferred screen updating is turned off because if a problem were to arise during the deferred operation the Script would have already finished and the On Error Statement could no longer be executed. Calling On Error GoTo 0 will resume deferred screen updating.

    When deferred screen updating is off, if you notice reduced performance in your app, you can call On Error GoTo 0 before affected sections of your Script. However, generally, we recommend calling On Error Statements at the top or bottom of Functions and avoiding turning error handling on and off throughout a Function.

  • Errors relating to problems inserting and updating records in a remote Target database are not available via the GetLastError or GetLastDataError Methods. These errors are accessed using GetNumSyncErrors, GetSyncErrorDataSource, GetSyncErrorDescription and GetSyncErrorRecordIndex instead. These errors are not, therefore, affected by calls to the error handling Statements and Methods and must be checked independently.

 

In order to preserve backward compatibility for apps originally created using Digitise Apps' predecessor MX, a project-level Property determines whether the newer error handling Statements and Methods introduced in MX v10.3 should be recognised by the Syntax Checker and at runtime. The Property is called Enable Script Error Handling and can be found in the Project Properties within App Studio, by selecting the root node in the Forms, Data Sources or Resources Panes.

The Statements and Methods introduced in MX v10.3 are: On Error Resume Next, On Error GoTo <label>, <label>:, On Error GoTo 0, GetLastError, GetLastErrorLine and GetLastErrorType. SetDataErrorOn, SetDataErrorOff and GetLastDataError were all introduced in versions of MX before v10.3.

If the Enable Script Error Handling Property is set to True, the v10.3 Statements and Methods can be used and their names or constituent words will be counted as reserved words and cannot be used, for example, as variable names. This means you can use either the GetLastError or GetLastDataError Scripting Methods, described above, to check for errors, though we recommend the newer GetLastError as it covers a wider range of error types than GetLastDataError.

If the Property is set to False, error handling works as it did prior to MX v10.3. Only the Methods available prior to v10.3 can be used and the names and constituent words of the newer Statements and Methods will not count as reserved words, allowing such code statements as Dim error = "" to be permitted. In this situation, you cannot use the GetLastError Scripting Method to check for errors and must use GetLastDataError instead.

If you open a project created using a version of MX earlier than v10.3 in the latest App Studio, Enable Script Error Handling will automatically be set to False by default. New projects and projects created using MX v10.3 or later will have it set to True. This means that if you load a pre-MX v10.3 Project into the latest App Studio you will need to set this property to True if you want to use the newer Statements and Methods.

 

If you are using an awi Web Service Data Source, you can pass information about errors which the Web Service encounters back to the Digitise Apps Client by returning the following XML format:

<ndlm-message>

<Type> </Type>

<Category> </Category>

<Code> </Code>

<Description> </Description>

</ndlm-message>

If errors are being reported to users in popup error messages, this string will be displayed within the details section of the error message. If errors are not displayed in popup error messages, you can obtain the string within your Script using the GetLastDataError Method, in which case the information contained in the message will be presented in the format:

Type=Typevalue, Category=Categoryvalue, Code=Codevalue, Description=Descriptionvalue

 

 

More details about using any of the Methods mentioned in this topic can be found in the descriptions for the individual Methods, which can be accessed from one of the Method lists: Alphabetical List of Methods or List of Methods by Category.