idlastro / FITS I/O: FITS_WRITE

[Source code]

NAME
FITS_WRITE
PURPOSE
To write a FITS primary data unit or extension.
EXPLANATION
***NOTE** This version of FITS_READ must be used with a post Sep 2006
   version of FITS_OPEN.
CALLING SEQUENCE
FITS_WRITE, filename_or_fcb, data, [header_in]
INPUTS
FILENAME_OR_FCB: name of the output data file or the FITS control
        block returned by FITS_OPEN (called with the /WRITE or
        /APPEND) parameters.
OPTIONAL INPUTS
DATA: data array to write.  If not supplied or set to a scalar, a
        null image is written.
HEADER_IN: FITS header keyword.  If not supplied, a minimal basic
        header will be created.  Required FITS keywords, SIMPLE,
        BITPIX, XTENSION, NAXIS, ... are added by FITS_WRITE and
        do not need to be supplied with the header.  If supplied,
        their values will be updated as necessary to reflect DATA.
INPUT KEYWORD PARAMETERS
XTENSION: type of extension to write (Default="IMAGE"). If not
        supplied, it will be taken from HEADER_IN.  If not in either
        place, the default is "IMAGE".  This parameter is ignored
        when writing the primary data unit.     Note that binary and
       and ASCII table extensions already have a properly formatted
       header (e.g. with TTYPE* keywords) and byte array data. 
EXTNAME: EXTNAME for the extension.  If not supplied, it will be taken
        from HEADER_IN.  If not supplied and not in HEADER_IN, no
        EXTNAME will be written into the output extension.
EXTVER: EXTVER for the extension.  If not supplied, it will be taken
       from HEADER_IN.  If not supplied and not in HEADER_IN, no
       EXTVER will be written into the output extension.
EXTLEVEL: EXTLEVEL for the extension.  If not supplied, it will be taken
       from HEADER_IN.  If not supplied and not in HEADER_IN, no
       EXTLEVEL will be written into the output extension.
NO_ABORT: Set to return to calling program instead of a RETALL
       when an I/O error is encountered.  If set, the routine will
       return  a non-null string (containing the error message) in the
       keyword MESSAGE.   If /NO_ABORT not set, then FITS_WRITE will 
       print the message and issue a RETALL
/NO_DATA: Set if you only want FITS_WRITE to write a header.  The
        header supplied will be written without modification and
        the user is expected to write the data using WRITEU to unit
        FCB.UNIT. When FITS_WRITE is called with /NO_DATA, the user is
        responsible for the validity of the header, and must write
        the correct amount and format of the data.  When FITS_WRITE
        is used in this fashion, it will pad the data from a previously
        written extension to 2880 blocks before writting the header.
OUTPUT KEYWORD PARAMETERS
MESSAGE: value of the error message for use with /NO_ABORT
 HEADER: actual output header written to the FITS file.
NOTES
If the first call to FITS_WRITE is an extension, FITS_WRITE will
automatically write a null image as the primary data unit.
Keywords and history in the input header will be properly separated
into the primary data unit and extension portions when constructing
the output header (See FITS_READ for information on the internal
Header format which separates the extension and PDU header portions).
EXAMPLES
Write an IDL variable to a FITS file with the minimal required header.
        FITS_WRITE,'newfile.fits',ARRAY
Write the same array as an image extension, with a null Primary data
unit.
        FITS_WRITE,'newfile.fits',ARRAY,xtension='IMAGE'
Write 4 additional image extensions to the same file.
        FITS_OPEN,'newfile.fits',fcb
        FITS_WRITE,fcb,data1,extname='FLUX',extver=1
        FITS_WRITE,fcb,err1,extname'ERR',extver=1
        FITS_WRITE,fcb,data2,extname='FLUX',extver=2
        FITS_WRITE,fcb,err2,extname='ERR',extver=2
        FITS_CLOSE,FCB
WARNING
FITS_WRITE currently does not completely update the file control block.
When mixing FITS_READ and FITS_WRITE commands it is safer to use 
file names, rather than passing the file control block.
PROCEDURES USED
FITS_OPEN, SXADDPAR, SXDELPAR, SXPAR()
HISTORY
Written by:     D. Lindler      August, 1995
Work for variable length extensions  W. Landsman   August 1997
Converted to IDL V5.0   W. Landsman   September 1997
PCOUNT and GCOUNT added for IMAGE extensions   J. Graham  October 1999
rite unsigned data types      W. Landsman   December 1999
ad data area with zeros not blanks  W. McCann/W. Landsman October 2000
eturn Message='' to signal normal operation W. Landsman Nov. 2000
nsure that required extension table keywords are in proper order
     W.V. Dixon/W. Landsman          March 2001
ssume since V5.1, remove NaNValue keyword   W. Landsman Nov. 2002
emoved obsolete !ERR system variable  W. Landsman Feb 2004
heck that byte array supplied with table extension W. Landsman Mar 2004
ake number of bytes 64bit to avoid possible overflow W.L  Apr 2006
ssume FITS_OPEN has opened the file with /SWAP_IF_LITTLE_ENDIAN
                 W. Landsman   September 2006
emoves BZERO and BSCALE for floating point output, D. Lindler, Sep 2008