Read from Binary File Function

Owning Palette: File I/O VIs and Functions

Requires: Base Development System

Reads binary data from a file and returns it in data. How the data is read depends on the format of the specified file. This function does not work for files inside an LLB.

Refer to the Preallocated Read from Binary File function for information about reading binary data and placing it into a pre-allocated array without incurring a copy.

Details  Examples

 Add to the block diagram  Find on the palette
data type sets the type of data the function uses to read from the binary file. The function interprets the data starting at the current file position to be count instances of data type. If the type is an array, string, or cluster containing an array or string, the function assumes that each instance of that data type contains size information. If an instance does not include size information, the function misinterprets the data. If LabVIEW determines that the data does not match the type, it sets data to the default for the specified type and returns an error.
prompt is the message that appears above the list of files and directories, or folder, in the file dialog box.
file can be a refnum or absolute file path. If it is a path, this function opens the file specified by the path. The default is to display a file dialog box and prompt you to select a file.

If you specify an empty or relative path or if the file does not exist, this function returns an error.
count is the number of data elements to read. Data elements can be bytes or instances of data type. The function returns count data elements in data, or if it reaches the end of the file, it returns all the complete data elements read thus far and an end-of-file error. By default, the function returns a single data element. If count is –1, the function reads the entire file starting from the current file position. If count is less than –1, the function returns an error.

If you wire data to count and the specified data type is an array, the function automatically returns a cluster of arrays or cluster array because LabVIEW does not allow arrays of arrays.

If you wire a file size with a data type other than a 32-bit integer to count, LabVIEW coerces the data type to a 32-bit integer. This means the VI may not read the amount of data you intend. If you wire –1 to count and the size of the file you want to read is too large to be represented by a 32-bit integer, LabVIEW returns an error.

If you wire a cluster of integers to count, the function returns a multidimensional array, one dimension per each cluster element. For example, if you wire a cluster which contains the values 1, 2, and 3 to count, the function returns a 3D array, in which the first dimension contains one element, the second dimension contains two elements, and the third dimension contains three elements.
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.

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.
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, depending on what you want to do with the file. The default is to close the file if it is referenced by a file path or selected from the file dialog box. If file is a refnum or if you wire refnum out to another function, LabVIEW assumes that the file is still in use until you close it.
data contains the data read from the file in the specified data type. It can consist of a string, an array, a cluster of arrays, or a cluster array, depending on which data type you are reading and how count is set.
cancelled is TRUE if you cancel the file dialog box. Otherwise, cancelled is FALSE, even if this function returns an error.
error out contains error information. This output provides standard error out functionality.

Read from Binary File Details

Use the Deny Access function to make sure no other users change the file while you read from it. Use the Set File Position function if you need to perform random access.

This function opens files as read-only. If you wire the refnum out output of this function to the file input of a write function, LabVIEW returns a permissions error. Use the Open/Create/Replace File function to open the file with the default read/write access and wire the refnum to the read and write functions.

Examples

Refer to the following VIs for examples of using the Read from Binary File function: