Aspects of error handling
 |
This article or section is currently being developed or reviewed. Some statements may be disputed, incorrect, unverified, biased or otherwise objectionable. Please read the discussion thread before making substantial changes. |
Writing VIs and SubVIs that incorporate error handling is considered good form, not only to allow the user indication of abnormal software execution, but also to allow the software to make decisions based on the status of previous operations. Including error clusters in your code assists in troubleshooting, modularity, and user friendliness.
The Error Cluster
The error cluster is a predefined LabVIEW cluster that is used to contain error status information. The cluster contains the following three components:
| Name | Data Type | Description |
|---|---|---|
| Status | Boolean | Indicates if an error has occurred (TRUE = error, FALSE = no error). |
| Code | 32-Bit signed integer | A standardized error code specific to the particular error. LabVIEW has a table of default error codes, although the user is able to define custom error codes. See below for more information. |
| Source | String | Textual information often describing the error and the VI it occurred within. |
Usage
Although one of the most obvious methods of conditional code execution might be to unbundle the Status Boolean of the error cluster, and feed it to the conditional terminal of a case structure (figure coming soon...), the complete cluster can be wired to it instead (figure coming soon...). The functionality of the code in (figure coming soon...) and (figure coming soon...) is identical, although its readability is vastly improved as the second example colors the case structure green for the No Error case, and red for the Error case. Wrapping the entire code of a SubVI within a conditional case structure based on the error input allows VIs at higher levels to continue functioning, without executing code that could be useless or even dangerous when an error has occurred. Consider the simple report generation example shown in (figure coming soon...).
A report is initially created, a file is then attached, the report is printed, and finally destroyed. The dataflow link between these SubVIs is the report’s reference number (refnum), which ensures each execute in a predefined order. If each of the SubVIs execute without error, then the process completes successfully. Conversely, if one of the SubVIs encounters an error, subsequent SubVIs are unaware of the problem and attempt to execute regardless. In the example above, an error in the Attach a File to the Report SubVI will not cause the Print the Report SubVI to fail, resulting in a blank report print. If effective error handling is introduced (figure coming soon...), the Print the Report SubVI will know if an error has occurred before its execution is requested. If the functional code inside the Print the Report SubVI is enclosed within a conditional case structure based on the error input, the printing code is bypassed, and the error cluster is passed on to the next SubVI.
To attain a higher level of user interaction, standard SubVIs exist to alert the user to an error on the error cluster, and prompt for conditional actions. The Simple Error Handler.vi (figure coming soon...) allows for a basic level of error cluster status reporting, displaying detected errors in a dialog box, and prompting the user for an action based on the type of dialog input (for example, OK, Cancel, Stop, etc.).
The Simple Error Handler.vi is a wrapper for the lower level General Error Handler.vi. The latter (figure coming soon...) is more configurable, and permits the dynamic definition of custom error codes, and error exception handling. LabVIEW 7.0 brings with it an addition to the error handling function palette, Clear Errors.vi (figure coming soon...). This VI is simply an error in control and an error out indicator, which are not linked on the wiring diagram, causing any errors on the wired error link to be cancelled. This VI can be useful when constructing custom error-handling VIs, including dialog boxes allowing user interaction that is not covered by the simple and general error-handling VIs, but should not be used alone. Although dumping the errors from the error cluster may be tempting, one must incorporate appropriate code to handle them.
Wiring Errors into a SubVI Connector Pane
As described above, SubVIs have an associated connector pane, and the placement of error cluster inputs and output is generally in the lower quadrants (error in on the left, and error out on the right), with corresponding exclamation marks over the connectors on the SubVI’s icon (figure coming soon...).
Default Error Codes
The LabVIEW execution system contains a large list of standard and specific errors, encouraging the reuse of generic codes across applications. A list of generic errors codes can be found under the LabVIEW Help menu (figure coming soon...). Another method of parsing a small number of errors is to select the Help Explain Error menu item. This will launch an interface that allows the user to enter an error code, and a brief explanation is displayed (figure coming soon...). This interface is also accessible by right-clicking on a front panel error cluster, and selecting Explain Error.
Custom Error Codes
National Instruments has set several error codes aside for custom use. If an existing error code does not adequately describe the error condition, the user can define custom codes that are specific to the application. Codes between 5000 through to 9999 are available for use, and do not need to conform to any other application. Although General Error Handler.vi can be used to define custom error codes, one can also create an XML file in the labview\user.lib\errors directory that contains custom error codes and their descriptions. This method is particularly useful if the user requires custom error codes to apply to several applications, or if the codes are used by several software engineers in a team or are to be distributed with an application.
For example, the XML filename must be in the format *-errors.txt (where * is user definable), and the internal file structure must adhere to the following format:
<?XML Version="1.0">
<nidocument>
<nicomment>
This is a custom error code definition file for my application.
</nicomment>
<nierror code="5000">
User Access Denied!
Contact the Security Department to gain clearance to perform this function.
</nierror>
<nierror code="5001">
User Unknown.
Contact the People Development Department.
</nierror>
<nierror code="5100">
Driver Unable to Contact Instrument Database.
Contact the Software Engineering Department Helpdesk.
</nierror>
<nierror code="5200">
Plug-In Module in R&D mode – not to be used in Production Environment.
Contact the New Product Development Group.
</nierror>
</nidocument>
As can be seen, a file comment can be created within the <nicomment> tag space. Each custom error is defined as an <nierror> with it’s associated error code, and its error message is then placed inside the <nierror> tag space. Although hand coding a custom error code XML file is possible, the Error Code File Editor (Tools->Advanced->Edit Error Codes) provides a simple GUI for file creation and editing (figure coming soon...). Once custom error code files have been created and/or altered, LabVIEW must be restarted for the changes to take effect. It is often useful to define code bands during the project planning stage, setting aside bands for specific related error groups.
Note: This entire section of WIKI about "Error Handling" could benefit from a deep reading of the online help for the General Error Handler.vi. That VI has more facilities than folks typically know. FOR EXAMPLE:
The General Error Handler.vi includes an input parameter for the type of dialog, one option is "no dialog." I would STRONGLY recommended instead of calling "Error Code Database.vi". The primary reason for the recommendation is that the translation of error code cluster into human readable strings involves much more than just looking up text in the database. The source string itself may include information to override or extend the database, and the text in either the source string or the database may include formatting commands, such as HTML tags for bold face. Encoding information in the source string is a technique that will become more common in the future.
You may desire to display the text, fully formatted, in a string indicator of your own instead of in any dialog. Use the function of General Error Handler CORE.vi (found on the block diagram of General Error Handler.vi) to do this.