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.


icon

Inputs/Outputs

  • cbsrn.png refnum in —

    refnum in specifies the file refnum associated with the file you want to read.

  • c1ddbl.png data in —

    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.

  • cenum.png byte order (0:big-endian, network order) —

    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.
    0big-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.
    1native, host order—Uses the byte-ordering format of the host computer. This endian form increases read and write speed.
    2little-endian—The least-significant byte occupies the lowest memory address. This endian form is used on Windows, macOS, and Linux.
  • cerrcodeclst.png error in —

    error in describes error conditions that occur before this node runs. This input provides standard error in functionality.

  • ibsrn.png refnum out —

    refnum out is the refnum of the file that the function read. You can wire this output to another file function.

  • i1ddbl.png data out —

    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.

  • ii32.png num elements read —

    num elements read returns the total number of elements in the data in array replaced with data from the file.

  • ierrcodeclst.png error out —

    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.

    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 TypeArrayContiguous Array SliceNoncontiguous Array Slice1
    Integers
    Single-precision, floating-point numeric
    Double-precision, floating-point numeric
    Extended-precision, floating-point numeric²
    Complex single-precision, floating-point numeric
    Complex double-precision, floating-point numeric
    Complex extended-precision, floating-point numeric²
    Fixed-point numeric²
    Boolean
    String
    All other data types
    Note
    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.