Preallocated Read from Binary File Function

Owning Palette: Advanced File VIs and Functions

Requires: Base Development System

Reads binary data from a file and places the data into an array that you have already allocated without incurring a copy of the data. Unlike the Read from Binary File function, this function avoids run-time memory allocations.

The performance of this function depends on the array you preallocate.

The connector pane displays the default data types for this polymorphic function.

Details  

Add to the block diagram

Find on the palette

	refnum in specifies the file refnum associated with the file you want to read.
	data in specifies the array in which to place data. This function attempts to read as many data elements as the array holds. Refer to the support table for information about the arrays and data types this function supports.
	byte order sets the endian form of the resulting data. Byte order, or endian form, indicates whether integers are represented in memory from most-significant byte to least-significant byte or vice versa. The function must read the data in the same byte order that the data was written. Note  This function requires that you set the byte order parameter to match the native byte order of the host computer running LabVIEW. If the computer is big endian, choose either native, host order or big-endian, network order endian form. If the computer is little endian, choose either native, host order or little-endian endian form. 0 big-endian, network order (default)—The most-significant byte occupies the lowest memory address. This endian form is used on PowerPC platforms such as VxWorks. This endian-form also is used when reading data written on a different platform. 1 native, host order—Uses the byte-ordering format of the host computer. This endian form increases read and write speed. 2 little-endian—The least-significant byte occupies the lowest memory address. This endian form is used on Windows, macOS, and Linux.
	error in describes error conditions that occur before this node runs. This input provides standard error in functionality.
	refnum out is the refnum of the file that the function read. You can wire this output to another file function.
	data out contains the data read from the file. This output does not resize to include only valid data. If LabVIEW reaches the end of the file before the data in array is full, then the array contains some invalid elements. Use the num elements read output to determine the exact amount of valid data in data out. If LabVIEW does not reach the end of the file before the data in array is full, LabVIEW leaves the file pointer where the read finished so that the next read starts where the last read left off.
	num elements read returns the total number of elements in the data in array replaced with data from the file.
	error out contains error information. This output provides standard error out functionality.

Preallocated Read from Binary File Details

The following block diagram shows an example of how this function works with a pre-allocated array. Each time the Preallocated Read from Binary File function executes, LabVIEW places the data from file in the same array.

Preallocated Read from Binary File Support

This function provides different levels of support for arrays you wire to place data from file:

  Fully supported. Because the function does not require a new allocation, it is probably faster than the Read from Binary File function.

  Supported. Because the function requires a new allocation and copy, it is probably slower than the Read from Binary File function.

  Not accepted by the function.

The following table describes support when the array you wire to data in is a particular array or array slice that contains a particular data type.

Data Type	Array	Contiguous Array Slice	Noncontiguous Array Slice1
Integers
Single-precision, floating-point numeric
Double-precision, floating-point numeric
Extended-precision, floating-point numeric2
Complex single-precision, floating-point numeric
Complex double-precision, floating-point numeric
Complex extended-precision, floating-point numeric2
Fixed-point numeric2
Boolean
String
All other data types
Notes: 1. LabVIEW must make a memory copy of a noncontiguous array slice. Therefore, the Preallocated Read from Binary File function is not faster than the Read from Binary File function if you wire a noncontiguous array slice to data in. 2. The Preallocated Read from Binary File function accepts extended precision, complex extended precision, and fixed-point data. However, this function allocates memory for a new copy with these data types, like the Read from Binary File function, because it cannot put the data in an existing allocation.

This function also fully supports each of the data types from the table as scalar values that are not contained in arrays.