Initial commit

1 files changed, 2156 insertions, 0 deletions

diff --git a/pkg/tbtables/cfitsio/quick.tex b/pkg/tbtables/cfitsio/quick.tex
new file mode 100644
index 00000000..28bd97ce
--- /dev/null
+++ b/pkg/tbtables/cfitsio/quick.tex
@@ -0,0 +1,2156 @@
+\documentclass[11pt]{article}
+\input{html.sty}
+\htmladdtonavigation
+   {\begin{rawhtml}
+ <A HREF="http://heasarc.gsfc.nasa.gov/docs/software/fitsio/fitsio.html">FITSIO Home</A>
+    \end{rawhtml}}
+
+\oddsidemargin=0.20in
+\evensidemargin=0.20in
+\textwidth=15.5truecm
+\textheight=21.5truecm
+
+\title{CFITSIO Quick Start Guide}
+\author{William Pence \thanks{HEASARC, NASA Goddard Space Flight Center,
+{\it William.D.Pence@nasa.gov}}}
+
+\date{January 2003}
+
+\begin{document}
+
+\maketitle
+\tableofcontents
+
+% ===================================================================
+\section{Introduction}
+
+This document is intended to help you quickly start writing C programs
+to read and write FITS files using the CFITSIO library.  It covers the
+most important CFITSIO routines that are needed to perform most types
+of operations on FITS files. For more complete information about these
+and all the other available routines in the library please refer to
+the  ``CFITSIO User's Reference Guide'', which is available from the
+CFITSIO Web site at {\tt http://heasarc.gsfc.nasa.gov/fitsio}.
+
+For more general information about the FITS data format, refer to the
+following web page:
+http://heasarc.gsfc.nasa.gov/docs/heasarc/fits.html
+
+FITS stands for Flexible Image Transport System and is the standard
+file format used to store most astronomical data files.  There are 2
+basic types of FITS files: images and tables.  FITS images often
+contain a 2-dimensional array of pixels representing an image of a
+piece of the sky, but  FITS images can also contain 1-D arrays (i.e,
+a spectrum or light curve), or  3-D arrays (a data cube), or
+even higher dimensional arrays of data.   An image may also have zero
+dimensions, in which case it is referred to as a null or empty array.
+The supported datatypes for the image arrays are 8, 16, and 32-bit
+integers, and 32 and 64-bit floating point real numbers.  Both signed
+and unsigned integers are supported.
+
+FITS tables contain rows and columns of data, similar to a
+spreadsheet.  All the values in a particular column must have the same
+datatype.  A cell of a column is not restricted to a single number, and
+instead can contain an array or vector of numbers.  There are actually
+2 subtypes of FITS tables: ASCII and binary. As the names imply,  ASCII
+tables store the data values in an ASCII representation whereas binary
+tables store the data values in a more efficient machine-readable
+binary format.  Binary tables are generally more compact and support
+more features (e.g., a wider range of datatypes, and vector columns)
+than ASCII tables.
+
+A single FITS file many contain multiple images or tables.  Each table
+or image is called a Header-Data Unit, or HDU.  The first HDU in a FITS
+file must be an image (but it may have zero axes) and is called the
+Primary Array.  Any additional HDUs in the file (which are also
+referred to as `extensions') may contain either an image or a table.
+
+Every HDU contains a header containing keyword records.  Each keyword
+record is 80 ASCII characters long and has the following format:
+
+\begin{verbatim}
+KEYWORD = value / comment string
+\end{verbatim}
+
+The keyword name can be up to 8 characters long (all uppercase).  The
+value can be either an integer or floating point number, a logical
+value (T or F), or a character string enclosed in single quotes.  Each
+header begins with a series of required keywords to describe the
+datatype and format of the following data unit, if any.  Any number of
+other optional keywords can be included in  the header to provide other
+descriptive information about the data.  For the most part, the CFITSIO
+routines automatically write the required FITS keywords for each HDU,
+so you, the programmer, usually do not need to worry about them.
+
+% ===================================================================
+\section{Installing and Using CFITSIO}
+
+First, you should download the CFITSIO software and the set of example
+FITS utility programs from the web site at
+http://heasarc.gsfc.nasa.gov/fitsio.  The example programs illustrate
+how to perform many common types of operations on FITS files using
+CFITSIO.  They are also useful when writing a new program because it is
+often easier to take a copy of one of these utility programs as a
+template and then modify it for your own purposes, rather than writing
+the new program completely from scratch.
+
+To build the CFITSIO library on Unix platforms, `untar' the source code
+distribution file and then execute the following commands in the
+directory containing the source code:
+
+\begin{verbatim}
+>  ./configure [--prefix=/target/installation/path]
+>  make           (or 'make shared')
+>  make install   (this step is optional)
+\end{verbatim}
+
+The optional
+'prefix' argument to configure gives the path to the directory where
+the CFITSIO library and include files should be installed via the later
+'make install' command. For example,
+
+\begin{verbatim}
+>  ./configure --prefix=/usr1/local
+\end{verbatim}
+
+will cause the 'make install' command to copy the CFITSIO libcfitsio file 
+to /usr1/local/lib and the necessary include files to /usr1/local/include
+(assuming of course that the  process has permission to write to these 
+directories).
+
+Pre-compiled versions of the CFITSIO DLL library are available for
+PCs.  On Macintosh machines, refer to the README.MacOS file for
+instructions on building CFITSIO using CodeWarrior.
+
+Any programs that use CFITSIO must of course be linked with the CFITSIO
+library when creating the executable file.  The exact procedure for
+linking a program depends on your software environment, but on Unix
+platforms, the command line to compile and link a program will look
+something like this:
+
+\begin{verbatim}
+gcc -o myprog myprog.c -L. -lcfitsio -lm -lnsl -lsocket
+\end{verbatim}
+
+You may not need to include all of the 'm', 'nsl', and 'socket' system
+libraries on your particular machine.  To find out what libraries are
+required on your (Unix) system, type {\tt'make testprog'} and see what
+libraries are then included on the resulting link line.
+
+\newpage
+% ===================================================================
+\section{Example Programs}
+
+Before describing the individual CFITSIO routines in detail, it is
+instructive to first look at an actual program.  The names of the
+CFITSIO routines are fairly descriptive (they all begin with {\tt
+fits\_}, so it should be reasonably clear what this program does:
+
+\begin{verbatim}
+----------------------------------------------------------------
+    #include <string.h>
+    #include <stdio.h>
+1:  #include "fitsio.h"
+
+    int main(int argc, char *argv[])
+    {
+2:      fitsfile *fptr;         
+        char card[FLEN_CARD]; 
+3:      int status = 0,  nkeys, ii;  /* MUST initialize status */
+
+4:      fits_open_file(&fptr, argv[1], READONLY, &status);
+        fits_get_hdrspace(fptr, &nkeys, NULL, &status);
+
+        for (ii = 1; ii <= nkeys; ii++)  { 
+          fits_read_record(fptr, ii, card, &status); /* read keyword */
+          printf("%s\n", card);
+        }
+        printf("END\n\n");  /* terminate listing with END */
+        fits_close_file(fptr, &status);
+
+        if (status)          /* print any error messages */
+5:          fits_report_error(stderr, status);
+        return(status);
+    }
+----------------------------------------------------------------
+\end{verbatim}
+
+This program opens the specified FITS file and prints
+out all the header keywords in the current HDU.
+Some other points to notice about the program are:
+\begin{enumerate}
+
+\item
+The {\tt fitsio.h} header file must be included to define the 
+various routines and symbols used in CFITSIO.
+
+\item
+
+The {\tt fitsfile}  parameter is the first argument in almost every
+CFITSIO routine.  It is a pointer to a structure (defined in {\tt
+fitsio.h}) that stores information about the particular FITS file that
+the routine will operate on.  Memory for this structure is
+automatically allocated when the file is first opened or created, and
+is freed when the file is closed.
+
+\item
+Almost every CFITSIO routine has a {\tt status} parameter as the last
+argument. The status value is also usually returned as the value of the
+function itself.  Normally status = 0, and a positive status value
+indicates an error of some sort.  The status variable must always be
+initialized to zero before use, because if status is greater than zero
+on input then the CFITSIO routines will simply return without doing
+anything.  This `inherited status' feature, where each CFITSIO routine
+inherits the status from the previous routine, makes it unnecessary to
+check the status value after every single CFITSIO routine call.
+Generally you should check the status after an especially important or
+complicated routine has been called, or after a block of
+closely related CFITSIO calls.  This example program has taken this
+feature to the extreme and only checks the status value at the 
+very end of the program.
+
+\item
+
+In this example program the file name to be opened is given as an
+argument on the command line ({\tt arg[1]}).  If the file contains more
+than 1 HDU or extension, you can specify which particular HDU to be
+opened by enclosing the name or number of the HDU in square brackets
+following the root name of the file.  For example, {\tt file.fts[0]}
+opens the  primary array, while {\tt file.fts[2]} will move to and open
+the 2nd extension in the file, and {\tt file.fit[EVENTS]} will open the
+extension that has a {\tt EXTNAME = 'EVENTS'} keyword in the header.
+Note that on the Unix command line you must enclose the file name in
+single or double quote characters if the name contains special
+characters such as `[' or `]'.
+
+All of the CFITSIO routines which read or write header keywords,
+image data, or table data operate only within the currently opened
+HDU in the file. To read or write information in a different HDU you must
+first explicitly move to that HDU (see the {\tt fits\_movabs\_hdu} and
+{\tt fits\_movrel\_hdu} routines in section 4.3).
+
+\item
+
+The {\tt fits\_report\_error} routine provides a convenient way to print out
+diagnostic messages about any error that may have occurred. 
+
+\end{enumerate}
+
+A set of example FITS utility programs are  available from the CFITSIO
+web site at \newline
+http://heasarc.gsfc.nasa.gov/docs/software/fitsio/cexamples.html.
+These are real working programs which illustrate how to read, write,
+and modify FITS files using the CFITSIO library.  Most of these
+programs are very short, containing only a few 10s of lines of
+executable code or less, yet they perform quite useful operations on
+FITS files. Running each program without any command line arguments
+will produce a short description of how to use the program.
+The currently available programs are:
+\begin{quote}
+fitscopy - copy a file
+\newline
+listhead - list header keywords
+\newline
+liststruc - show the structure of a FITS file.
+\newline
+modhead  - write or modify a header keyword
+\newline
+imarith  - add, subtract, multiply, or divide 2 images
+\newline
+imlist  - list pixel values in an image
+\newline
+imstat  - compute mean, min, and max pixel values in an image
+\newline
+tablist - display the contents of a FITS table
+\newline
+tabcalc  - general table calculator
+\end{quote}
+
+\newpage
+
+% ===================================================================
+\section{CFITSIO Routines}
+
+This chapter describes the main CFITSIO routines that can be used to
+perform the most common types of operations on FITS files.
+
+% ===================================================================
+{\bf \subsection{Error Reporting}}
+
+\begin{verbatim}
+void fits_report_error(FILE *stream, int status)
+void fits_get_errstatus(int status, char *err_text)
+float fits_get_version(float *version)
+\end{verbatim}
+
+The first routine prints out information about any error that
+has occurred.  Whenever any CFITSIO routine encounters an error it
+usually writes a message describing the nature of the error to an
+internal error message stack and then returns with a positive integer
+status value. Passing the error status value to this routine will
+cause  a generic description of the error and all the messages
+from the internal CFITSIO error stack to be printed to the specified
+stream.  The {\tt stream} parameter is usually set equal to
+{\tt "stdout"} or {\tt "stderr"}.
+
+The second routine simply returns a 30-character descriptive
+error message corresponding to the input status value.
+
+The last routine returns the current CFITSIO library version number.
+
+% ===================================================================
+{\bf \subsection{File Open/Close Routines}}
+
+\begin{verbatim}
+int fits_open_file( fitsfile **fptr, char *filename, int mode, int *status)
+int fits_open_data( fitsfile **fptr, char *filename, int mode, int *status)
+int fits_open_table(fitsfile **fptr, char *filename, int mode, int *status)
+int fits_open_image(fitsfile **fptr, char *filename, int mode, int *status)
+
+int fits_create_file(fitsfile **fptr, char *filename, int *status)
+int fits_close_file(fitsfile *fptr, int *status)
+\end{verbatim}
+
+These routines open or close a file.  The first {\tt fitsfile}
+parameter  in these and nearly every other CFITSIO routine is a pointer
+to a structure that CFITSIO uses to store relevant parameters about
+each opened file.  You should never directly read or write any
+information in this structure.  Memory for this structure is allocated
+automatically when the file is opened or created, and is freed when the
+file is closed.
+
+The {\tt mode} parameter in the {\tt fits\_open\_xxxx} set of routines
+can be set to either {\tt READONLY} or {\tt READWRITE} to select the
+type of file access that will be allowed. These symbolic constants are
+defined in {\tt fitsio.h}.
+
+The {\tt fits\_open\_file} routine opens the file and positions the internal
+file pointer to the beginning of the file, or to the specified
+extension if an extension name or number is appended to the file name
+(see the later section on ``CFITSIO File Names and Filters'' for a
+description of the syntax). {\tt fits\_open\_data} behaves similarly except
+that it will move to the first HDU containing significant data if a HDU
+name or number to open is not explicitly specified as part of the
+filename.  It will move to the first IMAGE HDU with NAXIS greater than
+0, or the first table that does not contain the strings `GTI' (a Good
+Time Interval extension) or `OBSTABLE' in the EXTNAME keyword value.
+The {\tt fits\_open\_table} and {\tt fits\_open\_image}  routines are similar
+except that they will move to the first significant table HDU or image
+HDU, respectively if a HDU name of number is not specified as part of
+the input file name.
+
+When opening an existing file, the {\tt filename} can include optional
+arguments, enclosed in square brackets that specify filtering
+operations that should be applied to the input file.  For example,
+\begin{verbatim}
+   myfile.fit[EVENTS][counts > 0]
+\end{verbatim}
+opens the table in the EVENTS extension and creates a virtual table by
+selecting only those rows where the COUNTS column value is greater than
+0.  See section 5 for more examples of these powerful filtering
+capabilities.
+
+In {\tt fits\_create\_file},  the {\tt filename} is simply the root name of
+the file to be created.  You can overwrite an existing file by
+prefixing the name with a `!' character (on the Unix command line this
+must be prefixed with a backslash, as in \verb+`\!file.fit'+).  
+If the file name ends with {\tt .gz} the file will be compressed
+using the gzip algorithm.  If the
+filename is {\tt stdout} or {\tt "-"} (a single dash character)
+then the output file will be piped to the stdout stream.  You can
+chain several tasks together by writing the output from the first task
+to {\tt stdout} and then reading the input file in the 2nd task from
+{\tt stdin} or {\tt "-"}.
+
+
+% ===================================================================
+{\bf \subsection{HDU-level Routines}}
+
+The routines listed in this section operate on Header-Data Units (HDUs) in a file.
+
+\begin{verbatim}
+_______________________________________________________________
+int fits_get_num_hdus(fitsfile *fptr, int *hdunum, int *status)
+int fits_get_hdu_num(fitsfile *fptr,  int *hdunum)
+\end{verbatim}
+
+The first routines returns the total number of HDUs in the FITS file,
+and the second routine returns the position of the currently opened HDU in
+the FITS file (starting with 1, not 0).
+
+\begin{verbatim}
+__________________________________________________________________________
+int fits_movabs_hdu(fitsfile *fptr, int hdunum, int *hdutype, int *status)
+int fits_movrel_hdu(fitsfile *fptr, int nmove,  int *hdutype, int *status)
+int fits_movnam_hdu(fitsfile *fptr, int hdutype, char *extname,
+                    int extver, int *status)
+\end{verbatim}
+
+These routines enable you to move to a different HDU in the file.
+Most of the CFITSIO functions which read or write keywords or data
+operate only on the currently opened HDU in the file.  The first
+routine moves to the specified absolute HDU number in the FITS
+file (the first HDU = 1), whereas the second routine moves a relative
+number of HDUs forward or backward from the currently open HDU.  The
+{\tt hdutype} parameter returns the type of the newly opened HDU, and will
+be equal to one of these symbolic constant values: {\tt IMAGE\_HDU,
+ASCII\_TBL, or BINARY\_TBL}.  {\tt hdutype} may be set to NULL
+if it is not needed.  The third routine moves to the (first) HDU
+that matches the input extension type, name, and version number,
+as given by the {\tt XTENSION, EXTNAME} (or {\tt HDUNAME}) and {\tt EXTVER} keywords.
+If the input value of {\tt extver} = 0, then the version number will
+be ignored when looking for a matching HDU.
+
+\begin{verbatim}
+_________________________________________________________________
+int fits_get_hdu_type(fitsfile *fptr,  int *hdutype, int *status)
+\end{verbatim}
+
+Get the type of the current HDU in the FITS file:  {\tt IMAGE\_HDU,
+ASCII\_TBL, or BINARY\_TBL}.
+
+\begin{verbatim}
+____________________________________________________________________
+int fits_copy_hdu(fitsfile *infptr, fitsfile *outfptr, int morekeys,
+                  int *status)
+int fits_copy_file(fitsfile *infptr, fitsfile *outfptr, int previous,
+                  int current, int following, > int *status)
+\end{verbatim}
+
+The first routine copies the current HDU from the FITS file associated
+with infptr and appends it to the end of the FITS file associated with
+outfptr.  Space may be reserved for {\tt morekeys} additional keywords
+in the output header.   The second routine copies any HDUs previous
+to the current HDU, and/or the current HDU, and/or any HDUs following the
+current HDU, depending on the value (True or False) of {\tt previous,
+current}, and {\tt following}, respectively.  For example,
+\begin{verbatim}
+  fits_copy_file(infptr, outfptr, 0, 1, 1, &status);
+\end{verbatim}
+will copy the current HDU and any HDUs that follow it from the input
+to the output file, but it will not copy any HDUs preceding the 
+current HDU.
+
+
+\newpage
+% ===================================================================
+\subsection{Image I/O Routines}
+
+This section lists the more important CFITSIO routines which operate on
+FITS images.
+
+\begin{verbatim}
+_______________________________________________________________
+int fits_get_img_type(fitsfile *fptr, int *bitpix, int *status)
+int fits_get_img_dim( fitsfile *fptr, int *naxis,  int *status)
+int fits_get_img_size(fitsfile *fptr, int maxdim,  long *naxes,
+                      int *status)
+int fits_get_img_param(fitsfile *fptr, int maxdim,  int *bitpix,
+                       int *naxis, long *naxes, int *status)
+\end{verbatim}
+
+Get information about the currently opened image HDU. The first routine
+returns the datatype of the image as (defined by the {\tt BITPIX}
+keyword), which can have the following symbolic constant values: 
+\begin{verbatim}
+    BYTE_IMG   =   8   ( 8-bit byte pixels, 0 - 255)
+    SHORT_IMG  =  16   (16 bit integer pixels)
+    LONG_IMG   =  32   (32-bit integer pixels)
+    FLOAT_IMG  = -32   (32-bit floating point pixels)
+    DOUBLE_IMG = -64   (64-bit floating point pixels)
+\end{verbatim}
+
+The second and third routines return the number of dimensions in the
+image (from the {\tt NAXIS} keyword), and the sizes of each dimension
+(from the {\tt NAXIS1, NAXIS2}, etc. keywords).  The last routine
+simply combines the function of the first 3 routines.  The input {\tt
+maxdim} parameter in this routine gives the maximum number dimensions
+that may be returned (i.e., the dimension of the {\tt naxes}
+array)
+
+\begin{verbatim}
+__________________________________________________________
+int fits_create_img(fitsfile *fptr, int bitpix, int naxis, 
+                    long *naxes, int *status)
+\end{verbatim}
+
+Create an image HDU by writing the required keywords which define the
+structure of the image.  The 2nd through 4th parameters  specified the
+datatype, the number of dimensions, and the sizes of the dimensions.
+The allowed values of the {\tt bitpix} parameter are listed above in
+the description of the {\tt fits\_get\_img\_type} routine.  If the FITS
+file pointed to by {\tt fptr} is empty (previously created with
+{\tt fits\_create\_file}) then this routine creates a primary array in
+the file, otherwise a new IMAGE extension is appended to end of the
+file following the other HDUs in the file.
+
+\begin{verbatim}
+______________________________________________________________
+int fits_write_pix(fitsfile *fptr, int datatype, long *fpixel,
+               long nelements, void *array, int *status);
+
+int fits_write_pixnull(fitsfile *fptr, int datatype, long *fpixel,
+               long nelements, void *array, void *nulval, int *status);
+
+int fits_read_pix(fitsfile *fptr, int  datatype, long *fpixel, 
+                  long nelements, void *nulval, void *array, 
+                  int *anynul, int *status)
+\end{verbatim}
+
+Read or write all or part of the FITS image.  There are 2 different
+'write' pixel routines:  The first simply writes the input array of pixels
+to the FITS file.  The second is similar, except that it substitutes
+the appropriate null pixel value in the FITS file for any pixels 
+which have a value equal to {\tt *nulval} (note that this parameter
+gives the address of the null pixel value, not the value itself).
+Similarly,  when reading an image, CFITSIO will substitute the value
+given by {\tt nulval}  for  any undefined pixels in the image, unless
+{\tt nulval = NULL}, in which case no checks will be made for undefined
+pixels when reading the FITS image.
+
+The {\tt fpixel} parameter in these routines is an array which gives
+the coordinate in each dimension of the first pixel to be read or
+written, and {\tt nelements} is the total number of pixels to read or
+write.  {\tt array} is the address of an array which either contains
+the pixel values to be written, or will hold the values of the pixels
+that are read.  When reading, {\tt array} must have been allocated
+large enough to hold all the returned pixel values.  These routines
+starts at the {\tt fpixel} location and then read or write the {\tt
+nelements} pixels, continuing on successive rows of the image if
+necessary.  For example, to write an entire 2D image, set {\tt
+fpixel[0] = fpixel[1] = 1}, and {\tt nelements = NAXIS1 * NAXIS2}.  Or
+to read just the 10th row of the image, set {\tt fpixel[0] = 1,
+fpixel[1] = 10}, and {\tt nelements = NAXIS1}.  The {\tt datatype}
+parameter specifies the datatype of the C {\tt array} in the program,
+which need not be the same as the datatype of the FITS image itself.
+If the datatypes differ then CFITSIO will convert the data as it is
+read or written.  The following symbolic constants are allowed for the
+value of {\tt datatype}:
+\begin{verbatim}
+  TBYTE     unsigned char
+  TSBYTE    signed char
+  TSHORT    signed short
+  TUSHORT   unsigned short
+  TINT      signed int
+  TUINT     unsigned int
+  TLONG     signed long
+  TULONG    unsigned long
+  TFLOAT    float
+  TDOUBLE   double
+\end{verbatim}
+
+
+\begin{verbatim}
+_________________________________________________________________
+int fits_write_subset(fitsfile *fptr, int datatype, long *fpixel,
+             long *lpixel, DTYPE *array, > int *status)
+
+int fits_read_subset(fitsfile *fptr, int  datatype, long *fpixel,
+             long *lpixel, long *inc, void *nulval,  void *array,
+             int *anynul, int *status)
+\end{verbatim}
+
+Read or write a rectangular section of the FITS image.  These are very
+similar to {\tt fits\_write\_pix} and {\tt fits\_read\_pix} except that
+you specify the last pixel coordinate (the upper right corner of the
+section) instead of the number of pixels to be read.  The read routine
+also has an {\tt inc} parameter which can be used to read only every
+{\tt inc-th} pixel along each dimension of the image.  Normally  {\tt
+inc[0] = inc[1] = 1} to read every pixel in a 2D image.  To read every
+other pixel in the entire 2D image, set
+\begin{verbatim}
+    fpixel[0] = fpixel[1] = 1
+    lpixel[0] = {NAXIS1}
+    lpixel[1] = {NAXIS2}  
+    inc[0] = inc[1] = 2  
+\end{verbatim}
+
+Or, to read the 8th row of a 2D image, set 
+\begin{verbatim}
+    fpixel[0] = 1
+    fpixel[1] = 8
+    lpixel[0] = {NAXIS1}
+    lpixel[1] = 8
+    inc[0] = inc[1] = 1
+\end{verbatim}
+
+\newpage
+% ===================================================================
+\subsection{Table I/O Routines}
+
+This section lists the most important CFITSIO routines which operate on
+FITS tables.
+
+\begin{verbatim}
+__________________________________________________________________________
+int fits_create_tbl(fitsfile *fptr, int tbltype, long nrows, int tfields,
+    char *ttype[],char *tform[], char *tunit[], char *extname, int *status)
+\end{verbatim}
+
+Create a new  table extension by writing the required keywords that
+define the table structure. The required null primary array
+will be created first if the file is initially completely empty.  {\tt
+tbltype} defines the type of table and can have values of {\tt
+ASCII\_TBL or BINARY\_TBL}.  Binary tables are generally preferred
+because they are more efficient and support a greater range of column
+datatypes than ASCII tables.
+
+The {\tt nrows} parameter gives the initial number of empty rows to be
+allocated for the table; this should normally be set to 0.  The {\tt tfields}
+parameter gives the number of columns in the table (maximum = 999).
+The {\tt
+ttype, tform}, and {\tt tunit} parameters give the name, datatype, and
+physical units of each column, and {\tt extname} gives the name for the
+table (the value of the {\tt EXTNAME} keyword).  
+The FITS Standard recommends that only
+letters, digits, and the underscore character be used in column names
+with no embedded spaces.  It is recommended that all the column names
+in a given table be unique within the first 8 characters.
+
+The following table
+shows the TFORM column format values that are allowed in ASCII tables
+and in binary tables:
+\begin{verbatim}
+        ASCII Table Column Format Codes
+        -------------------------------
+        (w = column width, d = no. of decimal places to display)
+            Aw   - character string
+            Iw   - integer
+            Fw.d - fixed floating point
+            Ew.d - exponential floating point
+            Dw.d - exponential floating point
+
+        Binary Table Column Format Codes
+        --------------------------------
+        (r = vector length, default = 1)
+            rA  - character string
+            rAw - array of strings, each of length w
+            rL  - logical
+            rX  - bit
+            rB  - unsigned byte
+            rS  - signed byte **
+            rI  - signed 16-bit integer
+            rU  - unsigned 16-bit integer **
+            rJ  - signed 32-bit integer
+            rV  - unsigned 32-bit integer **
+            rK  - 64-bit integer ***
+            rE  - 32-bit floating point
+            rD  - 64-bit floating point
+            rC  - 32-bit complex pair
+            rM  - 64-bit complex pair
+
+     ** The S, U and V format codes are not actual legal TFORMn values.
+        CFITSIO substitutes the somewhat more complicated set of
+        keywords that are used to represent unsigned integers or
+        signed bytes.
+
+    *** The 64-bit integer format is experimental and is not 
+        officially recognized in the FITS Standard.
+\end{verbatim}
+  
+The {\tt tunit} and {\tt extname} parameters are optional and
+may be set to NULL
+if they are not needed.  
+
+Note that it may be easier to create a new table by copying the
+header from another existing table with {\tt fits\_copy\_header} rather
+than calling this routine.
+
+\begin{verbatim}
+_______________________________________________________________
+int fits_get_num_rows(fitsfile *fptr, long *nrows, int *status)
+int fits_get_num_cols(fitsfile *fptr, int  *ncols, int *status)
+\end{verbatim}
+
+Get the number of rows or columns in the current FITS table.  The
+number of rows is given by the {\tt NAXIS2} keyword and the number of columns
+is given by the {\tt TFIELDS} keyword in the header of the table.
+
+\begin{verbatim}
+_______________________________________________________________
+int fits_get_colnum(fitsfile *fptr, int casesen, char *template,
+                    int *colnum, int *status)
+int fits_get_colname(fitsfile *fptr, int casesen, char *template,
+                    char *colname, int *colnum, int *status)
+\end{verbatim}
+
+Get the  column number (starting with 1, not 0) of the column whose
+name matches the specified template name.  The only difference in
+these 2 routines is that the 2nd one also returns the name of the
+column that matched the template string.
+
+Normally, {\tt casesen} should
+be set to {\tt CASEINSEN}, but it may be set to {\tt CASESEN} to force
+the name matching to be case-sensitive.
+
+The input {\tt template} string gives the name of the desired column and
+may include wildcard characters:  a `*' matches any sequence of
+characters (including zero characters), `?' matches any single
+character, and `\#' matches any consecutive string of decimal digits
+(0-9).  If more than one column name in the table matches the template
+string, then the first match is returned and the status value will be
+set to {\tt COL\_NOT\_UNIQUE}  as a warning that a unique match was not
+found.  To find the next column that matches the template, call this
+routine again leaving the input status value equal to {\tt
+COL\_NOT\_UNIQUE}.  Repeat this process until {\tt status =
+COL\_NOT\_FOUND}  is returned.
+
+\begin{verbatim}
+_______________________________________________________________
+int fits_get_coltype(fitsfile *fptr, int colnum, int *typecode,
+                     long *repeat, long *width, int *status)
+
+int fits_get_eqcoltype(fitsfile *fptr, int colnum, int *typecode,
+                     long *repeat, long *width, int *status)
+\end{verbatim}
+
+Return the datatype, vector repeat count, and the width in bytes of a
+single column element for column number {\tt colnum}.  Allowed values
+for the returned datatype in ASCII tables are:  {\tt TSTRING, TSHORT,
+TLONG, TFLOAT, and TDOUBLE}.  Binary tables support these additional
+types: {\tt TLOGICAL, TBIT, TBYTE, TINT32BIT, TCOMPLEX and TDBLCOMPLEX}.  The
+negative of the datatype code value is returned if it is a variable
+length array column.
+
+These 2 routines are similar, except that in the case of scaled
+integer columns the 2nd routine, fit\_get\_eqcoltype, returns the
+'equivalent' datatype that is needed to store the scaled values, which
+is not necessarily the same as the physical datatype of the unscaled values
+as stored in the FITS table.  For example if a '1I' column in a binary
+table has TSCALn = 1 and TZEROn = 32768, then this column effectively
+contains unsigned short integer values, and thus the returned value of
+typecode will be TUSHORT, not TSHORT.  Or, if TSCALn or TZEROn are not
+integers, then the equivalent datatype will be returned as TFLOAT or
+TDOUBLE, depending on the size of the integer.
+
+The repeat count is always 1 in ASCII tables.
+The 'repeat' parameter returns the vector repeat count on the binary
+table TFORMn keyword value. (ASCII table columns always have repeat
+= 1).  The 'width' parameter returns the width in bytes of a single
+column element (e.g., a '10D' binary table column will have width =
+8, an ASCII table 'F12.2' column will have width = 12, and a binary
+table'60A' character string  column will have width = 60);  Note that
+this routine supports the local convention for specifying arrays of
+fixed length strings within a binary table character column using
+the syntax TFORM = 'rAw' where 'r' is the total number of
+characters (= the width of the column) and 'w' is the width of a
+unit string within the column.  Thus if the column has TFORM =
+'60A12' then this means that each row of the table contains
+5 12-character substrings within the 60-character field, and thus 
+in this case this routine will return typecode = TSTRING, repeat =
+60, and width = 12.  The number of substings in any binary table
+character string field can be calculated by (repeat/width). 
+A null pointer may be given for any of the output parameters that
+ are not needed.
+
+\begin{verbatim}
+____________________________________________________________________________
+int fits_insert_rows(fitsfile *fptr, long firstrow, long nrows, int *status)
+int fits_delete_rows(fitsfile *fptr, long firstrow, long nrows, int *status)
+int fits_delete_rowrange(fitsfile *fptr, char *rangelist, int *status)
+int fits_delete_rowlist(fitsfile *fptr, long *rowlist, long nrows, int *stat)
+\end{verbatim}
+
+Insert or delete rows in a table.  The blank rows are inserted
+immediately following row {\tt frow}. Set {\tt frow} = 0 to insert rows
+at the beginning of the table.  The first 'delete' routine deletes {\tt
+nrows} rows beginning with row {\tt firstrow}.   The 2nd delete routine
+takes an input string listing the rows or row ranges to be deleted
+(e.g., '2,4-7, 9-12').  The last delete routine takes an input long
+integer array that specifies each individual row to be deleted.  The
+row lists must be sorted in ascending order.  All these routines update
+the value of the {\tt NAXIS2} keyword to reflect the new number of rows
+in the table.
+
+\begin{verbatim}
+_________________________________________________________________________
+int fits_insert_col(fitsfile *fptr, int colnum, char *ttype, char *tform,
+                    int *status)
+int fits_insert_cols(fitsfile *fptr, int colnum, int ncols, char **ttype,
+                     char **tform, int *status)
+
+int fits_delete_col(fitsfile *fptr, int colnum, int *status)
+\end{verbatim}
+
+Insert or delete columns in a table.  {\tt colnum} gives the position
+of the column to be inserted or deleted (where the first column of the
+table is at position 1).  {\tt ttype} and {\tt tform} give the column
+name and column format, where the allowed format codes are listed above
+in the description of the {\tt fits\_create\_table} routine.  The 2nd
+'insert' routine inserts multiple columns, where {\tt ncols} is the
+number of columns to insert, and  {\tt ttype} and {\tt tform} are
+arrays of string pointers in this case.
+
+\begin{verbatim}
+____________________________________________________________________
+int fits_copy_col(fitsfile *infptr, fitsfile *outfptr, int incolnum,
+        int outcolnum, int create_col, int *status);
+\end{verbatim}
+
+Copy a column from one table HDU to another.  If {\tt create\_col} = TRUE (i.e., not equal to zero),
+then a new column will be inserted in the output table at position
+{\tt outcolumn}, otherwise the values in the existing output column will be
+overwritten. 
+
+\begin{verbatim}
+__________________________________________________________________________
+int fits_write_col(fitsfile *fptr, int datatype, int colnum, long firstrow,
+                  long firstelem, long nelements, void *array, int *status)
+int fits_write_colnull(fitsfile *fptr, int datatype, int colnum, 
+                  long firstrow, long firstelem, long nelements, 
+                  void *array, void *nulval, int *status)
+int fits_write_col_null(fitsfile *fptr, int colnum, long firstrow,
+                  long firstelem, long nelements, int *status)
+
+int fits_read_col(fitsfile *fptr, int datatype, int colnum, long firstrow,
+       long firstelem, long nelements, void *nulval, void *array, 
+       int *anynul, int *status)
+
+\end{verbatim}
+
+Write or read elements in column number {\tt colnum}, starting with row
+{\tt firstsrow} and element {\tt firstelem} (if it is a vector
+column).  {\tt firstelem} is ignored if it is a scalar column. The {\tt
+nelements} number of elements are read or written continuing on
+successive rows of the table if necessary. {\tt array} is the address
+of an array which either contains the  values to be written, or will
+hold the returned values that are read.  When reading, {\tt array} must
+have been allocated large enough to hold all the returned values.
+
+There are 3 different 'write' column routines:  The first simply writes
+the input array into the column.  The second is similar, except that it
+substitutes the appropriate null pixel value in the column for any
+input array values which are equal to {\tt *nulval} (note that this
+parameter gives the address of the null pixel value, not the value
+itself).  The third write routine sets the specified table elements
+to a null value.  New rows will be automatical added to the table
+if the write operation extends beyond the current size of the table.
+
+When reading a column, CFITSIO will substitute the value given by {\tt
+nulval}  for  any undefined elements in the FITS column, unless {\tt
+nulval} or {\tt *nulval = NULL}, in which case no checks will be made
+for undefined values when reading the column.
+
+{\tt datatype} specifies the datatype of the C {\tt array} in the program,
+which need not be the same as the intrinsic datatype of the column in
+the FITS table.   The following symbolic constants are allowed for the
+value of {\tt datatype}:
+
+\begin{verbatim}
+  TSTRING   array of character string pointers
+  TBYTE     unsigned char
+  TSHORT    signed short
+  TUSHORT   unsigned short
+  TINT      signed int
+  TUINT     unsigned int
+  TLONG     signed long
+  TULONG    unsigned long
+  TFLOAT    float
+  TDOUBLE   double
+\end{verbatim}
+
+Note that {\tt TSTRING} corresponds to the C {\tt
+char**} datatype, i.e., a pointer to an array of pointers to an array
+of characters.
+
+Any column, regardless of it's intrinsic datatype, may be read as a
+{\tt TSTRING} character string. The display format of the returned
+strings will be determined by the {\tt TDISPn} keyword, if it exists,
+otherwise a default format will be used depending on the datatype of
+the column.  The {\tt tablist} example utility program (available from
+the CFITSIO web site) uses this feature to display all the values in a
+FITS table.
+
+\begin{verbatim}
+_____________________________________________________________________
+int fits_select_rows(fitsfile *infptr, fitsfile *outfptr, char *expr,
+                     int *status)
+int fits_calculator(fitsfile *infptr, char *expr, fitsfile *outfptr,
+                    char *colname, char *tform, int *status) 
+\end{verbatim}
+
+These are 2 of the most powerful routines in the CFITSIO library.  (See
+the full CFITSIO Reference Guide for a description of several related
+routines).  These routines can perform complicated transformations on
+tables based on an input arithmetic expression which is evaluated for
+each row of the table.  The first routine will select or copy rows of
+the table for which the expression evaluates to TRUE (i.e., not equal
+to zero).  The second routine writes the value of the expression to a
+column in the output table.  Rather than supplying the expression
+directly to these routines, the expression may also be written to a
+text file (continued over multiple lines if necessary) and the name of
+the file, prepended with a '@' character, may be supplied as the value
+of the 'expr' parameter (e.g.  '@filename.txt').
+
+The arithmetic expression may be a function of any column or keyword in
+the input table as shown in these examples:
+
+\begin{verbatim}
+Row Selection Expressions:
+   counts > 0                          uses COUNTS column value
+   sqrt( X**2 + Y**2) < 10.            uses X and Y column values
+   (X > 10) || (X < -10) && (Y == 0)   used 'or' and 'and' operators  
+   gtifilter()                         filter on Good Time Intervals
+   regfilter("myregion.reg")           filter using a region file
+   @select.txt                         reads expression from a text file
+Calculator Expressions:
+   #row % 10                        modulus of the row number
+   counts/#exposure                 Fn of COUNTS column and EXPOSURE keyword
+   dec < 85 ? cos(dec * #deg) : 0   Conditional expression: evaluates to
+                                      cos(dec) if dec < 85, else 0
+   (count{-1}+count+count{+1})/3.   running mean of the count values in the
+                                      previous, current, and next rows
+   max(0, min(X, 1000))             returns a value between 0 - 1000
+   @calc.txt                        reads expression from a text file
+\end{verbatim}
+
+Most standard mathematical operators and functions are supported.  If
+the expression includes the name of a column, than the value in the
+current row of the table will be used when evaluating the expression on
+each row.   An offset to an adjacent row can be specified by including
+the offset value in curly brackets after the column name as shown in
+one of the examples.  Keyword values can be included in the expression
+by preceding the keyword name with a `\#' sign.   See Section 5 of this
+document for more discussion of the expression syntax.
+
+{\tt gtifilter} is a special function which tests whether the {\tt
+TIME} column value in the input table falls within one or more Good
+Time Intervals.  By default, this function looks for a 'GTI' extension
+in the same file as the input table.  The 'GTI' table contains {\tt START} 
+and {\tt STOP} columns which define the range of
+each good time interval. See section 5.4.3 for more details.
+
+{\tt regfilter} is another special function which selects rows based on
+whether the spatial position associated with each row is located within
+in a specified region of the sky.  By default, the {\tt X} and {\tt Y}
+columns in the input table are assumed to give the position of each row.
+The spatial region is defined in an ASCII text file whose name is given
+as the argument to the {\tt regfilter} function. See section 5.4.4 for
+more details.
+
+The {\tt infptr} and {\tt outfptr} parameters in these routines may
+point to the same table or to different tables.  In {\tt
+fits\_select\_rows}, if the input and output tables are the same then
+the rows that do not satisfy the selection expression will be deleted
+from the table.  Otherwise, if the output table is different from the
+input table then the selected rows will be copied from the input table
+to the output table.
+
+The output column in {\tt fits\_calculator} may or may not already
+exist.  If it exists then the calculated values will be written to that
+column, overwriting the existing values.  If the column doesn't exist
+then the new column will be appended to the output table. The {\tt tform}
+parameter can be used to specify the datatype of the new column (e.g.,
+the {\tt TFORM} keyword value as in {\tt '1E', or '1J'}). If {\tt
+tform} = NULL then a default datatype will be used, depending on the
+expression.
+
+\begin{verbatim}
+_____________________________________________________________________
+int fits_read_tblbytes(fitsfile *fptr, long firstrow, long firstchar,
+                     long nchars, unsigned char *array, int *status)
+int fits_write_tblbytes (fitsfile *fptr, long firstrow, long firstchar,
+                     long nchars, unsigned char *array, int *status)
+\end{verbatim}
+
+These 2 routines provide low-level access to tables and are mainly
+useful as an efficient way to copy rows of a table from one file to
+another.  These routines simply read or write the specified number of
+consecutive characters (bytes) in a table, without regard for column
+boundaries.  For example, to read or write the first row of a table,
+set {\tt firstrow = 1, firstchar = 1}, and {\tt nchars = NAXIS1} where
+the length of a row is given by the value of the {\tt NAXIS1} header
+keyword.  When reading a table, {\tt array} must have been declared at
+least {\tt nchars} bytes long to hold the returned string of bytes.
+
+\newpage
+% ===================================================================
+\subsection{Header Keyword I/O Routines}
+\nopagebreak
+The following routines read and write header keywords in the current HDU.
+\nopagebreak
+
+\begin{verbatim}
+____________________________________________________________________
+int fits_get_hdrspace(fitsfile *fptr, int *keysexist, int *morekeys,
+                      int *status)
+\end{verbatim}
+\nopagebreak
+Return the number of existing keywords (not counting the mandatory END
+keyword) and the amount of empty space currently available for more
+keywords. The {\tt morekeys} parameter may be set to NULL if it's value is
+not needed.
+
+\begin{verbatim}
+___________________________________________________________________________
+int fits_read_record(fitsfile *fptr, int keynum, char *record, int *status)
+int fits_read_card(fitsfile *fptr, char *keyname, char *record, int *status)
+int fits_read_key(fitsfile *fptr, int datatype, char *keyname,
+                  void *value, char *comment, int *status)
+
+int fits_find_nextkey(fitsfile *fptr, char **inclist, int ninc,
+                      char **exclist, int nexc, char *card, int *status)
+
+int fits_read_key_unit(fitsfile *fptr, char *keyname, char *unit, 
+                       int *status)
+\end{verbatim}
+
+These routines all read a header record in the current HDU. The first
+routine reads keyword number {\tt keynum} (where the first keyword is
+at position 1).  This routine is most commonly used when sequentially
+reading every record in the header from beginning to end.  The 2nd and
+3rd routines read the named keyword and return either the whole
+80-byte record, or the keyword value and comment string.
+
+Wild card characters (*, ?, and \#) may be used when specifying the name
+of the keyword to be read, in which case the first matching keyword is
+returned.
+
+The {\tt datatype} parameter specifies the C datatype of the returned
+keyword value and can have one of the following symbolic constant
+values:  {\tt TSTRING, TLOGICAL} (== int), {\tt TBYTE}, {\tt TSHORT},
+{\tt TUSHORT}, {\tt TINT}, {\tt TUINT}, {\tt TLONG}, {\tt TULONG}, {\tt
+TFLOAT}, {\tt TDOUBLE}, {\tt TCOMPLEX}, and {\tt TDBLCOMPLEX}.  Data
+type conversion will be performed for numeric values if the intrinsic
+FITS keyword value does not have the same datatype.  The {\tt comment}
+parameter may be set equal to NULL if the comment string is not
+needed.
+
+The 4th routine provides an easy way to find all the keywords in the
+header that match one of the name templates in {\tt inclist} and do not
+match any of the name templates in {\tt exclist}.  {\tt ninc} and {\tt
+nexc} are the number of template strings in {\tt inclist} and {\tt
+exclist}, respectively.  Wild cards (*, ?, and \#) may be used in the
+templates to match multiple keywords.  Each time this routine is called
+it returns the next matching 80-byte keyword record.  It returns status
+= {\tt KEY\_NO\_EXIST} if there are no more matches.
+
+The 5th routine returns the keyword value units string, if any.
+The units are recorded at the beginning of the keyword comment field
+enclosed in square brackets.
+\begin{verbatim}
+_______________________________________________________________
+int fits_write_key(fitsfile *fptr, int datatype, char *keyname, 
+        void *value, char *comment, int *status)
+int fits_update_key(fitsfile *fptr, int datatype, char *keyname,
+        void *value, char *comment, int *status)
+int fits_write_record(fitsfile *fptr, char *card, int *status)
+
+int fits_modify_comment(fitsfile *fptr, char *keyname, char *comment,
+        int *status)
+int fits_write_key_unit(fitsfile *fptr, char *keyname, char *unit,
+        int *status)
+
+\end{verbatim}
+
+Write or modify a keyword  in the header of the current HDU.  The
+first routine appends the new keyword to the end of the header, whereas
+the second routine will update the value and comment fields of the
+keyword if it already exists, otherwise it behaves like the first
+routine and appends the new keyword.  Note that {\tt value} gives the
+address to the value and not the value itself.  The {\tt datatype}
+parameter specifies the C datatype of the keyword value and may have
+any of the values listed in the description of the keyword reading
+routines, above.  A NULL may be entered for the comment parameter, in
+which case the  keyword comment field will be unmodified or left
+blank.
+
+The third routine is more primitive and simply writes the 80-character
+{\tt card} record to the header.  It is the programmer's responsibility
+in this case to ensure that the record conforms to all the FITS format
+requirements for a header record.
+
+The fourth routine modifies the comment string in an existing keyword,
+and the last routine writes or updates the keyword units string for an
+existing keyword.  (The units are recorded at the beginning of the
+keyword comment field enclosed in square brackets).
+
+\begin{verbatim}
+___________________________________________________________________
+int fits_write_comment(fitsfile *fptr, char *comment,  int *status)
+int fits_write_history(fitsfile *fptr, char *history,  int *status)
+int fits_write_date(fitsfile *fptr,  int *status)
+\end{verbatim}
+
+Write a {\tt COMMENT, HISTORY}, or {\tt DATE} keyword to the current
+header.  The {\tt COMMENT} keyword is typically used to write a comment
+about the file or the data.  The {\tt HISTORY} keyword is typically
+used to provide information about the history of the processing
+procedures that have been applied to the data.  The {\tt comment} or
+{\tt history} string will be continued over multiple keywords if it is
+more than 70 characters long.
+
+The {\tt DATE} keyword is used to record the date and time that the
+FITS file was created.  Note that this file creation date is usually
+different from the date of the observation which obtained the data in
+the FITS file.  The {\tt DATE} keyword value is a character string in
+'yyyy-mm-ddThh:mm:ss' format. If a {\tt DATE} keyword already exists in
+the header, then this routine will update the value with the current
+system date.
+
+\begin{verbatim}
+___________________________________________________________________
+int fits_delete_record(fitsfile *fptr, int keynum,  int *status)
+int fits_delete_key(fitsfile *fptr, char *keyname,  int *status)
+\end{verbatim}
+
+Delete a keyword record. The first routine deletes a keyword at a
+specified position (the first keyword is at position 1, not 0),
+whereas the second routine deletes the named keyword.
+
+\begin{verbatim}
+_______________________________________________________________________
+int fits_copy_header(fitsfile *infptr, fitsfile *outfptr,  int *status)
+\end{verbatim}
+
+Copy all the header keywords from the current HDU associated with
+infptr to the current HDU associated with outfptr.  If the current
+output HDU is not empty, then a new HDU will be appended to the output
+file. The output HDU will then have the identical structure as the
+input HDU, but will contain no data.
+
+\newpage
+% ===================================================================
+\subsection{Utility Routines}
+
+This section lists the most important CFITSIO general utility routines.
+
+\begin{verbatim}
+___________________________________________________________________
+int fits_write_chksum( fitsfile *fptr, int *status)
+int fits_verify_chksum(fitsfile *fptr, int *dataok, int *hduok, int *status)
+\end{verbatim}
+
+These routines  compute or validate the checksums for the currenrt
+HDU.  The {\tt DATASUM} keyword is used to store the numerical value of
+the 32-bit, 1's complement checksum for the data unit alone.  The {\tt
+CHECKSUM} keyword is used to store the ASCII encoded COMPLEMENT of the
+checksum for the entire HDU.  Storing the complement, rather than the
+actual checksum, forces the checksum for the whole HDU to equal zero.
+If the file has been modified since the checksums were computed, then
+the HDU checksum will usually not equal zero.
+
+The returned {\tt dataok} and {\tt hduok} parameters will have a value
+= 1 if the data or HDU is verified correctly, a value = 0 if the
+{\tt DATASUM} or {\tt CHECKSUM} keyword is not present, or value = -1 if the
+computed checksum is not correct.
+
+
+\begin{verbatim}
+___________________________________________________________________
+int fits_parse_value(char *card, char *value, char *comment, int *status)
+int fits_get_keytype(char *value, char *dtype, int *status)
+int fits_get_keyclass(char *card)
+int fits_parse_template(char *template, char *card, int *keytype, int *status)
+
+\end{verbatim}
+
+{\tt fits\_parse\_value} parses the input 80-chararacter header keyword record, returning
+the value (as a literal character string) and comment strings.  If the
+keyword has no value (columns 9-10 not equal to '= '), then a null
+value string is returned and the comment string is set equal to column
+9 - 80 of the input string.
+
+{\tt fits\_get\_keytype} parses the keyword value string to determine its
+datatype.  {\tt dtype} returns with a value of 'C', 'L', 'I', 'F' or
+'X', for character string, logical, integer, floating point, or
+complex, respectively.
+
+{\tt fits\_get\_keyclass} returns a classification code that indicates
+the classification type of the input keyword record (e.g., a required
+structural keyword, a TDIM keyword, a WCS keyword, a comment keyword,
+etc.  See the CFITSIO Reference Guide for a list of the different
+classification codes.
+
+{\tt fits\_parse\_template} takes an input free format keyword template
+string and returns a formatted 80*char record that satisfies all the
+FITS requirements for a header keyword record.  The template should
+generally contain 3 tokens: the keyword name, the keyword value, and
+the keyword comment string.  The returned {\tt keytype} parameter
+indicates whether the keyword is a COMMENT keyword or not.   See the
+CFITSIO Reference Guide for more details.
+
+\newpage
+% ===================================================================
+\section{CFITSIO File Names and Filters}
+
+\subsection{Creating New Files}
+
+When creating a new output file on magnetic disk  with {\tt
+fits\_create\_file} the following features are supported.
+\begin{itemize}
+\item Overwriting, or 'Clobbering' an Existing File
+
+If the filename is preceded by an exclamation
+point (!) then if that file already exists it will be deleted prior to
+creating the new FITS file.  Otherwise if there is an existing file
+with the same name, CFITSIO will not overwrite the existing file and
+will return an error status code.  Note  that the exclamation point is
+a special UNIX character, so if it is used on the command line rather
+than entered at a task prompt, it must be preceded by a backslash to
+force the UNIX shell to pass it verbatim to the application program.
+
+\item Compressed Output Files
+
+If the output disk file name ends with the suffix '.gz', then CFITSIO
+will compress the file using the gzip compression algorithm before
+writing it to disk.  This can reduce the amount of disk space used by
+the file.  Note that this feature requires that the uncompressed file
+be constructed in memory before it is compressed and written to disk,
+so it can fail if there is insufficient available memory.
+
+One can also specify that any images written to the output file should
+be compressed using the newly developed `tile-compression' algorithm by
+appending `[compress]' to the name of the disk file (as in
+{\tt myfile.fits[compress]}).   Refer to the CFITSIO User's Reference Guide
+for more information about this new image compression format.
+
+\item Using a Template to Create a New FITS File
+
+The structure of any new FITS file that is to be created may be defined
+in an ASCII template file.  If the name of the template file is
+appended to the name of the FITS file itself, enclosed in parenthesis
+(e.g., {\tt 'newfile.fits(template.txt)'}) then CFITSIO will create a
+FITS file with that structure before opening it for the application to
+use.  The template file basically defines the dimensions and data type
+of the primary array and any IMAGE extensions, and the names and data
+types of the columns in any ASCII or binary table extensions.  The
+template file can also be used to define any optional keywords that
+should be written in any of the HDU headers.  The image pixel values
+and table entry values are all initialized to zero.  The application
+program can then write actual data into the HDUs.  See the CFITSIO
+Reference Guide for for a complete description of the template file
+syntax.
+
+\item Creating a Temporary Scratch File in Memory
+
+It is sometimes useful to create a temporary output file when testing
+an application program.  If the name of the file to be created is
+specified as {\tt mem:} then CFITSIO will create the file in
+memory where it will persist only until the program closes the file.
+Use of this {\tt mem:} output file usually enables the program to run
+faster, and of course the output file does not use up any disk space.
+
+
+\end{itemize}
+
+\subsection{Opening Existing Files}
+
+When opening a file with {\tt fits\_open\_file}, CFITSIO can read a
+variety of different input file formats and is not restricted to only
+reading FITS format files from magnetic disk. The following types of
+input files are all supported:
+
+\begin{itemize}
+\item FITS files compressed with {\tt zip, gzip} or {\tt compress}
+
+If CFITSIO cannot find the specified file to open it will automatically
+look for a file with the same rootname but with a {\tt .gz, .zip}, or
+{\tt .Z} extension.  If it finds such a compressed file, it will
+allocate a block of memory and uncompress the file into that memory
+space.  The application program will then transparently open this
+virtual FITS file in memory.  Compressed
+files can only be opened with 'readonly', not 'readwrite' file access.
+
+\item  FITS files on the internet, using {\tt ftp} or {\tt http} URLs
+
+Simply provide the full URL as the name of the file that you want to
+open.  For example,\linebreak {\tt
+ftp://legacy.gsfc.nasa.gov/software/fitsio/c/testprog.std}\linebreak
+will open the CFITSIO test FITS file that is located on the {\tt
+legacy} machine.  These files can only be opened with 'readonly' file
+access.
+
+\item  FITS files on {\tt stdin} or {\tt stdout} file streams
+
+If the name of the file to be opened is {\tt 'stdin'} or {\tt '-'} (a
+single dash character) then CFITSIO will read the file from the
+standard input stream.  Similarly, if the output file name is {\tt
+'stdout'} or {\tt '-'}, then the file will be written to the standard
+output stream.  In addition, if the output filename is {\tt
+'stdout.gz'} or {\tt '-.gz'} then it will be gzip compressed before
+being written to stdout.  This mechanism can be used to pipe FITS files
+from one task to another without having to write an intermediary FITS
+file on magnetic disk.
+
+\item FITS files that exist only in memory, or shared memory.
+
+In some applications, such as real time data acquisition, you may want
+to have one process write a FITS file into a certain section of
+computer memory, and then be able to open that file in memory with
+another process.  There is a specialized CFITSIO open routine called
+{\tt fits\_open\_memfile} that can be used for this purpose.  See the
+``CFITSIO User's Reference Guide'' for more details.
+
+\item  IRAF format images (with {\tt .imh} file extensions)
+
+CFITSIO supports reading IRAF format images by converting them on the
+fly into FITS images in memory.  The application program then reads
+this virtual FITS format image in memory.  There is currently no
+support for writing IRAF format images, or for reading or writing IRAF
+tables.
+
+\item Image arrays in raw binary format
+
+If the input file is a raw binary data array, then CFITSIO will convert
+it on the fly into a virtual FITS image with the basic set of required
+header keywords before it is opened by the application program.  In
+this case the data type and dimensions of the image must be specified
+in square brackets following the filename (e.g. {\tt
+rawfile.dat[ib512,512]}). The first character inside the brackets
+defines the datatype of the array:
+
+\begin{verbatim}
+     b         8-bit unsigned byte
+     i        16-bit signed integer
+     u        16-bit unsigned integer
+     j        32-bit signed integer
+     r or f   32-bit floating point
+     d        64-bit floating point
+\end{verbatim}
+An optional second character specifies the byte order of the array
+values: b or B indicates big endian (as in FITS files and the native
+format of SUN UNIX workstations and Mac PCs) and l or L indicates
+little endian (native format of DEC OSF workstations and IBM PCs).  If
+this character is omitted then the array is assumed to have the native
+byte order of the local machine.  These datatype characters are then
+followed by a series of one or more integer values separated by commas
+which define the size of each dimension of the raw array.  Arrays with
+up to 5 dimensions are currently supported.  
+
+Finally, a byte offset to the position of the first pixel in the data
+file may be specified by separating it with a ':' from the last
+dimension value.  If omitted, it is assumed that the offset = 0.  This
+parameter may be used to skip over any header information in the file
+that precedes the binary data.  Further examples:
+ 
+\begin{verbatim}
+  raw.dat[b10000]          1-dimensional 10000 pixel byte array
+  raw.dat[rb400,400,12]    3-dimensional floating point big-endian array
+  img.fits[ib512,512:2880] reads the 512 x 512 short integer array in a
+                           FITS file, skipping over the 2880 byte header
+\end{verbatim}
+
+\end{itemize}
+\newpage
+
+\subsection{Image Filtering}
+
+\subsubsection{Extracting a subsection of an image}
+
+When specifying the name of an image to be opened, you can select a
+rectangular subsection of the image to be extracted and opened by the
+application program.  The application program then opens a virtual
+image that only contains the pixels within the specified subsection.
+To do this, specify the the range of pixels (start:end) along each axis
+to be extracted from the original image enclosed in square brackets.
+You can also specify an optional pixel increment (start:end:step) for
+each axis of the input image.  A pixel step = 1 will be assumed if it
+is not specified.  If the starting pixel is larger then the end pixel,
+then the image will be flipped (producing a mirror image) along that
+dimension.  An asterisk, '*', may be used to specify the entire range
+of an axis, and '-*' will flip the entire axis.  In the following
+examples, assume that {\tt myfile.fits} contains a 512 x 512 pixel 2D
+image.
+
+\begin{verbatim}
+  myfile.fits[201:210, 251:260] - opens a 10 x 10 pixel subimage.
+
+  myfile.fits[*, 512:257] - opens a 512 x 256 image consisting of
+	      all the columns in the input image, but only rows 257
+	      through 512.  The image will be flipped along the Y axis
+	      since the starting row is greater than the ending
+	      row.
+
+  myfile.fits[*:2, 512:257:2] - creates a 256 x 128 pixel image.
+	      Similar to the previous example, but only every other row
+	      and column is read from the input image.
+
+  myfile.fits[-*, *] - creates an image containing all the rows and
+	      columns in the input image, but flips it along the X
+	      axis.
+\end{verbatim}
+
+If the array to be opened is in an Image extension, and not in the
+primary array of the file, then you need to specify the extension
+name or number in square brackets before giving the subsection range,
+as in {\tt  myfile.fits[1][-*, *]} to read the image in the
+first extension in the file.
+
+\subsubsection{Create an Image by Binning Table Columns}
+
+You can also create and open a virtual image by binning the values in a
+pair of columns of a FITS table (in other words, create a 2-D histogram
+of the values in the 2 columns).  This technique is often used in X-ray
+astronomy where each detected X-ray photon during an observation is
+recorded in a FITS table.  There are typically 2 columns in the table
+called  {\tt X} and {\tt Y} which record the pixel location of that
+event in a virtual 2D image.  To create an image from this table, one
+just scans the X and Y columns and counts up how many photons were
+recorded in each pixel of the image.  When table binning is specified,
+CFITSIO creates a temporary FITS primary array in memory by computing
+the histogram of the values in the specified columns.  After the
+histogram is computed the original FITS file containing the table is
+closed and the temporary FITS primary array is opened and passed to the
+application program.  Thus, the application program never sees the
+original FITS table and only sees the image in the new temporary file
+(which has no extensions).
+
+The table binning specifier is enclosed in square brackets following
+the root filename and table extension name or number and begins with
+the keyword 'bin', as in: \newline  
+{\tt 'myfile.fits[events][bin (X,Y)]'}. In
+this case, the X and Y columns in the 'events' table extension are
+binned up to create the image.  The size of the image is usually
+determined by the {\tt TLMINn} and {\tt TLMAXn} header keywords which
+give the minimum and maximum allowed pixel values in the columns.  For
+instance if {\tt TLMINn = 1} and {\tt TLMAXn = 4096} for both columns, this would
+generate a 4096 x 4096 pixel image by default.  This is rather large,
+so you can also specify a pixel binning factor to reduce the image
+size.  For example specifying ,  {\tt '[bin (X,Y) = 16]'} will use a
+binning factor of 16, which will produce a 256 x 256 pixel image in the
+previous example.
+
+If the TLMIN and TLMAX keywords don't exist, or you want to override
+their values,  you can specify the image range and binning factor
+directly, as in {\tt '[bin X = 1:4096:16, Y=1:4096:16]'}.  You can also
+specify the datatype of the created image by appending a b, i, j, r, or
+d (for 8-bit byte, 16-bit integers, 32-bit integer, 32-bit floating
+points, or 64-bit double precision floating point, respectively)  to
+the 'bin' keyword (e.g. {\tt '[binr (X,Y)]'} creates a floating point
+image).  If the datatype is not specified then a 32-bit integer image
+will be created by default.
+
+If the column name is not specified, then CFITSIO will first try to use
+the 'preferred column' as specified by the CPREF keyword if it exists
+(e.g., 'CPREF = 'DETX,DETY'), otherwise column names 'X', 'Y' will be
+assumed for the 2 axes.
+
+Note that this binning specifier is not restricted to only 2D images
+and can be used to create 1D, 3D, or 4D images as well.  It is also
+possible to specify a weighting factor that is applied during the
+binning.  Please refer to the ``CFITSIO User's Reference Guide'' for
+more details on these advanced features.
+\newpage
+
+\subsection{Table Filtering}
+
+\subsubsection{Column and Keyword Filtering}
+
+The column or keyword filtering specifier is used to modify the
+column structure and/or the header keywords in the HDU that was
+selected with the previous HDU location specifier.   It can
+be used to perform the following types of operations. 
+
+\begin{itemize}
+\item
+Append a new column to a table by giving the column name, optionally
+followed by the datatype in parentheses, followed by an equals sign and
+the arithmetic  expression to be used to compute the value.  The
+datatype is specified using the same syntax that is allowed for the
+value of the FITS TFORMn keyword (e.g., 'I', 'J', 'E', 'D', etc. for
+binary tables, and 'I8', F12.3', 'E20.12', etc.  for ASCII tables).  If
+the datatype is not specified then a default datatype will be chosen
+depending on the expression.
+
+\item
+Create a new header keyword by giving the keyword name, preceded by a
+pound sign '\#', followed by an equals sign and an arithmetic
+expression for the value of the keyword.  The expression may be a
+function of other header keyword values.  The comment string for the
+keyword may be specified in parentheses immediately following the
+keyword name.
+
+\item
+Overwrite the values in an existing column or keyword by giving the
+name followed by an equals sign and an arithmetic expression.
+
+\item
+Select a set of columns to be included in the filtered file by listing
+the column names separated with semi-colons.   Wild card characters may
+be used in the column names to match multiple columns.  Any other
+columns in the input table will not appear in the filtered file.
+
+\item
+Delete a column or keyword by listing the name preceded by a minus sign
+or an exclamation mark (!)
+
+\item
+Rename an existing column or keyword with the syntax 'NewName ==
+OldName'.
+
+\end{itemize}
+
+The column filtering specifier is enclosed in square brackets and
+begins with the string 'col'.   Multiple operations can be performed
+by separating them with semi-colons.  For  complex  or commonly used
+operations,  you can write the column filter to a text file, and then
+use it by giving the name of the text file, preceded by a '@'
+character.
+
+Some examples:
+
+\begin{verbatim}
+  [col PI=PHA * 1.1 + 0.2]      - creates new PI column from PHA values
+
+  [col rate = counts/exposure]  - creates or overwrites the rate column by
+                                  dividing the counts column by the
+                                  EXPOSURE keyword value.
+
+  [col TIME; X; Y]              - only the listed columns will appear
+                                  in the filtered file
+
+  [col Time;*raw]               - include the Time column and any other
+                                  columns whose name ends with 'raw'.
+
+  [col -TIME; Good == STATUS]   - deletes the TIME column and
+                                  renames the STATUS column to GOOD
+
+  [col @colfilt.txt]            - uses the filtering expression in
+                                  the colfilt.txt text file
+\end{verbatim}
+
+The original file is not changed by this filtering operation, and
+instead the modifications are made on a temporary copy of the input
+FITS file (usually in memory), which includes a copy of all the other
+HDUs in the input file.   The original input file is closed and the
+application program opens the filtered copy of the file.
+
+\subsubsection{Row Filtering}
+
+The row filter is used to select a subset of the rows from a table
+based on a boolean expression.  A temporary new FITS file is created on
+the fly (usually in memory) which contains only those rows for which
+the row filter expression evaluates to true (i.e., not equal to zero).
+The primary array and any other extensions in the input file are also
+copied to the temporary file.  The original FITS file is closed and the
+new temporary file is then opened by the application program.
+
+The row filter expression is enclosed in square brackets following the
+file name and extension name.  For example, {\tt
+'file.fits[events][GRADE==50]'}  selects only those rows in the EVENTS
+table where the GRADE column value is equal to 50).
+
+The row filtering  expression can be an arbitrarily  complex series of
+operations performed  on constants,  keyword values,  and column data
+taken from the specified FITS TABLE extension.  The expression 
+also can be written into a text file and then used by giving the
+filename preceded by a '@' character, as in
+{\tt '[@rowfilt.txt]'}.
+
+Keyword and column data  are referenced by   name.  Any  string of
+characters not surrounded by    quotes (ie, a constant  string)   or
+followed by   an open parentheses (ie,   a  function name)   will be
+initially interpreted   as a column  name and  its contents for the
+current row inserted into the expression.  If no such column exists,
+a keyword of that  name will be searched for  and its value used, if
+found.  To force the  name to be  interpreted as a keyword (in case
+there is both a column and keyword with the  same name), precede the
+keyword name with a single pound sign, '\#', as in {\tt \#NAXIS2}.  Due to
+the generalities of FITS column and  keyword names, if the column or
+keyword name  contains a space or a  character which might appear as
+an arithmetic  term then inclose  the  name in '\$'  characters as in
+{\tt \$MAX PHA\$} or {\tt \#\$MAX-PHA\$}.  The names are case insensitive.
+
+To access a table entry in a row other  than the current one, follow
+the  column's name  with  a row  offset  within  curly  braces.  For
+example, {\tt'PHA\{-3\}'} will evaluate to the value  of column PHA, 3 rows
+above  the  row currently  being processed.   One  cannot specify an
+absolute row number, only a relative offset.  Rows that fall outside
+the table will be treated as undefined, or NULLs.
+
+Boolean   operators can be  used in  the expression  in either their
+Fortran or C forms.  The following boolean operators are available:
+
+\begin{verbatim}
+    "equal"         .eq. .EQ. ==  "not equal"          .ne.  .NE.  !=
+    "less than"     .lt. .LT. <   "less than/equal"    .le.  .LE.  <= =<
+    "greater than"  .gt. .GT. >   "greater than/equal" .ge.  .GE.  >= =>
+    "or"            .or. .OR. ||  "and"                .and. .AND. &&
+    "negation"     .not. .NOT. !  "approx. equal(1e-7)"  ~
+\end{verbatim}
+
+Note  that the exclamation point,  '!', is a special UNIX character, so
+if it is used  on the command line rather than entered at a task
+prompt, it must be  preceded by a backslash to force the UNIX shell to
+ignore it.
+
+The expression may  also include arithmetic operators and functions.
+Trigonometric  functions use  radians,  not degrees.  The  following
+arithmetic  operators and  functions  can be  used in the expression
+(function names are case insensitive):
+
+ 
+\begin{verbatim}
+    "addition"           +          "subtraction"          -
+    "multiplication"     *          "division"             /
+    "negation"           -          "exponentiation"       **   ^
+    "absolute value"     abs(x)     "cosine"               cos(x)
+    "sine"               sin(x)     "tangent"              tan(x)
+    "arc cosine"         arccos(x)  "arc sine"             arcsin(x)
+    "arc tangent"        arctan(x)  "arc tangent"          arctan2(x,y)
+    "exponential"        exp(x)     "square root"          sqrt(x)
+    "natural log"        log(x)     "common log"           log10(x)
+    "modulus"            i % j      "random # [0.0,1.0)"   random()
+    "minimum"            min(x,y)   "maximum"              max(x,y)
+    "if-then-else"       b?x:y
+\end{verbatim}
+
+
+The  following  type  casting  operators  are  available,  where the
+inclosing parentheses are required and taken  from  the  C  language
+usage. Also, the integer to real casts values to double precision:
+
+\begin{verbatim}
+                "real to integer"    (int) x     (INT) x
+                "integer to real"    (float) i   (FLOAT) i
+\end{verbatim}
+
+
+Several constants are built in  for  use  in  numerical
+expressions:
+
+ 
+\begin{verbatim}
+        #pi              3.1415...      #e             2.7182...
+        #deg             #pi/180        #row           current row number
+        #null         undefined value   #snull         undefined string
+\end{verbatim}
+
+A  string constant must  be enclosed  in quotes  as in  'Crab'.  The
+"null" constants  are useful for conditionally  setting table values to
+a NULL, or undefined, value (For example,  {\tt "col1==-99 ? \#NULL :
+col1"}).
+
+There is also a function for testing if  two  values  are  close  to
+each  other,  i.e.,  if  they are "near" each other to within a user
+specified tolerance. The  arguments,  {\tt value\_1}  and  {\tt value\_2}  can  be
+integer  or  real  and  represent  the two values who's proximity is
+being tested to be within the specified tolerance, also  an  integer
+or real:
+
+\begin{verbatim}
+                    near(value_1, value_2, tolerance)
+\end{verbatim}
+
+When  a  NULL, or undefined, value is encountered in the FITS table,
+the expression will evaluate to NULL unless the undefined  value  is
+not   actually   required  for  evaluation,  e.g. "TRUE  .or.  NULL"
+evaluates to TRUE. The  following  two  functions  allow  some  NULL
+detection  and  handling:  
+
+\begin{verbatim}
+                   ISNULL(x)
+                   DEFNULL(x,y)
+\end{verbatim}
+
+The former returns a boolean value of TRUE if the  argument  x  is
+NULL.   The later  "defines"  a  value  to  be  substituted  for NULL
+values; it returns the value of x if x is not NULL, otherwise  it
+returns  the value of y.
+
+Bit  masks can be used to select out rows from bit columns ({\tt TFORMn =
+\#X}) in FITS files. To represent the mask,  binary,  octal,  and  hex
+formats are allowed:
+ 
+\begin{verbatim}
+                 binary:   b0110xx1010000101xxxx0001
+                 octal:    o720x1 -> (b111010000xxx001)
+                 hex:      h0FxD  -> (b00001111xxxx1101)
+\end{verbatim}
+
+In  all  the  representations, an x or X is allowed in the mask as a
+wild card. Note that the x represents a  different  number  of  wild
+card  bits  in  each  representation.  All  representations are case
+insensitive.
+
+To construct the boolean expression using the mask  as  the  boolean
+equal  operator  described above on a bit table column. For example,
+if you had a 7 bit column named flags in a  FITS  table  and  wanted
+all  rows  having  the bit pattern 0010011, the selection expression
+would be:
+
+ 
+\begin{verbatim}
+                            flags == b0010011
+    or
+                            flags .eq. b10011
+\end{verbatim}
+
+It is also possible to test if a range of bits is  less  than,  less
+than  equal,  greater  than  and  greater than equal to a particular
+boolean value:
+
+ 
+\begin{verbatim}
+                            flags <= bxxx010xx
+                            flags .gt. bxxx100xx
+                            flags .le. b1xxxxxxx
+\end{verbatim}
+
+Notice the use of the x bit value to limit the range of  bits  being
+compared.
+
+It  is  not necessary to specify the leading (most significant) zero
+(0) bits in the mask, as shown in the second expression above.
+
+Bit wise AND, OR and NOT operations are  also  possible  on  two  or
+more  bit  fields  using  the  '\&'(AND),  '$|$'(OR),  and the '!'(NOT)
+operators. All of these operators result in a bit  field  which  can
+then be used with the equal operator. For example:
+
+ 
+\begin{verbatim}
+                          (!flags) == b1101100
+                          (flags & b1000001) == bx000001
+\end{verbatim}
+
+Bit  fields can be appended as well using the '+' operator.  Strings
+can be concatenated this way, too.
+
+\subsubsection{Good Time Interval Filtering}
+
+    A common filtering method involves selecting rows which have a time
+    value which lies within what is called a Good Time Interval or GTI.
+    The time intervals are defined in a separate FITS table extension
+    which contains 2 columns giving the start and stop time of each
+    good interval.  The filtering operation accepts only those rows of
+    the input table which have an associated time which falls within
+    one of the time intervals defined in the GTI extension. A high
+    level function, gtifilter(a,b,c,d), is available which evaluates
+    each row of the input table  and returns TRUE  or FALSE depending
+    whether the row is inside or outside the  good time interval.  The
+    syntax is
+ 
+\begin{verbatim}
+      gtifilter( [ "gtifile" [, expr [, "STARTCOL", "STOPCOL" ] ] ] )
+\end{verbatim}
+    where  each "[]" demarks optional parameters.  Note that  the quotes
+    around the gtifile and START/STOP column are required.  Either single
+    or double quote characters may be used.  The gtifile,
+    if specified,  can be blank  ("") which will  mean to use  the first
+    extension  with   the name "*GTI*"  in   the current  file,  a plain
+    extension  specifier (eg, "+2",  "[2]", or "[STDGTI]") which will be
+    used  to  select  an extension  in  the current  file, or  a regular
+    filename with or without an extension  specifier which in the latter
+    case  will mean to  use the first  extension  with an extension name
+    "*GTI*".  Expr can be   any arithmetic expression, including  simply
+    the time  column  name.  A  vector  time expression  will  produce a
+    vector boolean  result.  STARTCOL and  STOPCOL are the  names of the
+    START/STOP   columns in the    GTI extension.  If   one  of them  is
+    specified, they both  must be.
+
+    In  its  simplest form, no parameters need to be provided -- default
+    values will be used.  The expression {\tt "gtifilter()"} is equivalent to
+ 
+\begin{verbatim}
+       gtifilter( "", TIME, "*START*", "*STOP*" )
+\end{verbatim}
+    This will search the current file for a GTI  extension,  filter  the
+    TIME  column in the current table, using START/STOP times taken from
+    columns in the GTI  extension  with  names  containing  the  strings
+    "START"  and "STOP".  The wildcards ('*') allow slight variations in
+    naming conventions  such  as  "TSTART"  or  "STARTTIME".   The  same
+    default  values  apply for unspecified parameters when the first one
+    or  two  parameters  are  specified.   The  function   automatically
+    searches   for   TIMEZERO/I/F   keywords  in  the  current  and  GTI
+    extensions, applying a relative time offset, if necessary.
+
+\subsubsection{Spatial Region Filtering}
+
+    Another common  filtering method selects rows based on whether the
+    spatial position associated with each row is located within a given
+    2-dimensional region.  The syntax for this high-level filter is
+ 
+\begin{verbatim}
+       regfilter( "regfilename" [ , Xexpr, Yexpr [ , "wcs cols" ] ] )
+\end{verbatim}
+    where each "[ ]" demarks optional parameters. The region file name
+    is required and must be  enclosed in quotes.  The remaining
+    parameters are optional.  The region file is an ASCII text file
+    which contains a list of one or more geometric shapes (circle,
+    ellipse, box, etc.) which defines a region on the celestial sphere
+    or an area within a particular 2D image.  The region file is
+    typically generated using an image display program such as fv/POW
+    (distribute by the HEASARC), or ds9 (distributed by the Smithsonian
+    Astrophysical Observatory).  Users should refer to the documentation
+    provided with these programs for more details on the syntax used in
+    the region files.
+
+    In its simpliest form, (e.g., {\tt regfilter("region.reg")} ) the
+    coordinates in the default 'X' and 'Y' columns will be used to
+    determine if each row is inside or outside the area specified in
+    the region file.  Alternate position column names, or expressions,
+    may be entered if needed, as in
+ 
+\begin{verbatim}
+        regfilter("region.reg", XPOS, YPOS)
+\end{verbatim}
+    Region filtering can be applied most unambiguously if the positions
+    in the region file and in the table to be filtered are both give in
+    terms of absolute celestial coordinate units.  In this case the
+    locations and sizes of the geometric shapes in the region file are
+    specified in angular units on the sky (e.g., positions given in
+    R.A. and Dec.  and sizes in arcseconds or arcminutes).  Similarly,
+    each row of the filtered table will have a celestial coordinate
+    associated with it.  This association is usually implemented using
+    a set of so-called 'World Coordinate System' (or WCS) FITS keywords
+    that define the coordinate transformation that must be applied to
+    the values in the 'X' and 'Y' columns to calculate the coordinate.
+
+    Alternatively, one can perform spatial filtering using unitless
+    'pixel' coordinates for the regions and row positions.  In this
+    case the user must be careful to ensure that the positions in the 2
+    files are self-consistent.  A typical problem is that the region
+    file may be generated using a binned image, but the unbinned
+    coordinates are given in the event table.  The ROSAT events files,
+    for example, have X and Y pixel coordinates that range from 1 -
+    15360.  These coordinates are typically binned by a factor of 32 to
+    produce a 480x480 pixel image.  If one then uses a region file
+    generated from this image (in image pixel units) to filter the
+    ROSAT events file, then the X and Y column values must be converted
+    to corresponding pixel units as in:
+ 
+\begin{verbatim}
+        regfilter("rosat.reg", X/32.+.5, Y/32.+.5)
+\end{verbatim}
+    Note that this binning conversion is not necessary if the region
+    file is specified using celestial coordinate units instead of pixel
+    units because CFITSIO is then able to directly compare the
+    celestial coordinate of each row in the table with the celestial
+    coordinates in the region file without having to know anything
+    about how the image may have been binned.
+
+    The last "wcs cols" parameter should rarely be needed. If supplied,
+    this  string contains the names of the 2 columns (space or comma
+    separated) which have the associated WCS keywords. If not supplied,
+    the filter  will scan the X  and Y expressions for column names.
+    If only one is found in each  expression, those columns will be
+    used, otherwise an error will be returned.
+
+    These region shapes are supported (names are case insensitive):
+ 
+\begin{verbatim}
+       Point         ( X1, Y1 )               <- One pixel square region
+       Line          ( X1, Y1, X2, Y2 )       <- One pixel wide region
+       Polygon       ( X1, Y1, X2, Y2, ... )  <- Rest are interiors with
+       Rectangle     ( X1, Y1, X2, Y2, A )       | boundaries considered
+       Box           ( Xc, Yc, Wdth, Hght, A )   V within the region
+       Diamond       ( Xc, Yc, Wdth, Hght, A )
+       Circle        ( Xc, Yc, R )
+       Annulus       ( Xc, Yc, Rin, Rout )
+       Ellipse       ( Xc, Yc, Rx, Ry, A )
+       Elliptannulus ( Xc, Yc, Rinx, Riny, Routx, Routy, Ain, Aout )
+       Sector        ( Xc, Yc, Amin, Amax )
+\end{verbatim}
+    where (Xc,Yc) is  the coordinate of  the shape's center; (X\#,Y\#) are
+    the coordinates  of the shape's edges;  Rxxx are the shapes' various
+    Radii or semimajor/minor  axes; and Axxx  are the angles of rotation
+    (or bounding angles for Sector) in degrees.  For rotated shapes, the
+    rotation angle  can  be left  off, indicating  no rotation.   Common
+    alternate  names for the regions  can also be  used: rotbox = box;
+    rotrectangle = rectangle;  (rot)rhombus = (rot)diamond;  and pie
+    = sector.  When a  shape's name is  preceded by a minus sign, '-',
+    the defined region  is instead the area  *outside* its boundary (ie,
+    the region is inverted).  All the shapes within a single region
+    file are OR'd together to create the region, and the order is
+    significant. The overall way of looking at region files is that if
+    the first region is an excluded region then a dummy included region
+    of the whole detector is inserted in the front. Then each region
+    specification as it is processed overrides any selections inside of
+    that region specified by previous regions. Another way of thinking
+    about this is that if a previous excluded region is completely
+    inside of a subsequent included region the excluded region is
+    ignored.
+
+    The positional coordinates may be given either in pixel units,
+    decimal degrees or hh:mm:ss.s, dd:mm:ss.s units.  The shape sizes
+    may be given in pixels, degrees, arcminutes, or arcseconds.  Look
+    at examples of region file produced by fv/POW or ds9 for further
+    details of the region file format.
+
+\subsubsection{Example Row Filters}
+ 
+\begin{verbatim}
+    [double && mag <= 5.0]        -  Extract all double stars brighter
+                                     than  fifth magnitude 
+
+    [#row >= 125 && #row <= 175]   - Extract row numbers 125 through 175
+
+    [abs(sin(theta * #deg)) < 0.5] - Extract all rows having the
+                                     absolute value of the sine of theta
+                                     less  than a half where the angles
+                                     are tabulated in degrees
+
+    [@rowFilter.txt]               - Extract rows using the expression
+                                     contained within the text file
+                                     rowFilter.txt
+
+    [gtifilter()]                  - Search the current file for a GTI
+				     extension,  filter  the TIME
+				     column in the current table, using
+				     START/STOP times taken from
+				     columns in the GTI  extension
+
+    [regfilter("pow.reg")]         - Extract rows which have a coordinate
+                                     (as given in the X and Y columns)
+                                     within the spatial region specified
+                                     in the pow.reg region file.
+\end{verbatim}
+
+\newpage
+\subsection{Combined Filtering Examples}
+
+The previous sections described all the individual types of filters
+that may be applied to the input file.  In this section we show
+examples which combine several different filters at once.  These
+examples all use the {\tt fitscopy} program that is distributed with
+the CFITSIO code.  It simply copies the input file to the output file.
+
+\begin{verbatim}
+fitscopy rosat.fit out.fit
+\end{verbatim}
+
+This trivial example simply makes an identical copy of the input
+rosat.fit file without any filtering.
+
+\begin{verbatim}
+fitscopy 'rosat.fit[events][col Time;X;Y][#row < 1000]' out.fit
+\end{verbatim}
+
+The output file contains only the Time, X, and Y columns, and only
+the first 999 rows from the 'EVENTS' table extension of the input file.
+All the other HDUs in the input file are copied to the output file
+without any modification.
+
+\begin{verbatim}
+fitscopy 'rosat.fit[events][PI < 50][bin (Xdet,Ydet) = 16]' image.fit
+\end{verbatim}
+
+This creates an output image by binning the Xdet and Ydet columns of
+the events table with a pixel binning factor of 16.  Only the rows
+which have a PI energy less than 50 are used to construct this image.
+The output image file contains a primary array image without any
+extensions.
+
+\begin{verbatim}
+fitscopy 'rosat.fit[events][gtifilter() && regfilter("pow.reg")]' out.fit
+\end{verbatim}
+
+The filtering expression in this example uses the {\tt gtifilter}
+function to test whether the TIME column value in each row is within
+one of the Good Time Intervals defined in the GTI extension in the same
+input file, and also uses the {\tt regfilter} function to test if the
+position associated with each row (derived by default from the values
+in the X and Y columns of the events table) is located within the area
+defined in the {\tt pow.reg} text region file (which was previously
+created with the {\tt fv/POW} image display program).  Only the rows
+which satisfy both tests are copied to the output table.
+
+\begin{verbatim}
+fitscopy 'r.fit[evt][PI<50]' stdout | fitscopy stdin[evt][col X,Y] out.fit
+\end{verbatim}
+
+In this somewhat convoluted example, fitscopy is used to first select
+the rows from the evt extension which have PI less than 50 and write the
+resulting table out to the stdout stream.  This is piped to a 2nd
+instance of fitscopy (with the Unix `$|$' pipe command) which reads that
+filtered FITS file from the stdin stream and copies only the X and Y
+columns from the evt table to the output file.
+
+\begin{verbatim}
+fitscopy 'r.fit[evt][col RAD=sqrt((X-#XCEN)**2+(Y-#YCEN)**2)][rad<100]' out.fit
+\end{verbatim}
+
+This example first creates a new column called RAD which gives the
+distance between the X,Y coordinate of each event and the coordinate
+defined by the XCEN and YCEN keywords in the header.  Then, only those
+rows which have a distance less than 100 are copied to the output
+table.  In other words, only the events which are located within 100
+pixel units from the (XCEN, YCEN) coordinate are copied to the output
+table.
+
+\begin{verbatim}
+fitscopy 'ftp://heasarc.gsfc.nasa.gov/rosat.fit[events][bin (X,Y)=16]' img.fit
+\end{verbatim}
+
+This example bins the X and Y columns of the hypothetical ROSAT file 
+at the HEASARC ftp site to create the output image.
+
+\begin{verbatim}
+fitscopy 'raw.fit[i512,512][101:110,51:60]' image.fit
+\end{verbatim}
+
+This example converts the 512 x 512 pixel raw binary 16-bit integer
+image to a FITS file and copies a 10 x 10 pixel subimage from it to the
+output FITS image.
+
+\newpage
+\section{CFITSIO Error Status Codes}
+
+The following table lists all the error status codes used by CFITSIO.
+Programmers are encouraged to use the symbolic mnemonics (defined in
+the file fitsio.h) rather than the actual integer status values to
+improve the readability of their code.
+
+\begin{verbatim}
+ Symbolic Const    Value     Meaning
+ --------------    -----  -----------------------------------------
+                     0    OK, no error
+ SAME_FILE         101    input and output files are the same
+ TOO_MANY_FILES    103    tried to open too many FITS files at once
+ FILE_NOT_OPENED   104    could not open the named file
+ FILE_NOT_CREATED  105    could not create the named file
+ WRITE_ERROR       106    error writing to FITS file
+ END_OF_FILE       107    tried to move past end of file
+ READ_ERROR        108    error reading from FITS file
+ FILE_NOT_CLOSED   110    could not close the file
+ ARRAY_TOO_BIG     111    array dimensions exceed internal limit
+ READONLY_FILE     112    Cannot write to readonly file
+ MEMORY_ALLOCATION 113    Could not allocate memory
+ BAD_FILEPTR       114    invalid fitsfile pointer
+ NULL_INPUT_PTR    115    NULL input pointer to routine 
+ SEEK_ERROR        116    error seeking position in file 
+
+ BAD_URL_PREFIX     121   invalid URL prefix on file name 
+ TOO_MANY_DRIVERS   122   tried to register too many IO drivers 
+ DRIVER_INIT_FAILED 123   driver initialization failed 
+ NO_MATCHING_DRIVER 124   matching driver is not registered 
+ URL_PARSE_ERROR    125   failed to parse input file URL
+
+ SHARED_BADARG     151    bad argument in shared memory driver
+ SHARED_NULPTR     152    null pointer passed as an argument
+ SHARED_TABFULL    153    no more free shared memory handles
+ SHARED_NOTINIT    154    shared memory driver is not initialized
+ SHARED_IPCERR     155    IPC error returned by a system call
+ SHARED_NOMEM      156    no memory in shared memory driver
+ SHARED_AGAIN      157    resource deadlock would occur
+ SHARED_NOFILE     158    attempt to open/create lock file failed
+ SHARED_NORESIZE   159    shared memory block cannot be resized at the moment
+
+ HEADER_NOT_EMPTY  201    header already contains keywords
+ KEY_NO_EXIST      202    keyword not found in header
+ KEY_OUT_BOUNDS    203    keyword record number is out of bounds
+ VALUE_UNDEFINED   204    keyword value field is blank 
+ NO_QUOTE          205    string is missing the closing quote
+ BAD_KEYCHAR       207    illegal character in keyword name or card
+ BAD_ORDER         208    required keywords out of order
+ NOT_POS_INT       209    keyword value is not a positive integer
+ NO_END            210    couldn't find END keyword
+ BAD_BITPIX        211    illegal BITPIX keyword value
+ BAD_NAXIS         212    illegal NAXIS keyword value
+ BAD_NAXES         213    illegal NAXISn keyword value
+ BAD_PCOUNT        214    illegal PCOUNT keyword value
+ BAD_GCOUNT        215    illegal GCOUNT keyword value
+ BAD_TFIELDS       216    illegal TFIELDS keyword value
+ NEG_WIDTH         217    negative table row size
+ NEG_ROWS          218    negative number of rows in table
+ COL_NOT_FOUND     219    column with this name not found in table
+ BAD_SIMPLE        220    illegal value of SIMPLE keyword
+ NO_SIMPLE         221    Primary array doesn't start with SIMPLE
+ NO_BITPIX         222    Second keyword not BITPIX
+ NO_NAXIS          223    Third keyword not NAXIS
+ NO_NAXES          224    Couldn't find all the NAXISn keywords
+ NO_XTENSION       225    HDU doesn't start with XTENSION keyword
+ NOT_ATABLE        226    the CHDU is not an ASCII table extension
+ NOT_BTABLE        227    the CHDU is not a binary table extension
+ NO_PCOUNT         228    couldn't find PCOUNT keyword
+ NO_GCOUNT         229    couldn't find GCOUNT keyword
+ NO_TFIELDS        230    couldn't find TFIELDS keyword
+ NO_TBCOL          231    couldn't find TBCOLn keyword
+ NO_TFORM          232    couldn't find TFORMn keyword
+ NOT_IMAGE         233    the CHDU is not an IMAGE extension
+ BAD_TBCOL         234    TBCOLn keyword value < 0 or > rowlength
+ NOT_TABLE         235    the CHDU is not a table
+ COL_TOO_WIDE      236    column is too wide to fit in table
+ COL_NOT_UNIQUE    237    more than 1 column name matches template
+ BAD_ROW_WIDTH     241    sum of column widths not = NAXIS1
+ UNKNOWN_EXT       251    unrecognizable FITS extension type
+ UNKNOWN_REC       252    unknown record; 1st keyword not SIMPLE or XTENSION
+ END_JUNK          253    END keyword is not blank
+ BAD_HEADER_FILL   254    Header fill area contains non-blank chars
+ BAD_DATA_FILL     255    Illegal data fill bytes (not zero or blank)
+ BAD_TFORM         261    illegal TFORM format code
+ BAD_TFORM_DTYPE   262    unrecognizable TFORM datatype code
+ BAD_TDIM          263    illegal TDIMn keyword value
+ BAD_HEAP_PTR      264    invalid BINTABLE heap pointer is out of range
+
+ BAD_HDU_NUM       301    HDU number < 1 or > MAXHDU
+ BAD_COL_NUM       302    column number < 1 or > tfields
+ NEG_FILE_POS      304    tried to move to negative byte location in file
+ NEG_BYTES         306    tried to read or write negative number of bytes
+ BAD_ROW_NUM       307    illegal starting row number in table
+ BAD_ELEM_NUM      308    illegal starting element number in vector
+ NOT_ASCII_COL     309    this is not an ASCII string column
+ NOT_LOGICAL_COL   310    this is not a logical datatype column
+ BAD_ATABLE_FORMAT 311    ASCII table column has wrong format
+ BAD_BTABLE_FORMAT 312    Binary table column has wrong format
+ NO_NULL           314    null value has not been defined
+ NOT_VARI_LEN      317    this is not a variable length column
+ BAD_DIMEN         320    illegal number of dimensions in array
+ BAD_PIX_NUM       321    first pixel number greater than last pixel
+ ZERO_SCALE        322    illegal BSCALE or TSCALn keyword = 0
+ NEG_AXIS          323    illegal axis length < 1
+
+ NOT_GROUP_TABLE       340   Grouping function error
+ HDU_ALREADY_MEMBER    341
+ MEMBER_NOT_FOUND      342
+ GROUP_NOT_FOUND       343
+ BAD_GROUP_ID          344
+ TOO_MANY_HDUS_TRACKED 345
+ HDU_ALREADY_TRACKED   346
+ BAD_OPTION            347
+ IDENTICAL_POINTERS    348
+ BAD_GROUP_ATTACH      349
+ BAD_GROUP_DETACH      350
+
+ NGP_NO_MEMORY         360     malloc failed
+ NGP_READ_ERR          361     read error from file
+ NGP_NUL_PTR           362     null pointer passed as an argument.
+                                 Passing null pointer as a name of
+                                 template file raises this error
+ NGP_EMPTY_CURLINE     363     line read seems to be empty (used
+                                 internally)
+ NGP_UNREAD_QUEUE_FULL 364     cannot unread more then 1 line (or single
+                                 line twice)
+ NGP_INC_NESTING       365     too deep include file nesting (infinite
+                                 loop, template includes itself ?)
+ NGP_ERR_FOPEN         366     fopen() failed, cannot open template file
+ NGP_EOF               367     end of file encountered and not expected
+ NGP_BAD_ARG           368     bad arguments passed. Usually means
+                                 internal parser error. Should not happen
+ NGP_TOKEN_NOT_EXPECT  369     token not expected here
+
+ BAD_I2C           401    bad int to formatted string conversion
+ BAD_F2C           402    bad float to formatted string conversion
+ BAD_INTKEY        403    can't interpret keyword value as integer
+ BAD_LOGICALKEY    404    can't interpret keyword value as logical
+ BAD_FLOATKEY      405    can't interpret keyword value as float
+ BAD_DOUBLEKEY     406    can't interpret keyword value as double
+ BAD_C2I           407    bad formatted string to int conversion
+ BAD_C2F           408    bad formatted string to float conversion
+ BAD_C2D           409    bad formatted string to double conversion
+ BAD_DATATYPE      410    illegal datatype code value
+ BAD_DECIM         411    bad number of decimal places specified
+ NUM_OVERFLOW      412    overflow during datatype conversion
+ DATA_COMPRESSION_ERR   413  error compressing image 
+ DATA_DECOMPRESSION_ERR 414  error uncompressing image 
+
+ BAD_DATE          420    error in date or time conversion 
+
+ PARSE_SYNTAX_ERR  431    syntax error in parser expression 
+ PARSE_BAD_TYPE    432    expression did not evaluate to desired type 
+ PARSE_LRG_VECTOR  433    vector result too large to return in array 
+ PARSE_NO_OUTPUT   434    data parser failed not sent an out column 
+ PARSE_BAD_COL     435    bad data encounter while parsing column 
+ PARSE_BAD_OUTPUT  436    Output file not of proper type          
+
+ ANGLE_TOO_BIG     501    celestial angle too large for projection 
+ BAD_WCS_VAL       502    bad celestial coordinate or pixel value 
+ WCS_ERROR         503    error in celestial coordinate calculation  
+ BAD_WCS_PROJ      504    unsupported type of celestial projection 
+ NO_WCS_KEY        505    celestial coordinate keywords not found
+ APPROX_WCS_KEY    506    approximate wcs keyword values were returned
+\end{verbatim}
+
+\end{document}