|LabVIEW 2016 Help|
|LabVIEW 2017 Help|
|LabVIEW 2018 Help|
|LabVIEW 2019 Help|
|LabVIEW 2020 Help|
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.
|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. |
|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.|
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.
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|
|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|
|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.