You are here: NI Home > Support > Product Reference > Manuals > LabVIEW 8.5 Help

This section reviews important concepts regarding array and string data in the Call Library Function Node.

(Windows) Refer to the labview\examples\dll\data passing\Call Native Code.llb for an example of using arrays and strings in shared libraries.

Arrays of Numeric Data

Arrays of numeric data can be comprised of any type of integers or floating point numbers with single (4-byte) or double (8-byte) precision. When you pass an array of data to a DLL function, you can pass the data as an array data pointer, as a LabVIEW array handle, or as a LabVIEW array handle pointer.

Array Data Pointers have the following characteristics whether you pass the Array Data Pointers in the Windows API or in another API:

• You can set the number of dimensions in the array, but you must not include information about the size of the array dimension(s). Instead, you must pass the size of the array dimension(s) information to your DLL in a separate variable.
• Never resize an array or perform operations that might change the length of the array data passed from LabVIEW. Resizing might cause a crash because the pointer sent is not an allocated block but points into the middle of an allocated block.
• To return an array of data, you should allocate an array of sufficient size in LabVIEW, pass the array to your function, and have this array act as the buffer. If the data takes less space, you can return the correct size as a separate parameter and then, on the calling diagram, use array subset to extract the valid data.

Remember that the Windows API does not use LabVIEW array handles, so with functions that are part of the Windows API you can use only Array Data Pointers.

If you pass the array data as a LabVIEW array handle, you can use LabVIEW CIN functions to resize the array. In order to call LabVIEW CIN functions, your compile must include the correct LabVIEW library file, which is located within the labview\cintools directory. The following table lists different compilers and the correct LabVIEW library file to use with the compiler.

Compiler	LabVIEW Library File
Xcode	liblvexports.a
Visual C++	labviewv.lib

String Data

The types of your string pointers must match the types of string pointers that your function uses, or errors occur. The Call Library Function Node offers the following choices:

• C String Pointer is a pointer to the string, followed by a NULL character. Most Win32 API functions use this C-style string pointer.
• Pascal String Pointer is a pointer to the string, preceded by a length byte.
• LabVIEW String Handle is a pointer to a pointer to the string, preceded by four bytes of length information.
• LabVIEW String Handle Pointer is a pointer to a handle for a string, preceded by four bytes of length information.

You can think of a string as an array of characters. Assembling the characters in order forms a string. LabVIEW stores a string in a special format in which the first four bytes of the array of characters form a 32-bit signed integer that stores how many characters appear in the string. Thus, a string with n characters requires n + 4 bytes to store in memory. For example, in the following figure, the string text contains four characters.

When LabVIEW stores the string, the first four bytes contain the value 4 as a 32-bit signed number, and each of the following four bytes contains a character of the string. The advantage of this type of string storage is that NULL characters are allowed in the string. Strings are virtually unlimited in length, up to 2³¹ characters. This method of string storage is illustrated in the previous figure. If you pass a LabVIEW string handle from the Call Library Function Node to the DLL, then you can use the LabVIEW CIN functions, such as DSSetHandleSize, to resize the LabVIEW string handle.

Remember, you must add the correct LabVIEW library file to your project. Refer to the previous table for a list of LabVIEW library files and the compilers with which they are used.

The Pascal string format is nearly identical to the LabVIEW string format, but instead of storing the length of the string as a 32-bit signed integer, the string length is stored as an 8-bit unsigned integer. Storing the string length as an 8-bit unsigned integer limits the length of a Pascal-style string to 255 characters. A Pascal string that is n characters long will requiren + 1 bytes of memory to store. The following figure illustrates a Pascal string.

C strings are probably the type of strings you will deal with most commonly. The similarities between the C-style string and normal numeric arrays in C becomes much more clear when you see that C strings are declared as char*, where char is typically an 8-bit unsigned integer. Unlike LabVIEW and Pascal strings, C strings do not contain any information that directly gives the length of the string. Instead, C strings use a special character called the NULL character to indicate the end of the string. NULL is defined to have a value of zero in the ASCII character set. Notice that NULL is the number zero and not the character “0.” Thus, in C, a string that contains n characters requires n + 1 bytes of memory to store: n bytes for the characters in the string and one additional byte for the NULL termination character. The following figure illustrates how a C-style string is stored in memory.

The advantage of C-style strings is that they are limited in size only by available memory. However, if you are acquiring data from an instrument that returns numeric data as a binary string, as is common with serial or GPIB instruments, values of zero in the string are possible. If you treat the string as a C-style string, your program incorrectly assumes that the end of the string has been reached, when in fact your instrument is returning a numeric value of zero. For binary data that might contain NULL values, consider using an array of 8-bit unsigned integers.

Observe the following guidelines when passing string data to a DLL:

• Never resize a string, concatenate a string, or perform operations that might increase the length of string data passed from LabVIEW if you are using the C or Pascal string pointers.
• If you must return data as a string, allocate a string of the appropriate length in LabVIEW and pass this string into the DLL to act as a buffer.
• If you pass a LabVIEW string handle from the Call Library Function Node to the DLL, you can use the LabVIEW CIN functions, such as DSSetHandleSize, to resize the LabVIEW string handle.

  In order to call LabVIEW CIN functions, your compile must include the correct LabVIEW library file, which is located within the labview\cintools directory. The previous table lists different compilers and the correct LabVIEW library file to use with the compiler.

Array and String Tip

When you are not passing LabVIEW handles and your DLL function must create an array, resize an array, or resize a string of data, you should break the DLL function into the following two DLL functions:

• Determine the number of elements that the array requires or the length of the string to be returned. Have the first DLL function return the desired size to LabVIEW.
• In LabVIEW, initialize an array or string with default values and pass this array to the second DLL function in your DLL, which actually places the data into the array. If you are working with string-based instrument control, it might be easier to pass an array of 8-bit integers than C strings because of the possibility of having NULL values in the string.

  When you are passing a LabVIEW array handle or LabVIEW string handle from the Call Library Function Node to your DLL, you can use the LabVIEW CIN functions to resize or create an array or string.