PRO BINREAD, LUN, DATA, HEADER=HEADER

;+
; NAME:
;    BINREAD
;
; PURPOSE:
;    Read an array from an unformatted binary file created by BINWRITE.
;
;    BINREAD can read files created by BINWRITE on any IDL platform;
;    any byte-swapping which may be required is handled automatically.
;
;    The data types supported are:
;    Type code    Type
;      1          Byte
;      2          Integer
;      3          Longword integer
;      4          Floating point
;      5          Double-precision floating
;      6          Complex floating
;      9          Double-precision complex
;     12          Unsigned Integer
;     13          Unsigned Longword Integer
;     14          64-bit Integer
;     15          Unsigned 64-bit Integer
;
;    The data types not supported are:
;    Type code    Type
;      0          Undefined
;      7          String
;      8          Structure
;     10          Pointer
;     11          Object reference
;
; CATEGORY:
;    Input/Output.
;
; CALLING SEQUENCE:
;    BINREAD, LUN, DATA
;
; INPUTS:
;    LUN       Logical unit number of a file which is open for reading.
;    
; OPTIONAL INPUTS:
;    None.
;	
; KEYWORD PARAMETERS:
;    HEADER    If set to a named variable, returns the dataset header.
;
; OUTPUTS:
;    DATA      Named variable where data will be stored.
;
; OPTIONAL OUTPUTS:
;    None
;
; COMMON BLOCKS:
;    None
;
; SIDE EFFECTS:
;    None
;
; RESTRICTIONS:
;    Requires IDL 5.1 or higher.
;
; EXAMPLE:
;
;;Write two arrays to an output file
;
;a = dist(256)
;b = bindgen(100)
;openw, lun, 'test.dat', /get_lun
;binwrite, lun, a
;binwrite, lun, b
;free_lun, lun
;
;;Read the two arrays from the file into new variables
;
;openr, lun, 'test.dat', /get_lun
;binread, lun, c, header=header
;binread, lun, d
;free_lun, lun
;print, header
;help, c, d
;
; MODIFICATION HISTORY:
; Liam.Gumley@ssec.wisc.edu (http://cimss.ssec.wisc.edu/~gumley)
; $Id: binread.pro,v 1.2 1999/09/30 16:29:05 gumley Exp $
;-

;- Check arguments

if n_elements(lun) eq 0 then message, 'LUN is undefined'
if not arg_present(data) then message, 'DATA cannot be modified'

;- Check that file is open for reading, and has a valid size

result = fstat(lun)
if result.read eq 0 then message, 'LUN is not open for reading'
if result.size lt 105L then message, 'File is not in valid BINWRITE format'

;- If file pointer is at beginning of file, or HEADER keyword was passed,
;- read the header text

if result.cur_ptr eq 0L or arg_present(header) then begin

  ;- Save current file pointer, then point to beginning of file
  
  current_pos = result.cur_ptr
  if current_pos gt 0L then point_lun, lun, 0L
  
  ;- Read the header text
  
  header = bytarr(80)
  readu, lun, header
  header = string(header)
  if strmid(header, 0, 3) ne 'IDL' then $
    message, 'File is not in valid BINWRITE format'
    
  ;- Reset the file pointer
  
  if current_pos gt 0L then point_lun, lun, current_pos
      
endif

;- Read magic value

magic_value = 0L
readu, lun, magic_value

;- Decode magic value to see if byte swapping is required

swap_flag = 0
if magic_value ne 123456789L then begin
  magic_value = swap_endian(magic_value)
  if magic_value eq 123456789L then begin
    swap_flag = 1
  endif else begin
    message, 'File is not in valid BINWRITE format'
  endelse
endif

;- Read the header information

info_size = 0L
readu, lun, info_size
if swap_flag then info_size = swap_endian(info_size)
info = lonarr(info_size)
readu, lun, info
if swap_flag then info = swap_endian(info)

;- Read the data

data = make_array(size=info)
readu, lun, data
if swap_flag then data = swap_endian(temporary(data))

END