The READ_BINARY function reads the contents of a binary file using a passed template or basic command line keywords. Data is read from the given filename or from the current file position in the open file pointed to by FileUnit. If no template is provided, keywords can be used to read a single IDL array of data.
Result = READ_BINARY ([Filename] | FileUnit [, TEMPLATE=template] | [[, DATA_START=value] [, DATA_TYPE=typecodes] [, DATA_DIMS=array] [, ENDIAN=string]] )
The result is an array or anonymous structure containing all of the entities read from the file.
A scalar string containing the name of the binary file to read. If filename and file unit are not specified, a dialog allows the user to choose a file.
A scalar containing an open IDL file unit number to read from.
Set this keyword to a scalar or array of up to eight elements specifying the size of the data to be read and returned. For example, DATA_DIMS=[512,512] specifies that a two-dimensional, 512 by 512 array be read and returned. DATA_DIMS=0 specifies that a single, scalar value be read and returned. Default is -1, which, if a TEMPLATE is not supplied that specifies otherwise, indicates that READ_BINARY will read to end-of-file and store the result in a 1-D array.
Set this keyword to specify where to begin reading in a file. This value is as an offset, in bytes, that will be applied to the initial position in the file. The default is 0.
Set this keyword to an IDL typecode of the data to be read. See documentation for the SIZE function for a listing of typecodes. Default is 1 (IDL's BYTE typecode).
Set this keyword to one of three string values: `big", "little" or "native" which specifies the byte ordering of the file to be read. If the computer running READ_BINARY uses byte ordering that is different than that of the file, READ_BINARY will swap the order of bytes in multi-byte data types read from the file. (Default: "native" = perform no byte swapping.)
Set this keyword to a template structure (created using the BINARY_TEMPLATE function) describing the file to be read. The TEMPLATE keyword cannot be used simultaneously with keywords DATA_START, DATA_TYPE, DATA_DIMS, or ENDIAN.
When a template is used with READ_BINARY, the the return value is a structure containing fields specified by the template. If a template is not used, the return value is an array.
Introduced: 5.3