Error Cluster data type

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.

An error cluster contains a Boolean “status”, an I32 numerical “code” and a “source” string in that order. Any cluster with this structure is treated as an error cluster in LabVIEW. The default value, “status” = false, “code” = 0 and “source” empty, is shown in Figure 1 for a typical control.

Figure 1: 3D error cluster control and terminal‎

Note that the default terminal and wire color was changed from pink to dark yellow in LabVIEW 8.2 (upgrade notes p. 35). The “status” is true if an error has occurred but remains false for warnings. The “code” assumes positive and negative values (see “error codes, ranges of” in LabVIEW Help).

Custom Error Codes

The following ranges are reserved for developers to define their own error codes (see Custom Error Code):

• 5000 to 9999
• -8999 to -8000
• 500000 to 599999

Use Tools >> Advanced >> Edit Error Codes to create text files to define your own errors.

The “source” identifies a VI and possibly its call chain as the origin of an error. Possible reasons for an error can be obtained from the Explain Error tool (see Figure 2). This tool is activated by selecting the Explain Error… item under the Help menu in LabVIEW or by right-clicking on any element of an error cluster with “status” true and selecting Explain Error.

Figure 2: Explain Error tool

General Error Handling

LabVIEW provides several VIs for working with error clusters. For example, the Error Cluster from Error Code.vi generates an error cluster based on a specified “code” (see Figure 3). You can also define custom codes using the General Error Handler.vi or by creating an XML-based text file in the <labview\user.lib\ errors> directory (see “error codes, defining custom” and “error codes, defining custom in text files” in LabVIEW Help). This VI outputs a “message”, like the “Explanation” from Explain Error, which identifies the “source” and describes possible causes associated with the “code”. This information can also be displayed using several different types of dialogs. This feature is commonly employed to identify errors in user interface applications.

Figure 3: connectors for Error Cluster from Error Code.vi and General Error Handler.vi

Error Comparison

Error clusters are also valid inputs to some comparison and array functions and can be used to control case structures and while loops (see Figure 4).

Figure 4: structures, comparison and array functions involving error cluster inputs

The comparison functions Equal?, Not Equal?, Greater?, Less?, Greater Or Equal? and Less Or Equal? can operate in two modes. The output is Boolean in the Compare Aggregates mode, while a cluster of three Booleans corresponding to each component of the error cluster is generated in the Compare Elements mode (see Figure 5).

Figure 5: typical indicators for both modes of a comparison function

The Select, Max & Min and In Range and Coerce functions can output an error cluster. While the Max & Min function returns ordered inputs in the Compare Aggregates mode, an output may not correspond to either error cluster if Compare Elements is selected (default). The Array Max & Min function always returns ordered inputs corresponding to the first and last elements of the Sort 1D Array output. The primary sort is performed on “status”, with secondary ordering by “code” and then “source”. Strings are sorted by ASCII code starting with the leading character. Note that error clusters behave like their Boolean “status” value when connected to the selector terminal of a Select function and Case Structure or the conditional terminal of a While Loop.

Error Selection

A common programming issue in LabVIEW involves selecting between two or more error clusters. This process involves finding the cluster with “status” true or “code” not equal zero if no “status” is true. The Merge Errors.vi shown in Figure 4 implements this search for up to three error clusters and an array of such clusters. This subVI is relatively fast with large error arrays. However, a significant portion of the execution time involves concatenation of inputs for the small arrays (<10 elements) typical in most applications. This result suggests that time critical applications should be built around the immediate selection between two error clusters rather than their concatenation into an array. The simplest method of comparing the “status” of two error clusters involves the Select function (see Figure 6).

Figure 6: diagram for a simple error selector that does not detect warnings

This function selects the first error cluster with “status” true, much like the Or function operating on Boolean inputs. Connecting “error 2” instead of “error 1” to the selector terminal is more analogous to the And function, which is typically less useful. While about 30 times faster than the Merge Errors.vi (LabVIEW 7.0), the Select function does not detect a warning (“status” false and “code” not equal zero).

Diagrams for several VIs that compare error clusters and detect warnings are shown below (fastest to slowest).

Figure 7: possible diagrams for an error selector that detects warnings

These VIs execute about 5 times faster than the Merge Errors.vi (LabVIEW 7.0), even with normal priority execution. (Merge Errors.vi uses the “subroutine” priority.) Inputs to selector terminals in the first and second diagrams are passed to “error” for the cases not shown. Otherwise, “error 1” is checked for nonzero “code” since neither cluster has “status” true. The last approach uses the Max & Min function in Compare Aggregates mode to order inputs. If just one of these clusters has “status” true, that input will be the “max” output since true > false. However, this output must be checked for “status” true or “code” nonzero to determine selection.

Error Cluster as Execution Order Specifier

LabVIEW is a dataflow language and as such preferred way to specify execution order of block diagram items is to connect output of a block diagram item to an input of another block diagram item. There are situations when some certain execution order is required but the outputs of the items to be executed earlier cannot be connected to the inputs of the items to be executed later. In these situations error cluster is a preferred way to specify the execution order of the items. It's preferred over sequence structures in almost all use cases.

This can easily be achieved by a private replacement for the 'merge errors' node, that also contains a 'No_Error'  constant:

The connector pane looks like this:

It can be used like this:

So a VI-Ref is opened independently if an error occured before, but after all preliminary portions of code had been finished. The printing actions relate to the eventual error of the OpenVI-Ref node only. All errors are merged as final action, so any error that might have shown up is reported, while the printing actions care only on VI-server related errors.

This little helper is too simple to provide its code as VI, though...

Tips and tricks

• Right-click the status button inside an error cluster on the front panel and select Explain Error to open the Explain Error dialog.

See also

• Error handling
• Error Case Structure