Chapter 2 CIN Parameter Passing
CIN MgErr CINRun(float32 *ap, float32 *bp,
LVBoolean *aequalbp) {
if (*ap == *bp)
*aequalbp= LVTRUE;
else
*aequalbp= LVFALSE;
return noErr;
}
How LabVIEW Passes Variably Sized Data to CINs
LabVIEW allocates memory for arrays and strings dynamically, and arrays and strings typically can grow quite large. If a string or array needs more space to hold new data, its current location may not offer enough contiguous space to hold the resulting string or array. In this case, LabVIEW may have to move the data to a location that offers more space.
To accommodate this 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. Handles are described in detail in Chapter 5, Manager Overview, and information about specific handle functions is in the Online Reference.
Alignment Considerations
When a CIN returns variably sized data, you need to adjust the size of the handle that references the array. One method of adjusting the handle size is to use the memory manager routine DSSetHandleSize or, if the data is stored in the application zone, the AZSetHandleSize routine, to adjust the size of the return data handle. Both techniques work, but they are trouble-prone because you have to calculate the size of the new handle correctly. It is difficult to calculate the size correctly in a platform-independent manner, however, because some platforms have special requirements about how you align and pad memory.
LabVIEW Code Interface Reference Manual |
2-10 |
© National Instruments Corporation |
Chapter 2 CIN Parameter Passing
Instead of using XXSetHandleSize, you should 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. This function is described in the Resizing Arrays and Strings section of this chapter.
If you are not familiar with alignment differences for various platforms, the following examples highlight the problem. Keep in mind that SetCINArraySize and NumericArrayResize take care of these issues for you.
Consider the case of a 1D array of double-precision numbers. On the PC, an array of double-precision floating-point numbers is stored in a handle, and 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 the Sun, 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 ensures that the array data falls on eight-byte boundaries.
As a more complicated example, consider a three-dimensional array of clusters, in which each cluster contains a double-precision floatingpoint number and a 4-byte integer. As in the previous example, the Sun stores this array in a handle. The first 12 bytes contain the number of pages, rows, and columns in the array. These dimension fields are followed by four bytes of filler (which ensures that the first doubleprecision number is on an 8-byte boundary) and then the data. Each element contains eight bytes for the double-precision number, followed by four bytes for the integer. Each cluster is followed by four bytes of padding, which ensures that the next element is properly aligned.
Arrays and Strings
LabVIEW passes array by handle, as described in the Alignment Considerations section of this chapter. For an n-dimensional array, the handle begins with n 4-byte values that describe 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, and the second four bytes indicate the number of columns. These dimension fields can be followed by filler and then the actual data. Each element can also have padding to meet alignment requirements.
© National Instruments Corporation |
2-11 |
LabVIEW Code Interface Reference Manual |