idlastro / FITS I/O: MWRFITS

[Source code]

NAME
MWRFITS
PURPOSE
Write all standard FITS data types from input arrays or structures.
EXPLANATION
Must be used with a post-September 2009 version of FXADDPAR.
CALLING SEQUENCE
MWRFITS, Input, Filename, [Header],
                /LSCALE , /ISCALE, /BSCALE, 
                /USE_COLNUM, /Silent, /Create, /No_comment, /Version, $
                Alias=, /ASCII, Separator=, Terminator=, Null=,
                /Logical_cols, /Bit_cols, /Nbit_cols, 
                Group=, Pscale=, Pzero=, Status=
INPUTS
Input = Array or structure to be written to FITS file.
        -When writing FITS primary data or image extensions
         input should be an array.
        --If data is to be grouped
          the Group keyword should be specified to point to
          a two dimensional array.  The first dimension of the
          Group array will be PCOUNT while the second dimension
          should be the same as the last dimension of Input.
        --If Input is undefined, then a dummy primary dataset
          or Image extension is created [This might be done, e.g.,
          to put appropriate keywords in a dummy primary
          HDU].
        -When writing an ASCII table extension, Input should
         be a structure array where no element of the structure
         is a structure or array (except see below).
        --A byte array will be written as A field.  No checking
          is done to ensure that the values in the byte field
          are valid ASCII.
        --Complex numbers are written to two columns with '_R' and
          '_I' appended to the TTYPE fields (if present).  The
          complex number is enclosed in square brackets in the output.
        --Strings are written to fields with the length adjusted
          to accommodate the largest string.  Shorter strings are
          blank padded to the right.
        -When writing a binary table extension, the input should
         be a structure array with no element of the structure
         being a substructure.
        If a structure is specified on input and the output
        file does not exist or the /CREATE keyword is specified
        a dummy primary HDU is created.
Filename = String containing the name of the file to be written.
         By default MWRFITS appends a new extension to existing
         files which are assumed to be valid FITS.  The /CREATE
         keyword can be used to ensure that a new FITS file
         is created even if the file already exists.
OUTPUTS
OPTIONAL INPUTS
Header = Header should be a string array.  Each element of the
         array is added as a row in the FITS  header.  No
         parsing is done of this data.  MWRFITS will prepend
         required structural (and, if specified, scaling)
         keywords before the rows specified in Header.
         Rows describing columns in the table will be appended
         to the contents of Header.
         Header lines will be extended or truncated to
         80 characters as necessary.
         If Header is specified then on return Header will have
         the header generated for the specified extension.
OPTIONAL INPUT KEYWORDS
ALias=   Set up aliases to convert from the IDL structure
         to the FITS column name.  The value should be
         a STRARR(2,*) value where the first element of
         each pair of values corresponds to a column
         in the structure and the second is the name
         to be used in the FITS file.
         The order of the alias keyword is compatible with
         use in MRDFITS.
ASCII  - Creates an ASCII table rather than a binary table.
         This keyword may be specified as:
         /ASCII - Use default formats for columns.
         ASCII='format_string' allows the user to specify
           the format of various data types such using the following
           syntax 'column_type:format, column_type:format'.  E.g.,
         ASCII='A:A1,I:I6,L:I10,B:I4,F:G15.9,D:G23.17,C:G15.9,M:G23.17'
         gives the default formats used for each type.  The TFORM
         fields for the real and complex types indicate will use corresponding
         E and D formats when a G format is specified.
         Note that the length of the field for ASCII strings and
         byte arrays is automatically determined for each column.
BIT_COLS=   An array of indices of the bit columns.   The data should
         comprise a byte array with the appropriate dimensions.
         If the number of bits per row (see NBIT_COLS)
         is greater than 8, then the first dimension of the array 
         should match the number of input bytes per row.
BSCALE   Scale floats, longs, or shorts to unsigned bytes (see LSCALE)
/CREATE   If this keyword is non-zero, then a new FITS file will
         be created regardless of whether the file currently
         exists.  Otherwise when the file already exists,
         a FITS extension will be appended to the existing file
         which is assumed to be a valid FITS file.
GROUP=   This keyword indicates that GROUPed FITS data is to
         be generated.
         Group should be a 2-D array of the appropriate output type.
         The first dimension will set the number of group parameters.
         The second dimension must agree with the last dimension
         of the Input array.
ISCALE   Scale floats or longs to short integer (see LSCALE)
LOGICAL_COLS=  An array of indices of the logical column numbers.
         These should start with the first column having index *1*.
         The structure element should either be an array of characters
         with the values 'T' or 'F', or an array of bytes having the 
         values byte('T')=84b, byte('F')=70b or 0b.     The use of bytes
         allows the specification of undefined values (0b).
LSCALE   Scale floating point numbers to long integers.
         This keyword may be specified in three ways.
         /LSCALE (or LSCALE=1) asks for scaling to be automatically
         determined. LSCALE=value divides the input by value.
         I.e., BSCALE=value, BZERO=0.  Numbers out of range are 
         given the value of NULL if specified, otherwise they are given
         the appropriate extremum value.  LSCALE=(value,value)
         uses the first value as BSCALE and the second as BZERO
         (or TSCALE and TZERO for tables).
NBIT_COLS=  The number of bits actually used in the bit array.
         This argument must point to an array of the same dimension
         as BIT_COLS.
/NO_COPY = By default, MWRFITS makes a copy of the input variable
         before any modifications necessary to write it to a FITS
         file.    If you have a large array/structure, and don't 
         require it for subsequent processing, then /NO_COPY will
         save memory.
NO_TYPES  If the NO_TYPES keyword is specified, then no TTYPE
         keywords will be created for ASCII and BINARY tables.
No_comment Do not write comment keywords in the header
NULL=    Value to be written for integers/strings which are
         undefined or unwritable.
PSCALE=  An array giving scaling parameters for the group keywords.
         It should have the same dimension as the first dimension
         of Group.
PZERO=   An array giving offset parameters for the group keywords.
         It should have the same dimension as the first dimension
         of Group.
Separator= This keyword can be specified as a string which will
         be used to separate fields in ASCII tables.  By default
         fields are separated by a blank.
/SILENT   Suppress informative messages.  Errors will still
         be reported.
Terminator= This keyword can be specified to provide a string which
         will be placed at the end of each row of an ASCII table.
         No terminator is used when not specified.
         If a non-string terminator is specified (including
         when the /terminator form is used), a new line terminator
         is appended.
USE_COLNUM  When creating column names for binary and ASCII tables
         MWRFITS attempts to use structure field name
         values.  If USE_COLNUM is specified and non-zero then
         column names will be generated as 'C1, C2, ... 'Cn'
         for the number of columns in the table.
Version   Print the version number of MWRFITS.
OPTIONAL OUTPUT KEYWORD
Status - 0 if FITS file is successfully written, -1 if there is a
         a problem (e.g. nonexistent directory, or no write permission)
EXAMPLE
Write a simple array:
     a=fltarr(20,20)
     mwrfits,a,'test.fits'
Append a 3 column, 2 row, binary table extension to file just created.
     a={name:'M31', coords:(30., 20.), distance:2}
     a=replicate(a, 2);
     mwrfits,a,'test.fits'
Now append an image extension:
     a=lonarr(10,10,10)
     mkhdr,hdr,a,/image       ;Create minimal image extension FITS header
     sxaddhist,["This is a comment line to put in the header", $
          "And another comment"],hdr,/comment
     mwrfits,a,'test.fits',hdr
RESTRICTIONS
(1)     Variable length columns are not supported for anything
        other than simple types (byte, int, long, float, double).
(2)     Empty strings are converted to 1 element blank strings (because
        IDL refuses to write an empty string (0b) from a structure)
NOTES
This multiple format FITS writer is designed to provide a
single, simple interface to writing all common types of FITS data.
Given the number of options within the program and the
variety of IDL systems available it is likely that a number
of bugs are yet to be uncovered. 
PROCEDURES USED
FXPAR(), FXADDPAR
MODIfICATION HISTORY
Version 0.9: By T. McGlynn   1997-07-23
       Initial beta release.
Dec 1, 1997, Lindler, Modified to work under VMS.
Version 0.91: T. McGlynn  1998-03-09
        Fixed problem in handling null primary arrays.
Version 0.92: T. McGlynn 1998-09-09
        Add no_comment flag and keep user comments on fields.
        Fix handling of bit fields.
Version 0.93: T. McGlynn 1999-03-10
        Fix table appends on VMS.
Version 0.93a  W. Landsman/D. Schlegel
        Update keyword values in chk_and_upd if data type has changed 
Version 0.94: T. McGlynn 2000-02-02
        Efficient processing of ASCII tables.
        Use G rather than E formats as defaults for ASCII tables
         and make the default precision long enough that transformations
         binary to/from ASCII are invertible.
        Some loop indices made long.
        Fixed some ends to match block beginnings.
Version 0.95: T. McGlynn 2000-11-06
        Several fixes to scaling.  Thanks to David Sahnow for
        documenting the problems.
        Added PCOUNT,GCOUNT keywords to Image extensions.
        Version numbers shown in SIMPLE/XTENSION comments
Version 0.96: T. McGlynn 2001-04-06
        Changed how files are opened to handle ~ consistently
Version 1.0: T. McGlynn 2001-12-04
        Unsigned integers,
        64 bit integers.
        Aliases
        Variable length arrays
        Some code cleanup
Version 1.1: T. McGlynn 2002-2-18
        Fixed major bug in processing of unsigned integers.
        (Thanks to Stephane Beland)
Version 1.2: Stephane Beland 2003-03-17
        Fixed problem in creating dummy dataset when passing undefined
        data, caused by an update to FXADDPAR routine.
Version 1.2.1 Stephane Beland 2003-09-10
        Exit gracefully if write privileges unavailable
Version 1.3 Wayne Landsman 2003-10-24
        Don't use EXECUTE() statement if on a virtual machine
Version 1.3a Wayne Landsman 2004-5-21
        Fix for variable type arrays
Version 1.4 Wayne Landsman 2004-07-16
        Use STRUCT_ASSIGN when modifying structure with pointer tags
Version 1.4a Wayne Landsman 2005-01-03
        Fix writing of empty strings in binary tables 
Version 1.4b Wayne Landsman 2006-02-23
        Propagate /SILENT keyword to mwr_tablehdr
Version 1.5 Wayne Landsman  2006-05-24
        Open file using /SWAP_IF_LITTLE_ENDIAN keyword 
        Convert empty strings to 1 element blank strings before writing            
Version 1.5a Wayne Landsman 2006-06-29
        Fix problem introduced 2006-05-24 with multidimensional strings
Version 1.5b K. Tolbert 2006-06-29
        Make V1.5a fix work pre-V6.0
Version 1.5c I.Evans/W.Landsman 2006-08-08
        Allow logical columns to be specified as bytes 
Version 1,5d K. Tolbert 2006-08-11 
        Make V1.5a fix work for scalar empty string
Version 1.6  W. Landsman  2006-09-22
        Assume since V5.5, remove VMS support
Version 1.6a  W. Landsman  2006-09-22
        Don't right-justify strings 
Version 1.7  W. Landsman  2009-01-12
        Added STATUS output keyword
Version 1.7a W. Landsman 2009-04-10
        Since V6.4 strings are no longer limited to 1024
        elements 
Version 1.8 Pierre Chanial 2009-06-23
        trim alias, implement logical TFORM 'L', don't
        add space after tform key.
Version 1.9 W. Landsman 2009-07-20
        Suppress compilation messages of supporting routines
Version 1.10 W. Landsman 2009-09-30
        Allow TTYPE values of 'T' and 'F', fix USE_COLNUM for bin tables
Version 1.11 W. Landsman 2010-11-18
        Allow LONG64 number of bytes, use V6.0 notation 
Version 1.11a W. Landsman 2012-08-12
        Better documentation, error checking for logical columns
Version 1.11b M. Haffner/W.L. 2012-10-12
        Added /No_COPY keyword, fix problem with 32 bit overflow
Version 1.12 W. Landsman  2014-04-23
Version 1.12a W.Landsman/M. Fossati 2014-10-14
        Fix LONG overflow for very large files
Version 1.12b I. Evans 2015-07-27
        Fix value check for byte('T'), byte('F'), or 0b for logical
        columns with null values
Version 1.13 W. Landsman 2016-02-24
        Abort if a structure supplied with more than 999 tags