Technical Article

Error Clusters in LabVIEW

October 15, 2021 by Seth Price

Simple errors may corrupt data files, crash LabVIEW, or crash the entire computer system. Implementing error clusters will help prevent these issues. Learn how to set up error clusters for your VI.

Built into ni’s LabVIEW software is a tool for handling errors, called an error cluster. Error clusters are used to capture any error that may occur during user entry, instrumentation access, or file access, rather than letting the virtual instrument (VI) crash. If error clusters are not used, a simple error may cause the entire VI to crash, perhaps corrupting data files, leaving instruments in an unknown state, or crashing the entire computer. 

To avoid this, error clusters capture the error and allow the programmer to decide how to handle it before it causes bigger problems. This could be as simple as asking the operator for valid input or as complicated as shutting down equipment properly before passing the error through the system.


The Error Cluster

The error cluster consists of several important parts: a status (boolean), a code (32-bit integer), and a source (string). Each of these pieces can be unbundled from the cluster (or unbundled by name) for the VI.


Figure 1. The LabVIEW error cluster. In this case, there is no error (status: false, shown as a checkmark).


The status boolean can determine an error, which is often fed into a case structure to handle the error. For convenience, LabVIEW is smart enough to know that an error cluster fed directly into a case structure will automatically check the status boolean. The programmer does not have to unbundle it separately. Case structures with an error cluster as input have their own special labels and colors: the two cases are “error” and “no error,” and the case structure border is colored green and red, respectively. 


Figure 2. In this piece of a VI, a mass is taken from a scale. 


If the scale reads properly in figure 2, the “no error” case is active. If there is a problem, rather than crashing the VI, the error cluster’s status is set to true, and the “error” case is active. 

The code is a number that refers to the specific error. The number displayed can be looked up to see what may be causing the error. In particular, a simple internet search can yield other users who have had the same error and how they either remedied or handled it in their VI. 

The source gives more information about the error. Sometimes, this information is more useful than the code, as it will display inactive ports and other machine-specific problems. Other times, the code can be more useful for finding a solution. 


Collecting and Handling Errors

Suppose a VI has multiple error sources, such as several devices interfaced and a file or two open. Any of these sources could generate an error. To combine these into one error, a programmer can use the “merge errors” blocks. Like many LabVIEW blocks, it can be dragged to account for multiple error sources at a time. The merge errors block will output the first error it encounters.


Figure 3. This merge errors block combines the error clusters from four separate instruments and outputs and reports the first error found (reading from top to bottom).


Once an error is found, it should be handled, typically in an error case structure. Inside the “true” case, only limited, essential work should be performed, such as closing file references, shutting down equipment, and notifying the operator of the error. All output voltages should be set to their safe state (usually 0) to ensure that motors, pumps, and heating elements are turned off. If possible, data files should be saved and backed up in this case. 

A “simple error handler” will display a message and allow the operator to press the “continue” button to continue executing the VI. This notifies the operator, and should only be a piece of the entire error handling strategy.


Figure 4. Simple error handler. 


Error clusters can be written by the programmer as well. They can assign the code and source to make the error more understandable in the context of a particular VI. Instead of the error listed above, the source could read, “error connecting to Pump #3. Please check the power and data cables.”


Using Error Clusters to Force Determinism

Error clusters can also force the run order and ensure that a VI’s nodes are placed in a determinate order. To connect these and force the run order, place the nodes in order from left to right, then connect the “error output” from the left-most node to the “error input” of the next node, and continue this process through all of the nodes that need to be determined.


Figure 5. The error cluster forces the run order: simulate signal, spectral measurements, distortion measurements, then tone measurements. 


If the error cluster wires were removed in figure 5, the simulate signal would happen first; then, the others would occur in a seemingly random fashion, running in different orders each time the programmer executed the VI.


Good Programming Practice

Because the run order may need to be set, or there is some potential for errors in most instrument or file access, error clusters should be used whenever they are available. All instrumentation or file access nodes have an error cluster input and output built into them. 

Programmers should include error cluster inputs and outputs in the sub-VIs they build, if for no other reason than to force the run order. The lower left-hand and lower right-hand terminals of the sub-VIs are used as error cluster input and output, respectively, by convention. 

Error clusters are a way to handle problems that arise at runtime. The programmer can use them to perform specific actions, such as shutting down hardware, closing files, or asking for valid operator input, rather than letting the VI, and perhaps the entire system, crash. Errors can be bunched together as needed and used to force the run order of the nodes in a VI.