idlastro / FITS Binary Table Extensions I/O: FXWRITE

[Source code]

NAME
FXWRITE
Purpose
Write a disk FITS file.
Explanation
Creates or appends to a disk FITS file and writes a FITS
header, and optionally an image data array.
Use
FXWRITE, FILENAME, HEADER [, DATA ]
Inputs
FILENAME = String containing the name of the file to be written.
HEADER   = String array containing the header for the FITS file.
Opt. Inputs
DATA     = IDL data array to be written to the file.  If not passed,
           then it is assumed that extensions will be added to the
           file.
Outputs
None.
Opt. Outputs
None.
Keywords
NANVALUE = Value signalling data dropout.  All points corresponding to
           this value are set to be IEEE NaN (not-a-number).  Ignored
           unless DATA is of type float, double-precision or complex.
NOUPDATE = If set, then the optional BSCALE and BZERO keywords in the
           HEADER array will not be changed.  The default is to reset
           these keywords to BSCALE=1, BZERO=0.
PPEND = If set, then an existing file will be appended to.
        Appending to a non-existent file will create it.  If
        a primary HDU already exists then it will be modified
        to have EXTEND = T.
LLOW_DEGEN = If set, then don't check for degenerate axes in
             CHECK_FITS.
ERRMSG   = If defined and passed, then any error messages will be
           returned to the user in this parameter rather than
           depending on the MESSAGE routine in IDL.  If no errors are
           encountered, then a null string is returned.  In order to
           use this feature, ERRMSG must be defined first, e.g.
                ERRMSG = ''
                FXWRITE, ERRMSG=ERRMSG, ...
                IF ERRMSG NE '' THEN ...
Calls
CHECK_FITS, GET_DATE, FXADDPAR, FXPAR
Common
None.
Restrictions
If DATA is passed, then HEADER must be consistent with it.  If no data
array is being written to the file, then HEADER must also be consistent
with that.  The routine FXHMAKE can be used to create a FITS header.
If found, then the optional keywords BSCALE and BZERO in the HEADER
array is changed so that BSCALE=1 and BZERO=0.  This is so that these
scaling parameters are not applied to the data a second time by another
routine.  Also, history records are added storing the original values
of these constants.  (Other values of BZERO are used for unsigned
integers.)
If the /NOUPDATE keyword is set, however, then the BSCALE and BZERO
keywords are not changed.  The user should then be aware that FITS
readers will apply these numbers to the data, even if the data is
already converted to floating point form.
Groups are not supported.
Side effects
HEADER may be modified.  One way it may be modified is describe
bove under NOUPDATE.  The first header card may also be
odified to conform to the FITS standard if it does not
lready agree (i.e. use of either the SIMPLE or XTENSION
eyword depending on whether the image is the primary HDU or
ot).
Category
Data Handling, I/O, FITS, Generic.
Prev. Hist.
W. Thompson, Jan 1992, from WRITEFITS by J. Woffard and W. Landsman.
Differences include:
        * Made DATA array optional, and HEADER array mandatory.
        * Changed order of HEADER and DATA parameters.
        * No attempt made to fix HEADER array.
W. Thompson, May 1992, changed open statement to force 2880 byte fixed
                       length records (VMS).  The software here does not
                       depend on this file configuration, but other
                       FITS readers might.
W. Thompson, Aug 1992, added code to reset BSCALE and BZERO records,
                       and added the NOUPDATE keyword.
Written
William Thompson, GSFC, January 1992.
Modified
Version 1, William Thompson, GSFC, 12 April 1993.
        Incorporated into CDS library.
Version 2, William Thompson, GSFC, 31 May 1994
        Added ERRMSG keyword.
Version 3, William Thompson, GSFC, 23 June 1994
        Modified so that ERRMSG is not touched if not defined.
Version 4, William Thompson, GSFC, 12 August 1999
        Catch error if unable to open file.
ersion 4.1 Wayne Landsman, GSFC, 02 May 2000
       Remove !ERR in call to CHECK_FITS, Use ARG_PRESENT()
ersion 5, William Thompson, GSFC, 22 September 2004
       Recognize unsigned integer types
ersion 5.1 W. Landsman 14 November 2004 
       Allow for need for 64bit number of bytes
ersion 6, Craig Markwardt, GSFC, 30 May 2005
       Ability to append to existing files
ersion 7, W. Landsman GSFC, Mar 2014
       Remove HOST_TO_IEEE, Use V6.0 notation
ersion 8, William Thompson, 26-Jun-2019, add /ALLOW_DEGEN
Version
Version 8, 26-Jun-2019