Error Cluster data type

2009-05-07T08:02:56Z

LuI:

== Error Cluster ==

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.

[[Image:Error cluster control and terminal.JPG|frame|center|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 ([http://www.ni.com/pdf/manuals/371780b.pdf 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''), with the range -8999 to -8000 (LabVIEW 8.2) and 5000 to 9999 reserved for user defined error codes. 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'''.

[[Image:Explain Error tool.jpg|frame|center|Figure 2: Explain Error tool]]

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.

[[Image:Fig 3-VI connectors.JPG|frame|center|Figure 3: connectors for Error Cluster from Error Code.vi and General Error Handler.vi]]

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''').

[[Image:Fig 3-error cluster examples.JPG|frame|center|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''').

[[Image:Comparison function indicators.JPG|frame|center|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''').

[[Image:Simple error selector diagram.JPG|frame|center|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).

[[Image:Error selector diagram A.JPG|frame|center]][[Image:Error selector diagrams B.JPG|frame|center|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: 

[[Image:SerializeprocessesBD.png|merge errors with No_Errors]] The connector pane looks like this: [[Image:SerializeprocessesCP.png|Connector Pane for 'SerializeIndependentProcesses]] 

It can be used like this: 

[[Image:SerializeprocessesUsage.png]]

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...

== See also ==

*[[Error handling]]
*[[Error Case Structure]]

[[Category:Data_types]]

File:SerializeprocessesUsage.png

2009-05-07T07:55:02Z

LuI:

File:SerializeprocessesCP.png

2009-05-07T07:42:21Z

LuI:

File:SerializeprocessesBD.png

2009-05-07T07:42:04Z

LuI:

LabVIEW Wiki - User contributions [en]

Error Cluster data type

File:SerializeprocessesUsage.png

File:SerializeprocessesCP.png

File:SerializeprocessesBD.png