Read File

Reads data from an open file specified by refnum and returns it in data. Reading begins at a location specified by pos mode and pos offset and depends on the format of the specified file.

convert eol determines whether the function converts the end of line markers it reads into LabVIEW end of line markers. You can wire convert eol only if data is a string. The system-specific end of line marker is a carriage return followed by a line feed on Windows, a carriage return on Macintosh, and a line feed on UNIX. The LabVIEW end of line marker is a line feed.

If convert eol is TRUE, the function converts all end of line markers it encounters into line feeds. If convert eol is FALSE (default), the function does not convert the end of line markers it reads.

If header is TRUE, LabVIEW ignores convert eol.

line mode, in conjunction with count, determines when the read stops. If line mode is TRUE, and if you do not wire count or count equals 0, Read File reads until it encounters an end of line marker--a carriage return, a line feed, or a carriage return followed by a line feed, or it encounters end of file. If line mode is TRUE, and count is greater than 0, Read File reads until it encounters an end of line marker, it encounters end of file, or it reads count characters.

If line mode is FALSE, Read File reads count characters. In this case, if you do not wire count, it defaults to 0. line mode defaults to FALSE. Do not wire the convert eol and line mode inputs for binary files. They are important for text files, but not for binary files.

refnum is the file refnum associated with the file you want to read. If refnum is a datalog file refnum, the Read File function reads data as records from the datalog file specified by refnum. If you want to read more than one data record at a time, use the count and offset parameters. The convert eol, header, pos mode, and pos offset parameters do not apply with datalog files, so you cannot wire them.
pos mode, together with pos offset, specifies where the read or write operation begins. If the computed location does not exist in the file, for example, pos mode = 0 and pos offset = –10, the file mark does not move, no data is read or written, and the function returns an error.

If you wire pos offset, pos mode defaults to 0, and the offset is relative to the beginning of the file. If you do not wire pos offset it defaults to 0, pos mode defaults to 2, and the operation starts at the current file mark. Do not wire these inputs if you want to read or write the data following the most recently read or written data.

0Start—The operation begins at the beginning of the file plus pos offset.
1End—The operation begins at the end of the file plus pos offset.
2Current—The operation begins at the current location of the file mark plus pos offset.
pos offset specifies how far from the location specified by pos mode to start reading or writing. You express pos offset in units of bytes. The default is 0.

Do not wire pos mode and pos offset if you want to read the data following the most recently read or written data.

error in describes error conditions that occur before this VI or function runs. The default is no error. If an error occurred before this VI or function runs, the VI or function passes the error in value to error out. This VI or function runs normally only if no error occurs before this VI or function runs. If an error occurs while this VI or function runs, it runs normally and sets its own error status in error out. Use the Simple Error Handler or General Error Handler VIs to display the description of the error code. Use error in and error out to check errors and to specify execution order by wiring error out from one node to error in of the next node.
status is TRUE (X) if an error occurred before this VI or function ran or FALSE (checkmark) to indicate a warning or that no error occurred before this VI or function ran. The default is FALSE.
code is the error or warning code. The default is 0. If status is TRUE, code is a non-zero error code. If status is FALSE, code is 0 or a warning code.
source describes the origin of the error or warning and is, in most cases, the name of the VI or function that produced the error or warning. The default is an empty string.
count is the number of records or bytes to read. If you do not wire byte stream type, you can wire count to only a numeric. For text or binary files, if you wire count but you do not wire byte stream type, data is a string. If you wire count and byte stream type, the function returns an array containing count elements of the same data type as byte stream type.

You can lock or unlock a range that extends beyond the end of the file to ensure that no other users append to a file while you append to it. This function returns an error if count is less than zero.

If refnum is a datalog file refnum, count is the number of records to read. The default is to read and return a single record of the datalog type specified when the file is created or opened. For example, if the type is a 16-bit integer, the function returns one 16-bit integer. If the type is an array of 16-bit integers, the functions returns one array of 16-bit integers. Records typically consist of clusters of diverse elements, but the rules for simple types used in these examples apply to those as well.

If you wire count, specify a scalar number if you want the function to return a 1D array of records. Specify a cluster of n scalar numbers if you want the function to return an n-dimension array of records.

If you wire count with a scalar number and the datalog type is something other than an array, the function returns that number of records in a 1D array. For example, if the type is a single-precision, floating-point number and count is 3, the array contains three, single-precision, floating-point numbers. However, if the type is an array, the function returns the records in a cluster array because LabVIEW does not have arrays of arrays. Therefore, if the datalog type is an array of single-precision, floating-point numbers and count is 3, the function returns a cluster array of three, single-precision, floating-point number arrays.

If the wired count is a cluster of n numbers, whose product is m, the function reads m instances of datalog type. The function returns an n-dimension array of instances of the type. For example, if the type is a single-precision, floating-point number and count is a two-element cluster with element 0 = 2 and element 1 = 10, the function returns a 2x10 array of 20, single-precision, floating-point numbers. However, if the datalog type is an array, the function returns the instances in a cluster array, because LabVIEW does not have arrays of arrays. Therefore, if the type is an array of single-precision, floating-point numbers and count is is a two-element cluster with element 0 = 2 and element 1 = 10, the function returns a 2x10 cluster array of 20 single-precision, floating-point number arrays.

The number of records read can be less than specified by count if this function encounters the end of file. In this case, the function returns all the records up to the end of file and returns an end-of-file error.

byte stream type can be any data type. Use this input when reading byte stream files to indicate which data type LabVIEW should use to interpret data in the file. This function interprets the data starting at the designated byte offset to be count instances of that type. If the type is variable-length, that is, an array, a string, or a cluster containing an array or string, the function assumes that each instance of the type contains the length or dimensions of that instance. If they do not, the function misinterprets the data. If LabVIEW determines that the data does not match the type, it sets the value of data to the default for its type and returns an error.

Refer to the Choosing a File I/O Format section of Chapter 13, Reading from and Writing to Files, in the LabVIEW User Manual for more information about the byte stream file and datalog file formats.

If the function encounters the end of the file before reading all of the requested data, it returns as many whole instances of the designated byte stream type as it finds.

If you wire byte stream type, count is the number of instances of the byte stream type to read. The default is to return a single instance of the byte stream type and return it to data.

If you wire count, it can be a scalar number, in which case the function returns a 1D array of instances of the byte stream type. Or it can be a cluster of n scalar numbers, in which case the function returns an n-dimension array of instances of the byte stream type.

If the wired count is a scalar number and the byte stream type is something other than an array, the function returns that number of instances in a 1D array. For example, if type is unwired and count is 3, the function returns a string with three characters. If the type is a single-precision, floating point number, the function returns an array of three, single-precision, floating point numbers. However, if byte stream type is an array, the function returns the instances in a cluster array, because LabVIEW does not have arrays of arrays. Therefore, if the type is an array of single-precision, floating point numbers and count is 3, the function returns a cluster array of three, single-precision, floating point number arrays.

If the wired count is a cluster of n numbers, the function returns an n-dimension array of instances of byte stream type. The size of each dimension is the value of the corresponding number according to its cluster order. The number of instances returned in this manner is the product of the n numbers. The function returns an n-dimension array of instances of byte stream type. For example, if the type is a single-precision, floating-point number and count is a two-element cluster with element 0 = 2 and element 1 = 10, the function returns a 2x10 array of 20, single-precision, floating-point numbers. However, if the byte stream type is an array, the function returns the instances in a cluster array, because LabVIEW does not have arrays of arrays. Therefore, if the type is an array of single-precision, floating-point numbers and count is is a two-element cluster with element 0 = 2 and element 1 = 10, the function returns a 2x10 cluster array of 20 single-precision, floating-point number arrays.

If you do not wire count, the function reads and returns a single record of the datalog type specified when the file is created or opened. For example, if the type is a 16-bit integer, the function returns one 16-bit integer. If the type is an array of 16-bit integers, the functions returns one array of 16-bit integers. Records typically consist of clusters of diverse elements, but the rules for simple types used in these examples apply to those as well.

dup refnum returns refnum unedited.
data contains the data read from the file. Refer to the previous description of count for more information about the structures data can have.
offset indicates the new location of the current file mark relative to the beginning of the file. offset is expressed in the same terms as pos offset, that is records for datalog files and bytes for byte stream files.
error out contains error information. If error in indicates that an error occurred before this VI or function ran, error out contains the same error information. Otherwise, it describes the error status that this VI or function produces. Right-click the error out indicator on the front panel and select Explain Error from the shortcut menu for more information about the error.
status is TRUE (X) if an error occurred or FALSE (checkmark) to indicate a warning or that no error occurred.
code is the error or warning code. If status is TRUE, code is a non-zero error code. If status is FALSE, code is 0 or a warning code.
source describes the origin of the error or warning and is, in most cases, the name of the VI or function that produced the error or warning.