Function:     CFTSD_GETH

Purpose:      Gets the header from a compressed FITS tape.

Category:     FITS

File:         cfts_io.c

Author:       Do Kester

Use:          INTEGER CFTSD_GETH( MTID,          Input          INTEGER
                                  HEADER,        Output         CHARACTER*(*)
                                  TID )          Input/Output   INTEGER

              CFTSD_GETH Returns:
                          >0 - number of characters transferred to HEADER
                               (i.e. ALL of the FITS header up to the
                               END record). The rest of HEADER is as
                               before the call.
                   -1 .. -10 - tape error (see MTIODEV.DC2)
                         -11 - not a FITS file.
                         -12 - found and skipped tape label
                         -13 - double tape mark found, tape skipped back to
                               before second tape mark.
                         -14 - keyword SIMPLE not present
                         -15 - SIMPLE=FALSE is not supported
                         -16 - keyword BITPIX not present
                         -17 - only BITPIX = 8, 16 and 32 supported.
                         -18 - keyword NAXIS not present
                         -19 - not enough NAXIS% keywords
                         -20 - could not get enough memory for internal ftsbuf.
                         -21 - the header array HEADER is too small for the
                               entire header.
                         -22 - conversion error
                         -23 - storage size of character type is not 1 byte
                         -24 - storage size of short type is not 2 bytes
                         -25 - storage size of int type is not 4 bytes
                         -29 - header contains illegal character 
              MTID      A device unit number as obtained from MTOPEN.
              HEADER    A string in which the header as read from unit
                        MTID will be stored as an array of strings.
              TID       Must be zero at input.
                        If output > zero, more bytes left to transfer
                        for FTSI_GETI or FTSI_GETR.

Description:
          
        CFTSD_GETH is functionally equivalent to FTSD_GETH, both for
        compressed as for normal fits files.

	CFTSD_GETH is used as an initialization routine for reading FITS data
	from a FITS tape.  The routine will try to read the file,
	interpreting the beginning of the file as a FITS header.  The data
	from tape will be stored in an (large) internal ftsbuf which will
	also be used in later calls of CFTSI_GETR and CFTSI_GETI. 

	 If the file consists of FITS blocks (i.e.  blocks of an integral
	number times 2880 bytes) CFTSD_GETH will try to read a number of FITS
	keywords nessecary for interpreting the FITS data: SIMPLE=, BITPIX=,
	NAXIS= and the NAXIS%= keywords.  If any of these is missing an error
	results.  Also CFTSD_GETH checks whether SIMPLE=T ( SIMPLE=F is not
	supported ), and whether the data can be read on the current machine
	given the value of BITPIX.    

	 Further error conditions are: the array HEADER provided by the
	caller is too small for the entire FITS header (-21), and not enough
	memory for internal databuffer (-20). 

	 CFTSD_GETH always assumes that the input 'tape' is positioned at the
	begining of a file, i.e.  immediately past an end of file mark.  If
	the first block read by CFTSD_GETH has length zero (i.e.  another end
	of file mark), the routine will skip back over that block and return
	with error -13; found double tape mark.  In FITS definition this
	means end of tape. 


Updates:
	07 Mar 1991 DK document creation