MODFITS

      Modify a FITS file by updating the header and/or data array.

      Since August 2003, the size of the supplied FITS header or data array
      does not need to match the size of the existing header or data array.

      MODFITS, Filename_or_fcb, Data, [ Header, EXTEN_NO =, ERRMSG=]

      FILENAME/FCB = Scalar string containing either the name of the FITS file
                  to be modified, or the IO file control block returned after
                  opening the file with FITS_OPEN,/UPDATE.   The explicit
                  use of FITS_OPEN can save time if many extensions in a
                  single file will be updated.
      DATA - data array to be inserted into the FITS file.   Set DATA = 0
               to leave the data portion of the FITS file unmodified
      HEADER - FITS header (string array) to be updated in the FITS file.

      EXTEN_NO - scalar integer specifying the FITS extension to modified.  For
               example, specify EXTEN = 1 or /EXTEN to modify the first
               FITS extension.

       ERRMSG - If this keyword is supplied, then any error mesasges will be
               returned to the user in this parameter rather than depending on
               on the MESSAGE routine in IDL.   If no errors are encountered
               then a null string is returned.

     (1) Modify the value of the DATE keyword in the primary header of a
             file TEST.FITS.
              IDL> h = headfits('test.fits')      ;Read primary header
              IDL> sxaddpar,h,'DATE','2001-03-23' ;Modify value of DATE
              IDL> modfits,'test.fits',0,h        ;Update header only
       (2) Replace the values of the primary image array in 'test.fits' with
               their absolute values
               IDL> im = readfits('test.fits')    ;Read image array
               IDL> im = abs(im)                  ;Take absolute values
               IDL> modfits,'test.fits',im        ;Update image array
       (3) Add some HISTORY records to the FITS header in the first extension
               of a file 'test.fits'
               IDL> h = headfits('test.fits',/ext)  ;Read first extension hdr
               IDL> sxaddhist,['Comment 1','Comment 2'],h
               IDL> modfits,'test.fits',0,h,/ext    ;Update extension hdr
       (4) Change 'OBSDATE' keyword to 'OBS-DATE' in every extension in a
           FITS file.    Explicitly open with FITS_OPEN to save compute time.
               fits_open,'test.fits',io,/update    ;Faster to explicity open
               for i = 1,nextend do begin          ;Loop over extensions
                   fits_read,io,0,h,/header_only,exten_no=i,/No_PDU ;Get header
                   date= sxpar(h,'OBSDATE')         ;Save keyword value
                   sxaddpar,h,'OBS-DATE',date,after='OBSDATE'
                   sxdelpar,h,'OBSDATE'             ;Delete bad keyword
                   modfits,io,0,h,exten_no=i        ;Update header
               endfor
           Note the use of the /No_PDU keyword in the FITS_READ call -- one
           does *not* want to append the primary header, if the STScI
           inheritance convention is adopted.

       Uses the BLKSHIFT procedure to shift the contents of the FITS file if
       the new data or header differs in size by more than 2880 bytes from the
       old data or header.
       Also see the procedures FXHMODIFY to add a single FITS keyword to a
       header in a FITS files, and FXBGROW to enlarge the size of a binary
       table.

       (1) Cannot be used to modifiy the data in FITS files with random
           groups or variable length binary tables.   (The headers in such
           files *can* be modified.)
       (2) If a data array but no FITS header is supplied, then MODFITS does
           not check to make sure that the existing header is consistent with
           the new data.
       (3) Does not work with compressed files

       Functions:   IS_IEEE_BIG(), N_BYTES(), SXPAR()
       Procedures:  BLKSHIFT, CHECK_FITS, FITS_OPEN, FITS_READ, HOST_TO_IEEE

       Written,    Wayne Landsman          December, 1994
       Converted to IDL V5.0   W. Landsman   September 1997
       Fixed possible problem when using WRITEU after READU   October 1997
       New and old sizes need only be the same within multiple of 2880 bytes
       Added call to IS_IEEE_BIG()     W. Landsman   May 1999
       Added ERRMSG output keyword     W. Landsman   May 2000
       Update tests for incompatible sizes   W. Landsman   December 2000
       Major rewrite to use FITS_OPEN procedures W. Landsman November 2001
       Add /No_PDU call to FITS_READ call  W. Landsman  June 2002
       Update CHECKSUM keywords if already present in header, add padding
       if new data  size is smaller than old  W.Landsman December 2002
       Only check XTENSION value if EXTEN_NO > 1   W. Landsman Feb. 2003
       Correct for unsigned data on little endian machines W. Landsman Apr 2003
       Major rewrite to allow changing size of data or header W.L. Aug 2003
       Fixed case where updated header exactly fills boundary W.L. Feb 2004
       More robust error reporting W.L. Dec 2004

[Home Page] [Software, Documentation] [IDL Documentation] [Quick Reference] [Feedback]