Passing Variably-Sized Data to CINs

»Table of Contents

LabVIEW dynamically allocates memory for arrays and strings. If a string or array needs more space to hold new data, its current location might not offer enough contiguous space to hold the resulting string or array. LabVIEW might have to move the data to a location that offers more space.

To accommodate the relocation of memory, LabVIEW uses handles to refer to the storage location of variably-sized data. A handle is a pointer to a pointer to the desired data. LabVIEW uses handles instead of simple pointers because handles allow LabVIEW to move the data without invalidating references from your code to the data. If LabVIEW moves the data, LabVIEW updates the intermediate pointer to reflect the new location. If you use the handle, references to the data go through the intermediate pointer, which always reflects the correct location of the data.

Alignment Considerations

When a CIN returns variably sized data, you need to adjust the size of the handle that references the array. You can adjust the handle size using the memory manager routine DSSetHandleSize. If the data is stored in the application zone, you can use the AZSetHandleSize routine to adjust the handle size. Both the DSSetHandleSize routine and the AZSetHandleSize routine work. However, it is difficult to calculate the size correctly in a platform-independent manner because some platforms have special requirements about how you align and pad memory.

Instead of using SetHandleSize, use the LabVIEW routines that take this alignment into account when resizing handles. You can use the SetCINArraySize routine to resize a string or an array of arbitrary data type.

The following examples highlight alignment differences for various platforms:

On Windows, a one-dimensional array of double-precision, floating-point numbers is stored in a handle. The first four bytes describe the number of elements in the array. These four bytes are followed by the 8-byte elements that make up the array.

On Mac OS, double-precision, floating-point numbers must be aligned to 8-byte boundaries—the 4-byte value is followed by four bytes of padding. This padding makes sure the array data falls on 8-byte boundaries.
In a three-dimensional array of clusters, each cluster contains a double-precision, floating-point number and a 4-byte integer.

You can use SetCINArraySize and NumericArrayResize to solve the preceding problems.

Arrays and Strings

LabVIEW passes arrays by handle. For an n-dimensional array, the handle begins with n 4-byte values describing the number of values stored in a given dimension of the array. Thus, for a one-dimensional array, the first four bytes indicate the number of elements in the array. For a two-dimensional array, the first four bytes indicate the number of rows. The second four bytes indicate the number of columns. These dimension fields can be followed by filler and then the actual data. Each element also can have padding to meet alignment requirements.

LabVIEW stores strings and Boolean arrays in memory as one-dimensional arrays of 8-bit unsigned integers. Use the Flatten to String function to convert LabVIEW data into a string.

Paths

The exact structure for Path data types is subject to change in future versions of LabVIEW. A Path is a dynamic data structure LabVIEW passes the same way it passes arrays. LabVIEW stores the data for Paths in an application zone handle.

Clusters Containing Variably-Sized Data

For cluster arguments, LabVIEW passes a pointer to a structure that contains the elements of the cluster. LabVIEW stores scalar values directly as components inside the structure. If a component is another cluster, LabVIEW stores the component cluster value as a component of the main cluster. If a component is an array or string, LabVIEW stores a handle to the array or string component in the structure.

Resizing Arrays and Strings

To resize return arrays and strings you pass to a CIN, use the LabVIEW SetCINArraySize routine. Pass to the SetCINArraySize function the handle you want to resize, information describing the data structure, and the desired size of the array or handle. SetCINArraySize takes into account any padding and alignment needed for the data structure. However, SetCINArraySize does not update the dimension fields in the array. If you successfully resize the array, you need to update the dimension fields to correctly reflect the number of elements in the array.

You can resize numeric arrays more easily with NumericArrayResize. Pass to the NumericArrayResize function the array you want to resize, a description of the data structure, and information about the new size of the array.

Consider the following issues when you resize arrays of variably-sized data, such as arrays of strings, with the SetCINArraySize or NumericArrayResize routines:

If the new size of the array is smaller, LabVIEW disposes of the handles used by the disposed element. Neither SetCINArraySize nor NumericArrayResize sets the dimension field of the array. You must set the dimension field of the array in your code after the function call.
If the new size of the array is larger, LabVIEW does not automatically create the handles for the new elements. You have to create these handles after the function returns.

Examples with Variably Sized Data

The following examples describe how to create CINs that work with variably-sized data types: