PRO BINWRITE, LUN, DATA

;+
; NAME:
;    BINWRITE
;
; PURPOSE:
;    Write an array to an unformatted binary file, which may
;    be read with BINREAD.
;
;    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:
;    BINWRITE, LUN, DATA
;
; INPUTS:
;    LUN     Logical unit number of a file which is open for writing.
;    DATA    Array of data to be written.
;    
; OPTIONAL INPUTS:
;    None.
;	
; KEYWORD PARAMETERS:
;    None.
;
; OUTPUTS:
;    None.
;
; OPTIONAL OUTPUTS:
;    None
;
; COMMON BLOCKS:
;    None
;
; SIDE EFFECTS:
;    The output file is overwritten if it exists.
;
; RESTRICTIONS:
;    Requires IDL 5.1 or higher.
;    Argument DATA must be an array.
;    Argument DATA must be a supported data type.
;
; 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
;
; MODIFICATION HISTORY:
; Liam.Gumley@ssec.wisc.edu (http://cimss.ssec.wisc.edu/~gumley)
; $Id: binwrite.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 n_elements(data) eq 0 then message, 'DATA is undefined'

;- Check that file is open for writing

result = fstat(lun)
if result.write eq 0 then message, 'LUN is not open for writing'

;- Check that data type is allowed

type_name = size(data, /tname)
if type_name eq 'STRING' or $
   type_name eq 'STRUCT' or $
   type_name eq 'POINTER' or $
   type_name eq 'OBJREF' then message, 'DATA type is not supported'

;- Check that DATA is an array

if size(data, /n_dimensions) lt 1 then message, 'DATA must be an array'

;- If file pointer is at the beginning of the file, write header text

if result.cur_ptr eq 0 then begin
  header = string(float(!version.release), !version.os, systime(), $
    format='("IDL ", f3.1, " BINWRITE file, Platform: ", a9, ", Created on: ", a)')
  writeu, lun, header
endif

;- Write header information for this data array to file

magic_value = 123456789L
info = size(data)
info_size = n_elements(info)
writeu, lun, magic_value, info_size, info

;- Write this data array to file

writeu, lun, data

END