Chapter 2 CIN Parameter Passing

LabVIEW stores strings in memory as one-dimensional arrays of unsigned 8-bit integers.

LabVIEW stores Boolean arrays in memory as a series of bits packed to the nearest 16-bit word. LabVIEW ignores unused bits in the last word. LabVIEW orders the bits from left to right; that is, the most significant bit (MSB) is index 0. As with other arrays, a 4-byte dimension size precedes Boolean arrays. The dimension size for Boolean arrays indicates the number of Booleans contained in the array.

Paths (Path)

The exact structure for Path data types is subject to change in future versions of LabVIEW. A Path is a dynamic data structure that LabVIEW passes the same way it passes arrays. LabVIEW stores the data for Paths in an application zone handle. See the Online Reference, accessed from LabVIEW’s Help window, or the Code Interface Node Reference online manual for descriptions of the functions that manipulate Paths.

Clusters Containing Variably Sized Data

For cluster arguments, LabVIEW passes a pointer to a structure containing the elements of the cluster. LabVIEW stores scalar values directly as components inside the structure. If a component is another cluster, LabVIEW stores this 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

You can use the LabVIEW SetCINArraySize routine to resize return arrays and strings that you pass to a CIN. You pass the function the handle that you want to resize, information that describes the data structure, and the desired size of the array or handle. The function takes into account any padding and alignment needed for the data structure. The function does not, however, 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. You pass to this function the array you

LabVIEW Code Interface Reference Manual

2-12

© National Instruments Corporation

Chapter 2 CIN Parameter Passing

want to resize, a description of the data structure, and information about the new size of the array.

When you resize arrays of variably-sized data (for example, arrays of strings) with the SetCINArraySize or NumericArrayResize routines, you should be aware of the following facts. If the new size of the array is smaller, LabVIEW disposes of the handles used by the disposed element. Neither function sets the dimension field of the array. You must do this in your code after the function call. If the new size is larger, however, LabVIEW does not automatically create the handles for the new elements. You have to create these handles after the function returns.

The SetCINArraySize and NumericArrayResize functions are described in the following sections

SetCINArraySize

syntax	MgErr	SetCINArraySize	(UHandle dataH, int32
		paramNum, int32	newNumElmts);

SetCINArraySize resizes a data handle based on the data structure of an argument that you pass to the CIN. It does not set the array dimension field.

Parameter	Type	Description
dataH	UHandle	The handle that you want to resize.
paramNum	int32	The number for this parameter in the
		argument list to the CIN. The leftmost
		parameter has a parameter number of 0,
		and the rightmost has a parameter
		number of n-1, where n is the total
		number of parameters
newNumElmts	int32	The new number of elements to which
		the handle should refer. For a one-
		dimensional array of five values, you
		pass a value of 5 for this argument. For a
		two-dimensional array of two rows by
		three columns, you pass a value of 6 for
		this argument.

© National Instruments Corporation

2-13

LabVIEW Code Interface Reference Manual

Chapter 2 CIN Parameter Passing

returns	MgErr, which can contain the errors in the following list. MgErrs are
	discussed in Chapter 5, Manager Overview.
	Error	Description
	noErr	No error.
	mFullErr	Not enough memory to perform operation
	mZoneErr	Handle is not in specified zone.

NumericArrayResize

syntax	MgErr	NumericArrayResize(int32 typeCode, int32
		numDims, UHandle *dataHP, int32
		totalNewSize);

NumericArrayResize resizes a data handle that refers to a numeric array. This routine also accounts for alignment issues. It does not set the array dimension field. If *dataHP is NULL, LabVIEW allocates a new array handle in *dataHP.

Parameter	Type	Description
typeCode	int32	Describes the data type for the array that
		you want to resize. The header file
		extcode.h defines the following
		constants for this argument
		iB Data is an array of signed 8-bit
		integers.
		iW is an array of signed 16-bit integers.
		iL Data is an array of signed 32-bit
		integers.
		uB Data is an array of unsigned 8-bit
		integers.
		uW Data is an array of unsigned 16-bit
		integers.
		uL Data is an array of unsigned 32-bit
		integers.
		fS Data is an array of single-precision
		(32-bit) numbers.

LabVIEW Code Interface Reference Manual

2-14

© National Instruments Corporation

Chapter 2 CIN Parameter Passing

Parameter	Type	Description
		fD Data is an array of double-precision
		(64-bit) numbers.
		fX Data is an array of extended-
		precision numbers.
		cS Data is an array of single-precision
		complex numbers.
		cD Data is an array of double-precision
		complex numbers.
		cX Data is an array of extended-
		precision complex numbers.
numDims	int32	The number of dimensions in the data
		structure to which the handle refers.
		Thus, if the handle refers to a
		two-dimensional array, you pass a
		value of 2 for numDims.
*dataHP	UHandle	A pointer to the handle that you want to
		resize. If this is a pointer to NULL,
		LabVIEW allocates and sizes a new
		handle appropriately and returns the
		handle in *dataHP.
totalNewSize	int32	The new number of elements to which
		the handle should refer. For a
		unidimensional array of five values,
		you pass a value of 5 for this argument.
		For a two-dimensional array of two
		rows by three columns, you pass a
		value of 6 for this argument.

returns	MgErr, which can contain the errors in the following list.
	Error	Description
	noErr	No error.
	mFullErr	Not enough memory to perform operation
	mZoneErr	Handle is not in specified zone.

© National Instruments Corporation

2-15

LabVIEW Code Interface Reference Manual