LabVIEW for Everyone: Graphical Programming Made Easy and Fun (3rd Edition)

Now that you've got the concept of arrays under your belt, clusters should be easy. Like an array, a cluster is a data structure that groups data. However, unlike an array, a cluster can group data of different types (i.e., numeric, Boolean, etc.); it is analogous to a struct in C or the data members of a class in C++ or Java. A cluster may be thought of as a bundle of wires, much like a telephone cable. Each wire in the cable represents a different element of the cluster. Because a cluster has only one "wire" in the block diagram (even though it carries multiple values of different data types), clusters reduce wire clutter and the number of connector terminals that subVIs need. You will find that the cluster data type appears frequently when you plot your data on graphs and charts. Figures 7.42 and 7.43 illustrate the concepts of bundling and unbundling clusters of element data.

You can access cluster elements by unbundling them all at once or by indexing one at a time, depending on the function you choose; each method has its place (see Figure 7.43). Think of unbundling a cluster as unwrapping a telephone cable and having access to the different-colored wires. Unlike arrays, which can change size dynamically, clusters have a fixed size, or a fixed number of wires in them.

You can connect cluster terminals with a wire only if they have exactly the same type; in other words, both clusters must have the same number of elements, and corresponding elements must match in both data type and order. The principle of polymorphism applies to clusters as well as arrays, as long as the data types match.

You will often see clusters used in error handling. Figure 7.44 shows the error clusters, Error In.ctl and Error Out.ctl, used by LabVIEW VIs to pass a record of errors among multiple VIs in a block diagram (for example, many of the data acquisition and file I/O VIs have error clusters built into them). These error clusters are so frequently used that they appear in the Modern>>Array, Matrix & Cluster subpalette of the Controls palette for easy access.

Creating Cluster Controls and Indicators

Create a cluster by placing a Cluster shell (Modern>>Array, Matrix & Cluster subpalette of the Controls palette) on the front panel. You can then place any front panel objects inside the cluster. Like arrays, you can deposit objects directly inside when you pull them off of the Controls palette, or you can drag an existing object into a cluster. Objects inside a cluster must be all controls or all indicators. You cannot combine both controls and indicators inside the same cluster, because the cluster itself must be one or the other. The cluster will be a control or indicator based on the status of the first object you place inside. Resize the cluster with the Positioning tool if necessary. Figure 7.45 shows a cluster with four controls.

You can create block diagram cluster constants in a similar two-step manner.

If you want your cluster to conform exactly to the size of the objects inside it, pop up on the border (NOT inside the cluster) and choose an option in the Autosizing menu.

Cluster Order

Cluster elements have a logical order unrelated to their position within the shell. The first object placed in the cluster is element zero, the second is element one, and so on. If you delete an element, the order adjusts automatically. You must keep track of your cluster order if you want to connect your cluster to another clusterthe order and data types must be identical. Also, if you choose to unbundle the cluster all at once, you'll want to know which value corresponds to which output on the cluster function (more about unbundling will be discussed later in this chapter in the section, "Unbundling Your Clusters").

Change the order within the cluster by popping up on the cluster border and choosing Reorder Controls in Cluster... from the pop-up menu. A new set of buttons appears in the Toolbar, and the cluster appearance changes, as shown in Figure 7.46.

The white boxes on the elements show their current places in the cluster order. The black boxes show the new places. Clicking on an element with the cluster order cursor sets the element's place in the cluster order to the number displayed on the Toolbar. You can type a new number into that field before you click on an object.

Revert Button

OK Button

If you don't like the changes you've made, revert to the old order by clicking on the Revert button. When you have the order the way you want, you can set it and return to your regular front panel by clicking on the OK button and exiting the cluster order edit mode.

You can quickly inspect the order of any cluster using the Context Help window. Simply move the Wiring tool over the wire, and the Context Help window will display the data type of the wirethe cluster elements are displayed in order, from top to bottom, as shown in Figure 7.47. (Show the Context Help window by selecting Help>>Show Context Help from the menu or by pressing the shortcut key <ctrl-H> [Windows], <command-H> [Mac OS X], or <meta-H> [Linux].)

Using Clusters to Pass Data to and from SubVIs

The connector pane of a VI can have a maximum of 28 terminals. You probably don't want to pass information to all 28 terminals when calling a subVI anywaythe wiring can be very tedious and you can easily make a mistake. By bundling a number of controls or indicators into a cluster, you can use a single terminal and wire to pass several values into or out of the subVI. You can use clusters to work around the 28-terminal limit for the connector or just enjoy simplified wiring with fewer (and therefore larger and easier to see) terminals.

Bundle Function

The Bundle function (Programming>>Cluster & Variant palette) assembles individual components into a new cluster or allows you to replace elements in an existing cluster (see Figure 7.48). The function appears as the icon at the left when you place it in the diagram window. You can increase the number of inputs by dragging the resize-handles at the top or bottom edge of the function that appear as you hover the mouse over it with the Positioning tool. When you wire to each input terminal, a symbol representing the data type of the wired element appears on the empty terminal. The order of the resultant cluster will be the order of inputs to the Bundle.

If you just want to create a new cluster, you do not need to wire an input to the center cluster input of the Bundle function. You do need to wire this input if you are replacing an element in the cluster. If you do wire this input, the Bundle will automatically adjust to match the input cluster.

Be careful with this functionif you add an element to your cluster without adding an element to the block diagram Bundle to match (or vice versa), your program will break!

Replacing a Cluster Element

If you want to replace an element in a cluster, wire the cluster to the middle terminal of the Bundle function (symbols for data types inside the cluster will appear in the Bundle inputs) and wire the new value(s) of the element(s) you want to replace to the corresponding inputs. You need to wire only to those terminals whose values you want to change (see Figure 7.49).

If you hover the wiring tool over the input terminals of the bundle node, the tip strip will show you the element name, if any.

Unbundling Your Clusters

Unbundle Function

The Unbundle function (Programming>>Cluster & Variant palette) splits a cluster into each of its individual components (see Figure 7.50). The output components are arranged from top to bottom in the same order they have in the cluster. If they have the same data type, the elements' order in the cluster is the only way you can distinguish between them. The function appears as the icon at left when you place it in the diagram window. When you wire an input cluster to an Unbundle, the Unbundle function automatically resizes to contain the same number of outputs as there are elements in the input cluster and the previously blank output terminals assume the symbols of the data types in the cluster.

Knowing the cluster order is essential when accessing cluster data with Bundle and Unbundle. For example, if you have two Booleans in the same cluster, it would be easy to mistakenly access Switch 2 instead of Switch 1 because they are referenced in the Unbundle function by order, NOT by name. Your VI will wire with no error, but your results will be incorrect.

LabVIEW does have a way to bundle and unbundle clusters using element names; we'll talk about it in a minute.

Activity 7-4: Cluster Practice

In this activity, you will build a VI to teach you how to work with clusters. You will create a cluster, unbundle it, and then re-bundle it and display the values in another cluster (see Figure 7.51).

Unbundle Function

Unbundle function (Cluster palette). This function will break out the cluster so you can access individual elements. It will resize so that it has four outputs, and the data-type labels will appear on the Unbundle function after you wire Input Cluster to it.

Bundle Function

Bundle function (Cluster palette). This function reassembles your cluster. Resize it so that it contains four inputs.

You can also access Bundle and Unbundle by popping up on a cluster terminal or wire and choosing the function you want from the Cluster and Variant Palette menu.

Bundling and Unbundling by Name

Sometimes you don't need to assemble or disassemble an entire clusteryou just need to operate on an element or two. You can use Bundle By Name and Unbundle By Name to do just that!

Bundle By Name, found in the Cluster palette, references elements by name instead of by position (as Bundle does). Unlike Bundle, you can access only the elements you need. However, Bundle By Name cannot create new clusters; it can only replace an element in an existing cluster. Unlike Bundle, you must always wire to Bundle By Name's middle input terminal to tell the function in which cluster to replace the element (see Figure 7.53).

Unbundle By Name, also located in the Cluster palette, returns elements whose name(s) you specify (see Figure 7.54). You don't have to worry about cluster order or correct Unbundle function size.

Make sure all cluster elements have owned labels when you are using the Bundle By Name and Unbundle By Name functions. Obviously, you can't access by name if you don't have namesLabVIEW won't know what you want!

For example, if you wanted to replace the value of Boolean 2 in the last exercise, you could use the Bundle By Name function without having to worry about cluster order or size, as shown in Figure 7.55.

Similarly, if you only needed to access the value of String, you would want to use the Unbundle By Name function.

As soon as you wire the cluster input of Bundle By Name or Unbundle By Name, the name of the first element in the cluster appears in the name input or output. To access another element, click on the name input or output with the Operating or Labeling tool. You should see a list of the names of all labeled elements in the cluster. Select your element from this list, and the name will appear in the name terminal. You can also access this list by popping up on name and choosing Select Item>> (see Figure 7.57).

Both functions can be resized to accommodate as many elements as you need; select each component you want to access individually. As an added plus, you no longer have to worry about your program breaking if you resize your cluster. The Bundle By Name and Unbundle By Name functions do not break unless you remove an element they reference.

Activity 7-5: More Fun with Clusters

In this activity, you will build a VI that checks whether the value of the Numeric 1 digital control in the input cluster is greater than or equal to zero. If it is less than zero, the VI will take the absolute value of all controls. If Numeric 1 is greater than or equal to zero, the VI does not take the absolute value of any controls. Regardless of the value of Numeric 1, the VI multiplies all values by 0.5 and displays the results in Output Cluster, demonstrating how you can use polymorphism with clusters (see Figure 7.58).

Unbundle By Name Function

Unbundle By Name function (Programming>>Cluster & Variant palette) extracts Numeric 1 from Input Cluster so you can compare it to zero. If "Numeric 1" isn't showing in the output name area, click with the Operating tool to choose it from the list of cluster elements.

Greater Or Equal To 0? Function

Greater Or Equal To 0? function (Programming>>Comparison palette). Function returns TRUE if the numeric input is zero or a positive number.

Absolute Value Function

Absolute Value (Programming>>Numeric palette) returns the input number if that number is greater than or equal to zero; returns the inverse of the input number if the input number is less than zero. In this activity, takes the absolute value of the entire cluster.