FXWRITE
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.
APPEND = 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.
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, HOST_TO_IEEE, 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
above under NOUPDATE. The first header card may also be
modified to conform to the FITS standard if it does not
already agree (i.e. use of either the SIMPLE or XTENSION
keyword depending on whether the image is the primary HDU or
not).
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.
Version 4.1 Wayne Landsman, GSFC, 02 May 2000
Remove !ERR in call to CHECK_FITS, Use ARG_PRESENT()
Version 5, William Thompson, GSFC, 22 September 2004
Recognize unsigned integer types
Version 5.1 W. Landsman 14 November 204
Allow for need for 64bit number of bytes
Version 6, Craig Markwardt, GSFC, 30 May 2005
Ability to append to existing files
Version
Version 6, 30 May 2005