FITS_WRITE
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
Write unsigned data types W. Landsman December 1999
Pad data area with zeros not blanks W. McCann/W. Landsman October 2000
Return Message='' to signal normal operation W. Landsman Nov. 2000
Ensure that required extension table keywords are in proper order
W.V. Dixon/W. Landsman March 2001
Assume since V5.1, remove NaNValue keyword W. Landsman Nov. 2002
Removed obsolete !ERR system variable W. Landsman Feb 2004
Check that byte array supplied with table extension W. Landsman Mar 2004
Make number of bytes 64bit to avoid possible overflow W.L Apr 2006
Asuume FITS_OPEN has opened the file with /SWAP_IF_LITTLE_ENDIAN
W. Landsman September 2006
Removes BZERO and BSCALE for floating point output, D. Lindler, Sep 2008