Document:     FTS_IO

Purpose:      Describes the FITS io routines

Category:     FITS

File:	      fts_io.c

Author:       P. Roelfsema

Description:  The fts_io routines read or write data from/to FITS tapes
	      and files.

	      The following functions are available:

	      FTSD_GETH 	Get a FITS header from tape.
	      FTSI_GETR 	Get real data from tape.
	      FTSI_GETI 	Get integer data from tape.

	      FTSD_PUTH 	Put a FITS header on tape.
	      FTSI_PUTR 	Put real data on tape.
	      FTSI_PUTI 	Put integer data on tape.

	      FTS_SKIPPIX	Skip pixels on a FITS tape.
	      FTS_SKIPFIL	Skips fits file(s).

	      Each routine is described in more detail in the
	      appropriate document.

Use:
	  To read a FITS tape first a tape-device must be opened using MTOPEN
	(see MTIODEV.DC2 and references therein).  From this device a FITS
	read operation is initialised by calling FTSD_GETH.  After FTSD_GETH
	the calling program has a character array containing the FITS header
	records.  Using the FTSD_FIND, FTSD_RCHAR, FTSD_RREAL etc.  routines
	the values of individual FITS keywords can be obtained from this
	header.  Subsequently a series of calls to FTSI_GETI or FTSI_GETR
	(combined with FTS_SKIPPIX calls) can be done to get the FITS data
	from the tape into an integer or real array respectively. A read
	operation can be stopped before the end of the tape-file by skipping
	to the next file with FTS_SKIPFIL.

	  After an error condition (i.e. a negative return value of one of the
	routines) the tape will always be positioned at the beginning of the
	next file.

	  A typical series of FTS calls for a FITS read operation would
	look as follows:

	  MTOPEN( )	      - open a tape-device
	  FTS_SKIPFIL( )      - skip some files

	  FTSD_GETH( )	      - get the header from tape
	  FTSD_RREAL( )     |
	  FTSD_RLOG( )	    |
	      . 	    | - decode the header
	      . 	    |
	  FTSD_RINT( )	    |

	  FTS_SKIPPIX( )      - skip some pixels

	  REPEAT	      - loop to
	     FTSI_GETR( )     -   read data
	  UNTIL( TID.EQ.0 )   -     until all is read in

	  MTCLOSE( )	      - close the tape-device

	  To write a FITS tape first a FITS header must be generated;
	such a header should be a long character type array which can be
	filled with FITS record using the FTSD_WCHAR etc. routines.
	Subsequently a tape-device must be opened using MTOPEN (see
	MTIODEV.DC2 and references therein). The FITS write operation is
	initialised by calling FTSD_PUTH which will store the above mentioned
	header on tape.  After FTSD_PUTH integer or real data can be written
	to the device mounted to mtid by calling the routines FTSI_PUTI or
	FTSI_PUTR. The writing of data ends when the FTSI_ routine is
	told to put 0 (zero) elements on tape, then two tapemarks
	(indicating EOF and EOT) will be written to tape.

	  After an error condition (negative return value) the file that
	was being written will be erased.  The tape will be positioned
	after the previous file on tape.

	  A typical series of FTS calls for a FITS write operation would
	look as follows:

	  MTOPEN( )	      - open a tape-device
	  REPEAT	      - skip some files until EOT
	  UNTIL( FTS_SKIPFIL( ) .EQ. -13 )

	  FTSD_WREAL( )     |
	  FTSD_WLOG( )	    |
	      . 	    | - fill the header
	      . 	    |
	  FTSD_WINT( )	    |
	  FTSD_PUTH( )	      - write the header to tape

	  REPEAT	      - loop to
	     FTSI_PUTR( )     -   write data
	  UNTIL( NPIX.EQ.0 )  -     until all is written
	  FTSI_PUTR( . 0 . )  - write 0 pixels => end of write

	  MTCLOSE( )	      - close the tape-device

Updates:
	Jun 27, 1990: PRR, Original document created
	Aug 22, 1990: SS,  Added write routines.
	Sep 12, 1990: SS,  Adjustments for new data structure.
	Oct  8, 1990: PRR, Major Rewrite.
	Nov 12, 1991: MV,  Casting of LONG_MIN, because of bug in
			   gcc compiler.