The simplifits library

A provisional version of it is in use for the tests of interfacing mysql and FITS. The main differences between such versions and the current one are:

• the full version is integrated with the XAS VOS libraries, while the provisional version either includes, bypasses or overrides some of such auxiliary calls
• both the original and the provisional versions (simplifits proper) deal exclusively with the generation of FITS files, they can write but not read !
• In addition all versions provide only basic functionalities, leaving more complex tasks to the calling program.

• simplifits proper consists of 610 Fortran lines (of which 293 of code).
• parametric configuration occurs in a 6-line include file
• simplinfits consists of 499 Fortran lines (of which 338 of code).
• parametric configuration occurs in a 20-line include file
• in addition there is 6-line default error handler routine.

reader

C...... open the file ........................................
        CALL FITSOPENOLD(N,filename,LU)
        CALL FITSSWAP(SWAP)
C
C...... read primary or extension header .....................
 1      CONTINUE         
C.....  get next keyword
        CALL FITSKWD(N,CARD,ENDED)
C       and decode it
        IF(.NOT.ENDED)THEN
          CALL FITSHDR(CARD,KEY,VALUE,COMMENT,ISCOMMENT)
          ...code to process the keywords...
C         and process next keyword
          GOTO 1
C       unless sequence of header kewyords is ended
        ELSE
          information about current HDU is automatically
          available in a COMMON block, use it if necessary
        ENDIF
C
C...... read or skip data ......................................
C       position to the wished record (for binary tables)
        CALL FITSSEEK(N,STARTREC,naxes(1))
C       loop on record
        DO I=STARTREC,ENDREC
            CALL FITSGETDATA(N,DATABUF,naxes(1))
            an user routine can use DATABUF and SWAP to extract
            and decode the content of DATABUF
        ENDDO
C
C..... process another extension ...............................
       CALL FITSHDU(N,+1,ENDED)
       IF(.NOT.ENDED)GOTO  1

writer

C...... open the file ........................................
        CALL FITSOPEN(N,filename,LU)
        CALL FITSSWAP(SWAP)
C.....  add mandatory primary header
        CALL FITSADDL(N,'SIMPLE'  ,.TRUE.)
        ....
        CALL FITSADDE(N)
C       add extension header for output file
        CALL FITSADDC(N,'XTENSION','BINTABLE' )
        ....
        CALL FITSADDE(N)
C.....  write some data
        DO loop on records
        an user routine can pack the record into BUFFER
        CALL FITSDATA(N,BUFFER(:NBYTE),NBYTE)
        ENDDO
C.....  ensure data is flushed to disk
        CALL FITSDATA(N,0,0)

• FITSSWAP(SWAP)
  it's a front-end to XAS VOS "conversion" calls and shall be preliminary called by a program wishing to access FITS data (it is not necessary to access a FITS header) to know whether the operating system requests (SWAP=.TRUE.) or not (SWAP=.FALSE.) to byte-swap binary data.

• FITSOPEN(NFILE,NAME,LU)
  is the call to open and create a new FITS file. The file is publicly accessed via an order number NFILE, although the routines internally use the logical unit LU

• FITSADDE(NFILE)
  is the prototype routine to write a FITS header keyword. This entry writes an END keyword and is used to close the header of an HDU. Other entry points are used to write named keywords :
  • FITSADDL(NFILE,KEYNAME,LOGVAL) a logical kewyord
  • FITSADDI(NFILE,KEYNAME,INTVAL) an integer keyword
  • FITSADDR(NFILE,KEYNAME,REAVAL) a real keyword
  • FITSADDD(NFILE,KEYNAME,DOUVAL) a double precision keyword
  • FITSADDC(NFILE,KEYNAME,STRVAL) a character keyword
  The routines take care of flushing data to disk whenever appropriate. The user shall generate headers and data in an HDU, and the various HDU in the correct sequence, eventually reserving space for keywords whose value will be updated later.

• FITSIMAG(NFILE,CMAP,BYTE,NX,NY,SWAP)
  is an high-level service routines which writes an entire image CMAP of size NX,NY and BYTE (2 or 4) bytes per pixel (integer and float images are not differentiated at this level, but according to the type of CMAP and to the appropriate header keyword. Byte-swap is done according to the value of SWAP preset by FITSSWAP. This routine is a record-by-record front-end to the next one.

• FITSDATA(NFILE,DATABUF,BUFLEN)
  is the catch-all routine used to write a logical record to disk. A logical record can be an image row or a binary table row. In the latter case it is responsibility of the caller to transfer the binary data (and eventually byteswap them) into appropriate locations in the byte array DATABUF of length BUFLEN. The routine just inserts the DATABUF buffer in the appropriate place in the FITS 2880-byte blocks and flushes them to disk as appropriate.
  A call to FITSDATA(NFILE,anything,0) is used to force flushing a block to disk (typically the last block) or to initialize a block to zero (typically the first block before writing).

• FITSUPDI(NFILE,KEYNAME,INTVAL)
  is the prototype routine which changes the value of an existing integer kewyord. Other entry points are used for other data types :
  • FITSUPDR(NFILE,KEYNAME,REAVAL) for a real keyword
  • FITSUPDD(NFILE,KEYNAME,DOUVAL) for a double precision keyword
  • FITSUPDC(NFILE,KEYNAME,STRVAL)for a character keyword
  The routine is inefficient and shall be used sparingly. It scans all headers (primary and extension) twice, and changes the first occurrence of a given name. It cannot be used for multiple instances with the same keyword name.

• FITSRNAM(NFILE,KEYOLD,KEYNEW)
  is used similarly to the previous family to rename a keyword.

  ---

• FITSOPENOLD(NFILE,NAME,LU)
  is the call to open an existing FITS file for reading. The file is publicly accessed via an order number NFILE, although the routines internally use the logical unit LU

• added 27 May 2003
• FITSCLOSEOLD(NFILE)
  is the call to close the previously opened file with order number NFILE, in the case one wants to re-use the same NFILE to read another file in the same program (it takes care to reset internal pointers). It is not necessary to call it if one accesses a single file.

• FITSKWD(NFILE,CARD,ENDED)
  is the basic interface to retrieve keywords one by one in sequence. It returns either the full 80-byte CARDimage or sets ENDED=.TRUE. if an END keyword was reached. In the latter case one can advance to the next HDU and read keywords from a further extension header. The routine keeps track of disk FITS blocks internally.
  A secondary entry point FITSREWHDR is used internally by FITSHDU to reset the keyword counter when changing HDU.

• FITSHDR(CARD,KEYNAME,VALUE,COMMENT,ISCOMMENT)
  is the basic interface to decode a keyword. It shall be called after CARD has been retrieved by the previous call, and returns the parsed keyword name, its value (as a string, decoding into a binary value with an internal READ is left to the caller), its comment field, and a logical flag ISCOMMENT which tells if the keyword is a pure comment (no value).
  In addition this routine interprets some of the mandatory keywords in the primary and binary table headers, and stores associated info in a common block.

• FITSHDUPARMS(NFILE)
  is called automatically by FITSKWD when and END card (i.e. the end of the current HDU) is encountered
  It uses the information stored in common block by FITSHDR to compute summary information about the current HDU (like the number of records in it, or the default display format).

• FITSHDU(NFILE,IPOS,ENDED)
  is intended to be used to move the record pointer to the next extension HDU (if IPOS=+1), or to rewind it at the beginning of the current HDU (if IPOS=0), or to backspace it to the beginning of the previous HDU (if IPOS=-1). Only the first function is currently implemented and tested.
  It also returns a logical flag ENDED in case an error is generated trying to access a non-existing record (i.e. beyond the end of the last HDU)

• FITSGETDATA(NFILE,DATABUF,BUFLEN)
  is the catch-all routine used to read a logical record from disk. A logical record can be an image row or a binary table row. It is responsibility of the caller to transfer the binary data (and eventually byteswap them) from appropriate locations in the byte array DATABUF of length BUFLEN. The routine just retrieves the DATABUF buffer from the appropriate place in the FITS 2880-byte blocks from disk.

  A secondary entry FITSSEEK(NFILE,IREC,BUFLEN) is used to position the disk block pointer to the logical record IREC, assuming those logical records are of size BUFLEN bytes.
  It is assumed that these calls are normally used to read a FITS file in sequence (i.e. FITSSEEK to skip unwanted records and FITSGETDATA to read the next good ones).

  A secondary entry FITSRESETPTR is called internally by FITSCLOSEOLD to make sure record reading starts from the beginning.

  ---

• FITSERROR
  is an error handler, to be called whenever one desires to deal with an error. The default handler just prints the error code ERRNO and the error message ERRMSG preset by the caller, then stops the program.
  It is assumed that each program can override this routine with a version of its own (e.g. one producing HTML code).
  The function can be called by each program to stop on unsupported situations (e.g. the prototype reader stops on conditions like binary table rows greater than a predefined number of bytes, accessing a non existing record or other unsupported functions), in addition the following conditions are unsupported at library level :
  • extensions other than BINTABLE or IMAGE
  • images with more than 3-d
  • tables with more than a predefined number of columns
  • unsupported column type (like P)
  • PCOUNT not zero