fbinrecread

Reads unformatted sequential access Fortran binary files.

Prototype

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

	return_val [rec_dims] :  rec_type

Arguments

Full or relative pathname to binary file.

Record number to read from the file beginning at 0.

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

String name of the data type of the record.

Return value

As specified by the rec_dims, rec_type arguments.

Description

fbinrecread reads the rec_num record of the file path and shapes it according to the dimension sizes in parameter rec_dims. 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 fbinrecread will read in the entire record as a singly dimensioned array.

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.

See Also

setfileoption, fbinnumrec, fbindirread, fbinread, fbinrecwrite, fbinwrite, isbigendian

Examples

Example 1

The below is a Fortran (f77) code fragment:

     integer a(5)
     real    x(100), y(399), z(128,64)
     
     open (11,file="example01",form="unformatted")

     write (11) a             ! 1st record   [rec_num=0]
     write (11) x             ! 2nd record   [rec_num=1]
     write (11) y             ! 3rd record   [rec_num=2]
     write (11) z             ! 4th record   [rec_num=3]

Below is the NCL code to read the above. Note that the shape appears to be different for the z variable. In Fortran, the leftmost dimension varies fastest while in NCL [C], the rightmost dimension varies fastest. Thus, the data record will match the fastest varying dimensions correctly.

     fili = "example01"       ; input file    
     a = fbinrecread (fili, 0,   5, "integer")        ; 1st record is zero
     x = fbinrecread (fili, 1, 100, "float")          ; 2nd           one 
     y = fbinrecread (fili, 2, 399, "float")          ; 3rd record is two
     z = fbinrecread (fili, 3, (/ 64,128 /), "float") ; 4th record is three

; sample of reading *all* the float variable in one record.
; data will be a 1D array of length (100+399+128*64)
                                           
  data = fbinrecread (fili, 1, -1, "float")           ; read x, y, z as 1D