NCL Home > Documentation > Functions > File IO

fbindirread

Reads records written by a Fortran direct access write.

Prototype

	function fbindirread (
		path     [1] : string,   
		rec_num  [1] : integer,  
		rec_dims [*] : integer,  
		rec_type [1] : string    
	)

	return_val [rec_dims] :  rec_type

Arguments

path

Pathname to binary file

rec_num

Record number to read from the file beginning at 0. Please see caveat below.

rec_dims

A singly dimensioned array of integer values that describe how to shape the data, or -1 if the size of the record is unknown.

rec_type

String name of the data type of the record.

Return value

As described by the rec_dims and rec_type arguments.

Description

fbindirread reads the rec_num record of the file path and shapes it according to the dimension sizes specified in the rec_dims parameter. The data type of the record is specified by the parameter rec_type. If the size and dimensionality of the record are unknown, the value -1 can be used for parameter rec_dims. In this case fbindirread will read in the entire file as a singly dimensioned array.

The file must have been been written to a file created by a fortran "open" statement of the form

    open (..., access="direct", form="unformatted", recl=..., ...)

All records in the file must have the same dimensions and must be the same type.

Note: As with any binary file, the "endian-ness" of the data on the file and that of the current system must agree. The "ReadByteOrder" option in the setfileoption procedure can be used to force the "endian" type in a file. This allows big-endian files to be read on a little-endian machine and vice versa. The isbigendian function can be used to determine the endian-ness of your current system.

This function was updated in version 4.3.0 in order to allow reads into files bigger than 2 GB. This change allows you to access records that occur past the 2 GB point in the file, but not to read into variables that would be larger than 2 GB.

Caveat: we've run across binary files that were written with 8-byte record markers. This function may expect them to be 4-bytes; it just depends on what system NCL was compiled on.
This happens if the Fortran program that created the binary file was compiled with a version of "g77" or "gfortran" that sets the marker size to whatever "off_t" is on that system.
As a work-around, you can recompile the code that created the binary file with the option "-frecord-marker=4" to force a 4-byte record, and run the code again to regenerate the file.
It is on our list to create a new option in setfileoption that will allow you to specify the record marker size that the file was written with.

Examples

  path = "/dummy/file.binary"
  nrec = 5
  dims = (/10,30/)
  x = fbindirread(path, nrec, dims, "float")