pro fsave, file = file, help = help

;+
;  PURPOSE:
;    Save a set of FSET frames to a portable XDR file that can be restored
;    later using FRESTORE.
; 
;  USAGE:
;    FSAVE
; 
;  OPTIONAL KEYWORDS:
;    FILE    Name of file name to contain frame information
;            (default='fsave??.xdr', where ?? starts at 01 and increments)
;    /HELP   Print help information only (default=do not print)
; 
;  USAGE NOTES:
;    (1) FSET must have been executed previously to create frame buffers.
;    (2) The file created by FSAVE is in XDR format, and thus is *portable*
;        between different IDL platforms. Each platform must however run
;        the same version of IDL (e.g. FSAVE files created in IDL 5.0
;        cannot be read in IDL 4.0.1).
;    (3) The following items are stored for each frame:
;          - The contents of the graphics window,
;          - The plot-related system variables (!P,!X,!Y,!Z,!MAP),
;          - The color table.
;        This means that the frames can be restored later (in another IDL
;        session, or even on another platform), and all overplotting commands
;        (e.g. OPLOT, PLOTS) will work normally. Map overplotting commands may
;        also be used on restored frames (e.g. MAP_GRID), as long as
;        .COMPILE MAP_SET
;        is done before the map overplotting commands are executed.
; 
;  AUTHOR: Liam Gumley, CIMSS/SSEC, 19-SEP-1997 (liam.gumley@ssec.wisc.edu)
;          29-SEP-1997 Fixed problem with color table for first frame
; 
;  RELATED COMMANDS:
;    FSET   Set up frames in memory
;    FRESTORE  Restore frames saved with FSAVE
; 
;  EXAMPLE:
; 
;  Create four frames with a graphic in each, save the frames to a file, 
;  exit IDL, and then restore the frames and start looping.
; 
; FSET
; LOADCT,13 & TV,BYTSCL(DIST(256),TOP=!D.TABLE_SIZE-1) & AF
; PLOT,INDGEN(10) & AF
; CONTOUR,DIST(32) & AF
; LOADCT,30 & MAP_SET,/CONTINENTS
; FSAVE,FILE='test.xdr'
; EXIT
; ;(restart IDL)
; FRESTORE,'test.xdr'
; LF
;-

;- return to caller if an error occurs

on_error, 2

;- print help message

if keyword_set( help ) then begin
  print, "  PURPOSE:
  print, "    Save a set of FSET frames to a portable XDR file that can be restored
  print, "    later using FRESTORE.
  print, " 
  print, "  USAGE:
  print, "    FSAVE
  print, " 
  print, "  OPTIONAL KEYWORDS:
  print, "    FILE    Name of file to contain frame information
  print, "      (default='fsave??.xdr', where ?? starts at 01 and increments)
  print, "    /HELP   Print help information only (default=do not print)
  print, " 
  print, "  USAGE NOTES:
  print, "    (1) FSET must have been executed previously to create frame buffers.
  print, "    (2) The file created by FSAVE is in XDR format, and thus is *portable*
  print, "     between different IDL platforms. Each platform must however run
  print, "     the same version of IDL (e.g. FSAVE files created in IDL 5.0
  print, "     cannot be read in IDL 4.0.1).
  print, "    (3) The following items are stored for each frame:
  print, "       - The contents of the graphics window,
  print, "       - The plot-related system variables (!P,!X,!Y,!Z,!MAP),
  print, "       - The color table.
  print, "     This means that the frames can be restored later (in another IDL
  print, "     session, or even on another platform), and all overplotting commands
  print, "     (e.g. OPLOT, PLOTS) will work normally. Map overplotting commands may
  print, "     also be used on restored frames (e.g. MAP_GRID), as long as
  print, "     .COMPILE MAP_SET
  print, "     is done before the map overplotting commands are executed.
  print, " 
  print, "  AUTHOR: Liam Gumley, CIMSS/SSEC, 19-OCT-1997 (liam.gumley@ssec.wisc.edu)
  print, "          29-SEP-1997 Fixed problem with color table for first frame
  print, " 
  print, "  RELATED COMMANDS:
  print, "    FSET   Set up frames in memory
  print, "    FRESTORE  Restore frames saved with FSAVE
  print, " 
  print, "  EXAMPLE:
  print, " 
  print, "  Create four frames with a graphic in each, save the frames to a file, 
  print, "  exit IDL, and then restore the frames and start looping.
  print, " 
  print, " FSET
  print, " LOADCT,13 & TV,BYTSCL(DIST(256),TOP=!D.TABLE_SIZE-1) & AF
  print, " PLOT,INDGEN(10) & AF
  print, " CONTOUR,DIST(32) & AF
  print, " LOADCT,30 & MAP_SET,/CONTINENTS
  print, " FSAVE,FILE='test.xdr'
  print, " EXIT
  print, " ;(restart IDL)
  print, " FRESTORE,'test.xdr'
  print, " LF
  goto, finish
endif

;- check keywords

if n_elements( file ) eq 0 then file = newfile( 'fsave', extension = 'xdr' )

;- common block to hold handle id

common frame_info, handle_id

;- check that handle_id is defined

if n_elements( handle_id ) eq 0 then $
  message, 'FSET must be executed before SF can be used'

;- get state information

handle_value, handle_id, state

;- save image for each frame

current = state.current
image = bytarr( state.xsize, state.ysize, state.frames )
for i = 0, state.frames - 1 do begin
  sf, i, /quiet
  image( *, *, i ) = tvrd()
endfor
sf, current, /quiet

;- update state information

handle_value, handle_id, state

;- save state information

save, state, image, /xdr, file = file

;- let user know what happened

print, strcompress( 'Saved ' + string( state.frames ) + $
  ' frames to ' + file + " (use  FRESTORE,'" + file + "'  to restore frames)" )

finish:

end