"Fossies" - the Fresh Open Source Software Archive

Member "cfitsio-4.0.0/docs/fitsio.tex" (20 May 2021, 349330 Bytes) of package /linux/misc/cfitsio-4.0.0.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) TeX and LaTeX source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 \documentclass[11pt]{book}
    2 \input{html.sty}
    3 \htmladdtonavigation
    4    {\begin{rawhtml}
    5  <A HREF="http://heasarc.gsfc.nasa.gov/docs/software/fitsio/fitsio.html">FITSIO Home</A>
    6     \end{rawhtml}}
    7 %\oddsidemargin=0.25in
    8 \oddsidemargin=0.00in
    9 \evensidemargin=0.00in
   10 \textwidth=6.5in
   11 %\topmargin=0.0in
   12 \textheight=8.75in
   13 \parindent=0cm
   14 \parskip=0.2cm
   15 \begin{document}
   16 \pagenumbering{roman}
   17 
   18 \begin{titlepage}
   19 \normalsize
   20 \vspace*{4.6cm}
   21 \begin{center}
   22 {\Huge \bf FITSIO User's Guide}\\
   23 \end{center}
   24 \medskip 
   25 \medskip
   26 \begin{center}
   27 {\LARGE \bf A Subroutine Interface to FITS Format Files}\\
   28 \end{center}
   29 \begin{center}
   30 {\LARGE \bf for Fortran Programmers}\\
   31 \end{center}
   32 \medskip
   33 \medskip
   34 \begin{center}
   35 {\Large Version 4.0\\}
   36 \end{center}
   37 \bigskip
   38 \vskip 2.5cm
   39 \begin{center}
   40 {HEASARC\\
   41 Code 662\\
   42 Goddard Space Flight Center\\
   43 Greenbelt, MD 20771\\
   44 USA}
   45 \end{center}
   46 
   47 \vfill
   48 \bigskip
   49 \begin{center}
   50 {\Large May 2021\\}
   51 \end{center}
   52 \vfill
   53 \end{titlepage}
   54 
   55 \clearpage
   56 
   57 \tableofcontents
   58 
   59 \chapter{Introduction }
   60 \pagenumbering{arabic}
   61 
   62 This document describes the Fortran-callable subroutine interface that
   63 is provided as part of the CFITSIO library (which is written in ANSI
   64 C).  This is a companion document to the CFITSIO User's Guide which
   65 should be consulted for further information about the underlying
   66 CFITSIO library.  In the remainder of this document, the terms FITSIO
   67 and CFITSIO are interchangeable and refer to the same library.
   68 
   69 FITSIO/CFITSIO is a machine-independent library of routines for reading
   70 and writing data files in the FITS (Flexible Image Transport System)
   71 data format.  It can also read IRAF format image files and raw binary
   72 data arrays by converting them on the fly into a virtual FITS format
   73 file.  This library was written to provide a powerful yet simple
   74 interface for accessing FITS files which will run on most commonly used
   75 computers and workstations. FITSIO supports all the features described
   76 in the official definition of the FITS format and can read and
   77 write all the currently defined types of extensions, including ASCII
   78 tables (TABLE), Binary tables (BINTABLE) and IMAGE extensions. The
   79 FITSIO subroutines insulate the programmer from having to deal with the
   80 complicated formatting details in the FITS file, however, it is assumed
   81 that users have a general knowledge about the structure and usage of
   82 FITS files.
   83 
   84 The CFITSIO package was initially developed by the HEASARC (High Energy
   85 Astrophysics Science Archive Research Center) at the NASA Goddard Space
   86 Flight Center to convert various existing and newly acquired
   87 astronomical data sets into FITS format and to further analyze data
   88 already in FITS format.  New features continue to be added to CFITSIO
   89 in large part due to contributions of ideas or actual code from users
   90 of the package.  The Integral Science Data Center in Switzerland, and
   91 the XMM/ESTEC project in The Netherlands made especially significant
   92 contributions that resulted in many of the new features that appeared
   93 in v2.0 of CFITSIO.
   94 
   95 The latest version of the CFITSIO source code, documentation, and
   96 example programs are available on the World-Wide Web or via anonymous
   97 ftp from:
   98 
   99 \begin{verbatim}
  100         http://heasarc.gsfc.nasa.gov/fitsio
  101         ftp://legacy.gsfc.nasa.gov/software/fitsio/c
  102 \end{verbatim}
  103 \newpage
  104 Any questions, bug reports, or suggested enhancements related to the CFITSIO
  105 package should be sent to the FTOOLS Help Desk at the HEASARC:
  106 
  107 \begin{verbatim}
  108         http://heasarc.gsfc.nasa.gov/cgi-bin/ftoolshelp
  109 \end{verbatim}
  110 
  111 This User's Guide assumes that readers already have a general
  112 understanding of the definition and structure of FITS format files.
  113 Further information about FITS formats is available from the FITS Support
  114 Office at {\tt http://fits.gsfc.nasa.gov}.  In particular, the
  115 'FITS Standard' gives the authoritative definition of the FITS data
  116 format.  Other documents available at that Web site
  117 provide additional historical background
  118 and practical advice on using FITS files.
  119 
  120 The HEASARC also provides a very sophisticated FITS file analysis
  121 program called `Fv' which can be used to display and edit the contents
  122 of any FITS file as well as construct new FITS files from scratch.
  123 Fv is freely available for
  124 most Unix platforms, Mac PCs, and Windows PCs.
  125 CFITSIO users may also be interested in the FTOOLS package of programs
  126 that can be used to manipulate and analyze FITS format files.
  127 Fv and FTOOLS are available from their respective Web sites at:
  128 
  129 \begin{verbatim}
  130         http://fv.gsfc.nasa.gov
  131         http://heasarc.gsfc.nasa.gov/ftools
  132 \end{verbatim}
  133 
  134 
  135 \chapter{ Creating FITSIO/CFITSIO }
  136 
  137 
  138 \section{Building the Library}
  139 
  140 To use the FITSIO subroutines one must first build the CFITSIO library,
  141 which requires a C compiler. gcc is ideal, or most other ANSI-C
  142 compilers will also work.  The CFITSIO code is contained in about 40 C
  143 source files (*.c) and header files (*.h). On VAX/VMS systems 2
  144 assembly-code files (vmsieeed.mar and vmsieeer.mar) are also needed.
  145 
  146 The Fortran interface subroutines to the C CFITSIO routines are located
  147 in the f77\_wrap1.c, through f77\_wrap4.c files.  These are relatively simple
  148 'wrappers' that translate the arguments in the Fortran subroutine into
  149 the appropriate format for the corresponding C routine.  This
  150 translation is performed transparently to the user by a set of C macros
  151 located in the cfortran.h file.  Unfortunately cfortran.h does not
  152 support every combination of C and Fortran compilers so the Fortran
  153 interface is not supported on all platforms. (see further notes below).
  154 
  155 A standard combination of C and Fortran compilers will be assumed by
  156 default, but one may also specify a particular Fortran compiler by
  157 doing:
  158 
  159 \begin{verbatim}
  160  >  setenv CFLAGS -DcompilerName=1
  161 \end{verbatim}
  162 (where 'compilerName' is the name of the compiler) before running
  163 the configure command.  The currently recognized compiler
  164 names are:
  165 
  166 \begin{verbatim}
  167  g77Fortran
  168  IBMR2Fortran
  169  CLIPPERFortran
  170  pgiFortran
  171  NAGf90Fortran
  172  f2cFortran
  173  hpuxFortran
  174  apolloFortran
  175  sunFortran
  176  CRAYFortran
  177  mipsFortran
  178  DECFortran
  179  vmsFortran
  180  CONVEXFortran
  181  PowerStationFortran
  182  AbsoftUNIXFortran
  183  AbsoftProFortran
  184  SXFortran
  185 \end{verbatim}
  186 Alternatively, one may edit the CFLAGS line in the Makefile to add the
  187 '-DcompilerName' flag after running the './configure' command.
  188 
  189 The CFITSIO library is built on Unix systems by typing:
  190 
  191 \begin{verbatim}
  192  >  ./configure [--prefix=/target/installation/path]
  193                 [--enable-sse2] [--enable-ssse3]
  194  >  make          (or  'make shared')
  195  >  make install  (this step is optional)
  196 \end{verbatim}
  197 at the operating system prompt.  The configure command customizes the
  198 Makefile for the particular system, then the `make' command compiles the
  199 source files and builds the library.  Type `./configure' and not simply
  200 `configure' to ensure that the configure script in the current directory
  201 is run and not some other system-wide configure script.  The optional
  202 'prefix' argument to configure gives the path to the directory where
  203 the CFITSIO library and include files should be installed via the later
  204 'make install' command. For example,
  205 
  206 \begin{verbatim}
  207    > ./configure --prefix=/usr1/local
  208 \end{verbatim}
  209 will cause the 'make install' command to copy the CFITSIO libcfitsio file
  210 to /usr1/local/lib and the necessary include files to /usr1/local/include
  211 (assuming of course that the  process has permission to write to these
  212 directories).
  213 
  214 The optional --enable-sse2 and --enable-ssse3 flags will cause configure to
  215 attempt to build CFITSIO using faster byte-swapping algorithms.
  216 See the "Optimizing Programs" section of this manual for
  217 more information about these options.
  218 
  219 By default, the Makefile will be configured to build the set of Fortran-callable
  220 wrapper routines whose calling sequences are described later in this
  221 document.
  222 
  223 The 'make shared' option builds a shared or dynamic version of the
  224 CFITSIO library.  When using the shared library the executable code is
  225 not copied into your program at link time and instead the program
  226 locates the necessary library code at run time, normally through
  227 LD\_LIBRARY\_PATH or some other method. The advantages of using a shared
  228 library are:
  229 
  230 \begin{verbatim}
  231    1.  Less disk space if you build more than 1 program
  232    2.  Less memory if more than one copy of a program using the shared
  233        library is running at the same time since the system is smart
  234        enough to share copies of the shared library at run time.
  235    3.  Possibly easier maintenance since a new version of the shared
  236        library can be installed without relinking all the software
  237        that uses it (as long as the subroutine names and calling
  238        sequences remain unchanged).
  239    4.  No run-time penalty.
  240 \end{verbatim}
  241 The disadvantages are:
  242 
  243 \begin{verbatim}
  244    1. More hassle at runtime.  You have to either build the programs
  245       specially or have LD_LIBRARY_PATH set right.
  246    2. There may be a slight start up penalty, depending on where you are
  247       reading the shared library and the program from and if your CPU is
  248       either really slow or really heavily loaded.
  249 \end{verbatim}
  250 
  251 On HP/UX systems, the environment variable CFLAGS should be set
  252 to -Ae before running configure to enable "extended ANSI" features.
  253 
  254 It may not be possible to statically link programs that use CFITSIO on
  255 some platforms (namely, on Solaris 2.6) due to the network drivers
  256 (which provide FTP and HTTP access to FITS files).  It is possible to
  257 make both a dynamic and a static version of the CFITSIO library, but
  258 network file access will not be possible using the static version.
  259 
  260 On VAX/VMS and ALPHA/VMS systems the make\_gfloat.com command file may
  261 be executed to build the cfitsio.olb object library using the default
  262 G-floating point option for double variables.  The make\_dfloat.com and
  263 make\_ieee.com files may be used instead to build the library with the
  264 other floating point options. Note that the getcwd function that is
  265 used in the group.c module may require that programs using CFITSIO be
  266 linked with the ALPHA\$LIBRARY:VAXCRTL.OLB library.  See the example
  267 link line in the next section of this document.
  268 
  269 On Windows IBM-PC type platforms the situation is more complicated
  270 because of the wide variety of Fortran compilers that are available and
  271 because of the inherent complexities of calling the CFITSIO C routines
  272 from Fortran.  Two different versions of the CFITSIO dll library are
  273 available, compiled with the Borland C++ compiler and the Microsoft
  274 Visual C++ compiler, respectively, in the files
  275 cfitsiodll\_2xxx\_borland.zip and cfitsiodll\_3xxx\_vcc.zip, where
  276 '3xxx' represents the current release number.  Both these dll libraries
  277 contain a set of Fortran wrapper routines which may be compatible with
  278 some, but probably not all, available Fortran compilers.  To test if
  279 they are compatible, compile the program testf77.f and try linking to
  280 these dll libraries.  If these libraries do not work with a particular
  281 Fortran compiler, then it may be necessary to modify the file
  282 "cfortran.h" to support that particular
  283 combination of C and Fortran compilers, and then rebuild the CFITSIO
  284 dll library.  This will require, however, some expertise in
  285 mixed language programming.
  286 
  287 CFITSIO should be compatible with most current ANCI C and C++ compilers:
  288 Cray supercomputers are currently not supported.
  289 
  290 
  291 \section{Testing the Library}
  292 
  293 The CFITSIO library should be tested by building and running
  294 the testprog.c program that is included with the release.
  295 On Unix systems type:
  296 
  297 \begin{verbatim}
  298     % make testprog
  299     % testprog > testprog.lis
  300     % diff testprog.lis testprog.out
  301     % cmp testprog.fit testprog.std
  302 \end{verbatim}
  303  On VMS systems,
  304 (assuming cc is the name of the C compiler command), type:
  305 
  306 \begin{verbatim}
  307     $ cc testprog.c
  308     $ link testprog, cfitsio/lib, alpha$library:vaxcrtl/lib
  309     $ run testprog
  310 \end{verbatim}
  311 The testprog program should produce a FITS file called `testprog.fit'
  312 that is identical to the `testprog.std' FITS file included with this
  313 release.  The diagnostic messages (which were piped to the file
  314 testprog.lis in the Unix example) should be identical to the listing
  315 contained in the file testprog.out.  The 'diff' and 'cmp' commands
  316 shown above should not report any differences in the files.  (There
  317 may be some minor formatting differences, such as the presence or
  318 absence of leading zeros, or 3 digit exponents in numbers,
  319 which can be ignored).
  320 
  321 The Fortran wrappers in CFITSIO may be tested with the testf77
  322 program.  On Unix systems the fortran compilation and link command
  323 may be called 'f77' or 'g77', depending on the system.
  324 
  325 \begin{verbatim}
  326    % f77 -o testf77 testf77.f -L. -lcfitsio -lnsl -lsocket
  327  or
  328    % f77 -f -o testf77 testf77.f -L. -lcfitsio    (under SUN O/S)
  329  or
  330    % f77 -o testf77 testf77.f -Wl,-L. -lcfitsio -lm -lnsl -lsocket (HP/UX)
  331  or
  332    % g77 -o testf77 -s testf77.f -lcfitsio -lcc_dynamic -lncurses (Mac OS-X)
  333 
  334    % testf77 > testf77.lis
  335    % diff testf77.lis testf77.out
  336    % cmp testf77.fit testf77.std
  337 \end{verbatim}
  338 On machines running SUN O/S, Fortran programs must be compiled with the
  339 '-f' option to force double precision variables to be aligned on 8-byte
  340 boundaries to make the fortran-declared variables compatible with C.  A
  341 similar compiler option may be required on other platforms.  Failing to
  342 use this option may cause the program to crash on FITSIO routines that
  343 read or write double precision variables.
  344 
  345 On Windows platforms, linking Fortran programs with a C library
  346 often depends on the particular compilers involved.  Some users have
  347 found the following commands work when using the Intel Fortran compiler:
  348 
  349 \begin{verbatim}
  350 ifort /libs.dll cfitsio.lib /MD testf77.f /Gm
  351 
  352 or possibly,
  353 
  354 ifort /libs:dll cfitsio.lib /MD /fpp /extfpp:cfortran.h,fitsio.h
  355     /iface:cvf testf77.f
  356 \end{verbatim}
  357 Also note that on some systems the output listing of the testf77
  358 program may differ slightly from the testf77.std template if leading
  359 zeros are not printed by default before the decimal point when using F
  360 format.
  361 
  362 A few other utility  programs are included with CFITSIO:
  363 
  364 \begin{verbatim}
  365     speed - measures the maximum throughput (in MB per second)
  366               for writing and reading FITS files with CFITSIO
  367 
  368     listhead - lists all the header keywords in any FITS file
  369 
  370     fitscopy - copies any FITS file (especially useful in conjunction
  371                  with the CFITSIO's extended input filename syntax)
  372 
  373     cookbook - a sample program that performs common read and
  374                  write operations on a FITS file.
  375 
  376     iter_a, iter_b, iter_c - examples of the CFITSIO iterator routine
  377 \end{verbatim}
  378 
  379 The first 4 of these utility programs can be compiled and linked by typing
  380 
  381 \begin{verbatim}
  382    %  make program_name
  383 \end{verbatim}
  384 
  385 
  386 \section{Linking Programs with FITSIO}
  387 
  388 When linking applications software with the FITSIO library, several system libraries usually need to be specified on the link comman
  389 Unix systems, the most reliable way to determine what libraries are required
  390 is to type 'make testprog' and see what libraries the configure script has
  391 added.  The typical libraries that may need to be added are -lm (the math
  392 library) and -lnsl and -lsocket (needed only for FTP and HTTP file access).
  393 These latter 2 libraries are not needed on VMS and Windows platforms,
  394 because FTP file access is not currently supported on those platforms.
  395 
  396 Note that when upgrading to a newer version of CFITSIO it is usually
  397 necessary to recompile, as well as relink, the programs that use CFITSIO,
  398 because the definitions in fitsio.h often change.
  399 
  400 
  401 \section{Getting Started with FITSIO}
  402 
  403 In order to effectively use the FITSIO library as quickly as possible,
  404 it is recommended that new users follow these steps:
  405 
  406 1.  Read the following `FITS Primer' chapter for a brief
  407 overview of the structure of FITS files.  This is especially important
  408 for users who have not previously dealt with the FITS table and image
  409 extensions.
  410 
  411 2.  Write a simple program to read or write a FITS file using the Basic
  412 Interface routines.
  413 
  414 3.  Refer to the cookbook.f program that is included with this release
  415 for examples of routines that perform various common FITS file
  416 operations.
  417 
  418 4. Read Chapters 4 and 5 to become familiar with the conventions and
  419 advanced features of the FITSIO interface.
  420 
  421 5.  Scan through the more extensive set of routines that are provided
  422 in the `Advanced Interface'.  These routines perform more specialized
  423 functions than are provided by the Basic Interface routines.
  424 
  425 
  426 \section{Example Program}
  427 
  428 The following listing shows an example of how to use the FITSIO
  429 routines in a Fortran program.  Refer to the cookbook.f program that
  430 is included with the FITSIO distribution for examples of other
  431 FITS programs.
  432 
  433 \begin{verbatim}
  434       program writeimage
  435 
  436 C     Create a FITS primary array containing a 2-D image
  437 
  438       integer status,unit,blocksize,bitpix,naxis,naxes(2)
  439       integer i,j,group,fpixel,nelements,array(300,200)
  440       character filename*80
  441       logical simple,extend
  442 
  443       status=0
  444 C     Name of the FITS file to be created:
  445       filename='ATESTFILE.FITS'
  446 
  447 C     Get an unused Logical Unit Number to use to create the FITS file
  448       call ftgiou(unit,status)
  449 
  450 C     create the new empty FITS file
  451       blocksize=1
  452       call ftinit(unit,filename,blocksize,status)
  453 
  454 C     initialize parameters about the FITS image (300 x 200 16-bit integers)
  455       simple=.true.
  456       bitpix=16
  457       naxis=2
  458       naxes(1)=300
  459       naxes(2)=200
  460       extend=.true.
  461 
  462 C     write the required header keywords
  463       call ftphpr(unit,simple,bitpix,naxis,naxes,0,1,extend,status)
  464 
  465 C     initialize the values in the image with a linear ramp function
  466       do j=1,naxes(2)
  467           do i=1,naxes(1)
  468               array(i,j)=i+j
  469           end do
  470       end do
  471 
  472 C     write the array to the FITS file
  473       group=1
  474       fpixel=1
  475       nelements=naxes(1)*naxes(2)
  476       call ftpprj(unit,group,fpixel,nelements,array,status)
  477 
  478 C     write another optional keyword to the header
  479       call ftpkyj(unit,'EXPOSURE',1500,'Total Exposure Time',status)
  480 
  481 C     close the file and free the unit number
  482       call ftclos(unit, status)
  483       call ftfiou(unit, status)
  484       end
  485 \end{verbatim}
  486 
  487 
  488 \section{Legal Stuff}
  489 
  490 Copyright (Unpublished--all rights reserved under the copyright laws of
  491 the United States), U.S. Government as represented by the Administrator
  492 of the National Aeronautics and Space Administration.  No copyright is
  493 claimed in the United States under Title 17, U.S. Code.
  494 
  495 Permission to freely use, copy, modify, and distribute this software
  496 and its documentation without fee is hereby granted, provided that this
  497 copyright notice and disclaimer of warranty appears in all copies.
  498 
  499 DISCLAIMER:
  500 
  501 THE SOFTWARE IS PROVIDED 'AS IS' WITHOUT ANY WARRANTY OF ANY KIND,
  502 EITHER EXPRESSED, IMPLIED, OR STATUTORY, INCLUDING, BUT NOT LIMITED TO,
  503 ANY WARRANTY THAT THE SOFTWARE WILL CONFORM TO SPECIFICATIONS, ANY
  504 IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
  505 PURPOSE, AND FREEDOM FROM INFRINGEMENT, AND ANY WARRANTY THAT THE
  506 DOCUMENTATION WILL CONFORM TO THE SOFTWARE, OR ANY WARRANTY THAT THE
  507 SOFTWARE WILL BE ERROR FREE.  IN NO EVENT SHALL NASA BE LIABLE FOR ANY
  508 DAMAGES, INCLUDING, BUT NOT LIMITED TO, DIRECT, INDIRECT, SPECIAL OR
  509 CONSEQUENTIAL DAMAGES, ARISING OUT OF, RESULTING FROM, OR IN ANY WAY
  510 CONNECTED WITH THIS SOFTWARE, WHETHER OR NOT BASED UPON WARRANTY,
  511 CONTRACT, TORT , OR OTHERWISE, WHETHER OR NOT INJURY WAS SUSTAINED BY
  512 PERSONS OR PROPERTY OR OTHERWISE, AND WHETHER OR NOT LOSS WAS SUSTAINED
  513 FROM, OR AROSE OUT OF THE RESULTS OF, OR USE OF, THE SOFTWARE OR
  514 SERVICES PROVIDED HEREUNDER."
  515 
  516 
  517 \section{Acknowledgments}
  518 
  519 The development of many of the powerful features in CFITSIO was made
  520 possible through collaborations with many people or organizations from
  521 around the world.  The following, in particular, have made especially
  522 significant contributions:
  523 
  524 Programmers from the Integral Science Data Center, Switzerland (namely,
  525 Jurek Borkowski, Bruce O'Neel, and Don Jennings), designed the concept
  526 for the plug-in I/O drivers that was introduced with CFITSIO 2.0.  The
  527 use of `drivers' greatly simplified  the low-level I/O, which in turn
  528 made other new features in CFITSIO (e.g., support for compressed FITS
  529 files and support for IRAF format image files) much easier to
  530 implement.  Jurek Borkowski wrote the Shared Memory driver, and Bruce
  531 O'Neel wrote the drivers for accessing FITS files over the network
  532 using the FTP, HTTP, and ROOT protocols.
  533 
  534 The ISDC also provided the template parsing routines (written by Jurek
  535 Borkowski) and the hierarchical grouping routines (written by Don
  536 Jennings).  The ISDC DAL (Data Access Layer) routines are layered on
  537 top of CFITSIO and make extensive use of these features.
  538 
  539 Uwe Lammers (XMM/ESA/ESTEC, The Netherlands) designed the
  540 high-performance lexical parsing algorithm that is used to do
  541 on-the-fly filtering of FITS tables.  This algorithm essentially
  542 pre-compiles the user-supplied selection expression into a form that
  543 can be rapidly evaluated for each row.  Peter Wilson (RSTX, NASA/GSFC)
  544 then wrote the parsing routines used by CFITSIO based on Lammers'
  545 design, combined with other techniques such as the CFITSIO iterator
  546 routine to further enhance the data processing throughput.  This effort
  547 also benefited from a much earlier lexical parsing routine that was
  548 developed by Kent Blackburn (NASA/GSFC). More recently, Craig Markwardt
  549 (NASA/GSFC) implemented additional functions (median, average, stddev)
  550 and other enhancements to the lexical parser.
  551 
  552 The CFITSIO iterator function is loosely based on similar ideas
  553 developed for the XMM Data Access Layer.
  554 
  555 Peter Wilson (RSTX, NASA/GSFC) wrote the complete set of
  556 Fortran-callable wrappers for all the CFITSIO routines, which in turn
  557 rely on the CFORTRAN macro developed by Burkhard Burow.
  558 
  559 The syntax used by CFITSIO for filtering or binning input FITS files is
  560 based on ideas developed for the AXAF Science Center Data Model by
  561 Jonathan McDowell, Antonella Fruscione, Aneta Siemiginowska and Bill
  562 Joye. See http://heasarc.gsfc.nasa.gov/docs/journal/axaf7.html for
  563 further description of the AXAF Data Model.
  564 
  565 The file decompression code were taken directly from the gzip (GNU zip)
  566 program developed by Jean-loup Gailly and others.
  567 
  568 Doug Mink, SAO, provided the routines for converting IRAF format
  569 images into FITS format.
  570 
  571 Martin Reinecke (Max Planck Institute, Garching)) provided the modifications to
  572 cfortran.h that are necessary to support 64-bit integer values when calling
  573 C routines from fortran programs.  The cfortran.h macros were originally developed
  574 by Burkhard Burow (CERN).
  575 
  576 Julian Taylor (ESO, Garching) provided the fast byte-swapping algorithms
  577 that use the SSE2 and SSSE3 machine instructions available on x86\_64 CPUs.
  578 
  579 In addition, many other people have made valuable contributions to the
  580 development of CFITSIO.  These include (with apologies to others that may
  581 have inadvertently been omitted):
  582 
  583 Steve Allen, Carl Akerlof, Keith Arnaud, Morten Krabbe Barfoed, Kent
  584 Blackburn, G Bodammer, Romke Bontekoe, Lucio Chiappetti, Keith Costorf,
  585 Robin Corbet, John Davis,  Richard Fink, Ning Gan, Emily Greene, Joe
  586 Harrington, Cheng Ho, Phil Hodge, Jim Ingham, Yoshitaka Ishisaki, Diab
  587 Jerius, Mark Levine, Todd Karakaskian, Edward King, Scott Koch,  Claire
  588 Larkin, Rob Managan, Eric Mandel, John Mattox, Carsten Meyer, Emi
  589 Miyata, Stefan Mochnacki, Mike Noble, Oliver Oberdorf, Clive Page,
  590 Arvind Parmar, Jeff Pedelty, Tim Pearson, Maren Purves, Scott Randall,
  591 Chris Rogers, Arnold Rots, Barry Schlesinger, Robin Stebbins, Andrew
  592 Szymkowiak, Allyn Tennant, Peter Teuben, James Theiler, Doug Tody,
  593 Shiro Ueno, Steve Walton, Archie Warnock, Alan Watson, Dan Whipple, Wim
  594 Wimmers, Peter Young, Jianjun Xu, and Nelson Zarate.
  595 
  596 
  597 \chapter{  A FITS Primer }
  598 
  599 This section gives a brief overview of the structure of FITS files.
  600 Users should refer to the documentation available from the FITS Support Office, as
  601 described in the introduction, for more detailed information on FITS
  602 formats.
  603 
  604 FITS was first developed in the late 1970's as a standard data
  605 interchange format between various astronomical observatories.  Since
  606 then FITS has become the defacto standard data format supported by most
  607 astronomical data analysis software packages.
  608 
  609 A FITS file consists of one or more Header + Data Units (HDUs), where
  610 the first HDU is called the `Primary HDU', or `Primary Array'.  The
  611 primary array contains an N-dimensional array of pixels, such as a 1-D
  612 spectrum, a 2-D image, or a 3-D data cube.  Six different primary
  613 datatypes are supported: Unsigned 8-bit bytes, 16, 32, and 64-bit signed
  614 integers, and 32 and 64-bit floating point reals.  FITS also has a
  615 convention for storing unsigned integers (see the later
  616 section entitled `Unsigned Integers' for more details). The primary HDU
  617 may also consist of only a header with a null array containing no
  618 data pixels.
  619 
  620 Any number of additional HDUs may follow the primary array; these
  621 additional HDUs are called FITS `extensions'.  There are currently 3
  622 types of extensions defined by the FITS standard:
  623 
  624 \begin{itemize}
  625 \item
  626   Image Extension - a N-dimensional array of pixels, like in a primary array
  627 \item
  628   ASCII Table Extension - rows and columns of data in ASCII character format
  629 \item
  630   Binary Table Extension - rows and columns of data in binary representation
  631 \end{itemize}
  632 
  633 In each case the HDU consists of an ASCII Header Unit followed by an optional
  634 Data Unit.  For historical reasons, each Header or Data unit must be an
  635 exact multiple of 2880 8-bit bytes long.  Any unused space is padded
  636 with fill characters (ASCII blanks or zeros).
  637 
  638 Each Header Unit consists of any number of 80-character keyword records
  639 or `card images' which have the general form:
  640 
  641 \begin{verbatim}
  642   KEYNAME = value / comment string
  643   NULLKEY =       / comment: This keyword has no value
  644 \end{verbatim}
  645 The keyword names may be up to 8 characters long and can only contain
  646 uppercase letters, the digits 0-9, the hyphen, and the underscore
  647 character. The keyword name is (usually) followed by an equals sign and
  648 a space character (= ) in columns 9 - 10 of the record, followed by the
  649 value of the keyword which may be either an integer, a floating point
  650 number, a character string (enclosed in single quotes), or a boolean
  651 value (the letter T or F).   A keyword may also have a null or undefined
  652 value if there is no specified value string, as in the second example.
  653 
  654 The last keyword in the header is always the `END' keyword which has no
  655 value or comment fields. There are many rules governing the exact
  656 format of a keyword record (see the FITS Standard) so it is better
  657 to rely on standard interface software like FITSIO to correctly
  658 construct or to parse the keyword records rather than try to deal
  659 directly with the raw FITS formats.
  660 
  661 Each Header Unit begins with a series of required keywords which depend
  662 on the type of HDU.  These required keywords specify the size and
  663 format of the following Data Unit.  The header may contain other
  664 optional keywords to describe other aspects of the data, such as the
  665 units or scaling values.  Other COMMENT or HISTORY keywords are also
  666 frequently added to further document the data file.
  667 
  668 The optional Data Unit immediately follows the last 2880-byte block in
  669 the Header Unit.  Some HDUs do not have a Data Unit and only consist of
  670 the Header Unit.
  671 
  672 If there is more than one HDU in the FITS file, then the Header Unit of
  673 the next HDU immediately follows the last 2880-byte block of the
  674 previous Data Unit (or Header Unit if there is no Data Unit).
  675 
  676 The main required keywords in FITS primary arrays or image extensions are:
  677 \begin{itemize}
  678 \item
  679 BITPIX -- defines the datatype of the array: 8, 16, 32, 64, -32, -64 for
  680 unsigned 8--bit byte, 16--bit signed integer, 32--bit signed integer,
  681 64--bit signed integer,
  682 32--bit IEEE floating point, and 64--bit IEEE double precision floating
  683 point, respectively.
  684 \item
  685 NAXIS --  the number of dimensions in the array, usually 0, 1, 2, 3, or 4.
  686 \item
  687 NAXISn -- (n ranges from 1 to NAXIS) defines the size of each dimension.
  688 \end{itemize}
  689 
  690 FITS tables start with the keyword XTENSION = `TABLE' (for ASCII
  691 tables) or XTENSION = `BINTABLE' (for binary tables) and have the
  692 following main keywords:
  693 \begin{itemize}
  694 \item
  695 TFIELDS -- number of fields or columns in the table
  696 \item
  697 NAXIS2 -- number of rows in the table
  698 \item
  699 TTYPEn -- for each column (n ranges from 1 to TFIELDS) gives the
  700 name of the column
  701 \item
  702 TFORMn -- the datatype of the column
  703 \item
  704 TUNITn -- the physical units of the column (optional)
  705 \end{itemize}
  706 
  707 Users should refer to the FITS Support Office at {\tt http://fits.gsfc.nasa.gov}
  708 for further information about the FITS format and related software
  709 packages.
  710 
  711 
  712 
  713 \chapter{FITSIO Conventions and Guidelines }
  714 
  715 
  716 \section{CFITSIO Size Limitations}
  717 
  718 CFITSIO places few restrictions on the size of FITS files that it
  719 reads or writes.  There are a few limits, however, which may affect
  720 some extreme cases:
  721 
  722 1.  The maximum number of FITS files that may be simultaneously opened by
  723 CFITSIO is set by NMAXFILES, as defined in fitsio2.h.  The current default
  724 value is 1000, but this may be increased if necessary. Note that CFITSIO
  725 allocates NIOBUF * 2880 bytes of I/O buffer space for each file that is
  726 opened.  The default value of NIOBUF is 40 (defined in fitsio.h), so this
  727 amounts to  more than 115K of memory  for each opened file (or 115 MB for
  728 1000 opened files).  Note that the underlying  operating system, may have a
  729 lower limit on the number of files that can be opened simultaneously.
  730 
  731 2.  By default, CFITSIO can handle FITS files up to 2.1 GB in size (2**31
  732 bytes).  This file size limit is often imposed by 32-bit operating
  733 systems.  More recently, as 64-bit operating systems become more common, an
  734 industry-wide standard (at least on Unix systems) has been developed to
  735 support larger sized files (see http://ftp.sas.com/standards/large.file/).
  736 Starting with version 2.1 of CFITSIO, larger FITS files up to 6 terabytes
  737 in size may be read and written on supported platforms.  In order
  738 to support these larger files, CFITSIO must be compiled with the
  739 '-D\_LARGEFILE\_SOURCE' and `-D\_FILE\_OFFSET\_BITS=64' compiler flags.
  740 Some platforms may also require the `-D\_LARGE\_FILES' compiler flag.
  741  This causes the compiler to allocate 8-bytes instead of
  742 4-bytes for the `off\_t' datatype which is used to store file offset
  743 positions.  It appears that in most cases it is not necessary to
  744 also include these compiler flags when compiling programs that link to
  745 the CFITSIO library.
  746 
  747 If CFITSIO is compiled with the -D\_LARGEFILE\_SOURCE
  748 and -D\_FILE\_OFFSET\_BITS=64 flags on a
  749 platform that supports large files, then it can read and write FITS
  750 files that contain up to 2**31 2880-byte FITS records, or approximately
  751 6 terabytes in size.  It is still required that the value of the NAXISn
  752 and PCOUNT keywords in each extension be within the range of a signed
  753 4-byte integer (max value = 2,147,483,648).  Thus, each dimension of an
  754 image (given by the NAXISn keywords), the total width of a table
  755 (NAXIS1 keyword), the number of rows in a table (NAXIS2 keyword), and
  756 the total size of the variable-length array heap in binary tables
  757 (PCOUNT keyword) must be less than this limit.
  758 
  759 Currently, support for large files within CFITSIO has been tested
  760 on the Linux, Solaris, and IBM AIX operating systems.
  761 
  762 
  763 \section{Multiple Access to the Same FITS File}
  764 
  765 CFITSIO supports simultaneous read and write access to multiple HDUs in
  766 the same FITS file.  Thus, one can open the same FITS file twice within
  767 a single program and move to 2 different HDUs in the file, and then
  768 read and write data or keywords to the 2 extensions just as if one were
  769 accessing 2 completely separate FITS files.   Since in general it is
  770 not possible to physically open the same file twice and then expect to
  771 be able to simultaneously (or in alternating succession) write to 2
  772 different locations in the file, CFITSIO recognizes when the file to be
  773 opened (in the call to fits\_open\_file) has already been opened and
  774 instead of actually opening the file again, just logically links the
  775 new file to the old file.  (This only applies if the file is opened
  776 more than once within the same program, and does not prevent the same
  777 file from being simultaneously opened by more than one program).  Then
  778 before CFITSIO reads or writes to either (logical) file, it makes sure
  779 that any modifications made to the other file have been completely
  780 flushed from the internal buffers to the file.  Thus, in principle, one
  781 could open a file twice, in one case pointing to the first extension
  782 and in the other pointing to the 2nd extension and then write data to
  783 both extensions, in any order, without danger of corrupting the file,
  784 There may be some efficiency penalties in doing this however, since
  785 CFITSIO has to flush all the internal buffers related to one file
  786 before switching to the  other, so it would still be prudent to
  787 minimize the number of times one switches back and forth between doing
  788 I/O to different HDUs in the same file.
  789 
  790 
  791 \section{Current Header Data Unit (CHDU)}
  792 
  793 In general, a FITS file can contain multiple Header Data Units, also
  794 called extensions.  CFITSIO only operates within one HDU at any given
  795 time, and the currently selected HDU is called the Current Header Data
  796 Unit (CHDU).  When a FITS file is first created or opened the CHDU is
  797 automatically defined to be the first HDU (i.e., the primary array).
  798 CFITSIO routines are provided to move to and open any other existing
  799 HDU within the FITS file or to append or insert a new HDU in the FITS
  800 file which then becomes the CHDU.
  801 
  802 
  803 \section{Subroutine Names}
  804 
  805 All FITSIO subroutine names begin with the letters 'ft' to distinguish
  806 them from other subroutines and are 5 or 6 characters long. Users should
  807 not name their own subroutines beginning with 'ft' to avoid conflicts.
  808 (The SPP interface routines all begin with 'fs'). Subroutines which read
  809 or get information from the FITS file have names beginning with
  810 'ftg...'. Subroutines which write or put information into the FITS file
  811 have names beginning with 'ftp...'.
  812 
  813 
  814 \section{Subroutine Families and Datatypes}
  815 
  816 Many of the subroutines come in families which differ only in the
  817 datatype of the associated parameter(s) .  The datatype of these
  818 subroutines is indicated by the last letter of the subroutine name
  819 (e.g., 'j' in 'ftpkyj') as follows:
  820 
  821 \begin{verbatim}
  822         x - bit
  823         b - character*1 (unsigned byte)
  824         i - short integer (I*2)
  825         j - integer (I*4, 32-bit integer)
  826         k - long long integer (I*8, 64-bit integer)
  827         e - real exponential floating point (R*4)
  828         f - real fixed-format floating point (R*4)
  829         d - double precision real floating-point (R*8)
  830         g - double precision fixed-format floating point (R*8)
  831         c - complex reals (pairs of R*4 values)
  832         m - double precision complex (pairs of R*8 values)
  833         l - logical (L*4)
  834         s - character string
  835 \end{verbatim}
  836 
  837 When dealing with the FITS byte datatype, it is important to remember
  838 that the raw values (before any scaling by the BSCALE and BZERO, or
  839 TSCALn and TZEROn keyword values) in byte arrays (BITPIX = 8) or byte
  840 columns (TFORMn = 'B') are interpreted as unsigned bytes with values
  841 ranging from 0 to 255. Some Fortran compilers support a non-standard
  842 byte datatype such as INTEGER*1, LOGICAL*1, or BYTE, which can sometimes
  843 be used instead of CHARACTER*1 variables. Many machines permit passing a
  844 numeric datatype (such as INTEGER*1) to the FITSIO subroutines which are
  845 expecting a CHARACTER*1 datatype, but this technically violates the
  846 Fortran-77 standard and is not supported on all machines (e.g., on a VAX/VMS
  847 machine one must use the VAX-specific \%DESCR function).
  848 
  849 One feature of the CFITSIO routines is that they can operate on a `X'
  850 (bit) column in a binary table as though it were a `B' (byte) column.
  851 For example a `11X' datatype column can be interpreted the same as a
  852 `2B' column (i.e., 2 unsigned 8-bit bytes).  In some instances, it can
  853 be more efficient to read and write whole bytes at a time, rather than
  854 reading or writing each individual bit.
  855 
  856 The double precision complex datatype is not a standard Fortran-77
  857 datatype.  If a particular Fortran compiler does not directly support
  858 this datatype,  then one may instead pass an array of pairs of double
  859 precision values to these subroutines.  The first  value in each pair
  860 is the real part, and the second is the imaginary part.
  861 
  862 
  863 \section{Implicit Data Type Conversion}
  864 
  865 The FITSIO routines that read and write numerical data can perform
  866 implicit data type conversion.  This means that the data type of the
  867 variable or array in the program does not need to be the same as the
  868 data type of the value in the FITS file.  Data type conversion is
  869 supported for numerical and string data types (if the string contains a
  870 valid number enclosed in quotes) when reading a FITS header keyword
  871 value and for numeric values when reading or writing values in the
  872 primary array or a table column.  CFITSIO returns status =
  873 NUM\_OVERFLOW  if the converted data value exceeds the range of the
  874 output data type.  Implicit data type conversion is not supported
  875 within binary tables for string, logical, complex, or double complex
  876 data types.
  877 
  878 In addition, any table column may be read as if it contained string values.
  879 In the case of numeric columns the returned string will be formatted
  880 using the TDISPn display format if it exists.
  881 
  882 
  883 \section{Data Scaling}
  884 
  885 When reading numerical data values in the primary array or a
  886 table column, the values will be scaled automatically by the BSCALE and
  887 BZERO (or TSCALn and TZEROn) header keyword values if they are
  888 present in the header.  The scaled data that is returned to the reading
  889 program will have
  890 
  891 \begin{verbatim}
  892         output value = (FITS value) * BSCALE + BZERO
  893 \end{verbatim}
  894 (a corresponding formula using TSCALn and TZEROn is used when reading
  895 from table columns).  In the case of integer output values the floating
  896 point scaled value is truncated to an integer (not rounded to the
  897 nearest integer).  The ftpscl and fttscl subroutines may be used to
  898 override the scaling parameters defined in the header (e.g., to turn
  899 off the scaling so that the program can read the raw unscaled values
  900 from the FITS file).
  901 
  902 When writing numerical data to the primary array or to a table
  903 column the data values will generally be automatically inversely scaled
  904 by the value of the BSCALE and BZERO (or TSCALn and TZEROn) header
  905 keyword values if they they exist in the header.  These keywords must
  906 have been written to the header before any data is written for them to
  907 have any effect.  Otherwise, one may use the ftpscl and fttscl
  908 subroutines to define or override the scaling keywords in the header
  909 (e.g., to turn off the scaling so that the program can write the raw
  910 unscaled values into the FITS file). If scaling is performed, the
  911 inverse scaled output value that is written into the FITS file will
  912 have
  913 
  914 \begin{verbatim}
  915          FITS value = ((input value) - BZERO) / BSCALE
  916 \end{verbatim}
  917 (a corresponding formula using TSCALn and TZEROn is used when
  918 writing to table columns).  Rounding to the nearest integer, rather
  919 than truncation, is performed when writing integer datatypes to the
  920 FITS file.
  921 
  922 
  923 \section{Error Status Values and the Error Message Stack}
  924 
  925 The last parameter in nearly every FITSIO subroutine is the error
  926 status value which is both an input and an output parameter.  A
  927 returned positive value for this parameter indicates an error was
  928 detected.  A listing of all the FITSIO status code values is given at
  929 the end of this document.
  930 
  931 The FITSIO library uses an `inherited status' convention for the status
  932 parameter which means that if a subroutine is called with a positive
  933 input value of the status parameter, then the subroutine will exit
  934 immediately without changing the value of the status parameter.  Thus,
  935 if one passes the status value returned from each FITSIO routine as
  936 input to the next FITSIO subroutine, then whenever an error is detected
  937 all further FITSIO processing will cease.  This convention can simplify
  938 the error checking in application programs because it is not necessary
  939 to check the value of the status parameter after every single FITSIO
  940 subroutine call.  If a program contains a sequence of several FITSIO
  941 calls, one can just check the status value after the last call.  Since
  942 the returned status values are generally distinctive, it should be
  943 possible to determine which subroutine originally returned the error
  944 status.
  945 
  946 FITSIO also maintains an internal stack of error messages (80-character
  947 maximum length) which in many cases provide a more detailed explanation
  948 of the cause of the error than is provided by the error status number
  949 alone. It is recommended that the error message stack be printed out
  950 whenever a program detects a FITSIO error. To do this, call the FTGMSG
  951 routine repeatedly to get the successive messages on the stack. When the
  952 stack is empty FTGMSG will return a blank string. Note that this is a
  953 `First In -- First Out' stack, so the oldest error message is returned
  954 first by ftgmsg.
  955 
  956 
  957 \section{Variable-Length Array Facility in Binary Tables}
  958 
  959 FITSIO provides easy-to-use support for reading and writing data in
  960 variable length fields of a binary table. The variable length columns
  961 have TFORMn keyword values of the form `1Pt(len)' or `1Qt(len)' where `t' is the
  962 datatype code (e.g., I, J, E, D, etc.) and `len' is an integer
  963 specifying the maximum length of the vector in the table.  If the value
  964 of `len' is not specified when the table is created (e.g., if the TFORM
  965 keyword value is simply specified as '1PE' instead of '1PE(400) ), then
  966 FITSIO will automatically scan the table when it is closed to
  967 determine the maximum length of the vector and will append this value
  968 to the TFORMn value.
  969 
  970 The same routines which read and write data in an ordinary fixed length
  971 binary table extension are also used for variable length fields,
  972 however, the subroutine parameters take on a slightly different
  973 interpretation as described below.
  974 
  975 All the data in a variable length field is written into an area called
  976 the `heap' which follows the main fixed-length FITS binary table.  The
  977 size of the heap, in bytes, is specified with the PCOUNT keyword in the
  978 FITS header.  When creating a new binary table, the initial value of
  979 PCOUNT should usually be set to zero.  FITSIO will recompute the size
  980 of the heap as the data is written and will automatically update the
  981 PCOUNT keyword value when the table is closed.  When writing variable
  982 length data to a table, CFITSIO will automatically extend the size
  983 of the heap area if necessary, so that any following HDUs do not
  984 get overwritten.
  985 
  986 By default the heap data area starts immediately after the last row of
  987 the fixed-length table.  This default starting location may be
  988 overridden by the THEAP keyword, but this is not recommended.
  989 If additional rows of data are added to the table, CFITSIO will
  990 automatically shift the the heap down to make room for the new
  991 rows, but it is obviously be more efficient to initially
  992 create the table with the necessary number of blank rows, so that
  993 the heap does not needed to be constantly moved.
  994 
  995 When writing to a variable length field, the entire array of values for
  996 a given row of the table must be written with a single call to FTPCLx.
  997 The total length of the array is calculated from (NELEM+FELEM-1). One
  998 cannot append more elements to an existing field at a later time; any
  999 attempt to do so will simply overwrite all the data which was previously
 1000 written. Note also that the new data will be written to a new area of
 1001 the heap and the heap space used by the previous write cannot be
 1002 reclaimed. For this reason it is advised that each row of a variable
 1003 length field only be written once. An exception to this general rule
 1004 occurs when setting elements of an array as undefined. One must first
 1005 write a dummy value into the array with FTPCLx, and then call FTPCLU to
 1006 flag the desired elements as undefined. (Do not use the FTPCNx family
 1007 of routines with variable length fields). Note that the rows of a table,
 1008 whether fixed or variable length, do not have to be written
 1009 consecutively and may be written in any order.
 1010 
 1011 When writing to a variable length ASCII character field (e.g., TFORM =
 1012 '1PA') only a single character string written.  FTPCLS writes the whole
 1013 length of the input string (minus any trailing blank characters), thus
 1014 the NELEM and FELEM parameters are ignored.  If the input string is
 1015 completely blank then FITSIO will write one blank character to the FITS
 1016 file.  Similarly, FTGCVS and FTGCFS read the entire string (truncated
 1017 to the width of the character string argument in the subroutine call)
 1018 and also ignore the NELEM and FELEM parameters.
 1019 
 1020 The FTPDES subroutine is useful in situations where multiple rows of a
 1021 variable length column have the identical array of values.  One can
 1022 simply write the array once for the first row, and then use FTPDES to
 1023 write the same descriptor values into the other rows (use the FTGDES
 1024 routine to read the first descriptor value);  all the rows will then
 1025 point to the same storage location thus saving disk space.
 1026 
 1027 When reading from a variable length array field one can only read as
 1028 many elements as actually exist in that row of the table; reading does
 1029 not automatically continue with the next row of the table as occurs
 1030 when reading an ordinary fixed length table field.  Attempts to read
 1031 more than this will cause an error status to be returned.  One can
 1032 determine the number of elements in each row of a variable column with
 1033 the FTGDES subroutine.
 1034 
 1035 
 1036 \section{Support for IEEE Special Values}
 1037 
 1038 The ANSI/IEEE-754 floating-point number standard defines certain
 1039 special values that are used to represent such quantities as
 1040 Not-a-Number (NaN), denormalized, underflow, overflow, and infinity.
 1041 (See the Appendix in the  FITS standard or the FITS User's
 1042 Guide for a list of these values).  The FITSIO subroutines that read
 1043 floating point data in FITS files recognize these IEEE special values
 1044 and by default interpret the overflow and infinity values as being
 1045 equivalent to a NaN, and convert the underflow and denormalized values
 1046 into zeros.  In some cases programmers may want access to the raw IEEE
 1047 values, without any modification by FITSIO.  This can be done by
 1048 calling the FTGPVx or FTGCVx routines while specifying 0.0 as the value
 1049 of the NULLVAL parameter.  This will force FITSIO to simply pass the
 1050 IEEE values through to the application program, without any
 1051 modification.  This does not work for double precision values on
 1052 VAX/VMS machines, however, where there is no easy way to bypass the
 1053 default interpretation of the IEEE special values. This is also not
 1054 supported when reading floating-point images that have been compressed
 1055 with the FITS tiled image compression convention that is discussed in
 1056 section 5.6;  the pixels values in tile compressed images are
 1057 represented by scaled integers, and a reserved integer value
 1058 (not a NaN) is used to represent undefined pixels.
 1059 
 1060 
 1061 
 1062 \section{When the Final Size of the FITS HDU is Unknown}
 1063 
 1064 It is not required to know the total size of a FITS data array or table
 1065 before beginning to write the data to the FITS file.  In the case of
 1066 the primary array or an image extension, one should initially create
 1067 the array with the size of the highest dimension (largest NAXISn
 1068 keyword) set to a dummy value, such as 1.  Then after all the data have
 1069 been written and the true dimensions are known, then the NAXISn value
 1070 should be updated using the fits\_ update\_key routine before moving to
 1071 another extension or closing the FITS file.
 1072 
 1073 When writing to FITS tables, CFITSIO automatically keeps track of the
 1074 highest row number that is written to, and will increase the size of
 1075 the table if necessary.  CFITSIO will also automatically insert space
 1076 in the FITS file if necessary, to ensure that the data 'heap', if it
 1077 exists, and/or any additional HDUs that follow the table do not get
 1078 overwritten as new rows are written to the table.
 1079 
 1080 As a general rule it is best to specify the initial number of rows = 0
 1081 when the table is created, then let CFITSIO keep track of the number of
 1082 rows that are actually written.  The application program should not
 1083 manually update the number of rows in the table (as given by the NAXIS2
 1084 keyword) since CFITSIO does this automatically.  If a table is
 1085 initially created with more than zero rows, then this will usually be
 1086 considered as the minimum size of the table, even if fewer rows are
 1087 actually written to the table.  Thus, if a table is initially created
 1088 with NAXIS2 = 20, and CFITSIO only writes 10 rows of data before
 1089 closing the table, then NAXIS2 will remain equal to 20.  If however, 30
 1090 rows of data are written to this table, then NAXIS2 will be increased
 1091 from 20 to 30.  The one exception to this automatic updating of the
 1092 NAXIS2 keyword is if the application program directly modifies the
 1093 value of NAXIS2 (up or down) itself just before closing the table.  In this
 1094 case, CFITSIO does not update NAXIS2 again, since it assumes that the
 1095 application program must have had a good reason for changing the value
 1096 directly.  This is not recommended, however, and is only provided for
 1097 backward compatibility with software that initially creates a table
 1098 with a large number of rows, than decreases the NAXIS2 value to the
 1099 actual smaller value just before closing the table.
 1100 
 1101 
 1102 \section{Local FITS Conventions supported by FITSIO}
 1103 
 1104 CFITSIO supports several local FITS conventions which are not
 1105 defined in the official FITS standard and which are not
 1106 necessarily recognized or supported by other FITS software packages.
 1107 Programmers should be cautious about using these features, especially
 1108 if the FITS files that are produced are expected to be processed by
 1109 other software systems which do not use the CFITSIO interface.
 1110 
 1111 
 1112 \subsection{Support for Long String Keyword Values.}
 1113 
 1114 The length of a standard FITS string keyword is limited to 68
 1115 characters because it must fit entirely within a single FITS header
 1116 keyword record.  In some instances it is necessary to encode strings
 1117 longer than this limit, so FITSIO supports a local convention in which
 1118 the string value is continued over multiple keywords. This
 1119 continuation convention uses an ampersand character at the end of each
 1120 substring to indicate that it is continued on the next keyword, and the
 1121 continuation keywords all have the name CONTINUE without an equal sign
 1122 in column 9. The string value may be continued in this way over as many
 1123 additional CONTINUE keywords as is required.  The following lines
 1124 illustrate this continuation convention which is used in the value of
 1125 the STRKEY keyword:
 1126 
 1127 \begin{verbatim}
 1128 LONGSTRN= 'OGIP 1.0'           / The OGIP Long String Convention may be used.
 1129 STRKEY  = 'This is a very long string keyword&'  / Optional Comment
 1130 CONTINUE  ' value that is continued over 3 keywords in the &  '
 1131 CONTINUE  'FITS header.' / This is another optional comment.
 1132 \end{verbatim}
 1133 It is recommended that the LONGSTRN keyword, as shown
 1134 here, always be included in any HDU that uses this longstring
 1135 convention.  A subroutine called FTPLSW
 1136 has been provided in CFITSIO to write this keyword if it does not
 1137 already exist.
 1138 
 1139 This long string convention is supported by the following FITSIO
 1140 subroutines that deal with string-valued keywords:
 1141 
 1142 \begin{verbatim}
 1143       ftgkys - read a string keyword
 1144       ftpkls - write (append) a string keyword
 1145       ftikls - insert a string keyword
 1146       ftmkls - modify the value of an existing string keyword
 1147       ftukls - update an existing keyword, or write a new keyword
 1148       ftdkey - delete a keyword
 1149 \end{verbatim}
 1150 These routines will transparently read, write, or delete a long string
 1151 value in the FITS file, so programmers in general do not have to be
 1152 concerned about the details of the convention that is used to encode
 1153 the long string in the FITS header.  When reading a long string, one
 1154 must ensure that the character string parameter used in these
 1155 subroutine calls has been declared long enough to hold the entire
 1156 string, otherwise the returned string value will be truncated.
 1157 
 1158 Note that the more commonly used FITSIO subroutine to write string
 1159 valued keywords (FTPKYS) does NOT support this long string convention
 1160 and only supports strings up to 68 characters in length.  This has been
 1161 done deliberately to prevent programs from inadvertently writing
 1162 keywords using this non-standard convention without the explicit intent
 1163 of the programmer or user.   The FTPKLS subroutine must be called
 1164 instead to write long strings.  This routine can also be used to write
 1165 ordinary string values less than 68 characters in length.
 1166 
 1167 
 1168 \subsection{Arrays of Fixed-Length Strings in Binary Tables}
 1169 
 1170 CFITSIO supports 2 ways to specify that a character column in a binary
 1171 table contains an array of fixed-length strings.  The first way, which
 1172 is officially supported by the FITS Standard document, uses the TDIMn keyword.
 1173 For example, if TFORMn = '60A' and TDIMn = '(12,5)' then that
 1174 column will be interpreted as containing an array of 5 strings, each 12
 1175 characters long.
 1176 
 1177 FITSIO also supports a
 1178 local convention for the format of the TFORMn keyword value of the form
 1179 'rAw' where 'r' is an integer specifying the total width in characters
 1180 of the column, and 'w' is an integer specifying the (fixed) length of
 1181 an individual unit string within the vector.  For example, TFORM1 =
 1182 '120A10' would indicate that the binary table column is 120 characters
 1183 wide and consists of 12 10-character length strings.  This convention
 1184 is recognized by the FITSIO subroutines that read or write strings in
 1185 binary tables.   The Binary Table definition document specifies that
 1186 other optional characters may follow the datatype code in the TFORM
 1187 keyword, so this local convention is in compliance with the
 1188 FITS standard, although other FITS readers are not required to
 1189 recognize this convention.
 1190 
 1191 
 1192 \subsection{Keyword Units Strings}
 1193 
 1194 One deficiency of the current FITS Standard is that it does not define
 1195 a specific convention for recording the physical units of a keyword
 1196 value.  The TUNITn keyword can be used to specify the physical units of
 1197 the values in a table column, but there is no analogous convention for
 1198 keyword values.  The comment field of the keyword is often used for
 1199 this purpose, but the units are usually not specified in a well defined
 1200 format that FITS readers can easily recognize and extract.
 1201 
 1202 To solve this deficiency, FITSIO uses a local convention in which the
 1203 keyword units are enclosed in square brackets as the first token in the
 1204 keyword comment field; more specifically, the opening square bracket
 1205 immediately follows the slash '/' comment field delimiter and a single
 1206 space character.  The following examples illustrate keywords that use
 1207 this convention:
 1208 
 1209 
 1210 \begin{verbatim}
 1211 EXPOSURE=               1800.0 / [s] elapsed exposure time
 1212 V_HELIO =                16.23 / [km s**(-1)] heliocentric velocity
 1213 LAMBDA  =                5400. / [angstrom] central wavelength
 1214 FLUX    = 4.9033487787637465E-30 / [J/cm**2/s] average flux
 1215 \end{verbatim}
 1216 
 1217 In general, the units named in the IAU(1988) Style Guide are
 1218 recommended, with the main exception that the preferred unit for angle
 1219 is 'deg' for degrees.
 1220 
 1221 The FTPUNT and FTGUNT subroutines in FITSIO write and read,
 1222 respectively, the keyword unit strings in an existing keyword.
 1223 
 1224 
 1225 \subsection{HIERARCH Convention for Extended Keyword Names}
 1226 
 1227 CFITSIO supports the HIERARCH keyword convention which allows keyword
 1228 names that are longer than 8 characters.  This convention
 1229 was developed at the European Southern Observatory (ESO) and allows characters
 1230 consisting of digits 0-9, upper case letters A-Z, the dash '-' and the underscore '\_'.
 1231 The components of hierarchical keywords are separated by a single ASCII space charater.
 1232 For instance:
 1233 
 1234 \begin{verbatim}
 1235 HIERARCH ESO INS FOCU POS = -0.00002500 / Focus position
 1236 \end{verbatim}
 1237 Basically, this convention uses the FITS keyword 'HIERARCH' to indicate
 1238 that this convention is being used, then the actual keyword name
 1239 ({\tt'ESO INS FOCU POS'} in this example) begins in column 10.  The
 1240 equals sign marks the end of the keyword name and is followed by the
 1241 usual value and comment fields just as in standard FITS keywords.
 1242 Further details of this convention are described at
 1243 http://fits.gsfc.nasa.gov/registry/hierarch\_keyword.html
 1244 and in Section 4.4 of the ESO Data Interface Control Document that
 1245 is linked to from
 1246 http://archive.eso.org/cms/tools-documentation/eso-data-interface-control.html.
 1247 
 1248 This convention allows a broader range of keyword names
 1249 than is allowed by the FITS Standard.  Here are more examples
 1250 of such keywords:
 1251 
 1252 \begin{verbatim}
 1253 HIERARCH LONGKEYWORD = 47.5 / Keyword has > 8 characters
 1254 HIERARCH LONG-KEY_WORD2 = 52.3 / Long keyword with hyphen, underscore and digit
 1255 HIERARCH EARTH IS A STAR = F / Keyword contains embedded spaces
 1256 \end{verbatim}
 1257 CFITSIO will transparently read and write these keywords, so application
 1258 programs do not in general need to know anything about the specific
 1259 implementation details of the HIERARCH convention.  In particular,
 1260 application programs do not need to specify the `HIERARCH' part of the
 1261 keyword name when reading or writing keywords (although it
 1262 may be included if desired).  When writing a keyword, CFITSIO first
 1263 checks to see if the keyword name is legal as a standard FITS keyword
 1264 (no more than 8 characters long and containing only letters, digits, or
 1265 a minus sign or underscore). If so it writes it as a standard FITS
 1266 keyword, otherwise it uses the hierarch convention to write the
 1267 keyword.   The maximum keyword name length is 67 characters, which
 1268 leaves only 1 space for the value field.  A more practical limit is
 1269 about 40 characters, which leaves enough room for most keyword values.
 1270 CFITSIO returns an error if there is not enough room for both the
 1271 keyword name and the keyword value on the 80-character card, except for
 1272 string-valued keywords which are simply truncated so that the closing
 1273 quote character falls in column 80. A space is also required on either 
 1274 side of the equal sign.
 1275 
 1276 
 1277 \section{Optimizing Code for Maximum Processing Speed}
 1278 
 1279 CFITSIO has been carefully designed to obtain the highest possible
 1280 speed when reading and writing FITS files.  In order to achieve the
 1281 best performance, however, application programmers must be careful to
 1282 call the CFITSIO routines appropriately and in an efficient sequence;
 1283 inappropriate usage of CFITSIO routines can greatly slow down the
 1284 execution speed of a program.
 1285 
 1286 The maximum possible I/O speed of CFITSIO depends of course on the type
 1287 of computer system that it is running on.  To get a general idea of what
 1288 data I/O speeds are possible on a particular machine, build the speed.c
 1289 program that is distributed with CFITSIO (type 'make speed' in the CFITSIO
 1290 directory).  This diagnostic program measures the speed of writing and reading
 1291 back a test FITS image, a binary table, and an ASCII table.
 1292 
 1293 The following 2 sections provide some background on how CFITSIO
 1294 internally manages the data I/O and describes some strategies that may
 1295 be used to optimize the processing speed of software that uses
 1296 CFITSIO.
 1297 
 1298 
 1299 \subsection{Background Information: How CFITSIO Manages Data I/O}
 1300 
 1301 Many CFITSIO operations involve transferring only a small number of
 1302 bytes to or from the FITS file (e.g, reading a keyword, or writing a
 1303 row in a table); it would be very inefficient to physically read or
 1304 write such small blocks of data directly in the FITS file on disk,
 1305 therefore CFITSIO maintains a set of internal Input--Output (IO)
 1306 buffers in RAM memory that each contain one FITS block (2880 bytes) of
 1307 data.  Whenever CFITSIO needs to access data in the FITS file, it first
 1308 transfers the FITS block containing those bytes into one of the IO
 1309 buffers in memory.  The next time CFITSIO needs to access bytes in the
 1310 same block it can then go to the fast IO buffer rather than using a
 1311 much slower system disk access routine.  The number of available IO
 1312 buffers is determined by the NIOBUF parameter (in fitsio2.h) and is
 1313 currently set to 40.
 1314 
 1315 Whenever CFITSIO reads or writes data it first checks to see if that
 1316 block of the FITS file is already loaded into one of the IO buffers.
 1317 If not, and if there is an empty IO buffer available, then it will load
 1318 that block into the IO buffer (when reading a FITS file) or will
 1319 initialize a new block (when writing to a FITS file).  If all the IO
 1320 buffers are already full, it must decide which one to reuse (generally
 1321 the one that has been accessed least recently), and flush the contents
 1322 back to disk if it has been modified before loading the new block.
 1323 
 1324 The one major exception to the above process occurs whenever a large
 1325 contiguous set of bytes are accessed, as might occur when reading or
 1326 writing a FITS image.  In this case CFITSIO bypasses the internal IO
 1327 buffers and simply reads or writes the desired bytes directly in the
 1328 disk file with a single call to a low-level file read or write
 1329 routine.  The minimum threshold for the number of bytes to read or
 1330 write this way is set by the MINDIRECT parameter and is currently set
 1331 to 3 FITS blocks = 8640 bytes.  This is the most efficient way to read
 1332 or write large chunks of data.  Note that this fast direct IO process is not
 1333 applicable when accessing columns of data in a FITS table because the
 1334 bytes are generally not contiguous since they are interleaved by the
 1335 other columns of data in the table.  This explains why the speed for
 1336 accessing FITS tables is generally slower than accessing
 1337 FITS images.
 1338 
 1339 Given this background information, the general strategy for efficiently
 1340 accessing FITS files should now be apparent:  when dealing with FITS
 1341 images, read or write large chunks of data at a time so that the direct
 1342 IO mechanism will be invoked;  when accessing FITS headers or FITS
 1343 tables, on the other hand, once a particular FITS block has been
 1344 loading into one of the IO buffers, try to access all the needed
 1345 information in that block before it gets flushed out of the IO buffer.
 1346 It is important to avoid the situation where the same FITS block is
 1347 being read then flushed from a IO buffer multiple times.
 1348 
 1349 The following section gives more specific suggestions for optimizing
 1350 the use of CFITSIO.
 1351 
 1352 
 1353 \subsection{Optimization Strategies}
 1354 
 1355 1.  Because the data in FITS files is always stored in "big-endian" byte order,
 1356 where the first byte of numeric values contains the most significant bits and the
 1357 last byte contains the least significant bits, CFITSIO must swap the order of the bytes
 1358 when reading or writing FITS files when running on little-endian machines (e.g.,
 1359 Linux and Microsoft Windows operating systems running on PCs with x86 CPUs).
 1360 
 1361 On fairly new CPUs that support "SSSE3" machine instructions
 1362 (e.g., starting with Intel Core 2 CPUs in 2007, and in AMD CPUs
 1363 beginning in 2011) significantly faster 4-byte and 8-byte swapping
 1364 algorithms are available. These faster byte swapping functions are
 1365 not used by default in CFITSIO (because of the potential code
 1366 portablility issues), but users can enable them on supported
 1367 platforms by adding the appropriate compiler flags (-mssse3 with gcc
 1368 or icc on linux) when compiling the swapproc.c source file, which will
 1369 allow the compiler to generate code using the SSSE3 instruction set.
 1370 A convenient way to do this is to configure the CFITSIO library
 1371 with the following command:
 1372 
 1373 \begin{verbatim}
 1374   >  ./configure --enable-ssse3
 1375 \end{verbatim}
 1376 Note, however, that a binary executable file that is
 1377 created using these faster functions will only run on
 1378 machines that support the SSSE3 machine instructions. It will
 1379 crash on machines that do not support them.
 1380 
 1381 For faster 2-byte swaps on virtually all x86-64 CPUs (even those that
 1382 do not support SSSE3), a variant using only SSE2 instructions exists.
 1383 SSE2 is enabled by default on x86\_64 CPUs with 64-bit operating systems
 1384 (and is also automatically enabled by the --enable-ssse3 flag).
 1385 When running on x86\_64 CPUs with 32-bit operating systems, these faster
 1386 2-byte swapping algorithms are not used by default in CFITSIO, but can be
 1387 enabled explicitly with:
 1388 
 1389 \begin{verbatim}
 1390 ./configure --enable-sse2
 1391 \end{verbatim}
 1392 Preliminary testing indicates that these SSSE3 and SSE2 based
 1393 byte-swapping algorithms can boost the CFITSIO performance when
 1394 reading or writing FITS images by 20\% - 30\% or more.
 1395 It is important to note, however, that compiler optimization must be
 1396 turned on (e.g., by using the -O1 or -O2 flags in gcc) when building
 1397 programs that use these fast byte-swapping algorithms in order
 1398 to reap the full benefit of the SSSE3 and SSE2 instructions; without
 1399 optimization, the code may actually run slower than when using
 1400 more traditional byte-swapping techniques.
 1401 
 1402 2.  When dealing with a FITS primary array or IMAGE extension, it is
 1403 more efficient to read or write large chunks of the  image at a time
 1404 (at least 3 FITS blocks = 8640 bytes) so that the direct IO mechanism
 1405 will be used as described in the previous section.  Smaller chunks of
 1406 data are read or written via the IO buffers, which is somewhat less
 1407 efficient because of the extra copy operation and additional
 1408 bookkeeping steps that are required.  In principle it is more efficient
 1409 to read or write as big an array of image pixels at one time as
 1410 possible, however, if the array becomes so large that the operating
 1411 system cannot store it all in RAM, then the performance may be degraded
 1412 because of the increased swapping of virtual memory to disk.
 1413 
 1414 3.  When dealing with FITS tables, the most important efficiency factor
 1415 in the software design is to read or write the data in the FITS file in
 1416 a single pass through the file.  An example of poor program design
 1417 would be to read a large, 3-column table by sequentially reading the
 1418 entire first column, then going back to read the 2nd column, and
 1419 finally the 3rd column; this obviously requires 3 passes through the
 1420 file which could triple the execution time of an I/O limited program.
 1421 For small tables this is not important, but when reading multi-megabyte
 1422 sized tables these inefficiencies can become significant.  The more
 1423 efficient procedure in this case is to read or write only as many rows
 1424 of the table as will fit into the available internal I/O buffers, then
 1425 access all the necessary columns of data within that range of rows.
 1426 Then after the program is completely finished with the data in those
 1427 rows it can move on to the next range of rows that will fit in the
 1428 buffers, continuing in this way until the entire file has been
 1429 processed.  By using this procedure of accessing all the columns of a
 1430 table in parallel rather than sequentially, each block of the FITS file
 1431 will only be read or written once.
 1432 
 1433 The optimal number of rows to read or write at one time in a given
 1434 table depends on the width of the table row, on the number of I/O
 1435 buffers that have been allocated in FITSIO, and also on the number of
 1436 other FITS files that are open at the same time (since one I/O buffer
 1437 is always reserved for each open FITS file).  Fortunately, a FITSIO
 1438 routine is available that will return the optimal number of rows for a
 1439 given table:  call ftgrsz(unit, nrows, status).  It is not critical to
 1440 use exactly the value of nrows returned by this routine, as long as one
 1441 does not exceed it.  Using a very small value however can also lead to
 1442 poor performance because of the overhead from the larger number of
 1443 subroutine calls.
 1444 
 1445 The optimal number of rows returned by ftgrsz is valid only as long as
 1446 the application program is only reading or writing data in the
 1447 specified table.  Any other calls to access data in the table header
 1448 would  cause additional blocks of data to be
 1449 loaded into the I/O buffers displacing data from the original table,
 1450 and should be avoided during the critical period while the table is
 1451 being read or written.
 1452 
 1453 4.  Use binary table extensions rather than ASCII table
 1454 extensions for better efficiency  when dealing with tabular data.  The
 1455 I/O to ASCII tables is slower because of the overhead in formatting or
 1456 parsing the ASCII data fields, and because ASCII tables are about twice
 1457 as large as binary tables with the same information content.
 1458 
 1459 5. Design software so that it reads the FITS header keywords in the
 1460 same order in which they occur in the file.  When reading keywords,
 1461 FITSIO searches forward starting from the position of the last keyword
 1462 that was read.  If it reaches the end of the header without finding the
 1463 keyword, it then goes back to the start of the header and continues the
 1464 search down to the position where it started.  In practice, as long as
 1465 the entire FITS header can fit at one time in the available internal I/O
 1466 buffers, then the header keyword access will be very fast and it makes
 1467 little difference which order they are accessed.
 1468 
 1469 6. Avoid the use of scaling (by using the BSCALE and BZERO or TSCAL and
 1470 TZERO keywords) in FITS files since the scaling operations add to the
 1471 processing time needed to read or write the data.  In some cases it may
 1472 be more efficient to temporarily turn off the scaling (using ftpscl or
 1473 fttscl) and then read or write the raw unscaled values in the FITS
 1474 file.
 1475 
 1476 7. Avoid using the 'implicit datatype conversion' capability in
 1477 FITSIO.  For instance, when reading a FITS image with BITPIX = -32
 1478 (32-bit floating point pixels), read the data into a single precision
 1479 floating point data array in the program.  Forcing FITSIO to convert
 1480 the data to a different datatype can significantly slow the program.
 1481 
 1482 8. Where feasible, design FITS binary tables using vector column
 1483 elements so that the data are written as a contiguous set of bytes,
 1484 rather than as single elements in multiple rows.  For example, it is
 1485 faster to access the data in a table that contains a single row
 1486 and 2 columns with TFORM keywords equal to  '10000E' and '10000J', than
 1487 it is to access the same amount of data in a table with 10000 rows
 1488 which has columns with the TFORM keywords equal to '1E' and '1J'.  In
 1489 the former case the 10000 floating point values in the first column are
 1490 all written in a contiguous block of the file which can be read or
 1491 written quickly, whereas in the second case each floating point value
 1492 in the first column is interleaved with the integer value in the second
 1493 column of the same row so CFITSIO has to explicitly move to the
 1494 position of each element to be read or written.
 1495 
 1496 9. Avoid the use of variable length vector columns in binary tables,
 1497 since any reading or writing of these data requires that CFITSIO first
 1498 look up or compute the starting address of each row of data in the
 1499 heap.  In practice, this is probably not a significant efficiency issue.
 1500 
 1501 10. When copying data from one FITS table to another, it is faster to
 1502 transfer the raw bytes instead of reading then writing each column of
 1503 the table.  The FITSIO subroutines FTGTBS and FTPTBS (for ASCII
 1504 tables), and  FTGTBB and FTPTBB (for binary tables) will perform
 1505 low-level reads or writes of any contiguous range of bytes in a table
 1506 extension.  These routines can be used to read or write a whole row (or
 1507 multiple rows) of a table with a single subroutine call.   These
 1508 routines are fast because they bypass all the usual data scaling, error
 1509 checking and machine dependent data conversion that is normally done by
 1510 FITSIO, and they allow the program to write the data to the output file
 1511 in exactly the same byte order.  For these same reasons, use of these
 1512 routines can be somewhat risky because no validation or machine
 1513 dependent conversion is performed by these routines.  In general these
 1514 routines are only recommended for optimizing critical pieces of code
 1515 and should only be used by programmers who thoroughly understand the
 1516 internal byte structure of the FITS tables they are reading or
 1517 writing.
 1518 
 1519 11. Another strategy for improving the speed of writing a FITS table,
 1520 similar to the previous one, is to directly construct the entire byte
 1521 stream for a whole table row (or multiple rows) within the application
 1522 program and then write it to the FITS file with
 1523 ftptbb.  This avoids all the overhead normally present
 1524 in the column-oriented CFITSIO write routines.  This technique should
 1525 only be used for critical applications, because it makes the code more
 1526 difficult to understand and maintain, and it makes the code more system
 1527 dependent (e.g., do the bytes need to be swapped before writing to the
 1528 FITS file?).
 1529 
 1530 12.  Finally, external factors such as the type of magnetic disk
 1531 controller (SCSI or IDE), the size of the disk cache, the average seek
 1532 speed of the disk, the amount of disk fragmentation, and the amount of
 1533 RAM available on the system can all have a significant impact on
 1534 overall I/O efficiency.  For critical applications, a system
 1535 administrator should review the proposed system hardware to identify any
 1536 potential I/O bottlenecks.
 1537 
 1538 
 1539 
 1540 \chapter{  Basic Interface Routines }
 1541 
 1542 This section defines a basic set of subroutines that can be
 1543 used to perform the most common types of read and write operations
 1544 on FITS files.  New users should start with these subroutines and
 1545 then, as needed, explore the more advance routines described in
 1546 the following chapter to perform more complex or specialized operations.
 1547 
 1548 A right arrow symbol ($>$) is used to separate the input parameters from
 1549 the output parameters in the  definition of each routine.  This symbol
 1550 is not actually part of the calling sequence.  Note that
 1551 the status parameter is both an input and an output parameter
 1552 and must be initialized = 0 prior to calling the FITSIO subroutines.
 1553 
 1554 Refer to Chapter 9 for the definition of all the parameters
 1555 used by these interface routines.
 1556 
 1557 
 1558 \section{FITSIO Error Status Routines \label{FTVERS}}
 1559 
 1560 
 1561 \begin{description}
 1562 \item[1 ] Return the current version number of the fitsio library.
 1563     The version number will be incremented with each new
 1564    release of CFITSIO.
 1565 \end{description}
 1566 
 1567 \begin{verbatim}
 1568         FTVERS( > version)
 1569 \end{verbatim}
 1570 
 1571 \begin{description}
 1572 \item[2 ] Return the descriptive text string corresponding to a FITSIO error
 1573     status code.   The 30-character length string contains a brief
 1574    description of the cause of the error.
 1575 \end{description}
 1576 
 1577 \begin{verbatim}
 1578         FTGERR(status, > errtext)
 1579 \end{verbatim}
 1580 
 1581 \begin{description}
 1582 \item[3 ] Return the top (oldest) 80-character error message from the
 1583     internal FITSIO stack of error messages and shift any remaining
 1584     messages on the stack up one level.  Any FITSIO error will
 1585     generate one or more messages on the stack.  Call this routine
 1586     repeatedly to get each message in sequence.  The error stack is empty
 1587    when a blank string is returned.
 1588 \end{description}
 1589 
 1590 \begin{verbatim}
 1591         FTGMSG( > errmsg)
 1592 \end{verbatim}
 1593 
 1594 \begin{description}
 1595 \item[4 ]The FTPMRK routine puts an invisible marker on the
 1596    CFITSIO error stack.  The FTCMRK routine can then be
 1597    used to delete any more recent error messages on the stack, back to
 1598    the position of the marker.  This preserves any older error messages
 1599    on the stack.  FTCMSG simply clears the entire error message stack.
 1600   These routines are called without any arguments.
 1601 \end{description}
 1602 
 1603 \begin{verbatim}
 1604         FTPMRK
 1605         FTCMRK
 1606         FTCMSG
 1607 \end{verbatim}
 1608 
 1609 
 1610 \begin{description}
 1611 \item[5 ] Print out the error message corresponding to the input status
 1612     value and all the error messages on the FITSIO stack  to the specified
 1613     file stream  (stream can be either the string 'STDOUT' or 'STDERR').
 1614    If the input status value = 0 then this routine does nothing.
 1615 \end{description}
 1616 
 1617 \begin{verbatim}
 1618        FTRPRT (stream, > status)
 1619 \end{verbatim}
 1620 
 1621 \begin{description}
 1622 \item[6 ] Write an 80-character message to the FITSIO error stack.  Application
 1623     programs should not normally write to the stack, but there may be
 1624    some situations where this is desirable.
 1625 \end{description}
 1626 
 1627 \begin{verbatim}
 1628         FTPMSG(errmsg)
 1629 \end{verbatim}
 1630 
 1631 
 1632 \section{File I/O Routines}
 1633 
 1634 
 1635 \begin{description}
 1636 \item[1 ]Open an existing FITS file with readonly or readwrite access.
 1637    This routine always opens the primary array (the first HDU) of
 1638    the file, and does not move to a following extension, if one was
 1639    specified as part of the filename.   Use the FTNOPN routine to
 1640    automatically move to the extension.  This routine will also
 1641    open IRAF images (.imh format files) and raw binary data arrays
 1642    with READONLY access by first converting them on the fly into
 1643    virtual FITS images.  See the `Extended File Name Syntax' chapter
 1644    for more details.  The FTDKOPN routine simply opens the specified
 1645    file without trying to interpret the filename using the extended
 1646   filename syntax.
 1647 \end{description}
 1648 
 1649 \begin{verbatim}
 1650         FTOPEN(unit,filename,rwmode, > blocksize,status)
 1651         FTDKOPN(unit,filename,rwmode, > blocksize,status)
 1652 \end{verbatim}
 1653 
 1654 \begin{description}
 1655 \item[2 ]Open an existing FITS file with readonly or readwrite access
 1656    and move to a following extension, if one was specified as
 1657    part of the filename.  (e.g.,  'filename.fits+2' or
 1658    'filename.fits[2]' will move to the 3rd HDU in the file).
 1659    Note that this routine differs from FTOPEN in that it does not
 1660   have the redundant blocksize argument.
 1661 \end{description}
 1662 
 1663 \begin{verbatim}
 1664         FTNOPN(unit,filename,rwmode, > status)
 1665 \end{verbatim}
 1666 
 1667 \begin{description}
 1668 \item[3 ]Open an existing FITS file with readonly or readwrite access
 1669    and then move to the first HDU containing significant data, if a) an HDU
 1670    name or number to open was not explicitly specified as part of the
 1671    filename, and b) if the FITS file contains a null primary array (i.e.,
 1672    NAXIS = 0).  In this case, it will look for the first IMAGE HDU with
 1673    NAXIS > 0, or the first table that does not contain the strings `GTI'
 1674    (Good Time Interval) or `OBSTABLE' in the EXTNAME keyword value.  FTTOPN
 1675    is similar, except it will move to the first significant table HDU
 1676    (skipping over any image HDUs) in the file if a specific HDU name
 1677    or number is not specified.  FTIOPN will move to the first non-null
 1678   image HDU, skipping over any tables.
 1679 \end{description}
 1680 
 1681 \begin{verbatim}
 1682         FTDOPN(unit,filename,rwmode, > status)
 1683         FTTOPN(unit,filename,rwmode, > status)
 1684         FTIOPN(unit,filename,rwmode, > status)
 1685 \end{verbatim}
 1686 
 1687 \begin{description}
 1688 \item[4 ]Open and initialize a new empty FITS file.   A template file may also be
 1689    specified to define the structure of the new file (see section 4.2.4).
 1690    The FTDKINIT routine simply creates the specified
 1691    file without trying to interpret the filename using the extended
 1692   filename syntax.
 1693 \end{description}
 1694 
 1695 \begin{verbatim}
 1696         FTINIT(unit,filename,blocksize, > status)
 1697         FTDKINIT(unit,filename,blocksize, > status)
 1698 \end{verbatim}
 1699 
 1700 \begin{description}
 1701 \item[5 ]Close a FITS file previously opened with ftopen or ftinit
 1702 \end{description}
 1703 
 1704 \begin{verbatim}
 1705         FTCLOS(unit, > status)
 1706 \end{verbatim}
 1707 
 1708 \begin{description}
 1709 \item[6 ] Move to a specified (absolute) HDU in the FITS file (nhdu = 1 for the
 1710    FITS primary array)
 1711 \end{description}
 1712 
 1713 \begin{verbatim}
 1714         FTMAHD(unit,nhdu, > hdutype,status)
 1715 \end{verbatim}
 1716 
 1717 \begin{description}
 1718 \item[7 ] Create a primary array (if none already exists), or insert a
 1719     new IMAGE extension immediately following the CHDU, or
 1720     insert a new Primary Array at the beginning of the file.  Any
 1721     following extensions in the file will be shifted down to make room
 1722     for the new extension.  If the CHDU is the last HDU in the file
 1723     then the new image extension will simply be appended to the end of
 1724     the file.   One can force a new primary array to be inserted at the
 1725     beginning of the FITS file by setting status = -9 prior
 1726     to calling the routine.  In this case the existing primary array will be
 1727     converted to an IMAGE extension. The new extension (or primary
 1728     array) will become the CHDU.  The FTIIMGLL routine is identical
 1729     to the FTIIMG routine except that the 4th parameter (the length
 1730     of each axis) is an array of 64-bit integers rather than an array
 1731    of 32-bit integers.
 1732 \end{description}
 1733 
 1734 \begin{verbatim}
 1735         FTIIMG(unit,bitpix,naxis,naxes, > status)
 1736         FTIIMGLL(unit,bitpix,naxis,naxesll, > status)
 1737 \end{verbatim}
 1738 
 1739 \begin{description}
 1740 \item[8 ] Insert a new ASCII TABLE extension immediately following the CHDU.
 1741     Any following extensions will be shifted down to make room for
 1742     the new extension.  If there are no other following extensions
 1743     then the new table extension will simply be appended to the
 1744     end of the file.  The new extension will become the CHDU. The FTITABLL
 1745     routine is identical
 1746     to the FTITAB routine except that the 2nd and 3rd parameters (that give
 1747     the size of the table) are 64-bit integers rather than
 1748     32-bit integers.  Under normal circumstances, the nrows and nrowsll
 1749     paramenters should have a value of 0; CFITSIO will automatically update
 1750    the number of rows as data is written to the table.
 1751 \end{description}
 1752 
 1753 \begin{verbatim}
 1754         FTITAB(unit,rowlen,nrows,tfields,ttype,tbcol,tform,tunit,extname, >
 1755                status)
 1756         FTITABLL(unit,rowlenll,nrowsll,tfields,ttype,tbcol,tform,tunit,extname, >
 1757                status)
 1758 \end{verbatim}
 1759 
 1760 \begin{description}
 1761 \item[9 ] Insert a new binary table extension immediately following the CHDU.
 1762     Any following extensions will be shifted down to make room for
 1763     the new extension.  If there are no other following extensions
 1764     then the new bintable extension will simply be appended to the
 1765      end of the file.  The new extension will become the CHDU. The FTIBINLL
 1766     routine is identical
 1767     to the FTIBIN routine except that the 2nd parameter (that gives
 1768     the length of the table) is a 64-bit integer rather than
 1769     a 32-bit integer. Under normal circumstances, the nrows and nrowsll
 1770     paramenters should have a value of 0; CFITSIO will automatically update
 1771    the number of rows as data is written to the table.
 1772 \end{description}
 1773 
 1774 \begin{verbatim}
 1775         FTIBIN(unit,nrows,tfields,ttype,tform,tunit,extname,varidat > status)
 1776         FTIBINLL(unit,nrowsll,tfields,ttype,tform,tunit,extname,varidat > status)
 1777 
 1778 \end{verbatim}
 1779 
 1780 \section{Keyword I/O Routines}
 1781 
 1782 
 1783 \begin{description}
 1784 \item[1 ]Put (append) an 80-character record into the CHU.
 1785 \end{description}
 1786 
 1787 \begin{verbatim}
 1788         FTPREC(unit,card, > status)
 1789 \end{verbatim}
 1790 
 1791 \begin{description}
 1792 \item[2 ] Put (append) a new keyword of the appropriate datatype into the CHU.
 1793      The E and D versions of this routine have the added feature that
 1794      if the 'decimals' parameter is negative, then the 'G' display
 1795      format rather then the 'E' format will be used when constructing
 1796      the keyword value, taking the absolute value of 'decimals' for the
 1797      precision.  This will suppress trailing zeros, and will use a
 1798      fixed format rather than an exponential format,
 1799     depending on the magnitude of the value.
 1800 \end{description}
 1801 
 1802 \begin{verbatim}
 1803         FTPKY[JKLS](unit,keyword,keyval,comment, > status)
 1804         FTPKY[EDFG](unit,keyword,keyval,decimals,comment, > status)
 1805 \end{verbatim}
 1806 
 1807 \begin{description}
 1808 \item[3 ]Get the nth 80-character header record from the CHU.  The first keyword
 1809    in the header is at key\_no = 1;  if key\_no = 0 then this subroutine
 1810    simple moves the internal pointer to the beginning of the header
 1811    so that subsequent keyword operations will start at the top of
 1812   the header; it also returns a blank card value in this case.
 1813 \end{description}
 1814 
 1815 \begin{verbatim}
 1816         FTGREC(unit,key_no, > card,status)
 1817 \end{verbatim}
 1818 
 1819 \begin{description}
 1820 \item[4 ] Get a keyword value (with the appropriate datatype) and comment from
 1821    the CHU
 1822 \end{description}
 1823 
 1824 \begin{verbatim}
 1825         FTGKY[EDJKLS](unit,keyword, > keyval,comment,status)
 1826 \end{verbatim}
 1827 
 1828 \begin{description}
 1829 \item[5 ] Delete an existing keyword record.
 1830 \end{description}
 1831 
 1832 \begin{verbatim}
 1833         FTDKEY(unit,keyword, > status)
 1834 \end{verbatim}
 1835 
 1836 
 1837 \section{Data I/O Routines}
 1838 
 1839 The following routines read or write data values in the current HDU of
 1840 the FITS file.  Automatic datatype conversion
 1841 will be attempted for numerical datatypes if the specified datatype is
 1842 different from the actual datatype of the FITS array or table column.
 1843 
 1844 
 1845 \begin{description}
 1846 \item[1 ]Write elements into the primary data array or image extension.
 1847 \end{description}
 1848 
 1849 \begin{verbatim}
 1850         FTPPR[BIJKED](unit,group,fpixel,nelements,values, > status)
 1851 \end{verbatim}
 1852 
 1853 \begin{description}
 1854 \item[2 ] Read elements from the primary data array or image extension.
 1855     Undefined array elements will be
 1856     returned with a value = nullval, unless nullval = 0 in which case no
 1857     checks for undefined pixels will be performed. The anyf parameter is
 1858     set to true (= .true.) if any of the returned
 1859    elements were undefined.
 1860 \end{description}
 1861 
 1862 \begin{verbatim}
 1863         FTGPV[BIJKED](unit,group,fpixel,nelements,nullval, > values,anyf,status)
 1864 \end{verbatim}
 1865 
 1866 \begin{description}
 1867 \item[3 ] Write elements into an ASCII or binary table column. The `felem'
 1868     parameter applies only to vector columns in binary tables and is
 1869    ignored when writing to ASCII tables.
 1870 \end{description}
 1871 
 1872 \begin{verbatim}
 1873         FTPCL[SLBIJKEDCM](unit,colnum,frow,felem,nelements,values, > status)
 1874 \end{verbatim}
 1875 
 1876 \begin{description}
 1877 \item[4 ] Read elements from an ASCII or binary table column.  Undefined
 1878     array elements will be returned with a value = nullval, unless nullval = 0
 1879     (or = ' ' for ftgcvs) in which case no checking for undefined values will
 1880     be performed. The ANYF parameter is set to true if any of the returned
 1881     elements are undefined.
 1882 
 1883     Any column, regardless of it's intrinsic datatype, may be read as a
 1884     string.  It should be noted however that reading a numeric column
 1885     as a string is 10 - 100 times slower than reading the same column
 1886     as a number due to the large overhead in constructing the formatted
 1887     strings.  The display format of the returned strings will be
 1888     determined by the TDISPn keyword, if it exists, otherwise by the
 1889     datatype of the column.  The length of the returned strings  can be
 1890     determined with the ftgcdw routine.  The following TDISPn display
 1891     formats are currently supported:
 1892 
 1893 \begin{verbatim}
 1894     Iw.m   Integer
 1895     Ow.m   Octal integer
 1896     Zw.m   Hexadecimal integer
 1897     Fw.d   Fixed floating point
 1898     Ew.d   Exponential floating point
 1899     Dw.d   Exponential floating point
 1900     Gw.d   General; uses Fw.d if significance not lost, else Ew.d
 1901 \end{verbatim}
 1902   where w is the width in characters of the displayed values, m is the minimum
 1903   number of digits displayed, and d is the number of digits to the right of the
 1904   decimal.  The .m field is optional.
 1905 \end{description}
 1906 
 1907 
 1908 \begin{verbatim}
 1909         FTGCV[SBIJKEDCM](unit,colnum,frow,felem,nelements,nullval, >
 1910                        values,anyf,status)
 1911 \end{verbatim}
 1912 
 1913 \begin{description}
 1914 \item[5 ] Get the table column number and full name of the column whose name
 1915     matches the input template string.  See the `Advanced Interface Routines'
 1916    chapter for a full description of this routine.
 1917 \end{description}
 1918 
 1919 \begin{verbatim}
 1920         FTGCNN(unit,casesen,coltemplate, > colname,colnum,status)
 1921 \end{verbatim}
 1922 
 1923 
 1924 \chapter{   Advanced Interface Subroutines }
 1925 
 1926 This chapter defines all the available subroutines in the FITSIO user
 1927 interface. For completeness, the basic subroutines described in the
 1928 previous chapter are also repeated here. A right arrow symbol is used
 1929 here to separate the input parameters from the output parameters in the
 1930 definition of each subroutine. This symbol is not actually part of the
 1931 calling sequence. An alphabetical list and definition of all the
 1932 parameters is given at the end of this section.
 1933 
 1934 
 1935 \section{FITS File Open and Close Subroutines: \label{FTOPEN}}
 1936 
 1937 
 1938 \begin{description}
 1939 \item[1 ]Open an existing FITS file with readonly or readwrite access. The
 1940 FTDKOPN routine simply opens the specified file without trying to
 1941 interpret the filename using the extended filename syntax. FTDOPN opens
 1942 the file and
 1943 also moves to the first HDU containing significant data, if no specific
 1944 HDU is specified as part of the filename.  FTTOPN and FTIOPN are similar
 1945 except that they will move to the first table HDU or image HDU, respectively,
 1946 if a HDU name or number is not specified as part of the filename.
 1947 \end{description}
 1948 
 1949 \begin{verbatim}
 1950         FTOPEN(unit,filename,rwmode, > blocksize,status)
 1951         FTDKOPN(unit,filename,rwmode, > blocksize,status)
 1952 
 1953         FTDOPN(unit,filename,rwmode, > status)
 1954         FTTOPN(unit,filename,rwmode, > status)
 1955         FTIOPN(unit,filename,rwmode, > status)
 1956 \end{verbatim}
 1957 
 1958 
 1959 \begin{description}
 1960 \item[2 ]Open an existing FITS file with readonly or readwrite access
 1961    and move to a following extension, if one was specified as
 1962    part of the filename.  (e.g.,  'filename.fits+2' or
 1963    'filename.fits[2]' will move to the 3rd HDU in the file).
 1964    Note that this routine differs from FTOPEN in that it does not
 1965   have the redundant blocksize argument.
 1966 \end{description}
 1967 
 1968 \begin{verbatim}
 1969         FTNOPN(unit,filename,rwmode, > status)
 1970 \end{verbatim}
 1971 
 1972 \begin{description}
 1973 \item[3 ] Reopen a FITS file that was previously opened with
 1974     FTOPEN, FTNOPN, or FTINIT.  The newunit number
 1975     may then be treated as a separate file, and one may
 1976     simultaneously read or write to 2 (or more)  different extensions in
 1977     the same file.   The FTOPEN and FTNOPN routines (above) automatically
 1978     detects cases where a previously opened file is being opened again,
 1979     and then internally call FTREOPEN, so programs should rarely
 1980    need to explicitly call this routine.
 1981 \end{description}
 1982 
 1983 \begin{verbatim}
 1984        FTREOPEN(unit, > newunit, status)
 1985 \end{verbatim}
 1986 
 1987 \begin{description}
 1988 \item[4 ]Open and initialize a new empty FITS file.
 1989    The FTDKINIT routine simply creates the specified
 1990    file without trying to interpret the filename using the extended
 1991   filename syntax.
 1992 \end{description}
 1993 
 1994 \begin{verbatim}
 1995        FTINIT(unit,filename,blocksize, > status)
 1996        FTDKINIT(unit,filename,blocksize, > status)
 1997 \end{verbatim}
 1998 
 1999 
 2000 \begin{description}
 2001 \item[5 ]  Create a new FITS file, using a template file to define its
 2002   initial size and structure.  The template may be another FITS HDU
 2003   or an ASCII template file.  If the input template file name
 2004   is blank, then this routine behaves the same as FTINIT.
 2005   The currently supported format of the ASCII template file is described
 2006   under the fits\_parse\_template routine (in the general Utilities
 2007   section), but this may change slightly later releases of
 2008  CFITSIO.
 2009 \end{description}
 2010 
 2011 \begin{verbatim}
 2012        FTTPLT(unit, filename, tplfilename, > status)
 2013 \end{verbatim}
 2014 
 2015 \begin{description}
 2016 \item[6 ]Flush internal buffers of data to the output FITS file
 2017    previously opened with ftopen or ftinit.  The routine usually
 2018    never needs to be called, but doing so will ensure that
 2019    if the program subsequently aborts, then the FITS file will
 2020   have at least been closed properly.
 2021 \end{description}
 2022 
 2023 \begin{verbatim}
 2024         FTFLUS(unit, > status)
 2025 \end{verbatim}
 2026 
 2027 \begin{description}
 2028 \item[7 ]Close a FITS file previously opened with ftopen or ftinit
 2029 \end{description}
 2030 
 2031 \begin{verbatim}
 2032         FTCLOS(unit, > status)
 2033 \end{verbatim}
 2034 
 2035 \begin{description}
 2036 \item[8 ] Close and DELETE a FITS file previously opened with ftopen or ftinit.
 2037     This routine may be  useful in cases where a FITS file is created, but
 2038    an error occurs which prevents the complete file from being written.
 2039 \end{description}
 2040 
 2041 \begin{verbatim}
 2042         FTDELT(unit, > status)
 2043 \end{verbatim}
 2044 
 2045 \begin{description}
 2046 \item[9 ] Get the value of an unused I/O unit number which may then be used
 2047     as input to FTOPEN or FTINIT.  This routine searches for the first
 2048     unused unit number in the range from with 99 down to 50.   This
 2049     routine just keeps an internal list of the allocated unit numbers
 2050     and does not physically check that the Fortran unit is available (to be
 2051     compatible with the SPP version of FITSIO).  Thus users must not
 2052     independently allocate any unit numbers in the range 50 - 99
 2053     if this routine is also to be used in the same program.  This
 2054     routine is provided for convenience only, and it is not required
 2055    that the unit numbers used by FITSIO be allocated by this routine.
 2056 \end{description}
 2057 
 2058 \begin{verbatim}
 2059         FTGIOU( > iounit, status)
 2060 \end{verbatim}
 2061 
 2062 \begin{description}
 2063 \item[10]  Free (deallocate) an I/O unit number which was previously allocated
 2064     with FTGIOU.   All previously allocated unit numbers may be
 2065    deallocated at once by calling FTFIOU with iounit = -1.
 2066 \end{description}
 2067 
 2068 \begin{verbatim}
 2069         FTFIOU(iounit, > status)
 2070 \end{verbatim}
 2071 
 2072 \begin{description}
 2073 \item[11]  Return the Fortran unit number that corresponds to the C fitsfile
 2074 pointer value, or vice versa.  These 2 C routines may be useful in
 2075 mixed language programs where both C and Fortran subroutines need
 2076 to access the same file.  For example, if a FITS file is opened
 2077 with unit 12 by a Fortran subroutine, then a C routine within the
 2078 same program could get the fitfile pointer value to access the same file
 2079 by calling  'fptr = CUnit2FITS(12)'.  These routines return a value
 2080 of zero if an error occurs.
 2081 \end{description}
 2082 
 2083 \begin{verbatim}
 2084       int       CFITS2Unit(fitsfile *ptr);
 2085       fitsfile* CUnit2FITS(int unit);
 2086 \end{verbatim}
 2087 
 2088 
 2089 \begin{description}
 2090 \item[11]  Parse the input filename and return the HDU number that would be
 2091 moved to if the file were opened with FTNOPN.    The returned HDU
 2092 number begins with 1 for the primary array, so for example, if the
 2093 input filename = `myfile.fits[2]' then hdunum = 3 will be returned.
 2094 FITSIO does not open the file to check if the extension actually exists
 2095 if an extension number is specified. If an extension *name* is included
 2096 in the file name specification (e.g.  `myfile.fits[EVENTS]' then this
 2097 routine will have to open the FITS file and look for the position of
 2098 the named extension, then close file again.  This is not possible if
 2099 the file is being read from the stdin stream, and an error will be
 2100 returned in this case.  If the filename does not specify an explicit
 2101 extension (e.g. 'myfile.fits') then hdunum = -99 will be returned,
 2102 which is functionally equivalent to hdunum = 1. This routine is mainly
 2103 used for backward compatibility in the ftools software package and is
 2104 not recommended for general use.  It is generally better and more
 2105 efficient to first open the FITS file with FTNOPN, then use FTGHDN to
 2106 determine which HDU in the file has been opened, rather than calling
 2107  FTEXTN followed by a call to FTNOPN.
 2108 \end{description}
 2109 
 2110 \begin{verbatim}
 2111         FTEXTN(filename, > nhdu, status)
 2112 \end{verbatim}
 2113 
 2114 \begin{description}
 2115 \item[12] Return the name of the opened FITS file.
 2116 \end{description}
 2117 
 2118 \begin{verbatim}
 2119         FTFLNM(unit, > filename, status)
 2120 \end{verbatim}
 2121 
 2122 \begin{description}
 2123 \item[13] Return the I/O mode of the open FITS file (READONLY = 0, READWRITE = 1).
 2124 \end{description}
 2125 
 2126 \begin{verbatim}
 2127         FTFLMD(unit, > iomode, status)
 2128 \end{verbatim}
 2129 
 2130 \begin{description}
 2131 \item[14] Return the file type of the opened FITS file (e.g. 'file://', 'ftp://',
 2132   etc.).
 2133 \end{description}
 2134 
 2135 \begin{verbatim}
 2136         FTURLT(unit, > urltype, status)
 2137 \end{verbatim}
 2138 
 2139 \begin{description}
 2140 \item[15]  Parse the input filename or URL into its component parts: the file
 2141 type (file://, ftp://, http://, etc), the base input file name, the
 2142 name of the output file that the input file is to be copied to prior
 2143 to opening, the HDU or extension specification, the filtering
 2144 specifier, the binning specifier, and the column specifier.  Blank
 2145 strings will be returned for any components that are not present
 2146 in the input file name.
 2147 \end{description}
 2148 
 2149 \begin{verbatim}
 2150        FTIURL(filename, > filetype, infile, outfile, extspec, filter,
 2151                binspec, colspec, status)
 2152 \end{verbatim}
 2153 
 2154 \begin{description}
 2155 \item[16] Parse the input file name and return the root file name.  The root
 2156 name includes the file type if specified, (e.g.  'ftp://' or 'http://')
 2157 and the full path name, to the extent that it is specified in the input
 2158 filename.  It does not include the HDU name or number, or any filtering
 2159 specifications.
 2160 \end{description}
 2161 
 2162 \begin{verbatim}
 2163        FTRTNM(filename, > rootname, status)
 2164 \end{verbatim}
 2165 
 2166 
 2167 \begin{description}
 2168 \item[16] Test if the input file or a compressed version of the file (with
 2169 a .gz, .Z, .z, or .zip extension) exists on disk.  The returned value of
 2170 the 'exists' parameter will have 1 of the 4 following values:
 2171 
 2172 \begin{verbatim}
 2173    2:  the file does not exist, but a compressed version does exist
 2174    1:  the disk file does exist
 2175    0:  neither the file nor a compressed version of the file exist
 2176   -1:  the input file name is not a disk file (could be a ftp, http,
 2177        smem, or mem file, or a file piped in on the STDIN stream)
 2178 \end{verbatim}
 2179 
 2180 \end{description}
 2181 
 2182 \begin{verbatim}
 2183       FTEXIST(filename, > exists, status);
 2184 \end{verbatim}
 2185 
 2186 \section{HDU-Level Operations \label{FTMAHD}}
 2187 
 2188 When a FITS file is first opened or created, the internal buffers in
 2189 FITSIO automatically point to the first HDU in the file.  The following
 2190 routines may be used to move to another HDU in the file.  Note that
 2191 the HDU numbering convention used in FITSIO  denotes the primary array
 2192 as the first HDU, the first extension in a FITS file is the second HDU,
 2193 and so on.
 2194 
 2195 
 2196 \begin{description}
 2197 \item[1 ] Move to a specified (absolute) HDU in the FITS file (nhdu = 1 for the
 2198    FITS primary array)
 2199 \end{description}
 2200 
 2201 \begin{verbatim}
 2202         FTMAHD(unit,nhdu, > hdutype,status)
 2203 \end{verbatim}
 2204 
 2205 \begin{description}
 2206 \item[2 ]Move to a new (existing) HDU forward or backwards relative to the CHDU
 2207 \end{description}
 2208 
 2209 \begin{verbatim}
 2210         FTMRHD(unit,nmove, > hdutype,status)
 2211 \end{verbatim}
 2212 
 2213 \begin{description}
 2214 \item[3 ] Move to the (first) HDU which has the specified extension type and
 2215     EXTNAME (or HDUNAME) and EXTVER keyword values.  The hdutype parameter
 2216     may have
 2217     a value of IMAGE\_HDU (0), ASCII\_TBL (1), BINARY\_TBL (2), or ANY\_HDU (-1)
 2218     where ANY\_HDU means that only the extname and extver values will be
 2219     used to locate the correct extension.  If the input value of
 2220     extver is 0 then the EXTVER keyword is ignored and the first HDU
 2221     with a matching EXTNAME (or HDUNAME) keyword will be found.  If no
 2222     matching HDU is found in the file then the current HDU will remain
 2223     unchanged
 2224    and a status = BAD\_HDU\_NUM (301) will be returned.
 2225 \end{description}
 2226 
 2227 \begin{verbatim}
 2228         FTMNHD(unit, hdutype, extname, extver, > status)
 2229 \end{verbatim}
 2230 
 2231 \begin{description}
 2232 \item[4 ]Get the number of the current HDU in the FITS file (primary array = 1)
 2233 \end{description}
 2234 
 2235 \begin{verbatim}
 2236         FTGHDN(unit, > nhdu)
 2237 \end{verbatim}
 2238 
 2239 \begin{description}
 2240 \item[5 ] Return the type of the current HDU in the FITS file.  The possible
 2241    values for hdutype are IMAGE\_HDU (0), ASCII\_TBL (1), or BINARY\_TBL (2).
 2242 \end{description}
 2243 
 2244 \begin{verbatim}
 2245         FTGHDT(unit, > hdutype, status)
 2246 \end{verbatim}
 2247 
 2248 \begin{description}
 2249 \item[6 ] Return the total number of HDUs in the FITS file.
 2250    The CHDU remains unchanged.
 2251 \end{description}
 2252 
 2253 \begin{verbatim}
 2254         FTTHDU(unit, > hdunum, status)
 2255 \end{verbatim}
 2256 
 2257 \begin{description}
 2258 \item[7 ]Create (append) a new empty HDU at the end of the FITS file.  This
 2259     new HDU becomes the Current HDU, but it is completely empty and contains
 2260     no header keywords or data.  It is recommended that FTIIMG, FTITAB or
 2261    FTIBIN be used instead of this routine.
 2262 \end{description}
 2263 
 2264 \begin{verbatim}
 2265         FTCRHD(unit, > status)
 2266 \end{verbatim}
 2267 
 2268 
 2269 \begin{description}
 2270 \item[8 ] Create a primary array (if none already exists), or insert a
 2271     new IMAGE extension immediately following the CHDU, or
 2272     insert a new Primary Array at the beginning of the file.  Any
 2273     following extensions in the file will be shifted down to make room
 2274     for the new extension.  If the CHDU is the last HDU in the file
 2275     then the new image extension will simply be appended to the end of
 2276     the file.   One can force a new primary array to be inserted at the
 2277     beginning of the FITS file by setting status = -9 prior
 2278     to calling the routine.  In this case the existing primary array will be
 2279     converted to an IMAGE extension. The new extension (or primary
 2280     array) will become the CHDU.  The FTIIMGLL routine is identical
 2281     to the FTIIMG routine except that the 4th parameter (the length
 2282     of each axis) is an array of 64-bit integers rather than an array
 2283    of 32-bit integers.
 2284 \end{description}
 2285 
 2286 \begin{verbatim}
 2287         FTIIMG(unit,bitpix,naxis,naxes, > status)
 2288         FTIIMGLL(unit,bitpix,naxis,naxesll, > status)
 2289 \end{verbatim}
 2290 
 2291 \begin{description}
 2292 \item[9 ] Insert a new ASCII TABLE extension immediately following the CHDU.
 2293     Any following extensions will be shifted down to make room for
 2294     the new extension.  If there are no other following extensions
 2295     then the new table extension will simply be appended to the
 2296     end of the file.  The new extension will become the CHDU. The FTITABLL
 2297     routine is identical
 2298     to the FTITAB routine except that the 2nd and 3rd parameters (that give
 2299     the size of the table) are 64-bit integers rather than
 2300    32-bit integers.
 2301 \end{description}
 2302 
 2303 \begin{verbatim}
 2304         FTITAB(unit,rowlen,nrows,tfields,ttype,tbcol,tform,tunit,extname, >
 2305                status)
 2306         FTITABLL(unit,rowlenll,nrowsll,tfields,ttype,tbcol,tform,tunit,extname, >
 2307                status)
 2308 \end{verbatim}
 2309 
 2310 
 2311 \begin{description}
 2312 \item[10]  Insert a new binary table extension immediately following the CHDU.
 2313     Any following extensions will be shifted down to make room for
 2314     the new extension.  If there are no other following extensions
 2315     then the new bintable extension will simply be appended to the
 2316     end of the file.  The new extension will become the CHDU. The FTIBINLL
 2317     routine is identical
 2318     to the FTIBIN routine except that the 2nd parameter (that gives
 2319     the length of the table) is a 64-bit integer rather than
 2320    a 32-bit integer.
 2321 \end{description}
 2322 
 2323 \begin{verbatim}
 2324         FTIBIN(unit,nrows,tfields,ttype,tform,tunit,extname,varidat > status)
 2325         FTIBINLL(unit,nrowsll,tfields,ttype,tform,tunit,extname,varidat > status)
 2326 
 2327 \end{verbatim}
 2328 
 2329 
 2330 \begin{description}
 2331 \item[11]  Resize an image by modifing the size, dimensions, and/or datatype of the
 2332     current primary array or image extension. If the new image, as specified
 2333     by the input arguments, is larger than the current existing image
 2334     in the FITS file then zero fill data will be inserted at the end
 2335     of the current image and any following extensions will be moved
 2336     further back in the file.  Similarly, if the new image is
 2337     smaller than the current image then any following extensions
 2338     will be shifted up towards the beginning of the FITS file
 2339     and the image data will be truncated to the new size.
 2340     This routine rewrites the BITPIX, NAXIS, and NAXISn keywords
 2341     with the appropriate values for new image. The FTRSIMLL routine is identical
 2342     to the FTRSIM routine except that the 4th parameter (the length
 2343     of each axis) is an array of 64-bit integers rather than an array
 2344    of 32-bit integers.
 2345 \end{description}
 2346 
 2347 \begin{verbatim}
 2348         FTRSIM(unit,bitpix,naxis,naxes,status)
 2349         FTRSIMLL(unit,bitpix,naxis,naxesll,status)
 2350 \end{verbatim}
 2351 
 2352 \begin{description}
 2353 \item[12] Delete the CHDU in the FITS file.  Any following HDUs will be shifted
 2354     forward in the file, to fill in the gap created by the deleted
 2355     HDU.  In the case of deleting the primary array (the first HDU in
 2356     the file) then the current primary array will be replace by a null
 2357     primary array containing the minimum set of required keywords and
 2358     no data.  If there are more extensions in the file following the
 2359     one that is deleted, then the the CHDU will be redefined to point
 2360     to the following extension.  If there are no following extensions
 2361     then the CHDU will be redefined to point to the previous HDU.  The
 2362     output HDUTYPE parameter indicates the type of the new CHDU after
 2363    the previous CHDU has been deleted.
 2364 \end{description}
 2365 
 2366 \begin{verbatim}
 2367         FTDHDU(unit, > hdutype,status)
 2368 \end{verbatim}
 2369 
 2370 \begin{description}
 2371 \item[13]  Copy all or part of the input FITS file and append it
 2372     to the end of the output FITS file.  If 'previous' (an integer parameter) is
 2373     not equal to 0, then any HDUs preceding the current HDU in the input file
 2374     will be copied to the output file.  Similarly, 'current' and 'following'
 2375     determine whether the current HDU, and/or any following HDUs in the input
 2376     file will be copied to the output file. If all 3 parameters are not equal
 2377     to zero, then the entire input file will be copied.  On return, the current
 2378     HDU in the input file will be unchanged, and the last copied HDU will be the
 2379    current HDU in the output file.
 2380 \end{description}
 2381 
 2382 \begin{verbatim}
 2383         FTCPFL(iunit, ounit, previous, current, following, > status)
 2384 \end{verbatim}
 2385 
 2386 \begin{description}
 2387 \item[14] Copy the entire CHDU from the FITS file associated with IUNIT to the CHDU
 2388     of the FITS file associated with OUNIT. The output HDU must be empty and
 2389     not already contain any keywords.  Space will be reserved for MOREKEYS
 2390     additional  keywords in the output header if there is not already enough
 2391    space.
 2392 \end{description}
 2393 
 2394 \begin{verbatim}
 2395         FTCOPY(iunit,ounit,morekeys, > status)
 2396 \end{verbatim}
 2397 
 2398 \begin{description}
 2399 \item[15] Copy the header (and not the data) from the CHDU associated with inunit
 2400     to the CHDU associated with outunit.  If the current output HDU
 2401     is not completely empty, then the CHDU will be closed and a new
 2402     HDU will be appended to the output file.  This routine will automatically
 2403     transform the necessary keywords when copying a primary array to
 2404     and image extension, or an image extension to a primary array.
 2405    An empty output data unit will be created (all values = 0).
 2406 \end{description}
 2407 
 2408 \begin{verbatim}
 2409         FTCPHD(inunit, outunit, > status)
 2410 \end{verbatim}
 2411 
 2412 \begin{description}
 2413 \item[16] Copy just the data from the CHDU associated with IUNIT
 2414     to the CHDU associated with OUNIT. This will overwrite
 2415     any data previously in the OUNIT CHDU.  This low level routine is used
 2416     by FTCOPY, but it may also be useful in certain application programs
 2417     which want to copy the data from one FITS file to another but also
 2418     want to modify the header keywords in the process. all the required
 2419     header keywords must be written to the OUNIT CHDU before calling
 2420    this routine
 2421 \end{description}
 2422 
 2423 \begin{verbatim}
 2424         FTCPDT(iunit,ounit, > status)
 2425 \end{verbatim}
 2426 
 2427 
 2428 \section{Define or Redefine the structure of the CHDU \label{FTRDEF}}
 2429 
 2430 It should rarely be necessary to call the subroutines in this section.
 2431 FITSIO internally calls these routines whenever necessary, so any calls
 2432 to these routines by application programs will likely be redundant.
 2433 
 2434 
 2435 \begin{description}
 2436 \item[1 ] This routine forces FITSIO to scan the current header keywords that
 2437     define the structure of the HDU (such as the NAXISn, PCOUNT and GCOUNT
 2438     keywords) so that it can initialize the internal buffers that describe
 2439     the HDU structure.  This routine may be used instead of the more
 2440     complicated calls to ftpdef, ftadef or ftbdef.  This routine is
 2441     also very useful for reinitializing the structure of an HDU,
 2442     if the number of rows in a table, as specified by the NAXIS2 keyword,
 2443    has been modified from its initial value.
 2444 \end{description}
 2445 
 2446 \begin{verbatim}
 2447         FTRDEF(unit, > status)   (DEPRECATED)
 2448 \end{verbatim}
 2449 
 2450 \begin{description}
 2451 \item[2 ]Define the structure of the primary array or IMAGE extension.  When
 2452    writing GROUPed FITS files that by convention set the NAXIS1 keyword
 2453    equal to 0, ftpdef must be called with naxes(1) = 1, NOT 0, otherwise
 2454    FITSIO will report an error status=308 when trying to write data
 2455    to a group. Note: it is usually simpler to call FTRDEF rather
 2456   than this routine.
 2457 \end{description}
 2458 
 2459 \begin{verbatim}
 2460         FTPDEF(unit,bitpix,naxis,naxes,pcount,gcount, > status)  (DEPRECATED)
 2461 \end{verbatim}
 2462 
 2463 \begin{description}
 2464 \item[3 ] Define the structure of an ASCII table (TABLE) extension. Note: it
 2465    is usually simpler to call FTRDEF rather than this routine.
 2466 \end{description}
 2467 
 2468 \begin{verbatim}
 2469         FTADEF(unit,rowlen,tfields,tbcol,tform,nrows > status) (DEPRECATED)
 2470 \end{verbatim}
 2471 
 2472 \begin{description}
 2473 \item[4 ] Define the structure of a binary table (BINTABLE) extension. Note: it
 2474    is usually simpler to call FTRDEF rather than this routine.
 2475 \end{description}
 2476 
 2477 \begin{verbatim}
 2478         FTBDEF(unit,tfields,tform,varidat,nrows > status) (DEPRECATED)
 2479 \end{verbatim}
 2480 
 2481 \begin{description}
 2482 \item[5 ] Define the size of the Current Data Unit, overriding the length
 2483     of the data unit as previously defined by ftpdef, ftadef, or ftbdef.
 2484     This is useful if one does not know the total size of the data unit until
 2485     after the data have been written.  The size (in bytes) of an ASCII or
 2486     Binary table is given by NAXIS1 * NAXIS2.  (Note that to determine the
 2487     value of NAXIS1 it is often more convenient to read the value of the
 2488     NAXIS1 keyword from the output file, rather than computing the row
 2489     length directly from all the TFORM keyword values).  Note: it
 2490    is usually simpler to call FTRDEF rather than this routine.
 2491 \end{description}
 2492 
 2493 \begin{verbatim}
 2494         FTDDEF(unit,bytlen, > status) (DEPRECATED)
 2495 \end{verbatim}
 2496 
 2497 \begin{description}
 2498 \item[6 ] Define the zero indexed byte offset of the 'heap' measured from
 2499     the start of the binary table data.  By default the heap is assumed
 2500     to start immediately following the regular table data, i.e., at
 2501     location NAXIS1 x NAXIS2.  This routine is only relevant for
 2502     binary tables which contain variable length array columns (with
 2503     TFORMn = 'Pt').  This subroutine also automatically writes
 2504     the value of theap to a keyword in the extension header.  This
 2505     subroutine must be called after the required keywords have been
 2506     written (with ftphbn) and after the table structure has been defined
 2507    (with ftbdef) but before any data is written to the table.
 2508 \end{description}
 2509 
 2510 \begin{verbatim}
 2511         FTPTHP(unit,theap, > status)
 2512 \end{verbatim}
 2513 
 2514 
 2515 \section{FITS Header I/O Subroutines}
 2516 
 2517 
 2518 \subsection{Header Space and Position Routines \label{FTHDEF}}
 2519 
 2520 
 2521 \begin{description}
 2522 \item[1 ] Reserve space in the CHU for MOREKEYS more header keywords.
 2523     This subroutine may be called to reserve space for keywords which are
 2524     to be written at a later time, after the data unit or subsequent
 2525     extensions have been written to the FITS file.  If this subroutine is
 2526     not explicitly called, then the initial size of the FITS header will be
 2527     limited to the space available at the time that  the first data is written
 2528     to the associated data unit.   FITSIO has the ability to dynamically
 2529     add more space to the header if needed, however it is more efficient
 2530    to preallocate the required space if the size is known in advance.
 2531 \end{description}
 2532 
 2533 \begin{verbatim}
 2534         FTHDEF(unit,morekeys, > status)
 2535 \end{verbatim}
 2536 
 2537 \begin{description}
 2538 \item[2 ] Return the number of existing keywords in the CHU (NOT including the
 2539     END keyword which is not considered a real keyword) and the remaining
 2540     space available to write additional keywords in the CHU.  (returns
 2541     KEYSADD = -1 if the header has not yet been closed).
 2542     Note that FITSIO will attempt to dynamically add space for more
 2543    keywords if required when appending new keywords to a header.
 2544 \end{description}
 2545 
 2546 \begin{verbatim}
 2547         FTGHSP(iunit, > keysexist,keysadd,status)
 2548 \end{verbatim}
 2549 
 2550 \begin{description}
 2551 \item[3 ] Return the number of keywords in the header and the current position
 2552     in the header.  This returns the number of the keyword record that
 2553     will be read next (or one greater than the position of the last keyword
 2554     that was read or written). A value of 1 is returned if the pointer is
 2555    positioned at the beginning of the header.
 2556 \end{description}
 2557 
 2558 \begin{verbatim}
 2559         FTGHPS(iunit, > keysexist,key_no,status)
 2560 \end{verbatim}
 2561 
 2562 \subsection{Read or Write Standard Header Routines \label{FTPHPR}}
 2563 
 2564 These subroutines provide a simple method of reading or writing most of
 2565 the keyword values that are normally required in a FITS files.  These
 2566 subroutines are provided for convenience only and are not required to
 2567 be used.  If preferred, users may call the lower-level subroutines
 2568 described in the previous section to individually read or write the
 2569 required keywords.  Note that in most cases, the required keywords such
 2570 as NAXIS, TFIELD, TTYPEn, etc, which define the structure of the HDU
 2571 must be written to the header before any data can be written to the
 2572 image or table.
 2573 
 2574 
 2575 \begin{description}
 2576 \item[1 ] Put the primary header or IMAGE extension keywords into the CHU.
 2577 There are 2 available routines: The simpler FTPHPS routine is
 2578 equivalent to calling ftphpr with the default values of SIMPLE = true,
 2579 pcount = 0, gcount = 1, and EXTEND = true.  PCOUNT, GCOUNT and EXTEND
 2580 keywords are not required in the primary header and are only written if
 2581 pcount is not equal to zero, gcount is not equal to zero or one, and if
 2582 extend is TRUE, respectively.  When writing to an IMAGE extension, the
 2583 SIMPLE and EXTEND parameters are ignored.
 2584 \end{description}
 2585 
 2586 \begin{verbatim}
 2587         FTPHPS(unit,bitpix,naxis,naxes, > status)
 2588 
 2589         FTPHPR(unit,simple,bitpix,naxis,naxes,pcount,gcount,extend, > status)
 2590 \end{verbatim}
 2591 
 2592 \begin{description}
 2593 \item[2 ] Get primary header or IMAGE extension keywords from the CHU.  When
 2594     reading from an IMAGE extension the SIMPLE and EXTEND parameters are
 2595    ignored.
 2596 \end{description}
 2597 
 2598 \begin{verbatim}
 2599         FTGHPR(unit,maxdim, > simple,bitpix,naxis,naxes,pcount,gcount,extend,
 2600                status)
 2601 \end{verbatim}
 2602 
 2603 \begin{description}
 2604 \item[3 ] Put the ASCII table header keywords into the CHU. The optional
 2605 TUNITn and EXTNAME keywords are written only if the input string
 2606 values are not blank.
 2607 \end{description}
 2608 
 2609 \begin{verbatim}
 2610         FTPHTB(unit,rowlen,nrows,tfields,ttype,tbcol,tform,tunit,extname, >
 2611                status)
 2612 \end{verbatim}
 2613 
 2614 \begin{description}
 2615 \item[4 ] Get the ASCII table header keywords from the CHU
 2616 \end{description}
 2617 
 2618 \begin{verbatim}
 2619         FTGHTB(unit,maxdim, > rowlen,nrows,tfields,ttype,tbcol,tform,tunit,
 2620                extname,status)
 2621 \end{verbatim}
 2622 
 2623 \begin{description}
 2624 \item[5 ]Put the binary table header keywords into the CHU. The optional
 2625    TUNITn and EXTNAME keywords are written only if the input string
 2626    values are not blank.  The pcount parameter, which specifies the
 2627    size of the variable length array heap, should initially = 0;
 2628    FITSIO will automatically update the PCOUNT keyword value if any
 2629    variable length array data is written to the heap.  The TFORM keyword
 2630    value for variable length vector columns should have the form 'Pt(len)'
 2631    or '1Pt(len)' where `t' is the data type code letter (A,I,J,E,D, etc.)
 2632    and  `len' is an integer specifying the maximum length of the vectors
 2633    in that column (len must be greater than or equal to the longest
 2634    vector in the column).  If `len' is not specified when the table is
 2635    created (e.g., the input TFORMn value is just '1Pt') then FITSIO will
 2636    scan the column when the table is first closed and will append the
 2637    maximum length to the TFORM keyword value.  Note that if the table
 2638    is subsequently modified to increase the maximum length of the vectors
 2639    then the modifying program is responsible for also updating the TFORM
 2640   keyword value.
 2641 \end{description}
 2642 
 2643 
 2644 \begin{verbatim}
 2645         FTPHBN(unit,nrows,tfields,ttype,tform,tunit,extname,varidat, > status)
 2646 \end{verbatim}
 2647 
 2648 \begin{description}
 2649 \item[6 ]Get the binary table header keywords from the CHU
 2650 \end{description}
 2651 
 2652 \begin{verbatim}
 2653         FTGHBN(unit,maxdim, > nrows,tfields,ttype,tform,tunit,extname,varidat,
 2654                status)
 2655 \end{verbatim}
 2656 
 2657 \subsection{Write Keyword Subroutines \label{FTPREC}}
 2658 
 2659 
 2660 \begin{description}
 2661 \item[1 ]Put (append) an 80-character record into the CHU.
 2662 \end{description}
 2663 
 2664 \begin{verbatim}
 2665         FTPREC(unit,card, > status)
 2666 \end{verbatim}
 2667 
 2668 \begin{description}
 2669 \item[2 ] Put (append) a COMMENT keyword into the CHU.  Multiple COMMENT keywords
 2670    will be written if the input comment string is longer than 72 characters.
 2671 \end{description}
 2672 
 2673 \begin{verbatim}
 2674         FTPCOM(unit,comment, > status)
 2675 \end{verbatim}
 2676 
 2677 \begin{description}
 2678 \item[3 ]Put (append) a HISTORY keyword into the CHU.  Multiple HISTORY keywords
 2679    will be written if the input history string is longer than 72 characters.
 2680 \end{description}
 2681 
 2682 \begin{verbatim}
 2683         FTPHIS(unit,history, > status)
 2684 \end{verbatim}
 2685 
 2686 \begin{description}
 2687 \item[4 ] Put (append) the DATE keyword into the CHU.  The keyword value will contain
 2688     the current system date as a character string in 'dd/mm/yy' format. If
 2689     a DATE keyword already exists in the header, then this subroutine will
 2690    simply update the keyword value in-place with the current date.
 2691 \end{description}
 2692 
 2693 \begin{verbatim}
 2694         FTPDAT(unit, > status)
 2695 \end{verbatim}
 2696 
 2697 \begin{description}
 2698 \item[5 ] Put (append) a new keyword of the appropriate datatype into the CHU.
 2699     Note that FTPKYS will only write string values up to 68 characters in
 2700     length; longer strings will be truncated.  The FTPKLS routine can be
 2701     used to write longer strings, using a non-standard FITS convention.
 2702      The E and D versions of this routine have the added feature that
 2703      if the 'decimals' parameter is negative, then the 'G' display
 2704      format rather then the 'E' format will be used when constructing
 2705      the keyword value, taking the absolute value of 'decimals' for the
 2706      precision.  This will suppress trailing zeros, and will use a
 2707      fixed format rather than an exponential format,
 2708     depending on the magnitude of the value.
 2709 \end{description}
 2710 
 2711 \begin{verbatim}
 2712         FTPKY[JKLS](unit,keyword,keyval,comment, > status)
 2713         FTPKY[EDFG](unit,keyword,keyval,decimals,comment, > status)
 2714 \end{verbatim}
 2715 
 2716 \begin{description}
 2717 \item[6 ] Put (append) a string valued keyword into the CHU which may be longer
 2718     than 68 characters in length.  This uses the Long String Keyword
 2719     convention that is described in the "Usage Guidelines and Suggestions"
 2720     section of this document.  Since this uses a non-standard FITS
 2721     convention to encode the long keyword string, programs which use
 2722     this routine should also call the FTPLSW routine to add some COMMENT
 2723     keywords to warn users of the FITS file that this convention is
 2724     being used.  FTPLSW also writes a keyword called LONGSTRN to record
 2725     the version of the longstring convention that has been used, in case
 2726     a new convention is adopted at some point in the future.   If the
 2727     LONGSTRN keyword is already present in the header, then FTPLSW will
 2728    simply return and will not write duplicate keywords.
 2729 \end{description}
 2730 
 2731 \begin{verbatim}
 2732         FTPKLS(unit,keyword,keyval,comment, > status)
 2733         FTPLSW(unit, > status)
 2734 \end{verbatim}
 2735 
 2736 \begin{description}
 2737 \item[7 ] Put (append) a new keyword with an undefined, or null, value into the CHU.
 2738    The value string of the keyword is left blank in this case.
 2739 \end{description}
 2740 
 2741 \begin{verbatim}
 2742         FTPKYU(unit,keyword,comment, > status)
 2743 \end{verbatim}
 2744 
 2745 \begin{description}
 2746 \item[8 ] Put (append) a numbered sequence of keywords into the CHU.   One may
 2747     append the same comment to every keyword (and eliminate the need
 2748     to have an array of identical comment strings, one for each keyword) by
 2749     including the ampersand character as the last non-blank character in the
 2750     (first) COMMENTS string parameter.  This same string
 2751     will then be used for the comment field in all the keywords. (Note
 2752     that the SPP version of these routines only supports a single comment
 2753    string).
 2754 \end{description}
 2755 
 2756 \begin{verbatim}
 2757         FTPKN[JKLS](unit,keyroot,startno,no_keys,keyvals,comments, > status)
 2758         FTPKN[EDFG](unit,keyroot,startno,no_keys,keyvals,decimals,comments, >
 2759                    status)
 2760 \end{verbatim}
 2761 
 2762 \begin{description}
 2763 \item[9 ]Copy an indexed keyword from one HDU to another, modifying
 2764     the index number of the keyword name in the process.  For example,
 2765     this routine could read the TLMIN3 keyword from the input HDU
 2766     (by giving keyroot = "TLMIN" and innum = 3) and write it to the
 2767     output HDU with the keyword name TLMIN4 (by setting outnum = 4).
 2768     If the input keyword does not exist, then this routine simply
 2769    returns without indicating an error.
 2770 \end{description}
 2771 
 2772 \begin{verbatim}
 2773         FTCPKY(inunit, outunit, innum, outnum, keyroot, > status)
 2774 \end{verbatim}
 2775 
 2776 \begin{description}
 2777 \item[10] Put (append) a 'triple precision' keyword into the CHU in F28.16 format.
 2778     The floating point keyword value is constructed by concatenating the
 2779     input integer value with the input double precision fraction value
 2780     (which must have a value between 0.0 and 1.0). The FTGKYT routine should
 2781     be used to read this keyword value, because the other keyword reading
 2782    subroutines will not preserve the full precision of the value.
 2783 \end{description}
 2784 
 2785 \begin{verbatim}
 2786         FTPKYT(unit,keyword,intval,dblval,comment, > status)
 2787 \end{verbatim}
 2788 
 2789 \begin{description}
 2790 \item[11] Write keywords to the CHDU that are defined in an ASCII template file.
 2791    The format of the template file is described under the ftgthd
 2792   routine below.
 2793 \end{description}
 2794 
 2795 \begin{verbatim}
 2796         FTPKTP(unit, filename, > status)
 2797 \end{verbatim}
 2798 
 2799 \begin{description}
 2800 \item[12] Append the physical units string to an existing keyword.  This
 2801     routine uses a local convention, shown in the following example,
 2802     in which the keyword units are enclosed in square brackets in the
 2803    beginning of the keyword comment field.
 2804 \end{description}
 2805 
 2806 
 2807 \begin{verbatim}
 2808      VELOCITY=                 12.3 / [km/s] orbital speed
 2809 
 2810         FTPUNT(unit,keyword,units, > status)
 2811 \end{verbatim}
 2812 
 2813 \subsection{Insert Keyword Subroutines \label{FTIREC}}
 2814 
 2815 
 2816 \begin{description}
 2817 \item[1 ] Insert a new keyword record into the CHU at the specified position
 2818     (i.e., immediately preceding the (keyno)th keyword in the header.)
 2819     This 'insert record' subroutine is somewhat less efficient
 2820     then the 'append record' subroutine (FTPREC) described above because
 2821    the remaining keywords in the header have to be shifted down one slot.
 2822 \end{description}
 2823 
 2824 \begin{verbatim}
 2825         FTIREC(unit,key_no,card, > status)
 2826 \end{verbatim}
 2827 
 2828 \begin{description}
 2829 \item[2 ] Insert a new keyword into the CHU.  The new keyword is inserted
 2830     immediately following the last keyword that has been read from the header.
 2831     The FTIKLS subroutine works the same as the FTIKYS subroutine, except
 2832     it also supports long string values greater than 68 characters in length.
 2833     These 'insert keyword' subroutines are somewhat less efficient then
 2834     the 'append keyword' subroutines described above because the remaining
 2835    keywords in the header have to be shifted down one slot.
 2836 \end{description}
 2837 
 2838 \begin{verbatim}
 2839         FTIKEY(unit, card, > status)
 2840         FTIKY[JKLS](unit,keyword,keyval,comment, > status)
 2841         FTIKLS(unit,keyword,keyval,comment, > status)
 2842         FTIKY[EDFG](unit,keyword,keyval,decimals,comment, > status)
 2843 \end{verbatim}
 2844 
 2845 \begin{description}
 2846 \item[3 ] Insert a new keyword with an undefined, or null, value into the CHU.
 2847    The value string of the keyword is left blank in this case.
 2848 \end{description}
 2849 
 2850 \begin{verbatim}
 2851         FTIKYU(unit,keyword,comment, > status)
 2852 \end{verbatim}
 2853 
 2854 \subsection{Read Keyword Subroutines \label{FTGREC}}
 2855 
 2856 These routines return the value of the specified keyword(s).  Wild card
 2857 characters (*, ?, or \#) may be used when specifying the name of the keyword
 2858 to be read: a '?' will match any single character at that position in the
 2859 keyword name and a '*' will match any length (including zero) string of
 2860 characters.  The '\#' character will match any consecutive string of
 2861 decimal digits (0 - 9). Note that when a wild card is used in the input
 2862 keyword name, the routine will only search for a match from the current
 2863 header position to the end of the header.  It will not resume the search
 2864 from the top of the header back to the original header position as is done
 2865 when no wildcards are included in the keyword name.  If the desired
 2866 keyword string is 8-characters long (the maximum length of a keyword
 2867 name) then a '*' may be appended as the ninth character of the input
 2868 name to force the keyword search to stop at the end of the header
 2869 (e.g., 'COMMENT *' will search for the next COMMENT keyword).  The
 2870 ffgrec routine may be used to set the starting position when doing
 2871 wild card searches.
 2872 
 2873 
 2874 \begin{description}
 2875 \item[1 ]Get the nth 80-character header record from the CHU.  The first keyword
 2876    in the header is at key\_no = 1;  if key\_no = 0 then this subroutine
 2877    simple moves the internal pointer to the beginning of the header
 2878    so that subsequent keyword operations will start at the top of
 2879   the header; it also returns a blank card value in this case.
 2880 \end{description}
 2881 
 2882 \begin{verbatim}
 2883         FTGREC(unit,key_no, > card,status)
 2884 \end{verbatim}
 2885 
 2886 \begin{description}
 2887 \item[2 ] Get the name, value (as a string), and comment of the nth keyword in CHU.
 2888     This routine also checks that the returned keyword name (KEYWORD) contains
 2889     only legal ASCII characters.  Call FTGREC and FTPSVC to bypass this error
 2890    check.
 2891 \end{description}
 2892 
 2893 \begin{verbatim}
 2894         FTGKYN(unit,key_no, > keyword,value,comment,status)
 2895 \end{verbatim}
 2896 
 2897 \begin{description}
 2898 \item[3 ] Get the 80-character header record for the named keyword
 2899 \end{description}
 2900 
 2901 \begin{verbatim}
 2902         FTGCRD(unit,keyword, > card,status)
 2903 \end{verbatim}
 2904 
 2905 \begin{description}
 2906 \item[4 ] Get the next keyword whose name matches one of the strings in
 2907     'inclist' but does not match any of the strings in 'exclist'.
 2908     The strings in inclist and exclist may contain wild card characters
 2909     (*, ?, and \#) as described at the beginning of this section.
 2910     This routine searches from the current header position to the
 2911     end of the header, only, and does not continue the search from
 2912     the top of the header back to the original position.  The current
 2913     header position may be reset with the ftgrec routine.  Note
 2914     that nexc may be set = 0 if there are no keywords to be excluded.
 2915     This routine returns status = 202 if a matching
 2916    keyword is not found.
 2917 \end{description}
 2918 
 2919 \begin{verbatim}
 2920         FTGNXK(unit,inclist,ninc,exclist,nexc, > card,status)
 2921 \end{verbatim}
 2922 
 2923 \begin{description}
 2924 \item[5 ]  Get the literal keyword value as a character string.  Regardless
 2925      of the datatype of the keyword, this routine simply returns the
 2926      string of characters in the value field of the keyword along with
 2927     the comment field.
 2928 \end{description}
 2929 
 2930 \begin{verbatim}
 2931         FTGKEY(unit,keyword, > value,comment,status)
 2932 \end{verbatim}
 2933 
 2934 \begin{description}
 2935 \item[6 ] Get a keyword value (with the appropriate datatype) and comment from
 2936    the CHU
 2937 \end{description}
 2938 
 2939 \begin{verbatim}
 2940         FTGKY[EDJKLS](unit,keyword, > keyval,comment,status)
 2941 \end{verbatim}
 2942 
 2943 \begin{description}
 2944 \item[7 ] Read a string-valued keyword and return the string length, the value string,
 2945     and/or the comment field. The first routine, FTGKSL, simply
 2946     returns the length of the character string value of the specified keyword.
 2947     The second routine, FTGSKY, also returns up to maxchar characters
 2948     of the keyword value string, starting with the firstchar character,
 2949     and the keyword comment string.
 2950     The length argument returns the total length of the keyword value string
 2951     regardless of how much of the string is actually returned (which
 2952     depends on the value of the firstchar and maxchar arguments).  These
 2953     routines support string keywords that use the CONTINUE convention to
 2954     continue long string values over multiple FITS header records.  Normally,
 2955     string-valued keywords have a maximum length of 68 characters, however,
 2956    CONTINUE'd string keywords may be arbitrarily long.
 2957 \end{description}
 2958 
 2959 \begin{verbatim}
 2960        FTGKSL(unit,keyword, > length,status)
 2961        FTGSKY(unit,keyword,firstchar,maxchar,> keyval,length,comment,status)
 2962 \end{verbatim}
 2963 
 2964 \begin{description}
 2965 \item[8 ] Get a sequence of numbered keyword values.  These
 2966    routines do not support wild card characters in the root name.
 2967 \end{description}
 2968 
 2969 \begin{verbatim}
 2970         FTGKN[EDJKLS](unit,keyroot,startno,max_keys, > keyvals,nfound,status)
 2971 \end{verbatim}
 2972 
 2973 \begin{description}
 2974 \item[9 ] Get the value of a floating point keyword, returning the integer and
 2975     fractional parts of the value in separate subroutine arguments.
 2976     This subroutine may be used to read any keyword but is especially
 2977    useful for reading the 'triple precision' keywords written by FTPKYT.
 2978 \end{description}
 2979 
 2980 \begin{verbatim}
 2981         FTGKYT(unit,keyword, > intval,dblval,comment,status)
 2982 \end{verbatim}
 2983 
 2984 \begin{description}
 2985 \item[10]  Get the physical units string in an existing keyword.  This
 2986     routine uses a local convention, shown in the following example,
 2987     in which the keyword units are
 2988     enclosed in square brackets in the beginning of the keyword comment
 2989     field.  A blank string is returned if no units are defined
 2990     for the keyword.
 2991 \end{description}
 2992 
 2993 \begin{verbatim}
 2994     VELOCITY=                 12.3 / [km/s] orbital speed
 2995 
 2996         FTGUNT(unit,keyword, > units,status)
 2997 \end{verbatim}
 2998 
 2999 \subsection{Modify Keyword Subroutines \label{FTMREC}}
 3000 
 3001 Wild card characters, as described in the Read Keyword section, above,
 3002 may be used when specifying the name of the keyword to be modified.
 3003 
 3004 
 3005 \begin{description}
 3006 \item[1 ] Modify (overwrite) the nth 80-character header record in the CHU
 3007 \end{description}
 3008 
 3009 \begin{verbatim}
 3010         FTMREC(unit,key_no,card, > status)
 3011 \end{verbatim}
 3012 
 3013 \begin{description}
 3014 \item[2 ] Modify (overwrite) the 80-character header record for the named keyword
 3015     in the CHU.  This can be used to overwrite the name of the keyword as
 3016    well as its value and comment fields.
 3017 \end{description}
 3018 
 3019 \begin{verbatim}
 3020         FTMCRD(unit,keyword,card, > status)
 3021 \end{verbatim}
 3022 
 3023 \begin{description}
 3024 \item[3 ] Modify (overwrite) the name of an existing keyword in the CHU
 3025    preserving the current value and comment fields.
 3026 \end{description}
 3027 
 3028 \begin{verbatim}
 3029         FTMNAM(unit,oldkey,keyword, > status)
 3030 \end{verbatim}
 3031 
 3032 \begin{description}
 3033 \item[4 ] Modify (overwrite) the comment field of an existing keyword in the CHU
 3034 \end{description}
 3035 
 3036 \begin{verbatim}
 3037         FTMCOM(unit,keyword,comment, > status)
 3038 \end{verbatim}
 3039 
 3040 \begin{description}
 3041 \item[5 ] Modify the value and comment fields of an existing keyword in the CHU.
 3042     The FTMKLS subroutine works the same as the FTMKYS subroutine, except
 3043     it also supports long string values greater than 68 characters in length.
 3044     Optionally, one may modify only the value field and leave the comment
 3045     field unchanged by setting the input COMMENT parameter equal to
 3046     the ampersand character (\&).
 3047      The E and D versions of this routine have the added feature that
 3048      if the 'decimals' parameter is negative, then the 'G' display
 3049      format rather then the 'E' format will be used when constructing
 3050      the keyword value, taking the absolute value of 'decimals' for the
 3051      precision.  This will suppress trailing zeros, and will use a
 3052      fixed format rather than an exponential format,
 3053     depending on the magnitude of the value.
 3054 \end{description}
 3055 
 3056 \begin{verbatim}
 3057         FTMKY[JKLS](unit,keyword,keyval,comment, > status)
 3058         FTMKLS(unit,keyword,keyval,comment, > status)
 3059         FTMKY[EDFG](unit,keyword,keyval,decimals,comment, > status)
 3060 \end{verbatim}
 3061 
 3062 \begin{description}
 3063 \item[6 ] Modify the value of an existing keyword to be undefined, or null.
 3064     The value string of the keyword is set to blank.
 3065     Optionally, one may leave the comment field unchanged by setting the
 3066    input COMMENT parameter equal to the ampersand character (\&).
 3067 \end{description}
 3068 
 3069 \begin{verbatim}
 3070         FTMKYU(unit,keyword,comment, > status)
 3071 \end{verbatim}
 3072 
 3073 \subsection{Update Keyword Subroutines \label{FTUCRD}}
 3074 
 3075 
 3076 \begin{description}
 3077 \item[1 ] Update an 80-character record in the CHU.  If the specified keyword
 3078     already exists then that header record will be replaced with
 3079     the input CARD string.  If it does not exist then the new record will
 3080     be added to the header.
 3081     The FTUKLS subroutine works the same as the FTUKYS subroutine, except
 3082    it also supports long string values greater than 68 characters in length.
 3083 \end{description}
 3084 
 3085 \begin{verbatim}
 3086         FTUCRD(unit,keyword,card, > status)
 3087 \end{verbatim}
 3088 
 3089 \begin{description}
 3090 \item[2 ] Update the value and comment fields of a keyword in the CHU.
 3091     The specified keyword is modified if it already exists (by calling
 3092     FTMKYx) otherwise a new keyword is created by calling FTPKYx.
 3093      The E and D versions of this routine have the added feature that
 3094      if the 'decimals' parameter is negative, then the 'G' display
 3095      format rather then the 'E' format will be used when constructing
 3096      the keyword value, taking the absolute value of 'decimals' for the
 3097      precision.  This will suppress trailing zeros, and will use a
 3098      fixed format rather than an exponential format,
 3099     depending on the magnitude of the value.
 3100 \end{description}
 3101 
 3102 \begin{verbatim}
 3103         FTUKY[JKLS](unit,keyword,keyval,comment, > status)
 3104         FTUKLS(unit,keyword,keyval,comment, > status)
 3105         FTUKY[EDFG](unit,keyword,keyval,decimals,comment, > status)
 3106 \end{verbatim}
 3107 
 3108 \begin{description}
 3109 \item[3 ] Update the value of an existing keyword to be undefined, or null,
 3110     or insert a new undefined-value keyword if it doesn't already exist.
 3111    The value string of the keyword is left blank in this case.
 3112 \end{description}
 3113 
 3114 \begin{verbatim}
 3115         FTUKYU(unit,keyword,comment, > status)
 3116 \end{verbatim}
 3117 
 3118 \subsection{Delete Keyword Subroutines \label{FTDREC}}
 3119 
 3120 
 3121 \begin{description}
 3122 \item[1 ] Delete an existing keyword record.  The space previously occupied by
 3123     the keyword is reclaimed by moving all the following header records up
 3124     one row in the header.  The first routine deletes a keyword at a
 3125     specified position in the header (the first keyword is at position 1),
 3126     whereas the second routine deletes a specifically named keyword.
 3127     Wild card characters, as described in the Read Keyword section, above,
 3128     may be used when specifying the name of the keyword to be deleted
 3129    (be careful!).
 3130 \end{description}
 3131 
 3132 \begin{verbatim}
 3133         FTDREC(unit,key_no, > status)
 3134         FTDKEY(unit,keyword, > status)
 3135 \end{verbatim}
 3136 
 3137 
 3138 \section{Data Scaling and Undefined Pixel Parameters  \label{FTPSCL}}
 3139 
 3140 These subroutines define or modify the internal parameters used by
 3141 FITSIO to either scale the data or to represent undefined pixels.
 3142 Generally FITSIO will scale the data according to the values of the BSCALE
 3143 and BZERO (or TSCALn and TZEROn) keywords, however these subroutines
 3144 may be used to override the keyword values.  This may be useful when
 3145 one wants to read or write the raw unscaled values in the FITS file.
 3146 Similarly, FITSIO generally uses the value of the BLANK or TNULLn
 3147 keyword to signify an undefined pixel, but these routines may be used
 3148 to override this value.  These subroutines do not create or modify the
 3149 corresponding header keyword values.
 3150 
 3151 
 3152 \begin{description}
 3153 \item[1 ] Reset the scaling factors in the primary array or image extension; does
 3154     not change the BSCALE and BZERO keyword values and only affects the
 3155     automatic scaling performed when the data elements are written/read
 3156     to/from the FITS file.   When reading from a FITS file the returned
 3157     data value = (the value given in the FITS array) * BSCALE + BZERO.
 3158     The inverse formula is used when writing data values to the FITS
 3159     file.  (NOTE: BSCALE and BZERO must be declared as Double Precision
 3160    variables).
 3161 \end{description}
 3162 
 3163 \begin{verbatim}
 3164         FTPSCL(unit,bscale,bzero, > status)
 3165 \end{verbatim}
 3166 
 3167 \begin{description}
 3168 \item[2 ] Reset the scaling parameters for a table column; does not change
 3169     the TSCALn or TZEROn keyword values and only affects the automatic
 3170     scaling performed when the data elements are written/read to/from
 3171     the FITS file.  When reading from a FITS file the returned data
 3172     value = (the value given in the FITS array) * TSCAL + TZERO.  The
 3173     inverse formula is used when writing data values to the FITS file.
 3174     (NOTE: TSCAL and TZERO  must be declared as Double Precision
 3175    variables).
 3176 \end{description}
 3177 
 3178 \begin{verbatim}
 3179         FTTSCL(unit,colnum,tscal,tzero, > status)
 3180 \end{verbatim}
 3181 
 3182 \begin{description}
 3183 \item[3 ] Define the integer value to be used to signify undefined pixels in the
 3184     primary array or image extension.  This is only used if BITPIX = 8, 16,
 3185     32. or 64  This does not create or change the value of the BLANK keyword in
 3186     the header. FTPNULLL is identical to FTPNUL except that the blank
 3187    value is a 64-bit integer instead of a 32-bit integer.
 3188 \end{description}
 3189 
 3190 \begin{verbatim}
 3191         FTPNUL(unit,blank, > status)
 3192         FTPNULLL(unit,blankll, > status)
 3193 \end{verbatim}
 3194 
 3195 \begin{description}
 3196 \item[4 ] Define the string to be used to signify undefined pixels in
 3197     a column in an ASCII table.  This does not create or change the value
 3198    of the TNULLn keyword.
 3199 \end{description}
 3200 
 3201 \begin{verbatim}
 3202         FTSNUL(unit,colnum,snull > status)
 3203 \end{verbatim}
 3204 
 3205 \begin{description}
 3206 \item[5 ] Define the value to be used to signify undefined pixels in
 3207     an integer column in a binary table (where TFORMn = 'B', 'I', 'J', or 'K').
 3208     This does not create or  change the value of the TNULLn keyword.
 3209     FTTNULLL is identical to FTTNUL except that the tnull
 3210    value is a 64-bit integer instead of a 32-bit integer.
 3211 \end{description}
 3212 
 3213 \begin{verbatim}
 3214         FTTNUL(unit,colnum,tnull > status)
 3215         FTTNULLL(unit,colnum,tnullll > status)
 3216 \end{verbatim}
 3217 
 3218 
 3219 \section{FITS Primary Array or IMAGE Extension I/O Subroutines \label{FTPPR}}
 3220 
 3221     These subroutines put or get data values in the primary data array
 3222 (i.e., the first HDU in the FITS file) or an IMAGE extension.  The
 3223 data array is represented as a single one-dimensional array of
 3224 pixels regardless of the actual dimensionality of the array, and the
 3225 FPIXEL parameter gives the position within this 1-D array of the first
 3226 pixel to read  or write.  Automatic data type conversion is performed
 3227 for numeric data (except for complex data types) if the data type of
 3228 the primary array (defined by the BITPIX keyword) differs from the data
 3229 type of the array in the calling subroutine.  The data values are also
 3230 scaled by the BSCALE and BZERO header values as they are being written
 3231 or read from the FITS array.  The ftpscl subroutine MUST be
 3232 called to define the scaling parameters when writing data to the FITS
 3233 array or to override the default scaling value given in the header when
 3234 reading the FITS array.
 3235 
 3236     Two sets of subroutines are provided to read the data array which
 3237 differ in the way undefined pixels are handled.  The first set of
 3238 routines (FTGPVx) simply return an array of data elements in which
 3239 undefined pixels are set equal to a value specified by the user in the
 3240 'nullval' parameter.  An additional feature of these subroutines is
 3241 that if the user sets nullval = 0, then no checks for undefined pixels
 3242 will be performed, thus increasing the speed of the program.  The
 3243 second set of routines (FTGPFx) returns the data element array and, in
 3244 addition, a logical array which defines whether the corresponding data
 3245 pixel is undefined.  The latter set of subroutines may be more
 3246 convenient to use in some circumstances, however, it requires an
 3247 additional array of logical values which can be unwieldy when working
 3248 with large data arrays.  Also for programmer convenience, sets of
 3249 subroutines to directly read or write 2 and 3 dimensional arrays  have
 3250 been provided, as well as a set of subroutines to read or write any
 3251 contiguous rectangular subset of pixels within the n-dimensional array.
 3252 
 3253 
 3254 \begin{description}
 3255 \item[1 ] Get the data type of the image (= BITPIX value).  Possible returned
 3256     values are: 8, 16, 32, 64, -32, or -64 corresponding to unsigned byte,
 3257     signed 2-byte integer, signed 4-byte integer, signed 8-byte integer,
 3258     real, and double.
 3259 
 3260     The second subroutine is similar to FTGIDT, except that if the image
 3261     pixel values are scaled, with non-default values for the BZERO and
 3262     BSCALE keywords, then this routine will return the 'equivalent'
 3263     data type that is needed to store the scaled values.  For example,
 3264     if BITPIX = 16 and BSCALE = 0.1 then the equivalent data type is
 3265     floating point, and -32 will be returned.  There are 2 special cases:
 3266     if the image contains unsigned 2-byte integer values, with BITPIX =
 3267     16, BSCALE = 1, and BZERO = 32768, then this routine will return
 3268     a non-standard value of 20 for the bitpix value.  Similarly if the
 3269     image contains unsigned 4-byte integers, then bitpix will
 3270    be returned with a value of 40.
 3271 \end{description}
 3272 
 3273 
 3274 \begin{verbatim}
 3275         FTGIDT(unit, > bitpix,status)
 3276         FTGIET(unit, > bitpix,status)
 3277 \end{verbatim}
 3278 
 3279 \begin{description}
 3280 \item[2 ] Get the dimension (number of axes = NAXIS) of the image
 3281 \end{description}
 3282 
 3283 \begin{verbatim}
 3284         FTGIDM(unit, > naxis,status)
 3285 \end{verbatim}
 3286 
 3287 \begin{description}
 3288 \item[3 ]  Get the size of all the dimensions of the image. The FTGISZLL
 3289     routine returns an array of 64-bit integers instead of 32-bit integers.
 3290 \end{description}
 3291 
 3292 \begin{verbatim}
 3293         FTGISZ(unit, maxdim, > naxes,status)
 3294         FTGISZLL(unit, maxdim, > naxesll,status)
 3295 \end{verbatim}
 3296 
 3297 \begin{description}
 3298 \item[4 ]  Get the parameters that define the type and size of the image.  This
 3299      routine simply combines calls to the above 3 routines. The FTGIPRLL
 3300     routine returns an array of 64-bit integers instead of 32-bit integers.
 3301 \end{description}
 3302 
 3303 
 3304 \begin{verbatim}
 3305         FTGIPR(unit, maxdim, > bitpix, naxis, naxes, int *status)
 3306         FTGIPRLL(unit, maxdim, > bitpix, naxis, naxesll, int *status)
 3307 \end{verbatim}
 3308 
 3309 \begin{description}
 3310 \item[5 ]Put elements into the data array
 3311 \end{description}
 3312 
 3313 \begin{verbatim}
 3314         FTPPR[BIJKED](unit,group,fpixel,nelements,values, > status)
 3315 \end{verbatim}
 3316 
 3317 \begin{description}
 3318 \item[6 ]Put elements into the data array, substituting the appropriate FITS null
 3319    value for all elements which are equal to the value of NULLVAL.  For
 3320    integer FITS arrays, the null value defined by the previous call to FTPNUL
 3321    will be substituted;  for floating point FITS arrays (BITPIX = -32
 3322    or -64) then the special IEEE NaN (Not-a-Number) value will be
 3323   substituted.
 3324 \end{description}
 3325 
 3326 \begin{verbatim}
 3327         FTPPN[BIJKED](unit,group,fpixel,nelements,values,nullval > status)
 3328 \end{verbatim}
 3329 
 3330 \begin{description}
 3331 \item[7 ]Set data array elements as undefined
 3332 \end{description}
 3333 
 3334 \begin{verbatim}
 3335         FTPPRU(unit,group,fpixel,nelements, > status)
 3336 \end{verbatim}
 3337 
 3338 \begin{description}
 3339 \item[8 ] Get elements from the data array.  Undefined array elements will be
 3340     returned with a value = nullval, unless nullval = 0 in which case no
 3341    checks for undefined pixels will be performed.
 3342 \end{description}
 3343 
 3344 \begin{verbatim}
 3345         FTGPV[BIJKED](unit,group,fpixel,nelements,nullval, > values,anyf,status)
 3346 \end{verbatim}
 3347 
 3348 \begin{description}
 3349 \item[9 ] Get elements and nullflags from data array.
 3350     Any undefined array elements will have the corresponding flagvals element
 3351    set equal to .TRUE.
 3352 \end{description}
 3353 
 3354 \begin{verbatim}
 3355         FTGPF[BIJKED](unit,group,fpixel,nelements, > values,flagvals,anyf,status)
 3356 \end{verbatim}
 3357 
 3358 \begin{description}
 3359 \item[10]  Put values into group parameters
 3360 \end{description}
 3361 
 3362 \begin{verbatim}
 3363         FTPGP[BIJKED](unit,group,fparm,nparm,values, > status)
 3364 \end{verbatim}
 3365 
 3366 \begin{description}
 3367 \item[11]  Get values from group parameters
 3368 \end{description}
 3369 
 3370 \begin{verbatim}
 3371         FTGGP[BIJKED](unit,group,fparm,nparm, > values,status)
 3372 \end{verbatim}
 3373 The following 4 subroutines transfer FITS images with 2 or 3 dimensions
 3374 to or from a data array which has been declared in the calling program.
 3375 The dimensionality of the FITS image is passed by the naxis1, naxis2,
 3376 and naxis3 parameters and the declared dimensions of the program array
 3377 are passed in the dim1 and dim2 parameters.  Note that the program array
 3378 does not have to have the same dimensions as the FITS array, but must
 3379 be at least as big.  For example if a FITS image with NAXIS1 = NAXIS2 = 400
 3380 is read into a program array which is dimensioned as 512 x 512 pixels,
 3381 then the image will just fill the lower left corner of the array
 3382 with pixels in the range 1 - 400 in the X an Y directions.  This has
 3383 the effect of taking a contiguous set of pixel value in the FITS array
 3384 and writing them to a non-contiguous array in program memory
 3385 (i.e., there are now some blank pixels around the edge of the image
 3386 in the program array).
 3387 
 3388 
 3389 \begin{description}
 3390 \item[11]  Put 2-D image into the data array
 3391 \end{description}
 3392 
 3393 \begin{verbatim}
 3394         FTP2D[BIJKED](unit,group,dim1,naxis1,naxis2,image, > status)
 3395 \end{verbatim}
 3396 
 3397 \begin{description}
 3398 \item[12]  Put 3-D cube into the data array
 3399 \end{description}
 3400 
 3401 \begin{verbatim}
 3402         FTP3D[BIJKED](unit,group,dim1,dim2,naxis1,naxis2,naxis3,cube, > status)
 3403 \end{verbatim}
 3404 
 3405 \begin{description}
 3406 \item[13]  Get 2-D image from the data array.  Undefined
 3407      pixels in the array will be set equal to the value of 'nullval',
 3408      unless nullval=0 in which case no testing for undefined pixels will
 3409     be performed.
 3410 \end{description}
 3411 
 3412 \begin{verbatim}
 3413         FTG2D[BIJKED](unit,group,nullval,dim1,naxis1,naxis2, > image,anyf,status)
 3414 \end{verbatim}
 3415 
 3416 \begin{description}
 3417 \item[14] Get 3-D cube from the data array.   Undefined
 3418     pixels in the array will be set equal to the value of 'nullval',
 3419     unless nullval=0 in which case no testing for undefined pixels will
 3420    be performed.
 3421 \end{description}
 3422 
 3423 \begin{verbatim}
 3424         FTG3D[BIJKED](unit,group,nullval,dim1,dim2,naxis1,naxis2,naxis3, >
 3425                      cube,anyf,status)
 3426 \end{verbatim}
 3427 
 3428 The following subroutines transfer a rectangular subset of the pixels
 3429 in a FITS N-dimensional image to or from an array which has been
 3430 declared in the calling program.  The fpixels and lpixels parameters
 3431 are integer arrays which specify the starting and ending pixels in each
 3432 dimension of the FITS image that are to be read or written.  (Note that
 3433 these are the starting and ending pixels in the FITS image, not in the
 3434 declared array). The array parameter is treated simply as a large
 3435 one-dimensional array of the appropriate datatype containing the pixel
 3436 values; The pixel values in the FITS array are read/written  from/to
 3437 this program array in strict sequence without any gaps;  it is up to
 3438 the calling routine to correctly interpret the dimensionality of this
 3439 array.  The two families of FITS reading routines (FTGSVx and FTGSFx
 3440 subroutines) also have an 'incs' parameter which defines the
 3441 data sampling interval in each dimension of the FITS array.  For
 3442 example, if incs(1)=2 and incs(2)=3 when reading a 2-dimensional
 3443 FITS image, then only every other pixel in the first dimension
 3444 and every 3rd pixel in the second dimension will be returned in
 3445 the 'array' parameter. [Note: the FTGSSx family of routines which
 3446 were present in previous versions of FITSIO have been superseded
 3447 by the more general FTGSVx family of routines.]
 3448 
 3449 
 3450 \begin{description}
 3451 \item[15]   Put an arbitrary data subsection into the data array.
 3452 \end{description}
 3453 
 3454 \begin{verbatim}
 3455         FTPSS[BIJKED](unit,group,naxis,naxes,fpixels,lpixels,array, > status)
 3456 \end{verbatim}
 3457 
 3458 \begin{description}
 3459 \item[16]    Get an arbitrary data subsection from the data array.  Undefined
 3460        pixels in the array will be set equal to the value of 'nullval',
 3461        unless nullval=0 in which case no testing for undefined pixels will
 3462       be performed.
 3463 \end{description}
 3464 
 3465 \begin{verbatim}
 3466         FTGSV[BIJKED](unit,group,naxis,naxes,fpixels,lpixels,incs,nullval, >
 3467                      array,anyf,status)
 3468 \end{verbatim}
 3469 
 3470 \begin{description}
 3471 \item[17]    Get an arbitrary data subsection from the data array.  Any Undefined
 3472        pixels in the array will have the corresponding 'flagvals'
 3473       element set equal to .TRUE.
 3474 \end{description}
 3475 
 3476 \begin{verbatim}
 3477         FTGSF[BIJKED](unit,group,naxis,naxes,fpixels,lpixels,incs, >
 3478                      array,flagvals,anyf,status)
 3479 \end{verbatim}
 3480 
 3481 
 3482 \section{FITS ASCII and Binary Table Data I/O Subroutines}
 3483 
 3484 
 3485 \subsection{Column Information Subroutines \label{FTGCNO}}
 3486 
 3487 
 3488 \begin{description}
 3489 \item[1 ]  Get the number of rows or columns in the current FITS table.
 3490      The number of rows is given by the NAXIS2 keyword and the
 3491      number of columns is given by the TFIELDS keyword in the header
 3492      of the table.  The FTGNRWLL routine is identical to FTGNRW except
 3493      that the number of rows is returned as a 64-bit integer rather
 3494     than a 32-bit integer.
 3495 \end{description}
 3496 
 3497 \begin{verbatim}
 3498         FTGNRW(unit, > nrows, status)
 3499         FTGNRWLL(unit, > nrowsll, status)
 3500         FTGNCL(unit, > ncols, status)
 3501 \end{verbatim}
 3502 
 3503 \begin{description}
 3504 \item[2 ] Get the table column number (and name) of the column whose name
 3505 matches an input template name.  The table column names are defined by
 3506 the TTYPEn keywords in the FITS header.  If a column does not have a
 3507 TTYPEn keyword, then these routines assume that the name consists of
 3508 all blank characters.  These 2 subroutines perform the same function
 3509 except that FTGCNO only returns the number of the matching column whereas
 3510 FTGCNN also returns the name of the column.  If CASESEN = .true. then
 3511 the column name match will be case-sensitive.
 3512 
 3513 The input column name template (COLTEMPLATE) is (1) either the exact
 3514 name of the column to be searched for, or (2) it may contain wild cards
 3515 characters (*, ?, or \#), or (3) it may contain the number of the desired
 3516 column (where the number is expressed as ASCII digits).  The first 2 wild
 3517 cards behave similarly to UNIX filename matching:  the '*' character matches
 3518 any sequence of characters (including zero characters) and the '?'
 3519 character matches any single character.  The \# wildcard will match
 3520 any consecutive string of decimal digits (0-9).  As an example, the template
 3521 strings 'AB?DE', 'AB*E', and 'AB*CDE' will all match the string
 3522 'ABCDE'.  If more than one column name in the table matches the
 3523 template string, then the first match is returned and the status value
 3524 will be set to 237 as a warning that a unique match was not found.  To
 3525 find the other cases that match the template, simply call the
 3526 subroutine again leaving the input status value equal to  237 and the
 3527 next matching name will then be returned.  Repeat this process until a
 3528 status = 219 (column name not found) is returned.  If these subroutines
 3529 fail to match the template to any of the columns in the table, they
 3530 lastly check if the template can be interpreted as a simple positive
 3531 integer (e.g., '7', or '512') and if so, they return that column
 3532 number.  If no matches are found then a status = 219 error is
 3533 returned.
 3534 
 3535 Note that the FITS Standard recommends that only letters, digits, and
 3536 the underscore character be used in column names (with no embedded
 3537 spaces in the name).  Trailing blank characters are not significant.
 3538 \end{description}
 3539 
 3540 \begin{verbatim}
 3541         FTGCNO(unit,casesen,coltemplate, > colnum,status)
 3542         FTGCNN(unit,casesen,coltemplate, > colname,colnum,status)
 3543 \end{verbatim}
 3544 
 3545 \begin{description}
 3546 \item[3 ] Get the datatype of a column in an ASCII or binary table.  This
 3547     routine returns an integer code value corresponding to the datatype
 3548     of the column. (See the FTBNFM and FTASFM subroutines in the Utilities
 3549     section of this document for a list of the code values).  The vector
 3550     repeat count (which is alway 1 for ASCII table columns) is also returned.
 3551     If the specified column has an ASCII character datatype (code = 16) then
 3552     the width of a unit string in the column is also returned.  Note that
 3553     this routine supports the local convention for specifying arrays of
 3554     strings within a binary table character column, using the syntax
 3555     TFORM = 'rAw' where 'r' is the total number of characters (= the width
 3556     of the column) and 'w' is the width of a unit string within the column.
 3557     Thus if the column has TFORM = '60A12' then this routine will return
 3558     datacode = 16, repeat = 60, and width = 12.  (The TDIMn
 3559     keyword may also be used to specify the unit string length; The pair
 3560     of keywords TFORMn = '60A' and TDIMn = '(12,5)'  would have the
 3561     same effect as TFORMn = '60A12').
 3562 
 3563    The second routine, FTEQTY is similar except that in
 3564    the case of scaled integer columns it returns the 'equivalent' data
 3565    type that is needed to store the scaled values, and not necessarily
 3566    the physical data type of the unscaled values as stored in the FITS
 3567    table.  For example if a '1I' column in a binary table has TSCALn =
 3568    1 and TZEROn = 32768, then this column effectively contains unsigned
 3569    short integer values, and thus the returned value of typecode will
 3570    be the code for an unsigned short integer, not a signed short integer.
 3571    Similarly, if a column has TTYPEn = '1I'
 3572    and TSCALn = 0.12, then the returned typecode
 3573   will be the code for a 'real' column.
 3574 \end{description}
 3575 
 3576 \begin{verbatim}
 3577         FTGTCL(unit,colnum, > datacode,repeat,width,status)
 3578         FTEQTY(unit,colnum, > datacode,repeat,width,status)
 3579 \end{verbatim}
 3580 
 3581 \begin{description}
 3582 \item[4 ] Return the display width of a column.  This is the length
 3583     of the string that will be returned
 3584     when reading the column as a formatted string.  The display width is
 3585     determined by the TDISPn keyword, if present, otherwise by the data
 3586    type of the column.
 3587 \end{description}
 3588 
 3589 \begin{verbatim}
 3590         FTGCDW(unit, colnum, > dispwidth, status)
 3591 \end{verbatim}
 3592 
 3593 \begin{description}
 3594 \item[5 ] Get information about an existing ASCII table column.  (NOTE: TSCAL and
 3595     TZERO must be declared as Double Precision variables).  All the
 3596    returned parameters are scalar quantities.
 3597 \end{description}
 3598 
 3599 \begin{verbatim}
 3600         FTGACL(unit,colnum, >
 3601                ttype,tbcol,tunit,tform,tscal,tzero,snull,tdisp,status)
 3602 \end{verbatim}
 3603 
 3604 \begin{description}
 3605 \item[6 ] Get information about an existing binary table column. (NOTE: TSCAL and
 3606     TZERO must be declared as Double Precision variables). DATATYPE is a
 3607     character string which returns the datatype of the column as defined
 3608     by the TFORMn keyword (e.g., 'I', 'J','E', 'D', etc.).  In the case
 3609     of an ASCII character column, DATATYPE will have a value of the
 3610     form 'An' where 'n' is an integer expressing the width of the field
 3611     in characters.  For example, if TFORM = '160A8' then FTGBCL will return
 3612     DATATYPE='A8' and REPEAT=20.   All the returned parameters are scalar
 3613    quantities.
 3614 \end{description}
 3615 
 3616 \begin{verbatim}
 3617         FTGBCL(unit,colnum, >
 3618                ttype,tunit,datatype,repeat,tscal,tzero,tnull,tdisp,status)
 3619 \end{verbatim}
 3620 
 3621 \begin{description}
 3622 \item[7 ] Put (append) a TDIMn keyword whose value has the form '(l,m,n...)'
 3623     where l, m, n... are the dimensions of a multidimensional array
 3624    column in a binary table.
 3625 \end{description}
 3626 
 3627 \begin{verbatim}
 3628         FTPTDM(unit,colnum,naxis,naxes, > status)
 3629 \end{verbatim}
 3630 
 3631 \begin{description}
 3632 \item[8 ] Return the number of and size of the dimensions of a table column.
 3633     Normally this information is given by the TDIMn keyword, but if
 3634     this keyword is not present then this routine returns NAXIS = 1
 3635    and NAXES(1) equal to the repeat count in the TFORM keyword.
 3636 \end{description}
 3637 
 3638 \begin{verbatim}
 3639         FTGTDM(unit,colnum,maxdim, > naxis,naxes,status)
 3640 \end{verbatim}
 3641 
 3642 \begin{description}
 3643 \item[9 ] Decode the input TDIMn keyword string (e.g. '(100,200)') and return the
 3644     number of and size of the dimensions of a binary table column. If the input
 3645     tdimstr character string is null, then this routine returns naxis = 1
 3646     and naxes[0] equal to the repeat count in the TFORM keyword. This routine
 3647    is called by FTGTDM.
 3648 \end{description}
 3649 
 3650 \begin{verbatim}
 3651         FTDTDM(unit,tdimstr,colnum,maxdim, > naxis,naxes, status)
 3652 \end{verbatim}
 3653 
 3654 \begin{description}
 3655 \item[10]  Return the optimal number of rows to read or write at one time for
 3656     maximum I/O efficiency.  Refer to the ``Optimizing Code'' section
 3657    in Chapter 5 for more discussion on how to use this routine.
 3658 \end{description}
 3659 
 3660 
 3661 \begin{verbatim}
 3662         FTGRSZ(unit, > nrows,status)
 3663 \end{verbatim}
 3664 
 3665 
 3666 \subsection{Low-Level Table Access Subroutines \label{FTGTBS}}
 3667 
 3668 The following subroutines provide low-level access to the data in ASCII
 3669 or binary tables and are mainly useful as an efficient way to copy all
 3670 or part of a table from one location to another.  These routines simply
 3671 read or write the specified number of consecutive bytes in an ASCII or
 3672 binary table, without regard for column boundaries or the row length in
 3673 the table.  The first two subroutines read or write consecutive bytes
 3674 in a table to or from a character string variable, while the last two
 3675 subroutines read or write consecutive bytes to or from a variable
 3676 declared as a numeric data type (e.g., INTEGER, INTEGER*2, REAL, DOUBLE
 3677 PRECISION).  These routines do not perform any machine dependent data
 3678 conversion or byte swapping, except that conversion to/from ASCII
 3679 format is performed by the FTGTBS and FTPTBS routines on machines which
 3680 do not use ASCII character codes in the internal data representations
 3681 (e.g., on IBM mainframe computers).
 3682 
 3683 
 3684 \begin{description}
 3685 \item[1 ] Read a consecutive string of characters from an ASCII table
 3686     into a character variable (spanning columns and multiple rows if necessary)
 3687     This routine should not be used with binary tables because of
 3688    complications related to passing string variables between C and Fortran.
 3689 \end{description}
 3690 
 3691 \begin{verbatim}
 3692         FTGTBS(unit,frow,startchar,nchars, > string,status)
 3693 \end{verbatim}
 3694 
 3695 \begin{description}
 3696 \item[2 ] Write a consecutive string of characters to an ASCII table
 3697     from a character variable (spanning columns and multiple rows if necessary)
 3698     This routine should not be used with binary tables because of
 3699    complications related to passing string variables between C and Fortran.
 3700 \end{description}
 3701 
 3702 \begin{verbatim}
 3703         FTPTBS(unit,frow,startchar,nchars,string, > status)
 3704 \end{verbatim}
 3705 
 3706 \begin{description}
 3707 \item[3 ] Read a consecutive array of bytes from an ASCII or binary table
 3708     into a numeric variable (spanning columns and multiple rows if necessary).
 3709     The array parameter may be declared as any numerical datatype as long
 3710     as the array is at least 'nchars' bytes long, e.g., if nchars = 17,
 3711    then declare the array as INTEGER*4 ARRAY(5).
 3712 \end{description}
 3713 
 3714 \begin{verbatim}
 3715         FTGTBB(unit,frow,startchar,nchars, > array,status)
 3716 \end{verbatim}
 3717 
 3718 \begin{description}
 3719 \item[4 ] Write a consecutive array of bytes to an ASCII or binary table
 3720     from a numeric variable (spanning columns and multiple rows if necessary)
 3721     The array parameter may be declared as any numerical datatype as long
 3722     as the array is at least 'nchars' bytes long, e.g., if nchars = 17,
 3723    then declare the array as INTEGER*4 ARRAY(5).
 3724 \end{description}
 3725 
 3726 \begin{verbatim}
 3727         FTPTBB(unit,frow,startchar,nchars,array, > status)
 3728 \end{verbatim}
 3729 
 3730 
 3731 \subsection{Edit Rows or Columns \label{FTIROW}}
 3732 
 3733 
 3734 \begin{description}
 3735 \item[1 ] Insert blank rows into an existing ASCII or binary table (in the CDU).
 3736     All the rows FOLLOWING row FROW are shifted down by NROWS rows.  If
 3737     FROW or FROWLL equals 0 then the blank rows are inserted at the beginning of the
 3738     table.  These routines modify the NAXIS2 keyword to reflect the new
 3739     number of rows in the table.  Note that it is *not* necessary to insert rows in a table before
 3740     writing data to those rows (indeed, it would be inefficient to do so).
 3741     Instead, one may simply write data to any row of the table, whether that
 3742    row of data already exists or not.
 3743 \end{description}
 3744 
 3745 \begin{verbatim}
 3746         FTIROW(unit,frow,nrows, > status)
 3747         FTIROWLL(unit,frowll,nrowsll, > status)
 3748 \end{verbatim}
 3749 
 3750 \begin{description}
 3751 \item[2 ] Delete rows from an existing ASCII or binary table (in the CDU).
 3752     The NROWS (or NROWSLL) is the number of rows are deleted, starting
 3753     with row FROW (or FROWLL), and
 3754     any remaining rows in the table are shifted up to fill in the space.
 3755     These routines modify the NAXIS2 keyword to reflect the new number
 3756    of rows in the table.
 3757 \end{description}
 3758 
 3759 \begin{verbatim}
 3760         FTDROW(unit,frow,nrows, > status)
 3761         FTDROWLL(unit,frowll,nrowsll, > status)
 3762 \end{verbatim}
 3763 
 3764 \begin{description}
 3765 \item[3 ] Delete a list of rows from an ASCII or binary table (in the CDU).
 3766     In the first routine, 'rowrange' is a character string listing the
 3767     rows or row ranges to delete (e.g., '2-4, 5, 8-9'). In the second
 3768     routine, 'rowlist' is an integer array of row numbers to be deleted
 3769     from the table.  nrows is the number of row numbers in the list.
 3770     The first row in the table is 1 not 0.  The list of row numbers
 3771    must be sorted in ascending order.
 3772 \end{description}
 3773 
 3774 \begin{verbatim}
 3775         FTDRRG(unit,rowrange, > status)
 3776         FTDRWS(unit,rowlist,nrows, > status)
 3777 \end{verbatim}
 3778 
 3779 \begin{description}
 3780 \item[4 ] Insert a blank column (or columns) into an existing ASCII or binary
 3781     table (in the CDU).  COLNUM specifies the column number that the (first)
 3782     new column should occupy in the table.  NCOLS specifies how many
 3783     columns are to be inserted. Any existing columns from this position and
 3784     higher are moved over to allow room for the new column(s).
 3785     The index number on all the following keywords will be incremented
 3786     if necessary to reflect the new position of the column(s) in the table:
 3787     TBCOLn, TFORMn, TTYPEn, TUNITn, TNULLn, TSCALn, TZEROn, TDISPn, TDIMn,
 3788     TLMINn, TLMAXn, TDMINn, TDMAXn, TCTYPn, TCRPXn, TCRVLn, TCDLTn, TCROTn,
 3789    and TCUNIn.
 3790 \end{description}
 3791 
 3792 \begin{verbatim}
 3793         FTICOL(unit,colnum,ttype,tform, > status)
 3794         FTICLS(unit,colnum,ncols,ttype,tform, > status)
 3795 \end{verbatim}
 3796 
 3797 \begin{description}
 3798 \item[5 ] Modify the vector length of a binary table column (e.g.,
 3799     change a column from TFORMn = '1E' to '20E').  The vector
 3800    length may be increased or decreased from the current value.
 3801 \end{description}
 3802 
 3803 \begin{verbatim}
 3804         FTMVEC(unit,colnum,newveclen, > status)
 3805 \end{verbatim}
 3806 
 3807 \begin{description}
 3808 \item[6 ] Delete a column from an existing ASCII or binary table (in the CDU).
 3809     The index number of all the keywords listed above (for FTICOL) will be
 3810     decremented if necessary to reflect the new position of the column(s) in
 3811     the table.  Those index keywords that refer to the deleted column will
 3812     also be deleted.  Note that the physical size of the FITS file will
 3813     not be reduced by this operation, and the empty FITS blocks if any
 3814    at the end of the file will be padded with zeros.
 3815 \end{description}
 3816 
 3817 \begin{verbatim}
 3818         FTDCOL(unit,colnum, > status)
 3819 \end{verbatim}
 3820 
 3821 \begin{description}
 3822 \item[7 ] Copy a column from one HDU to another (or to the same HDU).  If
 3823     createcol = TRUE, then a new column will be inserted in the output
 3824     table, at position `outcolumn', otherwise the existing output column will
 3825     be overwritten (in which case it must have a compatible datatype).
 3826    Note that the first column in a table is at colnum = 1.
 3827 \end{description}
 3828 
 3829 \begin{verbatim}
 3830         FTCPCL(inunit,outunit,incolnum,outcolnum,createcol, > status);
 3831 \end{verbatim}
 3832 
 3833 \subsection{Read and Write Column Data Routines \label{FTPCLS}}
 3834 
 3835 These subroutines put or get data values in the current ASCII or Binary table
 3836 extension.  Automatic data type conversion is performed for numerical data
 3837 types (B,I,J,E,D) if the data type of the column (defined by the TFORM keyword)
 3838 differs from the data type of the calling subroutine.  The data values are also
 3839 scaled by the TSCALn and TZEROn header values as they are being written to
 3840 or read from the FITS array.  The fttscl subroutine MUST be used to define the
 3841 scaling parameters when writing data to the table or to override the default
 3842 scaling values given in the header when reading from the table.
 3843 Note that it is *not* necessary to insert rows in a table before
 3844 writing data to those rows (indeed, it would be inefficient to do so).
 3845 Instead, one may simply write data to any row of the table, whether that
 3846 row of data already exists or not.
 3847 
 3848     In the case of binary tables with vector elements, the 'felem'
 3849 parameter defines the starting pixel within the element vector.  This
 3850 parameter is ignored with ASCII tables. Similarly, in the case of
 3851 binary tables the 'nelements' parameter specifies the total number of
 3852 vector values read or written (continuing on subsequent rows if
 3853 required) and not the number of table elements.  Two sets of
 3854 subroutines are provided to get the column data which differ in the way
 3855 undefined pixels are handled.  The first set of routines (FTGCV)
 3856 simply return an array of data elements in which undefined pixels are
 3857 set equal to a value specified by the user in the 'nullval' parameter.
 3858 An additional feature of these subroutines is that if the user sets
 3859 nullval = 0, then no checks for undefined pixels will be performed,
 3860 thus increasing the speed of the program.  The second set of routines
 3861 (FTGCF) returns the data element array and in addition a logical array
 3862 of flags which defines whether the corresponding data pixel is undefined.
 3863 
 3864     Any column, regardless of it's intrinsic datatype, may be read as a
 3865     string.  It should be noted however that reading a numeric column
 3866     as a string is 10 - 100 times slower than reading the same column as
 3867     a number due to the large overhead in constructing the formatted
 3868     strings.    The display format of the returned strings will be
 3869     determined by the TDISPn keyword, if it exists, otherwise by the
 3870     datatype of the column.  The length of the returned strings can be
 3871     determined with the ftgcdw routine.  The following TDISPn display
 3872     formats are currently supported:
 3873 
 3874 \begin{verbatim}
 3875     Iw.m   Integer
 3876     Ow.m   Octal integer
 3877     Zw.m   Hexadecimal integer
 3878     Fw.d   Fixed floating point
 3879     Ew.d   Exponential floating point
 3880     Dw.d   Exponential floating point
 3881     Gw.d   General; uses Fw.d if significance not lost, else Ew.d
 3882 \end{verbatim}
 3883   where w is the width in characters of the displayed values, m is the minimum
 3884   number of digits displayed, and d is the number of digits to the right of the
 3885   decimal.  The .m field is optional.
 3886 
 3887 
 3888 \begin{description}
 3889 \item[1 ] Put elements into an ASCII or binary table column (in the CDU).
 3890     (The SPP FSPCLS routine has an additional integer argument after
 3891     the VALUES character string which specifies the size of the 1st
 3892     dimension of this 2-D CHAR array).
 3893 
 3894     The alternate version of these routines, whose names end in 'LL'
 3895     after the datatype character, support large tables with more then
 3896     2*31 rows.  When calling these routines, the frow and felem parameters
 3897    *must* be 64-bit integer*8 variables, instead of normal 4-byte integers.
 3898 \end{description}
 3899 
 3900 \begin{verbatim}
 3901         FTPCL[SLBIJKEDCM](unit,colnum,frow,felem,nelements,values, > status)
 3902         FTPCL[LBIJKEDCM]LL(unit,colnum,frow,felem,nelements,values, > status)
 3903 \end{verbatim}
 3904 
 3905 \begin{description}
 3906 \item[2 ] Put elements into an ASCII or binary table column (in the CDU)
 3907     substituting the appropriate FITS null value for any elements that
 3908     are equal to NULLVAL.   For ASCII TABLE extensions, the
 3909     null value defined by the previous call to FTSNUL will be substituted;
 3910     For integer FITS columns, in a binary table  the null value
 3911     defined by the previous call to FTTNUL will be substituted;
 3912     For floating point FITS columns a special IEEE NaN (Not-a-Number)
 3913     value will be substituted.
 3914 
 3915     The alternate version of these routines, whose names end in 'LL'
 3916     after the datatype character, support large tables with more then
 3917     2*31 rows.  When calling these routines, the frow and felem parameters
 3918    *must* be 64-bit integer*8 variables, instead of normal 4-byte integers.
 3919 \end{description}
 3920 
 3921 \begin{verbatim}
 3922         FTPCN[SBIJKED](unit,colnum,frow,felem,nelements,values,nullval > status)
 3923         FTPCN[SBIJKED]LL(unit,colnum,(I*8) frow,(I*8) felem,nelements,values,
 3924                     nullval > status)
 3925 \end{verbatim}
 3926 
 3927 \begin{description}
 3928 \item[3 ] Put bit values into a binary byte ('B') or bit ('X') table column (in the
 3929     CDU).  LRAY is an array of logical values corresponding to the sequence of
 3930     bits to be written.  If LRAY is true then the corresponding bit is
 3931     set to 1, otherwise the bit is set to 0.  Note that in the case of
 3932     'X' columns, FITSIO will write to all 8 bits of each byte whether
 3933     they are formally valid or not.  Thus if the column is defined as
 3934     '4X', and one calls FTPCLX with  fbit=1 and nbit=8, then all 8 bits
 3935     will be written into the first byte (as opposed to writing the
 3936     first 4 bits into the first row and then the next 4 bits into the
 3937     next row), even though the last 4 bits of each byte are formally
 3938    not defined.
 3939 \end{description}
 3940 
 3941 \begin{verbatim}
 3942         FTPCLX(unit,colnum,frow,fbit,nbit,lray, > status)
 3943 \end{verbatim}
 3944 
 3945 \begin{description}
 3946 \item[4 ] Set table elements in a column as undefined
 3947 \end{description}
 3948 
 3949 \begin{verbatim}
 3950         FTPCLU(unit,colnum,frow,felem,nelements, > status)
 3951 \end{verbatim}
 3952 
 3953 \begin{description}
 3954 \item[5 ] Get elements from an ASCII or binary table column (in the CDU).  These
 3955     routines return the values of the table column array elements.  Undefined
 3956     array elements will be returned with a value = nullval, unless nullval = 0
 3957     (or = ' ' for ftgcvs) in which case no checking for undefined values will
 3958     be performed. The ANYF parameter is set to true if any of the returned
 3959     elements are undefined. (Note: the ftgcl routine simple gets an array
 3960     of logical data values without any checks for undefined values;  use
 3961     the ftgcfl routine to check for undefined logical elements).
 3962     (The SPP FSGCVS routine has an additional integer argument after
 3963     the VALUES character string which specifies the size of the 1st
 3964     dimension of this 2-D CHAR array).
 3965 
 3966     The alternate version of these routines, whose names end in 'LL'
 3967     after the datatype character, support large tables with more then
 3968     2*31 rows.  When calling these routines, the frow and felem parameters
 3969    *must* be 64-bit integer*8 variables, instead of normal 4-byte integers.
 3970 \end{description}
 3971 
 3972 \begin{verbatim}
 3973         FTGCL(unit,colnum,frow,felem,nelements, > values,status)
 3974         FTGCV[SBIJKEDCM](unit,colnum,frow,felem,nelements,nullval, >
 3975                        values,anyf,status)
 3976         FTGCV[BIJKEDCM]LL(unit,colnum,(I*8) frow, (I*8) felem, nelements,
 3977                    nullval, > values,anyf,status)
 3978 \end{verbatim}
 3979 
 3980 \begin{description}
 3981 \item[6 ] Get elements and null flags from an ASCII or binary table column (in the
 3982     CHDU).  These routines return the values of the table column array elements.
 3983     Any undefined array elements will have the corresponding flagvals element
 3984     set equal to .TRUE. The ANYF parameter is set to true if any of the
 3985     returned elements are undefined.
 3986     (The SPP FSGCFS routine has an additional integer argument after
 3987     the VALUES character string which specifies the size of the 1st
 3988     dimension of this 2-D CHAR array).
 3989 
 3990     The alternate version of these routines, whose names end in 'LL'
 3991     after the datatype character, support large tables with more then
 3992     2*31 rows.  When calling these routines, the frow and felem parameters
 3993    *must* be 64-bit integer*8 variables, instead of normal 4-byte integers.
 3994 \end{description}
 3995 
 3996 \begin{verbatim}
 3997         FTGCF[SLBIJKEDCM](unit,colnum,frow,felem,nelements, >
 3998                          values,flagvals,anyf,status)
 3999         FTGCF[BIJKED]LL(unit,colnum, (I*8) frow, (I*8) felem,nelements, >
 4000                          values,flagvals,anyf,status)
 4001 \end{verbatim}
 4002 
 4003 \begin{description}
 4004 \item[7 ] Get an arbitrary data subsection from an N-dimensional array
 4005     in a binary table vector column.  Undefined pixels
 4006     in the array will be set equal to the value of 'nullval',
 4007     unless nullval=0 in which case no testing for undefined pixels will
 4008     be performed.  The first and last rows in the table to be read
 4009     are specified by fpixels(naxis+1) and lpixels(naxis+1), and hence
 4010     are treated as the next higher dimension of the FITS N-dimensional
 4011     array.  The INCS parameter specifies the sampling interval in
 4012    each dimension between the data elements that will be returned.
 4013 \end{description}
 4014 
 4015 \begin{verbatim}
 4016         FTGSV[BIJKED](unit,colnum,naxis,naxes,fpixels,lpixels,incs,nullval, >
 4017                      array,anyf,status)
 4018 \end{verbatim}
 4019 
 4020 \begin{description}
 4021 \item[8 ] Get an arbitrary data subsection from an N-dimensional array
 4022     in a binary table vector column.  Any Undefined
 4023     pixels in the array will have the corresponding 'flagvals'
 4024     element set equal to .TRUE.   The first and last rows in the table
 4025     to be read are specified by fpixels(naxis+1) and lpixels(naxis+1),
 4026     and hence are treated as the next higher dimension of the FITS
 4027     N-dimensional array.  The INCS parameter specifies the sampling
 4028     interval in each dimension between the data elements that will be
 4029    returned.
 4030 \end{description}
 4031 
 4032 \begin{verbatim}
 4033         FTGSF[BIJKED](unit,colnum,naxis,naxes,fpixels,lpixels,incs, >
 4034                      array,flagvals,anyf,status)
 4035 \end{verbatim}
 4036 
 4037 \begin{description}
 4038 \item[9 ] Get bit values from a byte ('B') or bit (`X`) table column (in the
 4039     CDU).  LRAY is an array of logical values corresponding to the
 4040     sequence of bits to be read.  If LRAY is true then the
 4041     corresponding bit was set to 1, otherwise the bit was set to 0.
 4042     Note that in the case of 'X' columns, FITSIO will read  all 8 bits
 4043     of each byte whether they are formally valid or not.  Thus if the
 4044     column is defined as '4X', and one calls FTGCX with  fbit=1 and
 4045     nbit=8, then all 8 bits will be read from the first byte (as
 4046     opposed to reading the first 4 bits from the first row and then the
 4047     first 4 bits from the next row), even though the last 4 bits of
 4048    each byte are formally not defined.
 4049 \end{description}
 4050 
 4051 \begin{verbatim}
 4052         FTGCX(unit,colnum,frow,fbit,nbit, > lray,status)
 4053 \end{verbatim}
 4054 
 4055 \begin{description}
 4056 \item[10] Read any consecutive set of bits from an 'X' or 'B' column and
 4057     interpret them as an unsigned n-bit integer. NBIT must be less than
 4058     or equal to 16 when calling FTGCXI, and less than or equal to 32 when
 4059     calling FTGCXJ; there is no limit on the value of NBIT for FTGCXD, but
 4060     the returned double precision value only has 48 bits of precision on
 4061     most 32-bit word machines.  The NBITS bits are interpreted as an
 4062     unsigned integer unless NBITS = 16 (in FTGCXI) or 32 (in FTGCXJ) in which
 4063     case the string of bits are interpreted as 16-bit or 32-bit 2's
 4064     complement signed integers.  If NROWS is greater than 1 then the
 4065     same set of bits will be read from sequential rows in the table
 4066     starting with row FROW.  Note that the numbering convention
 4067     used here for the FBIT parameter adopts 1 for the first element of the
 4068    vector of bits;  this is the Most Significant Bit of the integer value.
 4069 \end{description}
 4070 
 4071 \begin{verbatim}
 4072         FTGCX[IJD](unit,colnum,frow,nrows,fbit,nbit, > array,status)
 4073 \end{verbatim}
 4074 
 4075 \begin{description}
 4076 \item[11] Get the descriptor for a variable length column in a binary table.
 4077     The descriptor consists of 2 integer parameters: the number of elements
 4078     in the array and the starting offset relative to the start of the heap.
 4079     The first routine returns a single descriptor whereas the second routine
 4080    returns the descriptors for a range of rows in the table.
 4081 \end{description}
 4082 
 4083 \begin{verbatim}
 4084         FTGDES(unit,colnum,rownum, > nelements,offset,status)
 4085         FTGDESLL(unit,colnum,rownum, > nelementsll,offsetll,status)
 4086 
 4087         FTGDESS(unit,colnum,firstrow,nrows > nelements,offset, status)
 4088         FTGDESSLL(unit,colnum,firstrow,nrows > nelementsll,offsetll, status)
 4089 \end{verbatim}
 4090 
 4091 \begin{description}
 4092 \item[12]  Write the descriptor for a variable length column in a binary table.
 4093     These subroutines can be used in conjunction with FTGDES to enable
 4094     2 or more arrays to point to the same storage location to save
 4095    storage space if the arrays are identical.
 4096 \end{description}
 4097 
 4098 \begin{verbatim}
 4099         FTPDES(unit,colnum,rownum,nelements,offset, > status)
 4100         FTPDESLL(unit,colnum,rownum,nelementsll,offsetll, > status)
 4101 \end{verbatim}
 4102 
 4103 
 4104 \section{Row Selection and Calculator Routines \label{FTFROW}}
 4105 
 4106 These routines all parse and evaluate an input string containing a user
 4107 defined arithmetic expression.  The first 3 routines select rows in a
 4108 FITS table, based on whether the expression evaluates to true (not
 4109 equal to zero) or false (zero).  The other routines evaluate the
 4110 expression and calculate a value for each row of the table.  The
 4111 allowed expression syntax is described in the row filter section in the
 4112 earlier `Extended File Name Syntax' chapter of this document.  The
 4113 expression may also be written to a text file, and the name of the
 4114 file, prepended with a '@' character may be supplied for the 'expr'
 4115 parameter (e.g.  '@filename.txt'). The  expression  in  the  file can
 4116 be arbitrarily complex and extend over multiple lines of the file.
 4117 Lines  that begin with 2 slash characters ('//') will  be ignored and
 4118 may be used to add comments to the file.
 4119 
 4120 
 4121 \begin{description}
 4122 \item[1 ] Evaluate a boolean expression over the indicated rows, returning an
 4123  array of flags indicating which rows evaluated to TRUE/FALSE
 4124 \end{description}
 4125 
 4126 \begin{verbatim}
 4127          FTFROW(unit,expr,firstrow, nrows, > n_good_rows, row_status, status)
 4128 \end{verbatim}
 4129 
 4130 \begin{description}
 4131 \item[2 ] Find the first row which satisfies the input boolean expression
 4132 \end{description}
 4133 
 4134 \begin{verbatim}
 4135          FTFFRW(unit, expr, > rownum, status)
 4136 \end{verbatim}
 4137 
 4138 \begin{description}
 4139 \item[3 ]Evaluate an expression on all rows of a table.  If the input and output
 4140 files are not the same, copy the TRUE rows to the output file;  if the output
 4141 table is not empty, then this routine will append the new
 4142 selected rows after the existing rows.  If the
 4143 files are the same, delete the FALSE rows (preserve the TRUE rows).
 4144 \end{description}
 4145 
 4146 \begin{verbatim}
 4147          FTSROW(inunit, outunit, expr, > status)
 4148 \end{verbatim}
 4149 
 4150 \begin{description}
 4151 \item[4 ] Calculate an expression for the indicated rows of a table, returning
 4152 the results, cast as datatype (TSHORT, TDOUBLE, etc), in array.  If
 4153 nulval==NULL, UNDEFs will be zeroed out.  For vector results, the number
 4154 of elements returned may be less than nelements if nelements is not an
 4155 even multiple of the result dimension.  Call FTTEXP to obtain
 4156 the dimensions of the results.
 4157 \end{description}
 4158 
 4159 \begin{verbatim}
 4160          FTCROW(unit,datatype,expr,firstrow,nelements,nulval, >
 4161              array,anynul,status)
 4162 \end{verbatim}
 4163 
 4164 \begin{description}
 4165 \item[5 ]Evaluate an expression and write the result either to a column (if
 4166 the expression is a function of other columns in the table) or to a
 4167 keyword (if the expression evaluates to a constant and is not a
 4168 function of other columns in the table).  In the former case, the
 4169 parName parameter is the name of the column (which may or may not already
 4170 exist) into which to write the results, and parInfo contains an
 4171 optional TFORM keyword value if a new column is being created.  If a
 4172 TFORM value is not specified then a default format will be used,
 4173 depending on the expression.  If the expression evaluates to a constant,
 4174 then the result will be written to the keyword name given by the
 4175 parName parameter, and the parInfo parameter may be used to supply an
 4176 optional comment for the keyword.  If the keyword does not already
 4177 exist, then the name of the keyword must be preceded with a '\#' character,
 4178 otherwise the result will be written to a column with that name.
 4179 \end{description}
 4180 
 4181 
 4182 \begin{verbatim}
 4183          FTCALC(inunit, expr, outunit, parName, parInfo, > status)
 4184 \end{verbatim}
 4185 
 4186 \begin{description}
 4187 \item[6 ] This calculator routine is similar to the previous routine, except
 4188 that the expression is only evaluated over the specified
 4189 row ranges.  nranges specifies the number of row ranges, and firstrow
 4190 and lastrow give the starting and ending row number of each range.
 4191 \end{description}
 4192 
 4193 \begin{verbatim}
 4194          FTCALC_RNG(inunit, expr, outunit, parName, parInfo,
 4195             nranges, firstrow, lastrow, > status)
 4196 \end{verbatim}
 4197 
 4198 \begin{description}
 4199 \item[7 ]Evaluate the given expression and return dimension and type information
 4200 on the result.  The returned dimensions correspond to a single row entry
 4201 of the requested expression, and are equivalent to the result of fits\_read\_tdim().
 4202 Note that strings are considered to be one element regardless of string length.
 4203 If maxdim == 0, then naxes is optional.
 4204 \end{description}
 4205 
 4206 \begin{verbatim}
 4207          FTTEXP(unit, expr, maxdim > datatype, nelem, naxis, naxes, status)
 4208 \end{verbatim}
 4209 
 4210 
 4211 
 4212 \section{Celestial Coordinate System Subroutines \label{FTGICS}}
 4213 
 4214 The FITS community has adopted a set of keyword conventions that define
 4215 the transformations needed to convert between pixel locations in an
 4216 image and the corresponding celestial coordinates on the sky, or more
 4217 generally, that define world coordinates that are to be associated with
 4218 any pixel location in an n-dimensional FITS array. CFITSIO is distributed
 4219 with a couple of self-contained World Coordinate System (WCS) routines,
 4220 however, these routines DO NOT support all the latest WCS conventions,
 4221 so it is STRONGLY RECOMMENDED that software developers use a more robust
 4222 external WCS library.  Several recommended libraries are:
 4223 
 4224 \begin{verbatim}
 4225   WCSLIB -  supported by Mark Calabretta
 4226   WCSTools - supported by Doug Mink
 4227   AST library - developed by the U.K. Starlink project
 4228 \end{verbatim}
 4229 
 4230 More information about the WCS keyword conventions and links to all of
 4231 these WCS libraries can be found on the FITS Support Office web site at
 4232 http://fits.gsfc.nasa.gov under the WCS link.
 4233 
 4234 The functions provided in these external WCS libraries will need access to
 4235 the  WCS information contained in the FITS file headers.  One convenient
 4236 way to pass this information to the external library is to use  FITSIO
 4237 to copy the header keywords into one long character string, and then
 4238 pass this string to an interface routine in the external library that
 4239 will extract the necessary WCS information (e.g., see the astFitsChan
 4240 and astPutCards routines in the Starlink AST library).
 4241 
 4242 The following FITSIO routines DO NOT support the more recent WCS conventions
 4243 that have been approved as part of the FITS standard.  Consequently,
 4244 the following routines ARE NOW DEPRECATED.  It is STRONGLY RECOMMENDED
 4245 that software developers not use these routines, and instead use an
 4246 external WCS library, as described above.
 4247 
 4248 These routines are included mainly for backward compatibility with
 4249 existing software.  They support the following standard map
 4250 projections: -SIN, -TAN, -ARC, -NCP, -GLS, -MER, and -AIT (these are the
 4251 legal values for the coordtype parameter).  These routines are based
 4252 on similar functions in Classic AIPS.  All the angular quantities are
 4253 given in units of degrees.
 4254 
 4255 
 4256 \begin{description}
 4257 \item[1 ] Get the values of all the standard FITS celestial coordinate system
 4258     keywords from the header of a FITS image (i.e., the primary array or
 4259     an image extension).  These values may then be passed to the subroutines
 4260     that perform the coordinate transformations.  If any or all of the WCS
 4261     keywords are not present, then default values will be returned. If
 4262     the first coordinate axis is the declination-like coordinate, then
 4263     this routine will swap them so that the longitudinal-like coordinate
 4264     is returned as the first axis.
 4265 
 4266     If the file uses the newer 'CDj\_i' WCS transformation matrix
 4267     keywords instead of old style 'CDELTn' and 'CROTA2' keywords, then
 4268     this routine will calculate and return the values of the equivalent
 4269     old-style keywords.    Note that the conversion from the new-style
 4270     keywords to the old-style values is sometimes only an
 4271     approximation, so if the approximation is larger than an internally
 4272     defined threshold level, then CFITSIO will still return the
 4273     approximate WCS keyword values, but will also return with status =
 4274     506, to warn the calling program that approximations have been
 4275     made.  It is then up to the calling program to decide whether the
 4276     approximations are sufficiently accurate for the particular
 4277     application, or whether more precise WCS transformations must be
 4278    performed using new-style WCS keywords directly.
 4279 \end{description}
 4280 
 4281 \begin{verbatim}
 4282         FTGICS(unit, > xrval,yrval,xrpix,yrpix,xinc,yinc,rot,coordtype,status)
 4283 \end{verbatim}
 4284 
 4285 \begin{description}
 4286 \item[2 ] Get the values of all the standard FITS celestial coordinate system
 4287     keywords from the header of a FITS table where the X and Y (or RA and
 4288     DEC coordinates are stored in 2 separate columns of the table.
 4289     These values may then be passed to the subroutines that perform the
 4290    coordinate transformations.
 4291 \end{description}
 4292 
 4293 \begin{verbatim}
 4294         FTGTCS(unit,xcol,ycol, >
 4295                xrval,yrval,xrpix,yrpix,xinc,yinc,rot,coordtype,status)
 4296 \end{verbatim}
 4297 
 4298 \begin{description}
 4299 \item[3 ]  Calculate the celestial coordinate corresponding to the input
 4300     X and Y pixel location in the image.
 4301 \end{description}
 4302 
 4303 \begin{verbatim}
 4304         FTWLDP(xpix,ypix,xrval,yrval,xrpix,yrpix,xinc,yinc,rot,
 4305                           coordtype, > xpos,ypos,status)
 4306 \end{verbatim}
 4307 
 4308 \begin{description}
 4309 \item[4 ]  Calculate the X and Y pixel location corresponding to the input
 4310     celestial coordinate in the image.
 4311 \end{description}
 4312 
 4313 \begin{verbatim}
 4314         FTXYPX(xpos,ypos,xrval,yrval,xrpix,yrpix,xinc,yinc,rot,
 4315                           coordtype, > xpix,ypix,status)
 4316 \end{verbatim}
 4317 
 4318 
 4319 \section{File Checksum Subroutines \label{FTPCKS}}
 4320 
 4321 The following routines either compute or validate the checksums for the
 4322 CHDU.  The DATASUM keyword is used to store the numerical value of the
 4323 32-bit, 1's complement checksum for the data unit alone.  If there is
 4324 no data unit then the value is set to zero. The numerical value is
 4325 stored as an ASCII string of digits, enclosed in quotes, because the
 4326 value may be too large to represent as a 32-bit signed integer.  The
 4327 CHECKSUM keyword is used to store the ASCII encoded COMPLEMENT of the
 4328 checksum for the entire HDU.  Storing the complement, rather than the
 4329 actual checksum, forces the checksum for the whole HDU to equal zero.
 4330 If the file has been modified since the checksums were computed, then
 4331 the HDU checksum will usually not equal zero.  These checksum keyword
 4332 conventions are based on a paper by Rob Seaman published in the
 4333 proceedings of the ADASS IV conference in Baltimore in November 1994
 4334 and a later revision in June 1995.
 4335 
 4336 
 4337 \begin{description}
 4338 \item[1 ] Compute and write the DATASUM and CHECKSUM keyword values for the CHDU
 4339     into the current header.  The DATASUM value is the 32-bit checksum
 4340     for the data unit, expressed as a decimal integer enclosed in single
 4341     quotes. The CHECKSUM keyword value is a 16-character string which
 4342     is the ASCII-encoded value for the complement of the checksum for
 4343     the whole HDU.  If these keywords already exist, their values
 4344     will be updated only if necessary (i.e., if the file has been modified
 4345    since the original keyword values were computed).
 4346 \end{description}
 4347 
 4348 \begin{verbatim}
 4349         FTPCKS(unit, > status)
 4350 \end{verbatim}
 4351 
 4352 \begin{description}
 4353 \item[2 ] Update the CHECKSUM keyword value in the CHDU, assuming that the
 4354     DATASUM keyword exists and already has the correct value.  This routine
 4355     calculates the new checksum for the current header unit, adds it to the
 4356     data unit checksum, encodes the value into an ASCII string, and writes
 4357    the string to the CHECKSUM keyword.
 4358 \end{description}
 4359 
 4360 \begin{verbatim}
 4361         FTUCKS(unit, > status)
 4362 \end{verbatim}
 4363 
 4364 \begin{description}
 4365 \item[3 ] Verify the CHDU by computing the checksums and comparing
 4366     them with the keywords.  The data unit is verified correctly
 4367     if the computed checksum equals the value of the DATASUM
 4368     keyword.  The checksum for the entire HDU (header plus data unit) is
 4369     correct if it equals zero.  The output DATAOK and HDUOK parameters
 4370     in this subroutine are integers which will have a value = 1
 4371     if the data or HDU is verified correctly, a value = 0
 4372     if the DATASUM or CHECKSUM keyword is not present, or value = -1
 4373    if the computed checksum is not correct.
 4374 \end{description}
 4375 
 4376 \begin{verbatim}
 4377         FTVCKS(unit, > dataok,hduok,status)
 4378 \end{verbatim}
 4379 
 4380 \begin{description}
 4381 \item[4 ] Compute and return the checksum values for the CHDU (as
 4382     double precision variables) without creating or modifying the
 4383     CHECKSUM and DATASUM keywords.  This routine is used internally by
 4384    FTVCKS, but may be useful in other situations as well.
 4385 \end{description}
 4386 
 4387 \begin{verbatim}
 4388         FTGCKS(unit, > datasum,hdusum,status)
 4389 \end{verbatim}
 4390 
 4391 \begin{description}
 4392 \item[5 ] Encode a checksum value (stored in a double precision variable)
 4393     into a 16-character string.  If COMPLEMENT = .true. then the 32-bit
 4394    sum value will be complemented before encoding.
 4395 \end{description}
 4396 
 4397 \begin{verbatim}
 4398         FTESUM(sum,complement, > checksum)
 4399 \end{verbatim}
 4400 
 4401 \begin{description}
 4402 \item[6 ] Decode a 16 character checksum string into a double precision value.
 4403     If COMPLEMENT = .true. then the 32-bit sum value will be complemented
 4404    after decoding.
 4405 \end{description}
 4406 
 4407 \begin{verbatim}
 4408         FTDSUM(checksum,complement, > sum)
 4409 \end{verbatim}
 4410 
 4411 
 4412 \section{ Date and Time Utility Routines \label{FTGSDT}}
 4413 
 4414 The following routines help to construct or parse the FITS date/time
 4415 strings.   Starting in the year 2000, the FITS DATE keyword values (and
 4416 the values of other `DATE-' keywords) must have the form 'YYYY-MM-DD'
 4417 (date only) or 'YYYY-MM-DDThh:mm:ss.ddd...' (date and time) where the
 4418 number of decimal places in the seconds value is optional.  These times
 4419 are in UTC.  The older 'dd/mm/yy' date format may not be used for dates
 4420 after 01 January 2000.
 4421 
 4422 
 4423 \begin{description}
 4424 \item[1 ] Get the current system date.  The returned year has 4 digits
 4425     (1999, 2000, etc.)
 4426 \end{description}
 4427 
 4428 \begin{verbatim}
 4429         FTGSDT( > day, month, year, status )
 4430 \end{verbatim}
 4431 
 4432 
 4433 \begin{description}
 4434 \item[2 ] Get the current system date and time string ('YYYY-MM-DDThh:mm:ss').
 4435 The time will be in UTC/GMT if available, as indicated by a returned timeref
 4436 value = 0.  If the returned value of timeref = 1 then this indicates that
 4437 it was not possible to convert the local time to UTC, and thus the local
 4438 time was returned.
 4439 \end{description}
 4440 
 4441 \begin{verbatim}
 4442         FTGSTM(> datestr, timeref, status)
 4443 \end{verbatim}
 4444 
 4445 
 4446 \begin{description}
 4447 \item[3 ] Construct a date string from the input date values.  If the year
 4448 is between 1900 and 1998, inclusive, then the returned date string will
 4449 have the old FITS format ('dd/mm/yy'), otherwise the date string will
 4450 have the new FITS format ('YYYY-MM-DD').  Use FTTM2S instead
 4451  to always return a date string using the new FITS format.
 4452 \end{description}
 4453 
 4454 \begin{verbatim}
 4455         FTDT2S( year, month, day, > datestr, status)
 4456 \end{verbatim}
 4457 
 4458 
 4459 \begin{description}
 4460 \item[4 ] Construct a new-format date + time string ('YYYY-MM-DDThh:mm:ss.ddd...').
 4461   If the year, month, and day values all = 0 then only the time is encoded
 4462   with format 'hh:mm:ss.ddd...'.  The decimals parameter specifies how many
 4463   decimal places of fractional seconds to include in the string.  If `decimals'
 4464  is negative, then only the date will be return ('YYYY-MM-DD').
 4465 \end{description}
 4466 
 4467 \begin{verbatim}
 4468         FTTM2S( year, month, day, hour, minute, second, decimals,
 4469                 > datestr, status)
 4470 \end{verbatim}
 4471 
 4472 
 4473 \begin{description}
 4474 \item[5 ] Return the date as read from the input string, where the string may be
 4475 in either the old ('dd/mm/yy')  or new ('YYYY-MM-DDThh:mm:ss' or
 4476 'YYYY-MM-DD') FITS format.
 4477 \end{description}
 4478 
 4479 \begin{verbatim}
 4480         FTS2DT(datestr, > year, month, day, status)
 4481 \end{verbatim}
 4482 
 4483 
 4484 \begin{description}
 4485 \item[6 ] Return the date and time as read from the input string, where the
 4486 string may be in either the old  or new FITS format.  The returned hours,
 4487 minutes, and seconds values will be set to zero if the input string
 4488 does not include the time ('dd/mm/yy' or 'YYYY-MM-DD') .  Similarly,
 4489 the returned year, month, and date values will be set to zero if the
 4490 date is not included in the input string ('hh:mm:ss.ddd...').
 4491 \end{description}
 4492 
 4493 \begin{verbatim}
 4494         FTS2TM(datestr, > year, month, day, hour, minute, second, status)
 4495 \end{verbatim}
 4496 
 4497 
 4498 \section{General Utility Subroutines \label{FTGHAD}}
 4499 
 4500 The following utility subroutines may be useful for certain applications:
 4501 
 4502 
 4503 \begin{description}
 4504 \item[1 ] Return the starting byte address of the CHDU and the next HDU.
 4505 \end{description}
 4506 
 4507 \begin{verbatim}
 4508         FTGHAD(iunit, > curaddr, nextaddr)
 4509 \end{verbatim}
 4510 
 4511 \begin{description}
 4512 \item[2 ] Convert a character string to uppercase (operates in place).
 4513 \end{description}
 4514 
 4515 \begin{verbatim}
 4516         FTUPCH(string)
 4517 \end{verbatim}
 4518 
 4519 \begin{description}
 4520 \item[3 ] Compare the input template string against the reference string
 4521     to see if they match.  The template string may contain wildcard
 4522     characters: '*' will match any sequence of characters (including
 4523     zero characters) and '?' will match any single character in the
 4524     reference string. The '\#' character will match any consecutive string
 4525     of decimal digits (0 - 9).  If CASESN = .true. then the match will be
 4526     case sensitive.  The returned MATCH parameter will be .true. if
 4527     the 2 strings match, and EXACT will be .true. if the match is
 4528     exact (i.e., if no wildcard characters were used in the match).
 4529    Both strings must be 68 characters or less in length.
 4530 \end{description}
 4531 
 4532 \begin{verbatim}
 4533         FTCMPS(str_template, string, casesen, > match, exact)
 4534 \end{verbatim}
 4535 
 4536 
 4537 \begin{description}
 4538 \item[4 ] Test that the keyword name contains only legal characters: A-Z,0-9,
 4539    hyphen, and underscore.
 4540 \end{description}
 4541 
 4542 \begin{verbatim}
 4543         FTTKEY(keyword, > status)
 4544 \end{verbatim}
 4545 
 4546 \begin{description}
 4547 \item[5 ] Test that the keyword record contains only legal printable ASCII
 4548      characters
 4549 \end{description}
 4550 
 4551 \begin{verbatim}
 4552         FTTREC(card, > status)
 4553 \end{verbatim}
 4554 
 4555 \begin{description}
 4556 \item[6 ] Test whether the current header contains any NULL (ASCII 0) characters.
 4557     These characters are illegal in the header, but they will go undetected
 4558     by most of the CFITSIO keyword header routines, because the null is
 4559     interpreted as the normal end-of-string terminator.  This routine returns
 4560     the position of the first null character in the header, or zero if there
 4561     are no nulls.  For example a returned value of 110 would indicate that
 4562     the first NULL is located in the 30th character of the second keyword
 4563     in the header (recall that each header record is 80 characters long).
 4564     Note that this is one of the few FITSIO routines in which the returned
 4565    value is not necessarily equal to the status value).
 4566 \end{description}
 4567 
 4568 \begin{verbatim}
 4569         FTNCHK(unit, > status)
 4570 \end{verbatim}
 4571 
 4572 \begin{description}
 4573 \item[7 ] Parse a header keyword record and return the name of the keyword
 4574     and the length of the name.
 4575     The keyword name normally occupies the first 8 characters of the
 4576     record, except under the HIERARCH convention where the name can
 4577    be up to 70 characters in length.
 4578 \end{description}
 4579 
 4580 \begin{verbatim}
 4581         FTGKNM(card, > keyname, keylength, staThe '\#' character will match any consecutive string
 4582     of decimal digits (0 - 9). tus)
 4583 \end{verbatim}
 4584 
 4585 \begin{description}
 4586 \item[8 ] Parse a header keyword record.
 4587     This subroutine parses the input header record to return the value (as
 4588     a character string) and comment strings.  If the keyword has no
 4589     value (columns 9-10 not equal to '= '), then the value string is returned
 4590     blank and the comment string is set equal to column 9 - 80 of the
 4591    input string.
 4592 \end{description}
 4593 
 4594 \begin{verbatim}
 4595         FTPSVC(card, > value,comment,status)
 4596 \end{verbatim}
 4597 
 4598 \begin{description}
 4599 \item[9 ] Construct a properly formated 80-character header keyword record from the
 4600     input keyword name, keyword value, and keyword comment strings.
 4601     Hierarchical keyword names (e.g., "ESO TELE CAM") are supported.
 4602     The value string may contain an integer, floating point, logical, or
 4603     quoted character string (e.g., "12", "15.7", "T",
 4604     or "'NGC 1313'").
 4605 \end{description}
 4606 
 4607 \begin{verbatim}
 4608         FTMKKY(keyname, value, comment, > card, status)
 4609 \end{verbatim}
 4610 
 4611 \begin{description}
 4612 \item[10] Construct a sequence keyword name (ROOT + nnn).
 4613     This subroutine appends the sequence number to the root string to create
 4614    a keyword name (e.g., 'NAXIS' + 2 = 'NAXIS2')
 4615 \end{description}
 4616 
 4617 \begin{verbatim}
 4618         FTKEYN(keyroot,seq_no, > keyword,status)
 4619 \end{verbatim}
 4620 
 4621 \begin{description}
 4622 \item[11] Construct a sequence keyword name (n + ROOT).
 4623     This subroutine concatenates the sequence number to the front of the
 4624    root string to create a keyword name (e.g., 1 + 'CTYP' = '1CTYP')
 4625 \end{description}
 4626 
 4627 \begin{verbatim}
 4628         FTNKEY(seq_no,keyroot, > keyword,status)
 4629 \end{verbatim}
 4630 
 4631 \begin{description}
 4632 \item[12] Determine the datatype of a keyword value string.
 4633     This subroutine parses the keyword value string (usually columns 11-30
 4634    of the header record) to determine its datatype.
 4635 \end{description}
 4636 
 4637 \begin{verbatim}
 4638         FTDTYP(value, > dtype,status)
 4639 \end{verbatim}
 4640 
 4641 \begin{description}
 4642 \item[13] Return the class of input header record.  The record is classified
 4643     into one of the following categories (the class values are
 4644     defined in fitsio.h).  Note that this is one of the few FITSIO
 4645    routines that does not return a status value.
 4646 \end{description}
 4647 
 4648 \begin{verbatim}
 4649        Class  Value             Keywords
 4650   TYP_STRUC_KEY  10  SIMPLE, BITPIX, NAXIS, NAXISn, EXTEND, BLOCKED,
 4651                      GROUPS, PCOUNT, GCOUNT, END
 4652                      XTENSION, TFIELDS, TTYPEn, TBCOLn, TFORMn, THEAP,
 4653                      and the first 4 COMMENT keywords in the primary array
 4654                      that define the FITS format.
 4655   TYP_CMPRS_KEY  20  The keywords used in the compressed image  or table
 4656                      format, including ZIMAGE, ZCMPTYPE, ZNAMEn, ZVALn,
 4657                      ZTILEn, ZBITPIX, ZNAXISn, ZSCALE, ZZERO, ZBLANK
 4658   TYP_SCAL_KEY   30  BSCALE, BZERO, TSCALn, TZEROn
 4659   TYP_NULL_KEY   40  BLANK, TNULLn
 4660   TYP_DIM_KEY    50  TDIMn
 4661   TYP_RANG_KEY   60  TLMINn, TLMAXn, TDMINn, TDMAXn, DATAMIN, DATAMAX
 4662   TYP_UNIT_KEY   70  BUNIT, TUNITn
 4663   TYP_DISP_KEY   80  TDISPn
 4664   TYP_HDUID_KEY  90  EXTNAME, EXTVER, EXTLEVEL, HDUNAME, HDUVER, HDULEVEL
 4665   TYP_CKSUM_KEY 100  CHECKSUM, DATASUM
 4666   TYP_WCS_KEY   110  CTYPEn, CUNITn, CRVALn, CRPIXn, CROTAn, CDELTn
 4667                      CDj_is, PVj_ms, LONPOLEs, LATPOLEs
 4668                      TCTYPn, TCTYns, TCUNIn, TCUNns, TCRVLn, TCRVns, TCRPXn,
 4669                      TCRPks, TCDn_k, TCn_ks, TPVn_m, TPn_ms, TCDLTn, TCROTn
 4670                      jCTYPn, jCTYns, jCUNIn, jCUNns, jCRVLn, jCRVns, iCRPXn,
 4671                      iCRPns, jiCDn,  jiCDns, jPVn_m, jPn_ms, jCDLTn, jCROTn
 4672                      (i,j,m,n are integers, s is any letter)
 4673   TYP_REFSYS_KEY 120 EQUINOXs, EPOCH, MJD-OBSs, RADECSYS, RADESYSs
 4674   TYP_COMM_KEY   130 COMMENT, HISTORY, (blank keyword)
 4675   TYP_CONT_KEY   140 CONTINUE
 4676   TYP_USER_KEY   150 all other keywords
 4677 
 4678          class = FTGKCL (char *card)
 4679 \end{verbatim}
 4680 
 4681 \begin{description}
 4682 \item[14] Parse the 'TFORM' binary table column format string.
 4683     This subroutine parses the input TFORM character string and returns the
 4684     integer datatype code, the repeat count of the field, and, in the case
 4685     of character string fields, the length of the unit string.  The following
 4686     datatype codes are returned (the negative of the value is returned
 4687    if the column contains variable-length arrays):
 4688 \end{description}
 4689 
 4690 \begin{verbatim}
 4691                 Datatype                DATACODE value
 4692                 bit, X                   1
 4693                 byte, B                 11
 4694                 logical, L              14
 4695                 ASCII character, A      16
 4696                 short integer, I        21
 4697                 integer, J              41
 4698                 real, E                 42
 4699                 double precision, D     82
 4700                 complex                 83
 4701                 double complex          163
 4702 
 4703         FTBNFM(tform, > datacode,repeat,width,status)
 4704 \end{verbatim}
 4705 
 4706 \begin{description}
 4707 \item[15] Parse the 'TFORM' keyword value that defines the column format in
 4708     an ASCII table.  This routine parses the input TFORM character
 4709     string and returns the datatype code, the width of the column,
 4710     and (if it is a floating point column) the number of decimal places
 4711     to the right of the decimal point.  The returned datatype codes are
 4712     the same as for the binary table, listed above, with the following
 4713     additional rules:  integer columns that are between 1 and 4 characters
 4714     wide are defined to be short integers (code = 21).  Wider integer
 4715     columns are defined to be regular integers (code = 41).  Similarly,
 4716     Fixed decimal point columns (with TFORM = 'Fw.d') are defined to
 4717     be single precision reals (code = 42) if w is between 1 and 7 characters
 4718     wide, inclusive.  Wider 'F' columns will return a double precision
 4719     data code (= 82).  'Ew.d' format columns will have datacode = 42,
 4720    and 'Dw.d' format columns will have datacode = 82.
 4721 \end{description}
 4722 
 4723 \begin{verbatim}
 4724         FTASFM(tform, > datacode,width,decimals,status)
 4725 \end{verbatim}
 4726 
 4727 \begin{description}
 4728 \item[16] Calculate the starting column positions and total ASCII table width
 4729     based on the input array of ASCII table TFORM values.  The SPACE input
 4730     parameter defines how many blank spaces to leave between each column
 4731     (it is recommended to have one space between columns for better human
 4732    readability).
 4733 \end{description}
 4734 
 4735 \begin{verbatim}
 4736         FTGABC(tfields,tform,space, > rowlen,tbcol,status)
 4737 \end{verbatim}
 4738 
 4739 \begin{description}
 4740 \item[17] Parse a template string and return a formatted 80-character string
 4741     suitable for appending to (or deleting from) a FITS header file.
 4742     This subroutine is useful for parsing lines from an ASCII template file
 4743     and reformatting them into legal FITS header records.  The formatted
 4744     string may then be passed to the FTPREC, FTMCRD, or FTDKEY subroutines
 4745    to append or modify a FITS header record.
 4746 \end{description}
 4747 
 4748 \begin{verbatim}
 4749         FTGTHD(template, > card,hdtype,status)
 4750 \end{verbatim}
 4751     The input TEMPLATE character string generally should contain 3 tokens:
 4752     (1) the KEYNAME, (2) the VALUE, and (3) the COMMENT string.  The
 4753     TEMPLATE string must adhere to the following format:
 4754 
 4755 
 4756 \begin{description}
 4757 \item[- ]     The KEYNAME token must begin in columns 1-8 and be a maximum  of 8
 4758         characters long.  If the first 8 characters of the template line are
 4759         blank then the remainder of the line is considered to be a FITS comment
 4760         (with a blank keyword name).  A legal FITS keyword name may only
 4761         contain the characters A-Z, 0-9, and '-' (minus sign) and
 4762         underscore.  This subroutine will automatically convert any lowercase
 4763         characters to uppercase in the output string.  If KEYNAME = 'COMMENT'
 4764         or 'HISTORY' then the remainder of the line is considered to be a FITS
 4765        COMMENT or HISTORY record, respectively.
 4766 \end{description}
 4767 
 4768 
 4769 \begin{description}
 4770 \item[- ]     The VALUE token must be separated from the KEYNAME token by one or more
 4771         spaces and/or an '=' character.  The datatype of the VALUE token
 4772         (numeric, logical, or character string) is automatically determined
 4773         and  the output CARD string is formatted accordingly.  The value
 4774         token may be forced to be interpreted as a string (e.g. if it is a
 4775         string of numeric digits) by enclosing it in single quotes.
 4776         If the value token is a character string that contains 1 or more
 4777         embedded blank space characters or slash ('/') characters then the
 4778        entire character string must be enclosed in single quotes.
 4779 \end{description}
 4780 
 4781 
 4782 \begin{description}
 4783 \item[- ]     The COMMENT token is optional, but if present must be separated from
 4784        the VALUE token by a blank space or a  '/' character.
 4785 \end{description}
 4786 
 4787 
 4788 \begin{description}
 4789 \item[- ]     One exception to the above rules is that if the first non-blank
 4790         character in the template string is a minus sign ('-') followed
 4791         by a single token, or a single token followed by an equal sign,
 4792         then it is interpreted as the name of a keyword which is to be
 4793        deleted from the FITS header.
 4794 \end{description}
 4795 
 4796 
 4797 \begin{description}
 4798 \item[- ]     The second exception is that if the template string starts with
 4799         a minus sign and is followed by 2 tokens then the second token
 4800         is interpreted as the new name for the keyword specified by
 4801         first token.  In this case the old keyword name (first token)
 4802         is returned in characters 1-8 of the returned CARD string, and
 4803         the new keyword name (the second token) is returned in characters
 4804         41-48 of the returned CARD string.  These old and new names
 4805         may then be passed to the FTMNAM subroutine which will change
 4806        the keyword name.
 4807 \end{description}
 4808 
 4809     The HDTYPE output parameter indicates how the returned CARD string
 4810     should be interpreted:
 4811 
 4812 \begin{verbatim}
 4813         hdtype                  interpretation
 4814         ------           -------------------------------------------------
 4815            -2            Modify the name of the keyword given in CARD(1:8)
 4816                          to the new name given in CARD(41:48)
 4817 
 4818            -1            CARD(1:8) contains the name of a keyword to be deleted
 4819                          from the FITS header.
 4820 
 4821             0            append the CARD string to the FITS header if the
 4822                          keyword does not already exist, otherwise update
 4823                          the value/comment if the keyword is already present
 4824                          in the header.
 4825 
 4826             1            simply append this keyword to the FITS header (CARD
 4827                          is either a HISTORY or COMMENT keyword).
 4828 
 4829             2            This is a FITS END record; it should not be written
 4830                          to the FITS header because FITSIO automatically
 4831                          appends the END record when the header is closed.
 4832 \end{verbatim}
 4833      EXAMPLES:  The following lines illustrate valid input template strings:
 4834 
 4835 \begin{verbatim}
 4836       INTVAL 7 This is an integer keyword
 4837       RVAL           34.6   /     This is a floating point keyword
 4838       EVAL=-12.45E-03  This is a floating point keyword in exponential notation
 4839       lval F This is a boolean keyword
 4840                   This is a comment keyword with a blank keyword name
 4841       SVAL1 = 'Hello world'   /  this is a string keyword
 4842       SVAL2  '123.5'  this is also a string keyword
 4843       sval3  123+  /  this is also a string keyword with the value '123+    '
 4844       # the following template line deletes the DATE keyword
 4845       - DATE
 4846       # the following template line modifies the NAME keyword to OBJECT
 4847       - NAME OBJECT
 4848 \end{verbatim}
 4849 
 4850 \begin{description}
 4851 \item[18]  Parse the input string containing a list of rows or row ranges, and
 4852      return integer arrays containing the first and last row in each
 4853      range.  For example, if rowlist = "3-5, 6, 8-9" then it will
 4854      return numranges = 3, rangemin = 3, 6, 8 and rangemax = 5, 6, 9.
 4855      At most, 'maxranges' number of ranges will be returned.  'maxrows'
 4856      is the maximum number of rows in the table; any rows or ranges
 4857      larger than this will be ignored.  The rows must be specified in
 4858      increasing order, and the ranges must not overlap. A minus sign
 4859      may be use to specify all the rows to the upper or lower bound, so
 4860      "50-" means all the rows from 50 to the end of the table, and "-"
 4861     means all the rows in the table, from 1 - maxrows.
 4862 \end{description}
 4863 
 4864 \begin{verbatim}
 4865     FTRWRG(rowlist, maxrows, maxranges, >
 4866            numranges, rangemin, rangemax, status)
 4867 \end{verbatim}
 4868 
 4869 
 4870 
 4871 \chapter{ The CFITSIO Iterator Function }
 4872 
 4873 The fits\_iterate\_data function in CFITSIO provides a unique method of
 4874 executing an arbitrary user-supplied `work' function that operates on
 4875 rows of data in  FITS tables or on pixels in FITS images.  Rather than
 4876 explicitly reading and writing the FITS images or columns of data, one
 4877 instead calls the CFITSIO iterator routine, passing to it the name of
 4878 the user's work function that is to be executed along with a list of
 4879 all the table columns or image arrays that are to be passed to the work
 4880 function.  The CFITSIO iterator function then does all the work of
 4881 allocating memory for the arrays, reading the input data from the FITS
 4882 file, passing them to the work function, and then writing any output
 4883 data back to the FITS file after the work function exits.  Because
 4884 it is often more efficient to process only a subset of the total table
 4885 rows at one time, the iterator function can determine the optimum
 4886 amount of data to pass in each iteration and repeatedly call the work
 4887 function until the entire table been processed.
 4888 
 4889 For many applications this single CFITSIO iterator function can
 4890 effectively replace all the other CFITSIO routines for reading or
 4891 writing data in FITS images or tables.  Using the iterator has several
 4892 important advantages over the traditional method of reading and writing
 4893 FITS data files:
 4894 
 4895 \begin{itemize}
 4896 \item
 4897 It cleanly separates the data I/O from the routine that operates on
 4898 the data.  This leads to a more modular and `object oriented'
 4899 programming style.
 4900 
 4901 \item
 4902 It simplifies the application program by eliminating the need to allocate
 4903 memory for the data arrays and eliminates most of the calls to the CFITSIO
 4904 routines that explicitly read and write the data.
 4905 
 4906 \item
 4907 It ensures that the data are processed as efficiently as possible.
 4908 This is especially important when processing tabular data since
 4909 the iterator function will calculate the most efficient number
 4910 of rows in the table to be passed at one time to the user's work
 4911 function on each iteration.
 4912 
 4913 \item
 4914 Makes it possible for larger projects to develop a library of work
 4915 functions that all have a uniform calling sequence and are all
 4916 independent of the details of the FITS file format.
 4917 
 4918 \end{itemize}
 4919 
 4920 There are basically 2 steps in using the CFITSIO iterator function.
 4921 The first step is to design the work function itself which must have a
 4922 prescribed set of input parameters.  One of these parameters is a
 4923 structure containing pointers to the arrays of data; the work function
 4924 can perform any desired operations on these arrays and does not need to
 4925 worry about how the input data were read from the file or how the
 4926 output data get written back to the file.
 4927 
 4928 The second step is to design the driver routine that opens all the
 4929 necessary FITS files and initializes  the input parameters to the
 4930 iterator function.  The driver program calls the CFITSIO iterator
 4931 function which then reads the data and passes it to the user's work
 4932 function.
 4933 
 4934 Further details on using the iterator function can be found in the
 4935 companion CFITSIO User's Guide, and in the iter\_a.f, iter\_b.f and
 4936 iter\_c.f example programs.
 4937 
 4938 
 4939 
 4940 \chapter{  Extended File Name Syntax }
 4941 
 4942 
 4943 \section{Overview}
 4944 
 4945 CFITSIO supports an extended syntax when specifying the name of the
 4946 data file to be opened or created  that includes the following
 4947 features:
 4948 
 4949 \begin{itemize}
 4950 \item
 4951 CFITSIO can read IRAF format images which have header file names that
 4952 end with the '.imh' extension, as well as reading and writing FITS
 4953 files,   This feature is implemented in CFITSIO by first converting the
 4954 IRAF image into a temporary FITS format file in memory, then opening
 4955 the FITS file.  Any of the usual CFITSIO routines then may be used to
 4956 read the image header or data.  Similarly, raw binary data arrays can
 4957 be read by converting them on the fly into virtual FITS images.
 4958 
 4959 \item
 4960 FITS files on the Internet can be read (and sometimes written) using the FTP,
 4961 HTTP, or ROOT protocols.
 4962 
 4963 \item
 4964 FITS files can be piped between tasks on the stdin and stdout streams.
 4965 
 4966 \item
 4967 FITS files can be read and written in shared memory.  This can potentially
 4968 achieve much better data I/O performance compared to reading and
 4969 writing the same FITS files on magnetic disk.
 4970 
 4971 \item
 4972 Compressed FITS files in gzip or Unix COMPRESS format can be directly read.
 4973 
 4974 \item
 4975 Output FITS files can be written directly in compressed gzip format,
 4976 thus saving disk space.
 4977 
 4978 \item
 4979 FITS table columns can be created, modified, or deleted 'on-the-fly' as
 4980 the table is opened by CFITSIO.  This creates a virtual FITS file containing
 4981 the modifications that is then opened by the application program.
 4982 
 4983 \item
 4984 Table rows may be selected, or filtered out, on the fly when the table
 4985 is opened by CFITSIO, based on an arbitrary user-specified expression.
 4986 Only rows for which the expression evaluates to 'TRUE' are retained
 4987 in the copy of the table that is opened by the application program.
 4988 
 4989 \item
 4990 Histogram images may be created on the fly by binning the values in
 4991 table columns, resulting in a virtual N-dimensional FITS image.  The
 4992 application program then only sees the FITS image (in the primary
 4993 array) instead of the original FITS table.
 4994 \end{itemize}
 4995 
 4996 The latter 3 features in particular add very powerful data processing
 4997 capabilities directly into CFITSIO, and hence into every task that uses
 4998 CFITSIO to read or write FITS files.  For example, these features
 4999 transform a very simple program that just copies an input FITS file to
 5000 a new output file (like the `fitscopy' program that is distributed with
 5001 CFITSIO) into a multipurpose FITS file processing tool.  By appending
 5002 fairly simple qualifiers onto the name of the input FITS file, the user
 5003 can perform quite complex table editing operations (e.g., create new
 5004 columns, or filter out rows in a table) or create FITS images by
 5005 binning or histogramming the values in table columns.  In addition,
 5006 these functions have been coded using new state-of-the art algorithms
 5007 that are, in some cases, 10 - 100 times faster than previous widely
 5008 used implementations.
 5009 
 5010 Before describing the complete syntax for the extended FITS file names
 5011 in the next section, here are a few examples of FITS file names that
 5012 give a quick overview of the allowed syntax:
 5013 
 5014 \begin{itemize}
 5015 \item
 5016 {\tt 'myfile.fits'}: the simplest case of a FITS file on disk in the current
 5017 directory.
 5018 
 5019 \item
 5020 {\tt 'myfile.imh'}: opens an IRAF format image file and converts it on the
 5021 fly into a temporary FITS format image in memory which can then be read with
 5022 any other CFITSIO routine.
 5023 
 5024 \item
 5025 {\tt rawfile.dat[i512,512]}: opens a raw binary data array (a 512 x 512
 5026 short integer array in this case) and converts it on the fly into a
 5027 temporary FITS format image in memory which can then be read with any
 5028 other CFITSIO routine.
 5029 
 5030 \item
 5031 {\tt myfile.fits.gz}: if this is the name of a new output file, the '.gz'
 5032 suffix will cause it to be compressed in gzip format when it is written to
 5033 disk.
 5034 
 5035 \item
 5036 {\tt 'myfile.fits.gz[events, 2]'}:  opens and uncompresses the gzipped file
 5037 myfile.fits then moves to the extension which has the keywords EXTNAME
 5038 = 'EVENTS' and EXTVER = 2.
 5039 
 5040 \item
 5041 {\tt '-'}:  a dash (minus sign) signifies that the input file is to be read
 5042 from the stdin file stream, or that the output file is to be written to
 5043 the stdout stream.
 5044 
 5045 \item
 5046 {\tt 'ftp://legacy.gsfc.nasa.gov/test/vela.fits'}:  FITS files in any ftp
 5047 archive site on the Internet may be directly opened with read-only
 5048 access.
 5049 
 5050 \item
 5051 {\tt 'http://legacy.gsfc.nasa.gov/software/test.fits'}: any valid URL to a
 5052 FITS file on the Web may be opened with read-only access.
 5053 
 5054 \item
 5055 {\tt 'root://legacy.gsfc.nasa.gov/test/vela.fits'}: similar to ftp access
 5056 except that it provides write as well as read access to the files
 5057 across the network. This uses the root protocol developed at CERN.
 5058 
 5059 \item
 5060 {\tt 'shmem://h2[events]'}: opens the FITS file in a shared memory segment and
 5061 moves to the EVENTS extension.
 5062 
 5063 \item
 5064 {\tt 'mem://'}:  creates a scratch output file in core computer memory.  The
 5065 resulting 'file' will disappear when the program exits, so this
 5066 is mainly useful for testing purposes when one does not want a
 5067 permanent copy of the output file.
 5068 
 5069 \item
 5070 {\tt 'myfile.fits[3; Images(10)]'}: opens a copy of the image contained in the
 5071 10th row of the 'Images' column in the binary table in the 3th extension
 5072 of the FITS file.  The application just sees this single image as the
 5073 primary array.
 5074 
 5075 \item
 5076 {\tt 'myfile.fits[1:512:2, 1:512:2]'}: opens a section of the input image
 5077 ranging from the 1st to the 512th pixel in  X and Y, and selects every
 5078 second pixel in both dimensions, resulting in a 256 x 256 pixel image
 5079 in this case.
 5080 
 5081 \item
 5082 {\tt 'myfile.fits[EVENTS][col Rad = sqrt(X**2 + Y**2)]'}:  creates and opens
 5083 a temporary file on the fly (in memory or on disk) that is identical to
 5084 myfile.fits except that it will contain a new column in the EVENTS
 5085 extension called 'Rad' whose value is computed using the indicated
 5086 expression which is a function of the values in the X and Y columns.
 5087 
 5088 \item
 5089 {\tt 'myfile.fits[EVENTS][PHA > 5]'}:  creates and opens a temporary FITS
 5090 files that is identical to 'myfile.fits' except that the EVENTS table
 5091 will only contain the rows that have values of the PHA column greater
 5092 than 5.  In general, any arbitrary boolean expression using a C or
 5093 Fortran-like syntax, which may combine AND and OR operators,
 5094 may be used to select rows from a table.
 5095 
 5096 \item
 5097 {\tt 'myfile.fits[EVENTS][bin (X,Y)=1,2048,4]'}:  creates a temporary FITS
 5098 primary array image which is computed on the fly by binning (i.e,
 5099 computing the 2-dimensional histogram) of the values in the X and Y
 5100 columns of the EVENTS extension.  In this case the X and Y coordinates
 5101 range from 1 to 2048 and the image pixel size is 4 units in both
 5102 dimensions, so the resulting image is 512 x 512 pixels in size.
 5103 
 5104 \item
 5105 The final example combines many of these feature into one complex
 5106 expression (it is broken into several lines for clarity):
 5107 
 5108 \begin{verbatim}
 5109   'ftp://legacy.gsfc.nasa.gov/data/sample.fits.gz[EVENTS]
 5110    [col phacorr = pha * 1.1 - 0.3][phacorr >= 5.0 && phacorr <= 14.0]
 5111    [bin (X,Y)=32]'
 5112 \end{verbatim}
 5113 In this case, CFITSIO (1) copies and uncompresses the FITS file from
 5114 the ftp site on the legacy machine, (2) moves to the 'EVENTS'
 5115 extension, (3) calculates a new column called 'phacorr', (4) selects
 5116 the rows in the table that have phacorr in the range 5 to 14, and
 5117 finally (5) bins the remaining rows on the X and Y column coordinates,
 5118 using a pixel size = 32 to create a 2D image.  All this processing is
 5119 completely transparent to the application program, which simply sees
 5120 the final 2-D image in the primary array of the opened file.
 5121 \end{itemize}
 5122 
 5123 The full extended CFITSIO FITS file name can contain several different
 5124 components depending on the context.  These components are described in
 5125 the following sections:
 5126 
 5127 \begin{verbatim}
 5128 When creating a new file:
 5129    filetype://BaseFilename(templateName)
 5130 
 5131 When opening an existing primary array or image HDU:
 5132    filetype://BaseFilename(outName)[HDUlocation][ImageSection]
 5133 
 5134 When opening an existing table HDU:
 5135    filetype://BaseFilename(outName)[HDUlocation][colFilter][rowFilter][binSpec]
 5136 \end{verbatim}
 5137 The filetype, BaseFilename, outName, HDUlocation, and ImageSection
 5138 components, if present, must be given in that order, but the colFilter,
 5139 rowFilter, and binSpec specifiers may follow in any order.  Regardless
 5140 of the order, however, the colFilter specifier, if present, will be
 5141 processed first by CFITSIO, followed by the rowFilter specifier, and
 5142 finally by the binSpec specifier.
 5143 
 5144 
 5145 Multiple colFilter or rowFilter specifications may appear as separated
 5146 bracketed expressions, in any order.  Multiple colFilter or rowFilter
 5147 expressions are treated internally as a single effective expression,
 5148 with order of operations determined from left to right.  CFITSIO does
 5149 not support the @filename.txt complex syntax option if multiple
 5150 expressions are also used.
 5151 
 5152 \section{Filetype}
 5153 
 5154 The type of file determines the medium on which the file is located
 5155 (e.g., disk or network) and, hence, which internal device driver is used by
 5156 CFITSIO to read and/or write the file.  Currently supported types are
 5157 
 5158 \begin{verbatim}
 5159         file://  - file on local magnetic disk (default)
 5160         ftp://   - a readonly file accessed with the anonymous FTP protocol.
 5161                    It also supports  ftp://username:password@hostname/...
 5162                    for accessing password-protected ftp sites.
 5163         http://  - a readonly file accessed with the HTTP protocol.  It
 5164                    supports username:password just like the ftp driver.
 5165                    Proxy HTTP servers are supported using the http_proxy
 5166                    environment variable (see following note).
 5167       stream://  - special driver to read an input FITS file from the stdin
 5168                    stream, and/or write an output FITS file to the stdout
 5169            stream.  This driver is fragile and has limited
 5170            functionality (see the following note).
 5171       gsiftp://  - access files on a computational grid using the gridftp
 5172                    protocol in the Globus toolkit (see following note).
 5173         root://  - uses the CERN root protocol for writing as well as
 5174                    reading files over the network.
 5175         shmem:// - opens or creates a file which persists in the computer's
 5176                    shared memory.
 5177         mem://   - opens a temporary file in core memory.  The file
 5178                    disappears when the program exits so this is mainly
 5179                    useful for test purposes when a permanent output file
 5180                    is not desired.
 5181 \end{verbatim}
 5182 If the filetype is not specified, then type file:// is assumed.
 5183 The double slashes '//' are optional and may be omitted in most cases.
 5184 
 5185 
 5186 \subsection{Notes about HTTP proxy servers}
 5187 
 5188 A proxy HTTP server may be used by defining the address (URL) and port
 5189 number of the proxy server with the http\_proxy environment variable.
 5190 For example
 5191 
 5192 \begin{verbatim}
 5193     setenv http_proxy http://heasarc.gsfc.nasa.gov:3128
 5194 \end{verbatim}
 5195 will cause CFITSIO to use port 3128 on the heasarc proxy server whenever
 5196 reading a FITS file with HTTP.
 5197 
 5198 
 5199 \subsection{Notes about the stream filetype driver}
 5200 
 5201 The stream driver can be used to efficiently read a FITS file from the stdin
 5202 file stream or write a FITS to the stdout file stream.  However, because these
 5203 input and output streams must be accessed sequentially, the FITS file reading or
 5204 writing application must also read and write the file sequentially, at least
 5205 within the tolerances described below.
 5206 
 5207 CFITSIO supports 2 different methods for accessing FITS files on the stdin and
 5208 stdout streams.  The original method, which is invoked by specifying a dash
 5209 character, "-", as the name of the file when opening or creating it, works by
 5210 storing a complete copy of the entire FITS file in memory.  In this case, when
 5211 reading from stdin, CFITSIO will copy the entire stream into memory before doing
 5212 any processing of the file.  Similarly, when writing to stdout, CFITSIO will
 5213 create a copy of the entire FITS file in memory, before finally flushing it out
 5214 to  the stdout stream when the FITS file is closed.  Buffering the entire FITS
 5215 file in this way allows the application to randomly access any part of the FITS
 5216 file, in any order, but it also requires that the user have sufficient available
 5217 memory (or virtual memory) to store the entire file, which may not be possible
 5218 in the case of very large files.
 5219 
 5220 The newer stream filetype provides a more memory-efficient method of accessing
 5221 FITS files on the stdin or stdout streams.  Instead of storing a copy of the
 5222 entire FITS file in memory, CFITSIO only uses a set of internal  buffer which by
 5223 default can store  40 FITS blocks, or about  100K bytes of the FITS file.  The
 5224 application program must process the FITS file sequentially from beginning to
 5225 end, within this 100K buffer.  Generally speaking the application  program must
 5226 conform to the following restrictions:
 5227 
 5228 \begin{itemize}
 5229 \item
 5230 The program must finish reading or writing the header keywords
 5231 before reading or writing any data in the HDU.
 5232 \item
 5233 The HDU can contain at most about 1400 header keywords.  This is the
 5234 maximum that can fit in the nominal 40 FITS block buffer.  In principle,
 5235 this limit could be increased by recompiling CFITSIO with a larger
 5236 buffer limit, which is set by the NIOBUF parameter in fitsio2.h.
 5237 \item
 5238 The program must read or write the data in a sequential manner from the
 5239 beginning to the end of the HDU.  Note that CFITSIO's internal
 5240 100K buffer allows a little latitude in meeting this requirement.
 5241 \item
 5242 The program cannot move back to a previous HDU in the FITS file.
 5243 \item
 5244 Reading or writing of variable length array columns in binary tables is not
 5245 supported on streams, because this requires moving back and forth between the
 5246 fixed-length portion of the binary table and the following heap area where the
 5247 arrays are actually stored.
 5248 \item
 5249 Reading or writing of tile-compressed images is not supported on streams,
 5250 because the images are internally stored using variable length arrays.
 5251 \end{itemize}
 5252 
 5253 
 5254 \subsection{Notes about the gsiftp filetype}
 5255 
 5256 DEPENDENCIES: Globus toolkit (2.4.3 or higher) (GT) should be installed.
 5257 There are two different ways to install GT:
 5258 
 5259 1) goto the globus toolkit web page www.globus.org and follow the
 5260    download and compilation instructions;
 5261 
 5262 2) goto the Virtual Data Toolkit web page http://vdt.cs.wisc.edu/
 5263    and follow the instructions (STRONGLY SUGGESTED);
 5264 
 5265 Once a globus client has been installed in your system with a specific flavour
 5266 it is possible to compile and install the CFITSIO libraries.
 5267 Specific configuration flags must be used:
 5268 
 5269 1)  --with-gsiftp[[=PATH]] Enable Globus Toolkit gsiftp protocol support
 5270     PATH=GLOBUS\_LOCATION i.e. the location of your globus installation
 5271 
 5272 2)  --with-gsiftp-flavour[[=PATH] defines the specific Globus flavour
 5273         ex. gcc32
 5274 
 5275 Both the flags must be used and it is mandatory to set  both the PATH and the
 5276 flavour.
 5277 
 5278 USAGE: To access files on a gridftp server it is necessary to use a gsiftp prefix:
 5279 
 5280 example: gsiftp://remote\_server\_fqhn/directory/filename
 5281 
 5282 The gridftp driver uses a local buffer on a temporary file the file is located
 5283 in the /tmp directory. If you have special permissions on /tmp or you do not have a /tmp
 5284 directory, it is possible to force another location setting the GSIFTP\_TMPFILE environment
 5285 variable (ex. export GSIFTP\_TMPFILE=/your/location/yourtmpfile).
 5286 
 5287 Grid FTP supports multi channel transfer. By default a single channel transmission is
 5288 available. However, it is possible to modify this behavior setting the GSIFTP\_STREAMS
 5289 environment variable (ex. export GSIFTP\_STREAMS=8).
 5290 
 5291 
 5292 \subsection{Notes about the root filetype}
 5293 
 5294 The original rootd server can be obtained from:
 5295 \verb-ftp://root.cern.ch/root/rootd.tar.gz-
 5296 but, for it to work correctly with CFITSIO one has to use a modified
 5297 version which supports a command to return the length of the file.
 5298 This modified version is available in rootd subdirectory
 5299 in the CFITSIO ftp area at
 5300 
 5301 \begin{verbatim}
 5302       ftp://legacy.gsfc.nasa.gov/software/fitsio/c/root/rootd.tar.gz.
 5303 \end{verbatim}
 5304 
 5305 This small server is started either by inetd when a client requests a
 5306 connection to a rootd server or by hand (i.e. from the command line).
 5307 The rootd server works with the ROOT TNetFile class. It allows remote
 5308 access to ROOT database files in either read or write mode. By default
 5309 TNetFile assumes port 432 (which requires rootd to be started as root).
 5310 To run rootd via inetd add the following line to /etc/services:
 5311 
 5312 \begin{verbatim}
 5313   rootd     432/tcp
 5314 \end{verbatim}
 5315 and to /etc/inetd.conf, add the following line:
 5316 
 5317 \begin{verbatim}
 5318   rootd stream tcp nowait root /user/rdm/root/bin/rootd rootd -i
 5319 \end{verbatim}
 5320 Force inetd to reread its conf file with "kill -HUP <pid inetd>".
 5321 You can also start rootd by hand running directly under your private
 5322 account (no root system privileges needed). For example to start
 5323 rootd listening on port 5151 just type:   \verb+rootd -p 5151+
 5324 Notice: no \& is needed. Rootd will go into background by itself.
 5325 
 5326 \begin{verbatim}
 5327   Rootd arguments:
 5328     -i                says we were started by inetd
 5329     -p port#          specifies a different port to listen on
 5330     -d level          level of debug info written to syslog
 5331                       0 = no debug (default)
 5332                       1 = minimum
 5333                       2 = medium
 5334                       3 = maximum
 5335 \end{verbatim}
 5336 Rootd can also be configured for anonymous usage (like anonymous ftp).
 5337 To setup rootd to accept anonymous logins do the following (while being
 5338 logged in as root):
 5339 
 5340 \begin{verbatim}
 5341    - Add the following line to /etc/passwd:
 5342 
 5343      rootd:*:71:72:Anonymous rootd:/var/spool/rootd:/bin/false
 5344 
 5345      where you may modify the uid, gid (71, 72) and the home directory
 5346      to suite your system.
 5347 
 5348    - Add the following line to /etc/group:
 5349 
 5350      rootd:*:72:rootd
 5351 
 5352      where the gid must match the gid in /etc/passwd.
 5353 
 5354    - Create the directories:
 5355 
 5356      mkdir /var/spool/rootd
 5357      mkdir /var/spool/rootd/tmp
 5358      chmod 777 /var/spool/rootd/tmp
 5359 
 5360      Where /var/spool/rootd must match the rootd home directory as
 5361      specified in the rootd /etc/passwd entry.
 5362 
 5363    - To make writeable directories for anonymous do, for example:
 5364 
 5365      mkdir /var/spool/rootd/pub
 5366      chown rootd:rootd /var/spool/rootd/pub
 5367 \end{verbatim}
 5368 That's all.  Several additional remarks:  you can login to an anonymous
 5369 server either with the names "anonymous" or "rootd".  The password should
 5370 be of type user@host.do.main. Only the @ is enforced for the time
 5371 being.  In anonymous mode the top of the file tree is set to the rootd
 5372 home directory, therefore only files below the home directory can be
 5373 accessed.  Anonymous mode only works when the server is started via
 5374 inetd.
 5375 
 5376 
 5377 \subsection{Notes about the shmem filetype:}
 5378 
 5379 Shared memory files are currently supported on most Unix platforms,
 5380 where the shared memory segments are managed by the operating system
 5381 kernel and `live' independently of processes. They are not deleted (by
 5382 default) when the process which created them terminates, although they
 5383 will disappear if the system is rebooted.  Applications can create
 5384 shared memory files in CFITSIO by calling:
 5385 
 5386 \begin{verbatim}
 5387    fit_create_file(&fitsfileptr, "shmem://h2", &status);
 5388 \end{verbatim}
 5389 where the root `file' names are currently restricted to be 'h0', 'h1',
 5390 'h2', 'h3', etc., up to a maximum number defined by the the value of
 5391 SHARED\_MAXSEG (equal to 16 by default).  This is a prototype
 5392 implementation of the shared memory interface and a more robust
 5393 interface, which will have fewer restrictions on the number of files
 5394 and on their names, may be developed in the future.
 5395 
 5396 When opening an already existing FITS file in shared memory one calls
 5397 the usual CFITSIO routine:
 5398 
 5399 \begin{verbatim}
 5400    fits_open_file(&fitsfileptr, "shmem://h7", mode, &status)
 5401 \end{verbatim}
 5402 The file mode can be READWRITE or READONLY just as with disk files.
 5403 More than one process can operate on READONLY mode files at the same
 5404 time.  CFITSIO supports proper file locking (both in READONLY and
 5405 READWRITE modes), so calls to fits\_open\_file may be locked out until
 5406 another other process closes the file.
 5407 
 5408 When an application is finished accessing a FITS file in a shared
 5409 memory segment, it may close it  (and the file will remain in the
 5410 system) with fits\_close\_file, or delete it with fits\_delete\_file.
 5411 Physical deletion is postponed until the last process calls
 5412 ffclos/ffdelt.  fits\_delete\_file tries to obtain a READWRITE lock on
 5413 the file to be deleted, thus it can be blocked if the object was not
 5414 opened in READWRITE mode.
 5415 
 5416 A shared memory management utility program called `smem', is included
 5417 with the CFITSIO distribution.  It can be built by typing `make smem';
 5418 then type `smem -h' to get a list of valid options.  Executing smem
 5419 without any options causes it to list all the shared memory segments
 5420 currently residing in the system and managed by the shared memory
 5421 driver. To get a list of all the shared memory objects, run the system
 5422 utility program `ipcs  [-a]'.
 5423 
 5424 
 5425 \section{Base Filename}
 5426 
 5427 The base filename is the name of the file optionally including the
 5428 director/subdirectory path, and in the case of `ftp', `http', and `root'
 5429 filetypes, the machine identifier.  Examples:
 5430 
 5431 \begin{verbatim}
 5432     myfile.fits
 5433     !data.fits
 5434     /data/myfile.fits
 5435     fits.gsfc.nasa.gov/ftp/sampledata/myfile.fits.gz
 5436 \end{verbatim}
 5437 
 5438 When creating a new output file on magnetic disk (of type file://) if
 5439 the base filename begins with an exclamation point (!) then any
 5440 existing file with that same basename will be deleted prior to creating
 5441 the new FITS file.  Otherwise if the file to be created already exists,
 5442 then CFITSIO will return an error and will not overwrite the existing
 5443 file.  Note  that the exclamation point,  '!', is a special UNIX character,
 5444 so if it is used  on the command line rather than entered at a task
 5445 prompt, it must be  preceded by a backslash to force the UNIX
 5446 shell to pass it verbatim to the application program.
 5447 
 5448 If the output disk file name ends with the suffix '.gz', then CFITSIO
 5449 will compress the file using the gzip compression algorithm before
 5450 writing it to disk.  This can reduce the amount of disk space used by
 5451 the file.  Note that this feature requires that the uncompressed file
 5452 be constructed in memory before it is compressed and written to disk,
 5453 so it can fail if there is insufficient available memory.
 5454 
 5455 An input FITS file may be compressed with the gzip or Unix compress
 5456 algorithms, in which case CFITSIO will uncompress the file on the fly
 5457 into a temporary file (in memory or on disk).  Compressed files may
 5458 only be opened with read-only permission.  When specifying the name of
 5459 a compressed FITS file it is not necessary to append the file suffix
 5460 (e.g., `.gz' or `.Z').  If CFITSIO cannot find the input file name
 5461 without the suffix, then it will automatically search for a compressed
 5462 file with the same root name.  In the case of reading ftp and http type
 5463 files, CFITSIO generally looks for a compressed version of the file
 5464 first, before trying to open the uncompressed file.  By default,
 5465 CFITSIO copies (and uncompressed if necessary) the ftp or http FITS
 5466 file into memory on the local machine before opening it.  This will
 5467 fail if the local machine does not have enough memory to hold the whole
 5468 FITS file, so in this case, the output filename specifier (see the next
 5469 section) can be used to further control how CFITSIO reads ftp and http
 5470 files.
 5471 
 5472 If the input file is an IRAF image file (*.imh file) then CFITSIO will
 5473 automatically convert it on the fly into a virtual FITS image before it
 5474 is opened by the application program.  IRAF images can only be opened
 5475 with READONLY file access.
 5476 
 5477 Similarly, if the input file is a raw binary data array, then CFITSIO
 5478 will convert it on the fly into a virtual FITS image with the basic set
 5479 of required header keywords before it is opened by the application
 5480 program (with READONLY access).  In this case the data type and
 5481 dimensions of the image must be specified in square brackets following
 5482 the filename (e.g. rawfile.dat[ib512,512]). The first character (case
 5483 insensitive) defines the datatype of the array:
 5484 
 5485 \begin{verbatim}
 5486      b         8-bit unsigned byte
 5487      i        16-bit signed integer
 5488      u        16-bit unsigned integer
 5489      j        32-bit signed integer
 5490      r or f   32-bit floating point
 5491      d        64-bit floating point
 5492 \end{verbatim}
 5493 An optional second character specifies the byte order of the array
 5494 values: b or B indicates big endian (as in FITS files and the native
 5495 format of SUN UNIX workstations and Mac PCs) and l or L indicates
 5496 little endian (native format of DEC OSF workstations and IBM PCs).  If
 5497 this character is omitted then the array is assumed to have the native
 5498 byte order of the local machine.  These datatype characters are then
 5499 followed by a series of one or more integer values separated by commas
 5500 which define the size of each dimension of the raw array.  Arrays with
 5501 up to 5 dimensions are currently supported.  Finally, a byte offset to
 5502 the position of the first pixel in the data file may be specified by
 5503 separating it with a ':' from the last dimension value.  If omitted, it
 5504 is assumed that the offset = 0.  This parameter may be used to skip
 5505 over any header information in the file that precedes the binary data.
 5506 Further examples:
 5507 
 5508 \begin{verbatim}
 5509   raw.dat[b10000]           1-dimensional 10000 pixel byte array
 5510   raw.dat[rb400,400,12]     3-dimensional floating point big-endian array
 5511   img.fits[ib512,512:2880]  reads the 512 x 512 short integer array in
 5512                             a FITS file, skipping over the 2880 byte header
 5513 \end{verbatim}
 5514 
 5515 One special case of input file is where the filename = `-' (a dash or
 5516 minus sign) or 'stdin' or 'stdout', which signifies that the input file
 5517 is to be read from the stdin stream, or written to the stdout stream if
 5518 a new output file is being created.  In the case of reading from stdin,
 5519 CFITSIO first copies the whole stream into a temporary FITS file (in
 5520 memory or on disk), and subsequent reading of the FITS file occurs in
 5521 this copy.  When writing to stdout, CFITSIO first constructs the whole
 5522 file in memory (since random access is required), then flushes it out
 5523 to the stdout stream when the file is closed.   In addition, if the
 5524 output filename = '-.gz' or 'stdout.gz' then it will be gzip compressed
 5525 before being written to stdout.
 5526 
 5527 This ability to read and write on the stdin and stdout steams allows
 5528 FITS files to be piped between tasks in memory rather than having to
 5529 create temporary intermediate FITS files on disk.  For example if task1
 5530 creates an output FITS file, and task2 reads an input FITS file, the
 5531 FITS file may be piped between the 2 tasks by specifying
 5532 
 5533 \begin{verbatim}
 5534    task1 - | task2 -
 5535 \end{verbatim}
 5536 where the vertical bar is the Unix piping symbol.  This assumes that the 2
 5537 tasks read the name of the FITS file off of the command line.
 5538 
 5539 
 5540 \section{Output File Name when Opening an Existing File}
 5541 
 5542 An optional output filename may be specified in parentheses immediately
 5543 following the base file name to be opened.  This is mainly useful in
 5544 those cases where CFITSIO creates a temporary copy of the input FITS
 5545 file before it is opened and passed to the application program.  This
 5546 happens by default when opening a network FTP or HTTP-type file, when
 5547 reading a compressed FITS file on a local disk, when reading from the
 5548 stdin stream, or when a column filter, row filter, or binning specifier
 5549 is included as part of the input file specification.  By default this
 5550 temporary file is created in memory.  If there is not enough memory to
 5551 create the file copy, then CFITSIO will exit with an error.   In these
 5552 cases one can force a permanent file to be created on disk, instead of
 5553 a temporary file in memory, by supplying the name in parentheses
 5554 immediately following the base file name.  The output filename can
 5555 include the '!' clobber flag.
 5556 
 5557 Thus, if the input filename to CFITSIO is:
 5558 \verb+file1.fits.gz(file2.fits)+
 5559 then CFITSIO will uncompress `file1.fits.gz' into the local disk file
 5560 `file2.fits' before opening it.  CFITSIO does not automatically delete
 5561 the output file, so it will still exist after the application program
 5562 exits.
 5563 
 5564 In some cases, several different temporary FITS files will be created
 5565 in sequence, for instance, if one opens a remote file using FTP, then
 5566 filters rows in a binary table extension, then create an image by
 5567 binning a pair of columns.  In this case, the remote file will be
 5568 copied to a temporary local file, then a second temporary file will be
 5569 created containing the filtered rows of the table, and finally a third
 5570 temporary file containing the binned image will be created.  In cases
 5571 like this where multiple files are created, the outfile specifier will
 5572 be interpreted the name of the final file as described below, in descending
 5573 priority:
 5574 
 5575 \begin{itemize}
 5576 \item
 5577 as the name of the final image file if an image within a single binary
 5578 table cell is opened or if an image is created by binning a table column.
 5579 \item
 5580 as the name of the file containing the filtered table if a column filter
 5581 and/or a row filter are specified.
 5582 \item
 5583 as the name of the local copy of the remote FTP or HTTP file.
 5584 \item
 5585 as the name of the uncompressed version of the FITS file, if a
 5586 compressed FITS file on local disk has been opened.
 5587 \item
 5588 otherwise, the output filename is ignored.
 5589 \end{itemize}
 5590 
 5591 
 5592 The output file specifier is useful when reading FTP or HTTP-type
 5593 FITS files since it can be used to create a local disk copy of the file
 5594 that can be reused in the future.  If the output file name = `*' then a
 5595 local file with the same name as the network file will be created.
 5596 Note that CFITSIO will behave differently depending on whether the
 5597 remote file is compressed or not as shown by the following examples:
 5598 \begin{itemize}
 5599 \item
 5600 `ftp://remote.machine/tmp/myfile.fits.gz(*)' - the remote compressed
 5601 file is copied to the local compressed file `myfile.fits.gz', which
 5602 is then uncompressed in local memory before being opened and passed
 5603 to the application program.
 5604 
 5605 \item
 5606 `ftp://remote.machine/tmp/myfile.fits.gz(myfile.fits)' - the remote
 5607 compressed file is copied and uncompressed into the local file
 5608 `myfile.fits'.  This example requires less local memory than the
 5609 previous example since the file is uncompressed on disk instead of
 5610 in memory.
 5611 
 5612 \item
 5613 `ftp://remote.machine/tmp/myfile.fits(myfile.fits.gz)' - this will
 5614 usually produce an error since CFITSIO itself cannot compress files.
 5615 \end{itemize}
 5616 
 5617 The exact behavior of CFITSIO in the latter case depends on the type of
 5618 ftp server running on the remote machine and how it is configured.  In
 5619 some cases, if the file `myfile.fits.gz' exists on the remote machine,
 5620 then the server will copy it to the local machine.  In other cases the
 5621 ftp server will automatically create and transmit a compressed version
 5622 of the file if only the uncompressed version exists.  This can get
 5623 rather confusing, so users should use a certain amount of caution when
 5624 using the output file specifier with FTP or HTTP file types, to make
 5625 sure they get the behavior that they expect.
 5626 
 5627 
 5628 \section{Template File Name when Creating a New File}
 5629 
 5630 When a new FITS file is created with a call to fits\_create\_file, the
 5631 name of a template file may be supplied in parentheses immediately
 5632 following the name of the new file to be created.  This template is
 5633 used to define the structure of one or more HDUs in the new file.  The
 5634 template file may be another FITS file, in which case the newly created
 5635 file will have exactly the same keywords in each HDU as in the template
 5636 FITS file, but all the data units will be filled with zeros.  The
 5637 template file may also be an ASCII text file, where each line (in
 5638 general) describes one FITS keyword record.  The format of the ASCII
 5639 template file is described below.
 5640 
 5641 
 5642 \section{Image Tile-Compression Specification}
 5643 
 5644 When specifying the name of the output FITS file to be created, the
 5645 user can indicate that images should be written in tile-compressed
 5646 format (see section 5.5, ``Primary Array or IMAGE Extension I/O
 5647 Routines'') by enclosing the compression parameters in square brackets
 5648 following the root disk file name.  Here are some examples of the
 5649 syntax for specifying tile-compressed output images:
 5650 
 5651 \begin{verbatim}
 5652     myfile.fit[compress]    - use Rice algorithm and default tile size
 5653 
 5654     myfile.fit[compress GZIP] - use the specified compression algorithm;
 5655     myfile.fit[compress Rice]     only the first letter of the algorithm
 5656     myfile.fit[compress PLIO]     name is required.
 5657 
 5658     myfile.fit[compress Rice 100,100]   - use 100 x 100 pixel tile size
 5659     myfile.fit[compress Rice 100,100;2] - as above, and use noisebits = 2
 5660 \end{verbatim}
 5661 
 5662 
 5663 \section{HDU Location Specification}
 5664 
 5665 The optional HDU location specifier defines which HDU (Header-Data
 5666 Unit, also known as an `extension') within the FITS file to initially
 5667 open.  It must immediately follow the base file name (or the output
 5668 file name if present).  If it is not specified then the first HDU (the
 5669 primary array) is opened.  The HDU location specifier is required if
 5670 the colFilter, rowFilter, or binSpec specifiers are present, because
 5671 the primary array is not a valid HDU for these operations. The HDU may
 5672 be specified either by absolute position number, starting with 0 for
 5673 the primary array, or by reference to the HDU name, and optionally, the
 5674 version number and the HDU type of the desired extension.  The location
 5675 of an image within a single cell of a binary table may also be
 5676 specified, as described below.
 5677 
 5678 The absolute position of the extension is specified either by enclosed
 5679 the number in square brackets (e.g., `[1]' = the first extension
 5680 following the primary array) or by preceded the number with a plus sign
 5681 (`+1').  To specify the HDU by name, give the name of the desired HDU
 5682 (the value of the EXTNAME or HDUNAME keyword) and optionally the
 5683 extension version number (value of the EXTVER keyword) and the
 5684 extension type (value of the XTENSION keyword: IMAGE, ASCII or TABLE,
 5685 or BINTABLE), separated by commas and all enclosed in square brackets.
 5686 If the value of EXTVER and XTENSION are not specified, then the first
 5687 extension with the correct value of EXTNAME is opened. The extension
 5688 name and type are not case sensitive, and the extension type may be
 5689 abbreviated to a single letter (e.g., I = IMAGE extension or primary
 5690 array, A or T = ASCII table extension, and B = binary table BINTABLE
 5691 extension).   If the HDU location specifier is equal to `[PRIMARY]' or
 5692 `[P]', then the primary array (the first HDU) will be opened.
 5693 
 5694 FITS images are most commonly stored in the primary array or an image
 5695 extension, but images can also be stored as a vector in a single cell
 5696 of a binary table (i.e. each row of the vector column contains a
 5697 different image).  Such an image can be opened with CFITSIO by
 5698 specifying the desired column  name and the row number after the binary
 5699 table HDU specifier as shown in the following examples. The column name
 5700 is separated from the HDU specifier by a semicolon and the row number
 5701 is enclosed in parentheses.  In this case CFITSIO copies the image from
 5702 the table cell into a temporary primary array before it is opened.  The
 5703 application program then just sees the image in the primary array,
 5704 without any extensions.  The particular row to be opened may be
 5705 specified either by giving an absolute integer row number (starting
 5706 with 1 for the first row), or by specifying a boolean expression that
 5707 evaluates to TRUE for the desired row.  The first row that satisfies
 5708 the expression will be used.  The row selection expression has the same
 5709 syntax as described in the Row Filter Specifier section, below.
 5710 
 5711  Examples:
 5712 
 5713 \begin{verbatim}
 5714    myfile.fits[3] - open the 3rd HDU following the primary array
 5715    myfile.fits+3  - same as above, but using the FTOOLS-style notation
 5716    myfile.fits[EVENTS] - open the extension that has EXTNAME = 'EVENTS'
 5717    myfile.fits[EVENTS, 2]  - same as above, but also requires EXTVER = 2
 5718    myfile.fits[events,2,b] - same, but also requires XTENSION = 'BINTABLE'
 5719    myfile.fits[3; images(17)] - opens the image in row 17 of the 'images'
 5720                                 column in the 3rd extension of the file.
 5721    myfile.fits[3; images(exposure > 100)] - as above, but opens the image
 5722                    in the first row that has an 'exposure' column value
 5723                    greater than 100.
 5724 \end{verbatim}
 5725 
 5726 
 5727 \section{Image Section}
 5728 
 5729 A virtual file containing a rectangular subsection of an image can be
 5730 extracted and opened by specifying the range of pixels (start:end)
 5731 along each axis to be extracted from the original image.  One can also
 5732 specify an optional pixel increment (start:end:step) for each axis of
 5733 the input image.  A pixel step = 1 will be assumed if it is not
 5734 specified.  If the start pixel is larger then the end pixel, then the
 5735 image will be flipped (producing a mirror image) along that dimension.
 5736 An asterisk, '*', may be used to specify the entire range of an axis,
 5737 and '-*' will flip the entire axis. The input image can be in the
 5738 primary array, in an image extension, or contained in a vector cell of
 5739 a binary table. In the later 2 cases the extension name or number must
 5740 be specified before the image section specifier.
 5741 
 5742  Examples:
 5743 
 5744 \begin{verbatim}
 5745   myfile.fits[1:512:2, 2:512:2] -  open a 256x256 pixel image
 5746               consisting of the odd numbered columns (1st axis) and
 5747               the even numbered rows (2nd axis) of the image in the
 5748               primary array of the file.
 5749 
 5750   myfile.fits[*, 512:256] - open an image consisting of all the columns
 5751               in the input image, but only rows 256 through 512.
 5752               The image will be flipped along the 2nd axis since
 5753               the starting pixel is greater than the ending pixel.
 5754 
 5755   myfile.fits[*:2, 512:256:2] - same as above but keeping only
 5756               every other row and column in the input image.
 5757 
 5758   myfile.fits[-*, *] - copy the entire image, flipping it along
 5759               the first axis.
 5760 
 5761   myfile.fits[3][1:256,1:256] - opens a subsection of the image that
 5762               is in the 3rd extension of the file.
 5763 
 5764   myfile.fits[4; images(12)][1:10,1:10] - open an image consisting
 5765           of the first 10 pixels in both dimensions. The original
 5766           image resides in the 12th row of the 'images' vector
 5767           column in the table in the 4th extension of the file.
 5768 \end{verbatim}
 5769 
 5770 When CFITSIO opens an image section it first creates a temporary file
 5771 containing the image section plus a copy of any other HDUs in the
 5772 file.  This temporary file is then opened by the application program,
 5773 so it is not possible to write to or modify the input file when
 5774 specifying an image section.  Note that CFITSIO automatically updates
 5775 the world coordinate system keywords in the header of the image
 5776 section, if they exist, so that the coordinate associated with each
 5777 pixel in the image section will be computed correctly.
 5778 
 5779 
 5780 \section{Image Transform Filters}
 5781 
 5782 CFITSIO can apply a user-specified mathematical function to the value
 5783 of every pixel in a FITS image, thus creating a new virtual image
 5784 in computer memory that is then opened and read by the application
 5785 program.  The original FITS image is not modified by this process.
 5786 
 5787 The image transformation specifier is appended to the input
 5788 FITS file name and is enclosed in square brackets.  It begins with the
 5789 letters 'PIX' to distinguish it from other types of FITS file filters
 5790 that are recognized by CFITSIO.  The image transforming function may
 5791 use any of the mathematical operators listed in the following
 5792 'Row Filtering Specification' section of this document.
 5793 Some examples of  image transform filters are:
 5794 
 5795 \begin{verbatim}
 5796  [pix X * 2.0]               - multiply each pixel by 2.0
 5797  [pix sqrt(X)]               - take the square root of each pixel
 5798  [pix X + #ZEROPT            - add the value of the ZEROPT keyword
 5799  [pix X>0 ? log10(X) : -99.] - if the pixel value is greater
 5800                                than 0, compute the base 10 log,
 5801                                else set the pixel = -99.
 5802 \end{verbatim}
 5803 Use the letter 'X' in the expression to represent the current pixel value
 5804 in the image.  The expression is evaluated
 5805 independently for each pixel in the image and may be a function of 1) the
 5806 original pixel value, 2) the value of other pixels in the image at
 5807 a given relative offset from the position of the pixel that is being
 5808 evaluated, and 3) the value of
 5809 any header keywords.  Header keyword values are represented
 5810 by the name of the keyword preceded by the '\#' sign.
 5811 
 5812 
 5813 To access the the value of adjacent pixels in the image,
 5814 specify the (1-D) offset from the current pixel in curly brackets.
 5815 For example
 5816 
 5817 \begin{verbatim}
 5818  [pix  (x{-1} + x + x{+1}) / 3]
 5819 \end{verbatim}
 5820 will replace each pixel value with the running mean of the values of that
 5821 pixel and it's 2 neighboring pixels.  Note that in this notation the image
 5822 is treated as a 1-D array, where each row of the image (or higher dimensional
 5823 cube) is appended one after another in one long array of pixels.
 5824 It is possible to refer to pixels
 5825 in the rows above or below the current pixel by using the value of the
 5826 NAXIS1 header keyword.  For example
 5827 
 5828 \begin{verbatim}
 5829  [pix (x{-#NAXIS1} + x + x{#NAXIS1}) / 3]
 5830 \end{verbatim}
 5831 will compute the mean of each image pixel and the pixels immediately
 5832 above and below it in the adjacent rows of the image.
 5833 The following more complex example
 5834 creates a smoothed virtual image where each pixel
 5835 is a 3 x 3 boxcar average of the input image pixels:
 5836 
 5837 \begin{verbatim}
 5838   [pix (X + X{-1} + X{+1}
 5839       + X{-#NAXIS1} + X{-#NAXIS1 - 1} + X{-#NAXIS1 + 1}
 5840       + X{#NAXIS1} + X{#NAXIS1 - 1} + X{#NAXIS1 + 1}) / 9.]
 5841 \end{verbatim}
 5842 If the pixel offset
 5843 extends beyond the first or last pixel in the image, the function will
 5844 evaluate to undefined, or NULL.
 5845 
 5846 For  complex  or commonly used image filtering operations,
 5847 one  can  write the expression into an external text  file and
 5848 then import it  into the
 5849 filter using  the syntax '[pix @filename.txt]'.   The mathematical
 5850 expression can
 5851 extend over multiple lines of text in the  file.
 5852 Any lines in the external text file
 5853 that begin with 2 slash characters ('//') will be ignored and may be
 5854 used to add comments into the file.
 5855 
 5856 When using column filtering to open a file ``on the fly,'' it is permitted
 5857 to use multiple column filtering expressions.  For example, the
 5858 syntax
 5859 \begin{verbatim}
 5860   filename.fits[col *][col -Y][col Z=X+1]
 5861 \end{verbatim}
 5862 would be treated as equivalent to joining the expressions with semicolons, 
 5863 or
 5864 \begin{verbatim}
 5865   filename.fits[col *; -Y;col Z=X+1]
 5866 \end{verbatim}
 5867 Please note that if multiple column filtering expressions are used, it is
 5868 not permitted to also use the \verb+[col @filename.txt]+ syntax in any
 5869 of the individual expressions.
 5870 
 5871 By default, the datatype of the resulting image will be the same as
 5872 the original image, but one may force a different datatype by appended
 5873 a code letter to the 'pix' keyword:
 5874 
 5875 \begin{verbatim}
 5876       pixb  -  8-bit byte    image with BITPIX =   8
 5877       pixi  - 16-bit integer image with BITPIX =  16
 5878       pixj  - 32-bit integer image with BITPIX =  32
 5879       pixr  - 32-bit float   image with BITPIX = -32
 5880       pixd  - 64-bit float   image with BITPIX = -64
 5881 \end{verbatim}
 5882 Also by default, any other HDUs in the input file will be copied without
 5883 change to the
 5884 output virtual FITS file, but one may discard the other HDUs by adding
 5885 the number '1' to the 'pix' keyword (and following any optional datatype code
 5886 letter).  For example:
 5887 
 5888 \begin{verbatim}
 5889      myfile.fits[3][pixr1  sqrt(X)]
 5890 \end{verbatim}
 5891 will create a virtual FITS file containing only a primary array image
 5892 with 32-bit floating point pixels that have a value equal to the square
 5893 root of the pixels in the image that is in the 3rd extension
 5894 of the 'myfile.fits' file.
 5895 
 5896 
 5897 
 5898 
 5899 \section{Column and Keyword Filtering Specification}
 5900 
 5901 The optional column/keyword filtering specifier is used to modify the
 5902 column structure and/or the header keywords in the HDU that was
 5903 selected with the previous HDU location specifier. This filtering
 5904 specifier must be enclosed in square brackets and can be distinguished
 5905 from a general row filter specifier (described below) by the fact that
 5906 it begins with the string 'col ' and is not immediately followed by an
 5907 equals sign.  The original file is not changed by this filtering
 5908 operation, and instead the modifications are made on a copy of the
 5909 input FITS file (usually in memory), which also contains a copy of all
 5910 the other HDUs in the file.  This temporary file is passed to the
 5911 application program and will persist only until the file is closed or
 5912 until the program exits, unless the outfile specifier (see above) is
 5913 also supplied.
 5914 
 5915 The column/keyword filter can be used to perform the following
 5916 operations.  More than one operation may be specified by separating
 5917 them with commas or semi-colons.
 5918 
 5919 \begin{itemize}
 5920 
 5921 \item
 5922 Copy only a specified list of columns columns to the filtered input file.
 5923 The list of column name should be separated by commas or semi-colons.  Wild card
 5924 characters may be used in the column names to match multiple columns.
 5925 If the expression contains both a list of columns to be included and
 5926 columns to be deleted, then all the columns in the original table
 5927 except the explicitly deleted columns will appear in the filtered
 5928 table (i.e., there is no need to explicitly list the columns to
 5929 be included if any columns are being deleted).
 5930 
 5931 \item
 5932 Delete a column or keyword by listing the name preceded by a minus
 5933 sign or an exclamation mark (!), e.g., '-TIME' will delete the TIME
 5934 column if it exists, otherwise the TIME keyword.  An error is returned
 5935 if neither a column nor keyword with this name exists.  Note  that the
 5936 exclamation point,  '!', is a special UNIX character, so if it is used
 5937 on the command line rather than entered at a task prompt, it must be
 5938 preceded by a backslash to force the UNIX shell to ignore it.
 5939 
 5940 \item
 5941 Rename an existing column or keyword with the syntax 'NewName ==
 5942 OldName'.  An error is returned if neither a column nor keyword with
 5943 this name exists.
 5944 
 5945 \item
 5946 Append a new column or keyword to the table.  To create a column,
 5947 give the new name, optionally followed by the datatype in parentheses,
 5948 followed by a single equals sign and an  expression to be used to
 5949 compute the value (e.g., 'newcol(1J) = 0' will create a new 32-bit
 5950 integer column called 'newcol' filled with zeros).  The datatype is
 5951 specified using the same syntax that is allowed for the value of the
 5952 FITS TFORMn keyword (e.g., 'I', 'J', 'E', 'D', etc. for binary tables,
 5953 and 'I8', F12.3', 'E20.12', etc. for ASCII tables).  If the datatype is
 5954 not specified then an appropriate datatype will be chosen depending on
 5955 the form of the expression (may be a character string, logical, bit, long
 5956 integer, or double column). An appropriate vector count (in the case
 5957 of binary tables) will also be added if not explicitly specified.
 5958 
 5959 When creating a new keyword, the keyword name must be preceded by a
 5960 pound sign '\#', and the expression must evaluate to a scalar
 5961 (i.e., cannot have a column name in the expression).  The comment
 5962 string for the keyword may be specified in parentheses immediately
 5963 following the keyword name (instead of supplying a datatype as in
 5964 the case of creating a new column).  If the keyword name ends with a
 5965 pound sign '\#', then cfitsio will substitute the number of the
 5966 most recently referenced column for the \# character .
 5967 This is especially useful when writing
 5968 a column-related keyword like TUNITn for a newly created column,
 5969 as shown in the following examples.
 5970 
 5971 COMMENT and HISTORY keywords may also be created with the following syntax:
 5972 
 5973 \begin{verbatim}
 5974    #COMMENT = 'This is a comment keyword'
 5975    #HISTORY = 'This is a history keyword'
 5976 \end{verbatim}
 5977 Note that the equal sign and the quote characters will be removed, so
 5978 that the resulting header keywords in these cases will look like this:
 5979 
 5980 \begin{verbatim}
 5981    COMMENT This is a comment keyword
 5982    HISTORY This is a history keyword
 5983 \end{verbatim}
 5984 These two special keywords are always appended to the end of the header
 5985 and will not affect any previously existing COMMENT or HISTORY keywords.
 5986 
 5987 \item
 5988 Recompute (overwrite) the values in an existing column or keyword by
 5989 giving the name followed by an equals sign and an arithmetic
 5990 expression.
 5991 \end{itemize}
 5992 
 5993 The expression that is used when appending or recomputing columns or
 5994 keywords can be arbitrarily complex and may be a function of other
 5995 header keyword values and other columns (in the same row).  The full
 5996 syntax and available functions for the expression are described below
 5997 in the row filter specification section.
 5998 
 5999 If the expression contains both a list of columns to be included and
 6000 columns to be deleted, then all the columns in the original table
 6001 except the explicitly deleted columns will appear in the filtered
 6002 table.  If no columns to be deleted are specified, then only the
 6003 columns that are explicitly listed will be included in the filtered
 6004 output table.  To include all the columns, add the '*' wildcard
 6005 specifier at the end of the list, as shown in the examples.
 6006 
 6007 For  complex  or commonly used operations,  one  can also  place the
 6008 operations into an external text  file and import it  into the  column
 6009 filter using  the syntax '[col @filename.txt]'.   The operations can
 6010 extend over multiple lines of the  file, but multiple operations must
 6011 still be separated by commas or semi-colons.   Any lines in the external text file
 6012 that begin with 2 slash characters ('//') will be ignored and may be
 6013 used to add comments into the file.
 6014 
 6015 Examples:
 6016 
 6017 \begin{verbatim}
 6018    [col Time, rate]              - only the Time and rate columns will
 6019                                    appear in the filtered input file.
 6020 
 6021    [col Time, *raw]              - include the Time column and any other
 6022                                    columns whose name ends with 'raw'.
 6023 
 6024    [col -TIME; Good == STATUS]   - deletes the TIME column and
 6025                                    renames the status column to 'Good'
 6026 
 6027    [col PI=PHA * 1.1 + 0.2; #TUNIT#(column units) = 'counts';*]
 6028                                  - creates new PI column from PHA values
 6029                                    and also writes the TUNITn keyword
 6030                                    for the new column.  The final '*'
 6031                                    expression means preserve all the
 6032                                    columns in the input table in the
 6033                                    virtual output table;  without the '*'
 6034                                    the output table would only contain
 6035                                    the single 'PI' column.
 6036 
 6037    [col rate = rate/exposure, TUNIT#(&) = 'counts/s';*]
 6038                                  - recomputes the rate column by dividing
 6039                                    it by the EXPOSURE keyword value. This
 6040                                    also modifies the value of the TUNITn
 6041                                    keyword for this column. The use of the
 6042                                    '&' character for the keyword comment
 6043                                    string means preserve the existing
 6044                                    comment string for that keyword. The
 6045                                    final '*' preserves all the columns
 6046                                    in the input table in the virtual
 6047                                    output table.
 6048 \end{verbatim}
 6049 
 6050 
 6051 \section{Row Filtering Specification}
 6052 
 6053     When entering the name of a FITS table that is to be opened by a
 6054     program, an optional row filter may be specified to select a subset
 6055     of the rows in the table.  A temporary new FITS file is created on
 6056     the fly which contains only those rows for which the row filter
 6057     expression evaluates to true.  (The primary array and any other
 6058     extensions in the input file are also copied to the temporary
 6059     file).  The original FITS file is closed and the new virtual file
 6060     is opened by the application program.  The row filter expression is
 6061     enclosed in square brackets following the file name and extension
 6062     name (e.g., 'file.fits[events][GRADE==50]'  selects only those rows
 6063     where the GRADE column value equals 50).   When dealing with tables
 6064     where each row has an associated time and/or 2D spatial position,
 6065     the row filter expression can also be used to select rows based on
 6066     the times in a Good Time Intervals (GTI) extension, or on spatial
 6067     position as given in a SAO-style region file.
 6068 
 6069 
 6070 \subsection{General Syntax}
 6071 
 6072     The row filtering  expression can be an arbitrarily  complex series
 6073     of operations performed  on constants,  keyword values,  and column
 6074     data taken from the specified FITS TABLE extension.  The expression
 6075     must evaluate to a boolean  value for each row  of the table, where
 6076     a value of FALSE means that the row will be excluded.
 6077 
 6078     For complex or commonly  used filters, one can place the expression
 6079     into a text file and import it into the row filter using the syntax
 6080     '[@filename.txt]'.  The expression can be  arbitrarily complex and
 6081     extend over multiple lines of the file.  Any lines in the external
 6082     text file that begin with 2 slash characters ('//') will be ignored
 6083     and may be used to add comments into the file.
 6084 
 6085     Keyword and   column data  are referenced by   name.  Any  string of
 6086     characters not surrounded by    quotes (ie, a constant  string)   or
 6087     followed by   an open parentheses (ie,   a  function name)   will be
 6088     initially interpreted   as a column  name and  its contents for the
 6089     current row inserted into the expression.  If no such column exists,
 6090     a keyword of that  name will be searched for  and its value used, if
 6091     found.  To force the  name to be  interpreted as a keyword (in case
 6092     there is both a column and keyword with the  same name), precede the
 6093     keyword name with a single pound sign, '\#', as in '\#NAXIS2'.  Due to
 6094     the generalities of FITS column and  keyword names, if the column or
 6095     keyword name  contains a space or a  character which might appear as
 6096     an arithmetic  term then enclose  the  name in '\$'  characters as in
 6097     \$MAX PHA\$ or \#\$MAX-PHA\$.  Names are case insensitive.
 6098 
 6099     To access a table entry in a row other  than the current one, follow
 6100     the  column's name  with  a row  offset  within  curly  braces.  For
 6101     example, 'PHA\{-3\}' will evaluate to the value  of column PHA, 3 rows
 6102     above  the  row currently  being processed.   One  cannot specify an
 6103     absolute row number, only a relative offset.  Rows that fall outside
 6104     the table will be treated as undefined, or NULLs.
 6105 
 6106     When using row filtering to open a file ``on the fly,'' it is permitted
 6107     to use multiple row filtering expressions.  For example, the expression
 6108 \begin{verbatim}
 6109   filename.fits[#ROW > 5][X.gt.7]
 6110 \end{verbatim}
 6111 would be treated as equivalent to joining the expressions with logical ``and''
 6112 like this,
 6113 \begin{verbatim}
 6114   filename.fits[(#ROW > 5)&&(X.gt.7)]
 6115 \end{verbatim}
 6116 Please note that if multiple row filtering expressions are used, it is
 6117 not permitted to also use the \verb+[@filename.txt]+ syntax in any
 6118 of the individual expressions.
 6119     
 6120 
 6121 %% <!-- IMPORTANT NOTE IMPORTANT NOTE IMPORTANT NOTE -->
 6122 %% <!-- If you edit this file then you must also edit 
 6123 %%      the following other locations where calculator 
 6124 %%      expressions are documented:
 6125 %%         heacore/cfitsio/docs/cfitsio.tex
 6126 %%         heacore/cfitsio/docs/fitsio.tex
 6127 %%         heatools/help/rowfilter.html
 6128 %%         heatools/help/colfilter.html
 6129 %%         heatools/help/calc_express.html
 6130 %%         heatools/ftcalc/ftcalc.html
 6131 %%         heatools/ftselect/ftselect.html
 6132 %%         ftools/futils/tasks/fselect/fselect.hlp
 6133 %%         ftools/futils/tasks/fcalc/fcalc.hlp
 6134 %%         ftools/guis/fv/doc/expressions.html
 6135 %%   -->
 6136 
 6137     Boolean   operators can be  used in  the expression  in either their
 6138     Fortran or C forms.  The following boolean operators are available:
 6139 
 6140 \begin{verbatim}
 6141     "equal"         .eq. .EQ. ==  "not equal"          .ne.  .NE.  !=
 6142     "less than"     .lt. .LT. <   "less than/equal"    .le.  .LE.  <= =<
 6143     "greater than"  .gt. .GT. >   "greater than/equal" .ge.  .GE.  >= =>
 6144     "or"            .or. .OR. ||  "and"                .and. .AND. &&
 6145     "negation"     .not. .NOT. !  "approx. equal(1e-7)"  ~
 6146 \end{verbatim}
 6147 
 6148 Note that the exclamation point, '!', is a special UNIX character, so
 6149 if it is used on the command line rather than entered at a task
 6150 prompt, it must be preceded by a backslash to force the UNIX shell to
 6151 ignore it.
 6152 
 6153 The expression may  also include arithmetic operators and functions.
 6154 Trigonometric  functions use  radians,  not degrees.  The  following
 6155 arithmetic  operators and  functions  can be  used in the expression
 6156 (function names are case insensitive).  A null value will be returned
 6157 in case of illegal operations such as divide by zero, sqrt(negative)
 6158 log(negative), log10(negative), arccos(.gt. 1), arcsin(.gt. 1).
 6159 
 6160 \begin{verbatim}
 6161     "addition"           +          "subtraction"          -
 6162     "multiplication"     *          "division"             /
 6163     "negation"           -          "exponentiation"       **   ^
 6164     "absolute value"     abs(x)     "cosine"               cos(x)
 6165     "sine"               sin(x)     "tangent"              tan(x)
 6166     "arc cosine"         arccos(x)  "arc sine"             arcsin(x)
 6167     "arc tangent"        arctan(x)  "arc tangent"          arctan2(y,x)
 6168     "hyperbolic cos"     cosh(x)    "hyperbolic sin"       sinh(x)
 6169     "hyperbolic tan"     tanh(x)    "round to nearest int" round(x)
 6170     "round down to int"  floor(x)   "round up to int"      ceil(x)
 6171     "exponential"        exp(x)     "square root"          sqrt(x)
 6172     "natural log"        log(x)     "common log"           log10(x)
 6173     "modulus"            x % y      
 6174     "bitwise AND"        x & y      "bitwise OR"           x | y
 6175     "bitwise XOR"        x ^^ y     (bitwise operators are 32-bit int only)
 6176     "random # [0.0,1.0)" random()
 6177     "random Gaussian"    randomn()  "random Poisson"       randomp(x)
 6178     "minimum"            min(x,y)   "maximum"              max(x,y)
 6179     "cumulative sum"     accum(x)   "sequential difference" seqdiff(x)
 6180     "if-then-else"       b?x:y
 6181     "angular separation" angsep(ra1,dec1,ra2,de2) (all in degrees)
 6182     "substring"          strmid(s,p,n) "string search"     strstr(s,r)
 6183 \end{verbatim}
 6184 The bitwise operators for AND, OR and XOR operate upon 32-bit integer 
 6185 expressions only.
 6186 
 6187 Three different random number functions are provided: random(), with
 6188 no arguments, produces a uniform random deviate between 0 and 1;
 6189 randomn(), also with no arguments, produces a normal (Gaussian) random
 6190 deviate with zero mean and unit standard deviation; randomp(x)
 6191 produces a Poisson random deviate whose expected number of counts is
 6192 X.  X may be any positive real number of expected counts, including
 6193 fractional values, but the return value is an integer.
 6194 
 6195 When the random functions are used in a vector expression, by default
 6196 the same random value will be used when evaluating each element of the
 6197 vector.  If different random numbers are desired, then the name of a
 6198 vector column should be supplied as the single argument to the random
 6199 function (e.g., "flux + 0.1 * random(flux)", where "flux" is the name
 6200 of a vector column).  This will create a vector of random numbers that
 6201 will be used in sequence when evaluating each element of the vector
 6202 expression.
 6203 
 6204 An alternate syntax for the min and max functions  has only a single
 6205 argument which  should be  a  vector value (see  below).  The result
 6206 will be the minimum/maximum element contained within the vector.
 6207 
 6208 The accum(x) function forms the cumulative sum of x, element by
 6209 element.  Vector columns are supported simply by performing the
 6210 summation process through all the values.  Null values are treated as
 6211 0.  The seqdiff(x) function forms the sequential difference of x,
 6212 element by element.  The first value of seqdiff is the first value of
 6213 x.  A single null value in x causes a pair of nulls in the output.
 6214 The seqdiff and accum functions are functional inverses, i.e.,
 6215 seqdiff(accum(x)) == x as long as no null values are present.
 6216 
 6217 In the if-then-else expression, "b?x:y", b is an explicit boolean
 6218 value or expression.  There is no automatic type conversion from
 6219 numeric to boolean values, so one needs to use "iVal!=0" instead of
 6220 merely "iVal" as the boolean argument. x and y can be any scalar data
 6221 type (including string).
 6222 
 6223 The angsep function computes the angular separation in degrees between
 6224 2 celestial positions, where the first 2 parameters give the RA-like
 6225 and Dec-like coordinates (in decimal degrees) of the first position,
 6226 and the 3rd and 4th parameters give the coordinates of the second
 6227 position.
 6228 
 6229 The substring function strmid(S,P,N) extracts a substring from S,
 6230 starting at string position P, with a substring length N.  The first
 6231 character position in S is labeled as 1. If P is 0, or refers to a
 6232 position beyond the end of S, then the extracted substring will be
 6233 NULL.  S, P, and N may be functions of other columns.
 6234 
 6235 The string search function strstr(S,R) searches for the first
 6236 occurrence of the substring R in S.  The result is an integer,
 6237 indicating the character position of the first match (where 1 is the
 6238 first character position of S).  If no match is found, then strstr()
 6239 returns a NULL value.
 6240 
 6241 The following type casting operators are available, where the
 6242 enclosing parentheses are required and taken from the C language
 6243 usage. Also, the integer to real casts values to double precision:
 6244 
 6245 \begin{verbatim}
 6246                 "real to integer"    (int) x     (INT) x
 6247                 "integer to real"    (float) i   (FLOAT) i
 6248 \end{verbatim}
 6249 
 6250     In addition, several constants are built in  for  use  in  numerical
 6251     expressions:
 6252 
 6253 
 6254 \begin{verbatim}
 6255         #pi              3.1415...      #e             2.7182...
 6256         #deg             #pi/180        #row           current row number
 6257         #null         undefined value   #snull         undefined string
 6258 \end{verbatim}
 6259 
 6260     A  string constant must  be enclosed  in quotes  as in  'Crab'.  The
 6261     "null" constants  are useful for conditionally  setting table values
 6262     to a NULL, or undefined, value (eg., "col1==-99 ? \#NULL : col1").
 6263 
 6264     Integer constants may be specified using the following notation,
 6265 \begin{verbatim}
 6266            13245   decimal integer
 6267            0x12f3  hexidecimal integer
 6268            0o1373  octal integer
 6269            0b01001 binary integer
 6270 \end{verbatim}
 6271     Note that integer constants are only allowed to be 32-bit, i.e.
 6272     between -2^(31) and +2^(31).  Integer constants may be used in any
 6273     arithmetic expression where an integer would be appropriate.  Thus,
 6274     they are distinct from bitmasks (which may be of arbitrary length,
 6275     allow the "wildcard" bit, and may only be used in logical
 6276     expressions; see below).
 6277 
 6278     There is also a function for testing if  two  values  are  close  to
 6279     each  other,  i.e.,  if  they are "near" each other to within a user
 6280     specified tolerance. The  arguments,  value\_1  and  value\_2  can  be
 6281     integer  or  real  and  represent  the two values who's proximity is
 6282     being tested to be within the specified tolerance, also  an  integer
 6283     or real:
 6284 
 6285 \begin{verbatim}
 6286                     near(value_1, value_2, tolerance)
 6287 \end{verbatim}
 6288     When  a  NULL, or undefined, value is encountered in the FITS table,
 6289     the expression will evaluate to NULL unless the undefined  value  is
 6290     not   actually   required  for  evaluation,  e.g. "TRUE  .or.  NULL"
 6291     evaluates to TRUE. The  following  two  functions  allow  some  NULL
 6292     detection  and  handling:
 6293 
 6294 \begin{verbatim}
 6295          "a null value?"              ISNULL(x)
 6296          "define a value for null"    DEFNULL(x,y)
 6297          "declare certain value null" SETNULL(x,y)
 6298 \end{verbatim}
 6299     ISNULL(x)
 6300     returns a boolean value of TRUE if the  argument  x  is  NULL. DEFNULL(x,y)
 6301     "defines"  a  value  to  be  substituted  for NULL values; it
 6302     returns the value of x if x is not NULL, otherwise  it  returns  the
 6303     value of y.  SETNULL(x,y) allows NULL values to be inserted into
 6304     a variable; if x==y, a NULL value is returned; otherwise y is returned
 6305     (x and y must be numerical, and x must be a scalar).
 6306 
 6307 \subsection{Bit Masks}
 6308 
 6309     Bit  masks can be used to select out rows from bit columns (TFORMn =
 6310     \#X) in FITS files. To represent the mask,  binary,  octal,  and  hex
 6311     formats are allowed:
 6312 
 6313 
 6314 \begin{verbatim}
 6315                  binary:   b0110xx1010000101xxxx0001
 6316                  octal:    o720x1 -> (b111010000xxx001)
 6317                  hex:      h0FxD  -> (b00001111xxxx1101)
 6318 \end{verbatim}
 6319 
 6320     In  all  the  representations, an x or X is allowed in the mask as a
 6321     wild card. Note that the x represents a  different  number  of  wild
 6322     card  bits  in  each  representation.  All  representations are case
 6323     insensitive.  Although bitmasks may be of arbitrary length and contain
 6324     a wildcard, they may only be used in logical expressions, unlike 
 6325     integer constants (see above) which may be used in any arithmetic
 6326     expression.
 6327 
 6328     To construct the boolean expression using the mask  as  the  boolean
 6329     equal  operator  described above on a bit table column. For example,
 6330     if you had a 7 bit column named flags in a  FITS  table  and  wanted
 6331     all  rows  having  the bit pattern 0010011, the selection expression
 6332     would be:
 6333 
 6334 
 6335 \begin{verbatim}
 6336                             flags == b0010011
 6337     or
 6338                             flags .eq. b10011
 6339 \end{verbatim}
 6340 
 6341     It is also possible to test if a range of bits is  less  than,  less
 6342     than  equal,  greater  than  and  greater than equal to a particular
 6343     boolean value:
 6344 
 6345 
 6346 \begin{verbatim}
 6347                             flags <= bxxx010xx
 6348                             flags .gt. bxxx100xx
 6349                             flags .le. b1xxxxxxx
 6350 \end{verbatim}
 6351 
 6352     Notice the use of the x bit value to limit the range of  bits  being
 6353     compared.
 6354 
 6355     It  is  not necessary to specify the leading (most significant) zero
 6356     (0) bits in the mask, as shown in the second expression above.
 6357 
 6358     Bit wise AND, OR and NOT operations are  also  possible  on  two  or
 6359     more  bit  fields  using  the  '\&'(AND),  '$|$'(OR),  and the '!'(NOT)
 6360     operators. All of these operators result in a bit  field  which  can
 6361     then be used with the equal operator. For example:
 6362 
 6363 
 6364 \begin{verbatim}
 6365                           (!flags) == b1101100
 6366                           (flags & b1000001) == bx000001
 6367 \end{verbatim}
 6368 
 6369     Bit  fields can be appended as well using the '+' operator.  Strings
 6370     can be concatenated this way, too.
 6371 
 6372 
 6373 \subsection{Vector Columns}
 6374 
 6375     Vector columns can also be used  in  building  the  expression.   No
 6376     special  syntax  is required if one wants to operate on all elements
 6377     of the vector.  Simply use the column name as for a  scalar  column.
 6378     Vector  columns  can  be  freely  intermixed  with scalar columns or
 6379     constants in virtually all expressions.  The result will be  of  the
 6380     same dimension as the vector.  Two vectors in an expression, though,
 6381     need to  have  the  same  number  of  elements  and  have  the  same
 6382     dimensions.   The  only  places  a vector column cannot be used (for
 6383     now, anyway) are the SAO  region  functions  and  the  NEAR  boolean
 6384     function.
 6385 
 6386     Arithmetic and logical operations are all performed on an element by
 6387     element basis.  Comparing two vector columns,  eg  "COL1  ==  COL2",
 6388     thus  results  in  another vector of boolean values indicating which
 6389     elements of the two vectors are equal.
 6390 
 6391     Eight functions are available that operate on a vector and return a
 6392     scalar result:
 6393 
 6394 \begin{verbatim}
 6395     "minimum"      MIN(V)          "maximum"               MAX(V)
 6396     "average"      AVERAGE(V)      "median"                MEDIAN(V)
 6397     "summation"    SUM(V)          "standard deviation"    STDDEV(V)
 6398     "# of values"  NELEM(V)        "# of non-null values"  NVALID(V)
 6399 \end{verbatim}
 6400     where V represents the name of a vector column or a manually
 6401     constructed vector using curly brackets as described below.  The
 6402     first 6 of these functions ignore any null values in the vector when
 6403     computing the result.  The STDDEV() function computes the sample
 6404     standard deviation, i.e. it is proportional to 1/SQRT(N-1) instead
 6405     of 1/SQRT(N), where N is NVALID(V).
 6406 
 6407     The SUM function literally sums all  the elements in x,  returning a
 6408     scalar value.   If x  is  a  boolean  vector, SUM returns the number
 6409     of TRUE elements. The NELEM function  returns the number of elements
 6410     in vector x whereas NVALID return the number of non-null elements in
 6411     the  vector.   (NELEM  also  operates  on  bit  and string  columns,
 6412     returning their column widths.)  As an example, to  test whether all
 6413     elements of two vectors satisfy a  given logical comparison, one can
 6414     use the expression
 6415 
 6416 \begin{verbatim}
 6417               SUM( COL1 > COL2 ) == NELEM( COL1 )
 6418 \end{verbatim}
 6419 
 6420     which will return TRUE if all elements  of  COL1  are  greater  than
 6421     their corresponding elements in COL2.
 6422 
 6423     To  specify  a  single  element  of  a  vector, give the column name
 6424     followed by  a  comma-separated  list  of  coordinates  enclosed  in
 6425     square  brackets.  For example, if a vector column named PHAS exists
 6426     in the table as a one dimensional, 256  component  list  of  numbers
 6427     from  which  you  wanted to select the 57th component for use in the
 6428     expression, then PHAS[57] would do the  trick.   Higher  dimensional
 6429     arrays  of  data  may appear in a column.  But in order to interpret
 6430     them, the TDIMn keyword must appear in the header.  Assuming that  a
 6431     (4,4,4,4)  array  is packed into each row of a column named ARRAY4D,
 6432     the  (1,2,3,4)  component  element  of  each  row  is  accessed   by
 6433     ARRAY4D[1,2,3,4].    Arrays   up   to   dimension  5  are  currently
 6434     supported.  Each vector index can itself be an expression,  although
 6435     it  must  evaluate  to  an  integer  value  within the bounds of the
 6436     vector.  Vector columns which contain spaces or arithmetic operators
 6437     must   have   their   names  enclosed  in  "\$"  characters  as  with
 6438     \$ARRAY-4D\$[1,2,3,4].
 6439 
 6440     A  more  C-like  syntax  for  specifying  vector  indices  is   also
 6441     available.   The element used in the preceding example alternatively
 6442     could be specified with the syntax  ARRAY4D[4][3][2][1].   Note  the
 6443     reverse  order  of  indices  (as in C), as well as the fact that the
 6444     values are still ones-based (as  in  Fortran  --  adopted  to  avoid
 6445     ambiguity  for  1D vectors).  With this syntax, one does not need to
 6446     specify all of the indices.  To  extract  a  3D  slice  of  this  4D
 6447     array, use ARRAY4D[4].
 6448 
 6449     Variable-length vector columns are not supported.
 6450 
 6451     Vectors can  be manually constructed  within the expression  using a
 6452     comma-separated list of  elements surrounded by curly braces ('\{\}').
 6453     For example, '\{1,3,6,1\}' is a 4-element vector containing the values
 6454     1, 3, 6, and 1.  The  vector can contain  only boolean, integer, and
 6455     real values (or expressions).  The elements will  be promoted to the
 6456     highest  datatype   present.  Any   elements   which  are themselves
 6457     vectors, will be expanded out with  each of its elements becoming an
 6458     element in the constructed vector.
 6459 
 6460 
 6461 \subsection{Good Time Interval Filtering and Calculation}
 6462 
 6463     There are two functions for filtering and calculating based
 6464     on Good Time Intervals, or GTIs.  GTIs are commonly used to
 6465     express fragmented time ranges that are not easy to express with a
 6466     single start and stop time.  The time intervals are defined in a
 6467     FITS table extension which contains 2 columns giving the
 6468     start and stop time of each good interval.
 6469 
 6470     A common filtering method involves selecting rows which have a
 6471     time value which lies within any GTI.  The gtifilter() filtering
 6472     operation accepts only those rows of the input table which have an
 6473     associated time which falls within one of the time intervals
 6474     defined in a separate GTI extension.  gtifilter(a,b,c,d) evaluates
 6475     each row of the input table and returns TRUE or FALSE depending
 6476     whether the row is inside or outside the good time interval.  The
 6477     syntax is
 6478 
 6479 \begin{verbatim}
 6480       gtifilter( [ "gtifile" [, expr [, "STARTCOL", "STOPCOL" ] ] ] )
 6481     or
 6482       gtifilter( [ 'gtifile' [, expr [, 'STARTCOL', 'STOPCOL' ] ] ] )
 6483 \end{verbatim}
 6484     where  each "[]" demarks optional parameters.  Note that  the quotes
 6485     around the gtifile and START/STOP column are required.  Either single
 6486     or double quotes may be used.  In cases where this expression is
 6487     entered on the Unix command line, enclose the entire expression in
 6488     double quotes, and then use single quotes within the expression to
 6489     enclose the 'gtifile' and other terms.  It is also usually possible
 6490     to do the reverse, and enclose the whole expression in single quotes
 6491     and then use double quotes within the expression.  The gtifile,
 6492     if specified,  can be blank  ("") which will  mean to use  the first
 6493     extension  with   the name "*GTI*"  in   the current  file,  a plain
 6494     extension  specifier (eg, "+2",  "[2]", or "[STDGTI]") which will be
 6495     used  to  select  an extension  in  the current  file, or  a regular
 6496     filename with or without an extension  specifier which in the latter
 6497     case  will mean to  use the first  extension  with an extension name
 6498     "*GTI*".  Expr can be   any arithmetic expression, including  simply
 6499     the time  column  name.  A  vector  time expression  will  produce a
 6500     vector boolean  result.  STARTCOL and  STOPCOL are the  names of the
 6501     START/STOP   columns in the    GTI extension.  If   one  of them  is
 6502     specified, they both  must be.
 6503 
 6504     In  its  simplest form, no parameters need to be provided -- default
 6505     values will be used.  The expression "gtifilter()" is equivalent to
 6506 
 6507 \begin{verbatim}
 6508        gtifilter( "", TIME, "*START*", "*STOP*" )
 6509 \end{verbatim}
 6510     This will search the current file for a GTI  extension,  filter  the
 6511     TIME  column in the current table, using START/STOP times taken from
 6512     columns in the GTI  extension  with  names  containing  the  strings
 6513     "START"  and "STOP".  The wildcards ('*') allow slight variations in
 6514     naming conventions  such  as  "TSTART"  or  "STARTTIME".   The  same
 6515     default  values  apply for unspecified parameters when the first one
 6516     or  two  parameters  are  specified.   The  function   automatically
 6517     searches   for   TIMEZERO/I/F   keywords  in  the  current  and  GTI
 6518     extensions, applying a relative time offset, if necessary.
 6519 
 6520     A separate function, gtioverlap(a,b,c,d,e), computes the overlap
 6521     between a user-requested time range and the entries in a GTI.  The
 6522     cases of no overlap, partial overlap, or overlap of many GTIs
 6523     within the user requested range are handled.  gtioverlap() is very
 6524     useful for calculating exposure times and fractional exposures of
 6525     individual time bins, say for a light curve.  The syntax of
 6526     gtioverlap() is
 6527 
 6528 \begin{verbatim}
 6529       gtioverlap( "gtifile" , startExpr, stopExpr [, "STARTCOL", "STOPCOL" ] )
 6530     or
 6531       gtioverlap( 'gtifile' , startExpr, stopExpr [, 'STARTCOL', 'STOPCOL' ] )
 6532 \end{verbatim}
 6533 
 6534     The requirements for specifying the gtifile are the same as for
 6535     gtifilter() as described above.  Unlike gtifilter(), the startExpr
 6536     and stopExpr are not optional.  startExpr provides a start of the
 6537     user requested time interval.  startExpr is typically TIME, but
 6538     can be any valid expression.  Likewise, stopExpr provides the stop
 6539     of the user requested time interval, and can be an expression.
 6540     For example, for a light curve with a TIME column and time bin
 6541     size of 1.0 seconds, the expression
 6542 
 6543 \begin{verbatim}
 6544       gtioverlap('gtifile',TIME,TIME+1.0)
 6545 \end{verbatim}
 6546 
 6547     would calculate the amount of overlap exposure time between each
 6548     one second time bin and the GTI in 'gtifile'.  In this case the
 6549     time bin is assumed to begin at the time specified by TIME and end
 6550     1 second later.  Neither startExpr nor stopExpr are required to be
 6551     constant, and a light curve is not required to have a constant bin
 6552     size.  For tables, the overlap is calculated for each entry in the
 6553     table.
 6554 
 6555     It is also possible to calculate a single overlap value, which
 6556     would typically be placed in a keyword.  For example, a way to to
 6557     compute the total overlap exposure of a file whose TIME column is
 6558     bounded by the keywords TSTART and TSTOP, overlapping with the
 6559     specified GTI, would be
 6560 
 6561 \begin{verbatim}
 6562       #EXPOSURE = gtioverlap('gtifile',#TSTART,#TSTOP)
 6563 \end{verbatim}
 6564 
 6565     The \verb+#EXPOSURE+ syntax with a leading \+#+ ensures that the 
 6566     requested values are treated as keywords.  Otherwise, a column
 6567     named EXPOSURE will be created with the (constant) exposure value
 6568     in each entry.  
 6569 
 6570 
 6571 
 6572 \subsection{Spatial Region Filtering}
 6573 
 6574     Another common  filtering method selects rows based on whether the
 6575     spatial position associated with each row is located within a given
 6576     2-dimensional region.  The syntax for this high-level filter is
 6577 
 6578 \begin{verbatim}
 6579        regfilter( "regfilename" [ , Xexpr, Yexpr [ , "wcs cols" ] ] )
 6580 \end{verbatim}
 6581     where each "[]" demarks optional parameters. The region file name
 6582     is required and must be  enclosed in quotes.  The remaining
 6583     parameters are optional.  There are 2 supported formats for the
 6584     region file: ASCII file or FITS binary table.  The region file
 6585     contains a list of one or more geometric shapes (circle,
 6586     ellipse, box, etc.) which defines a region on the celestial sphere
 6587     or an area within a particular 2D image.  The region file is
 6588     typically generated using an image display program such as fv/POW
 6589     (distribute by the HEASARC), or ds9 (distributed by the Smithsonian
 6590     Astrophysical Observatory).  Users should refer to the documentation
 6591     provided with these programs for more details on the syntax used in
 6592     the region files.  The FITS region file format is defined in a document
 6593     available from the FITS Support Office at
 6594     http://fits.gsfc.nasa.gov/ registry/ region.html
 6595 
 6596     In its simplest form, (e.g., regfilter("region.reg") ) the
 6597     coordinates in the default 'X' and 'Y' columns will be used to
 6598     determine if each row is inside or outside the area specified in
 6599     the region file.  Alternate position column names, or expressions,
 6600     may be entered if needed, as in
 6601 
 6602 \begin{verbatim}
 6603         regfilter("region.reg", XPOS, YPOS)
 6604 \end{verbatim}
 6605     Region filtering can be applied most unambiguously if the positions
 6606     in the region file and in the table to be filtered are both give in
 6607     terms of absolute celestial coordinate units.  In this case the
 6608     locations and sizes of the geometric shapes in the region file are
 6609     specified in angular units on the sky (e.g., positions given in
 6610     R.A. and Dec.  and sizes in arcseconds or arcminutes).  Similarly,
 6611     each row of the filtered table will have a celestial coordinate
 6612     associated with it.  This association is usually implemented using
 6613     a set of so-called 'World Coordinate System' (or WCS) FITS keywords
 6614     that define the coordinate transformation that must be applied to
 6615     the values in the 'X' and 'Y' columns to calculate the coordinate.
 6616 
 6617     Alternatively, one can perform spatial filtering using unitless
 6618     'pixel' coordinates for the regions and row positions.  In this
 6619     case the user must be careful to ensure that the positions in the 2
 6620     files are self-consistent.  A typical problem is that the region
 6621     file may be generated using a binned image, but the unbinned
 6622     coordinates are given in the event table.  The ROSAT events files,
 6623     for example, have X and Y pixel coordinates that range from 1 -
 6624     15360.  These coordinates are typically binned by a factor of 32 to
 6625     produce a 480x480 pixel image.  If one then uses a region file
 6626     generated from this image (in image pixel units) to filter the
 6627     ROSAT events file, then the X and Y column values must be converted
 6628     to corresponding pixel units as in:
 6629 
 6630 \begin{verbatim}
 6631         regfilter("rosat.reg", X/32.+.5, Y/32.+.5)
 6632 \end{verbatim}
 6633     Note that this binning conversion is not necessary if the region
 6634     file is specified using celestial coordinate units instead of pixel
 6635     units because CFITSIO is then able to directly compare the
 6636     celestial coordinate of each row in the table with the celestial
 6637     coordinates in the region file without having to know anything
 6638     about how the image may have been binned.
 6639 
 6640     The last "wcs cols" parameter should rarely be needed. If supplied,
 6641     this  string contains the names of the 2 columns (space or comma
 6642     separated) which have the associated WCS keywords. If not supplied,
 6643     the filter  will scan the X  and Y expressions for column names.
 6644     If only one is found in each  expression, those columns will be
 6645     used, otherwise an error will be returned.
 6646 
 6647     These region shapes are supported (names are case insensitive):
 6648 
 6649 \begin{verbatim}
 6650        Point         ( X1, Y1 )               <- One pixel square region
 6651        Line          ( X1, Y1, X2, Y2 )       <- One pixel wide region
 6652        Polygon       ( X1, Y1, X2, Y2, ... )  <- Rest are interiors with
 6653        Rectangle     ( X1, Y1, X2, Y2, A )       | boundaries considered
 6654        Box           ( Xc, Yc, Wdth, Hght, A )   V within the region
 6655        Diamond       ( Xc, Yc, Wdth, Hght, A )
 6656        Circle        ( Xc, Yc, R )
 6657        Annulus       ( Xc, Yc, Rin, Rout )
 6658        Ellipse       ( Xc, Yc, Rx, Ry, A )
 6659        Elliptannulus ( Xc, Yc, Rinx, Riny, Routx, Routy, Ain, Aout )
 6660        Sector        ( Xc, Yc, Amin, Amax )
 6661 \end{verbatim}
 6662     where (Xc,Yc) is  the coordinate of  the shape's center; (X\#,Y\#) are
 6663     the coordinates  of the shape's edges;  Rxxx are the shapes' various
 6664     Radii or semi-major/minor  axes; and Axxx  are the angles of rotation
 6665     (or bounding angles for Sector) in degrees.  For rotated shapes, the
 6666     rotation angle  can  be left  off, indicating  no rotation.   Common
 6667     alternate  names for the regions  can also be  used: rotbox = box;
 6668     rotrectangle = rectangle;  (rot)rhombus = (rot)diamond;  and pie
 6669     = sector.  When a  shape's name is  preceded by a minus sign, '-',
 6670     the defined region  is instead the area  *outside* its boundary (ie,
 6671     the region is inverted).  All the shapes within a single region
 6672     file are OR'd together to create the region, and the order is
 6673     significant. The overall way of looking at region files is that if
 6674     the first region is an excluded region then a dummy included region
 6675     of the whole detector is inserted in the front. Then each region
 6676     specification as it is processed overrides any selections inside of
 6677     that region specified by previous regions. Another way of thinking
 6678     about this is that if a previous excluded region is completely
 6679     inside of a subsequent included region the excluded region is
 6680     ignored.
 6681 
 6682     The positional coordinates may be given either in pixel units,
 6683     decimal degrees or hh:mm:ss.s, dd:mm:ss.s units.  The shape sizes
 6684     may be given in pixels, degrees, arcminutes, or arcseconds.  Look
 6685     at examples of region file produced by fv/POW or ds9 for further
 6686     details of the region file format.
 6687 
 6688     There are three functions that are primarily for use with SAO region
 6689     files and the  FSAOI  task, but they  can  be  used  directly.  They
 6690     return  a  boolean true   or  false  depending   on  whether a   two
 6691     dimensional point is in the region or not:
 6692 
 6693 \begin{verbatim}
 6694     "point in a circular region"
 6695           circle(xcntr,ycntr,radius,Xcolumn,Ycolumn)
 6696 
 6697     "point in an elliptical region"
 6698          ellipse(xcntr,ycntr,xhlf_wdth,yhlf_wdth,rotation,Xcolumn,Ycolumn)
 6699 
 6700     "point in a rectangular region"
 6701              box(xcntr,ycntr,xfll_wdth,yfll_wdth,rotation,Xcolumn,Ycolumn)
 6702 
 6703     where
 6704        (xcntr,ycntr) are the (x,y) position of the center of the region
 6705        (xhlf_wdth,yhlf_wdth) are the (x,y) half widths of the region
 6706        (xfll_wdth,yfll_wdth) are the (x,y) full widths of the region
 6707        (radius) is half the diameter of the circle
 6708        (rotation) is the angle(degrees) that the region is rotated with
 6709              respect to (xcntr,ycntr)
 6710        (Xcoord,Ycoord) are the (x,y) coordinates to test, usually column
 6711              names
 6712        NOTE: each parameter can itself be an expression, not merely a
 6713              column name or constant.
 6714 \end{verbatim}
 6715 
 6716 
 6717 \subsection{Example Row Filters}
 6718 
 6719 \begin{verbatim}
 6720     [ binary && mag <= 5.0]        - Extract all binary stars brighter
 6721                                      than  fifth magnitude (note that
 6722                                      the initial space is necessary to
 6723                                      prevent it from being treated as a
 6724                                      binning specification)
 6725 
 6726     [#row >= 125 && #row <= 175]   - Extract row numbers 125 through 175
 6727 
 6728     [IMAGE[4,5] .gt. 100]          - Extract all rows that have the
 6729                                      (4,5) component of the IMAGE column
 6730                                      greater than 100
 6731 
 6732     [abs(sin(theta * #deg)) < 0.5] - Extract all rows having the
 6733                                      absolute value of the sine of theta
 6734                                      less  than a half where the angles
 6735                                      are tabulated in degrees
 6736 
 6737     [SUM( SPEC > 3*BACKGRND )>=1]  - Extract all rows containing a
 6738                                      spectrum, held in vector column
 6739                                      SPEC, with at least one value 3
 6740                                      times greater than the background
 6741                                      level held in a keyword, BACKGRND
 6742 
 6743     [VCOL=={1,4,2}]                - Extract all rows whose vector column
 6744                                      VCOL contains the 3-elements 1, 4, and
 6745                                      2.
 6746 
 6747     [@rowFilter.txt]               - Extract rows using the expression
 6748                                      contained within the text file
 6749                                      rowFilter.txt
 6750 
 6751     [gtifilter()]                  - Search the current file for a GTI
 6752                      extension,  filter  the TIME
 6753                      column in the current table, using
 6754                      START/STOP times taken from
 6755                      columns in the GTI  extension
 6756 
 6757     [regfilter("pow.reg")]         - Extract rows which have a coordinate
 6758                                      (as given in the X and Y columns)
 6759                                      within the spatial region specified
 6760                                      in the pow.reg region file.
 6761 
 6762     [regfilter("pow.reg", Xs, Ys)] - Same as above, except that the
 6763                                      Xs and Ys columns will be used to
 6764                                      determine the coordinate of each
 6765                                      row in the table.
 6766 \end{verbatim}
 6767 
 6768 
 6769 \section{ Binning or Histogramming Specification}
 6770 
 6771 The optional binning specifier is enclosed in square brackets and can
 6772 be distinguished from a general row filter specification by the fact
 6773 that it begins with the keyword 'bin'  not immediately followed by an
 6774 equals sign.  When binning is specified, a temporary N-dimensional FITS
 6775 primary array is created by computing the histogram of the values in
 6776 the specified columns of a FITS table extension.  After the histogram
 6777 is computed the input FITS file containing the table is then closed and
 6778 the temporary FITS primary array is opened and passed to the
 6779 application program.  Thus, the application program never sees the
 6780 original FITS table and only sees the image in the new temporary file
 6781 (which has no additional extensions).  Obviously, the application
 6782 program must be expecting to open a FITS image and not a FITS table in
 6783 this case.
 6784 
 6785 The data type of the FITS histogram image may be specified by appending
 6786 'b' (for 8-bit byte), 'i' (for 16-bit integers), 'j' (for 32-bit
 6787 integer), 'r' (for 32-bit floating points), or 'd' (for 64-bit double
 6788 precision floating point)  to the 'bin' keyword (e.g. '[binr X]'
 6789 creates a real floating point image).  If the datatype is not
 6790 explicitly specified then a 32-bit integer image will be created by
 6791 default, unless the weighting option is also specified in which case
 6792 the image will have a 32-bit floating point data type by default.
 6793 
 6794 The histogram image may have from 1 to 4 dimensions (axes), depending
 6795 on the number of columns that are specified.  The general form of the
 6796 binning specification is:
 6797 
 6798 \begin{verbatim}
 6799  [bin{bijrd}  Xcol=min:max:binsize, Ycol= ..., Zcol=..., Tcol=...; weight]
 6800 \end{verbatim}
 6801 in which up to 4 columns, each corresponding to an axis of the image,
 6802 are listed. The column names are case insensitive, and the column
 6803 number may be given instead of the name, preceded by a pound sign
 6804 (e.g., [bin \#4=1:512]).  If the column name is not specified, then
 6805 CFITSIO will first try to use the 'preferred column' as specified by
 6806 the CPREF keyword if it exists (e.g., 'CPREF = 'DETX,DETY'), otherwise
 6807 column names 'X', 'Y', 'Z', and 'T' will be assumed for each of the 4
 6808 axes, respectively.  In cases where the column name could be confused
 6809 with an arithmetic expression, enclose the column name in parentheses to
 6810 force the name to be interpreted literally.
 6811 
 6812 Each column name may be followed by an equals sign and then the lower
 6813 and upper range of the histogram, and the size of the histogram bins,
 6814 separated by colons.  Spaces are allowed before and after the equals
 6815 sign but not within the 'min:max:binsize' string.  The min, max and
 6816 binsize values may be integer or floating point numbers, or they may be
 6817 the names of keywords in the header of the table.  If the latter, then
 6818 the value of that keyword is substituted into the expression.
 6819 
 6820 Default values for the min, max and binsize quantities will be
 6821 used if not explicitly given in the binning expression as shown
 6822 in these examples:
 6823 
 6824 \begin{verbatim}
 6825     [bin x = :512:2]  - use default minimum value
 6826     [bin x = 1::2]    - use default maximum value
 6827     [bin x = 1:512]   - use default bin size
 6828     [bin x = 1:]      - use default maximum value and bin size
 6829     [bin x = :512]    - use default minimum value and bin size
 6830     [bin x = 2]       - use default minimum and maximum values
 6831     [bin x]           - use default minimum, maximum and bin size
 6832     [bin 4]           - default 2-D image, bin size = 4 in both axes
 6833     [bin]             - default 2-D image
 6834 \end{verbatim}
 6835 CFITSIO  will use the value of the TLMINn, TLMAXn, and TDBINn keywords,
 6836 if they exist, for the default min, max, and binsize, respectively.  If
 6837 they do not exist then CFITSIO will use the actual minimum and maximum
 6838 values in the column for the histogram min and max values.  The default
 6839 binsize will be set to 1, or (max - min) / 10., whichever is smaller,
 6840 so that the histogram will have at least 10 bins along each axis.
 6841 
 6842 A shortcut notation is allowed if all the columns/axes have the same
 6843 binning specification.  In this case all the column names may be listed
 6844 within parentheses, followed by the (single) binning specification, as
 6845 in:
 6846 
 6847 \begin{verbatim}
 6848     [bin (X,Y)=1:512:2]
 6849     [bin (X,Y) = 5]
 6850 \end{verbatim}
 6851 
 6852 The optional weighting factor is the last item in the binning specifier
 6853 and, if present, is separated from the list of columns by a
 6854 semi-colon.  As the histogram is accumulated, this weight is used to
 6855 incremented the value of the appropriated bin in the histogram.  If the
 6856 weighting factor is not specified, then the default weight = 1 is
 6857 assumed.  The weighting factor may be a constant integer or floating
 6858 point number, or the name of a keyword containing the weighting value.
 6859 Or the weighting factor may be the name of a table column in which case
 6860 the value in that column, on a row by row basis, will be used.
 6861 
 6862 In some cases, the column or keyword may give the reciprocal of the
 6863 actual weight value that is needed.  In this case, precede the weight
 6864 keyword or column name by a slash '/' to tell CFITSIO to use the
 6865 reciprocal of the value when constructing the histogram.
 6866 
 6867 For  complex or commonly  used  histograms, one  can also  place its
 6868 description  into  a  text  file and  import   it  into  the binning
 6869 specification  using the  syntax '[bin  @filename.txt]'.  The file's
 6870 contents  can extend over   multiple lines, although  it must still
 6871 conform to the  no-spaces rule  for the min:max:binsize syntax and each
 6872 axis specification must still be comma-separated.  Any lines in the
 6873 external text file that begin with 2 slash characters ('//') will be
 6874 ignored and may be used to add comments into the file.
 6875 
 6876  Examples:
 6877 
 6878 
 6879 \begin{verbatim}
 6880     [bini detx, dety]                - 2-D, 16-bit integer histogram
 6881                                        of DETX and DETY columns, using
 6882                                        default values for the histogram
 6883                                        range and binsize
 6884 
 6885     [bin (detx, dety)=16; /exposure] - 2-D, 32-bit real histogram of DETX
 6886                                        and DETY columns with a bin size = 16
 6887                                        in both axes. The histogram values
 6888                                        are divided by the EXPOSURE keyword
 6889                                        value.
 6890 
 6891     [bin time=TSTART:TSTOP:0.1]      - 1-D lightcurve, range determined by
 6892                                        the TSTART and TSTOP keywords,
 6893                                        with 0.1 unit size bins.
 6894 
 6895     [bin pha, time=8000.:8100.:0.1]  - 2-D image using default binning
 6896                                        of the PHA column for the X axis,
 6897                                        and 1000 bins in the range
 6898                                        8000. to 8100. for the Y axis.
 6899 
 6900     [bin @binFilter.txt]             - Use the contents of the text file
 6901                                        binFilter.txt for the binning
 6902                                        specifications.
 6903 
 6904 \end{verbatim}
 6905 
 6906 
 6907 \chapter{Template Files }
 6908 
 6909 When a new FITS file is created with a call to fits\_create\_file, the
 6910 name of a template file may be supplied in parentheses immediately
 6911 following the name of the new file to be created.  This template is
 6912 used to define the structure of one or more HDUs in the new file.  The
 6913 template file may be another FITS file, in which case the newly created
 6914 file will have exactly the same keywords in each HDU as in the template
 6915 FITS file, but all the data units will be filled with zeros.  The
 6916 template file may also be an ASCII text file, where each line (in
 6917 general) describes one FITS keyword record.  The format of the ASCII
 6918 template file is described in the following sections.
 6919 
 6920 
 6921 \section{Detailed Template Line Format}
 6922 
 6923 The format of each ASCII template line closely follows the format of a
 6924 FITS keyword record:
 6925 
 6926 \begin{verbatim}
 6927   KEYWORD = KEYVALUE / COMMENT
 6928 \end{verbatim}
 6929 except that free format may be used (e.g., the equals sign may appear
 6930 at any position in the line) and TAB characters are allowed and are
 6931 treated the same as space characters.  The KEYVALUE and COMMENT fields
 6932 are optional.  The equals sign character is also optional, but it is
 6933 recommended that it be included for clarity.  Any template line that
 6934 begins with the pound '\#' character is ignored by the template parser
 6935 and may be use to insert comments into the template file itself.
 6936 
 6937 The KEYWORD name field is limited to 8 characters in length and only
 6938 the letters A-Z, digits 0-9, and the hyphen and underscore characters
 6939 may be used, without any embedded spaces. Lowercase letters in the
 6940 template keyword name will be converted to uppercase.  Leading spaces
 6941 in the template line preceding the keyword name are generally ignored,
 6942 except if the first 8 characters of a template line are all blank, then
 6943 the entire line is treated as a FITS comment keyword (with a blank
 6944 keyword name) and is copied verbatim into the FITS header.
 6945 
 6946 The KEYVALUE field may have any allowed  FITS  data type: character
 6947 string, logical, integer, real, complex integer, or complex real.  Integer
 6948 values must be within the allowed range of a 'signed long' variable;
 6949 some C compilers only suppport 4-byte long integers with a range
 6950 from -2147483648 to +2147483647, whereas other C compilers support 8-byte
 6951 integers with a range of plus or minus 2**63.
 6952 
 6953 The character string values need not be enclosed in single quote characters
 6954 unless they are necessary to distinguish the string from a different
 6955 data type (e.g.  2.0 is a real but '2.0' is a string).  The keyword has
 6956 an undefined (null) value if the template record only contains blanks
 6957 following the "=" or between the "=" and the "/" comment field
 6958 delimiter.
 6959 
 6960 String keyword values longer than 68 characters (the maximum length
 6961 that will fit in a single FITS keyword record) are permitted using the
 6962 CFITSIO long string convention. They can either be specified as a
 6963 single long line in the template, or by using multiple lines where the
 6964 continuing lines contain the 'CONTINUE' keyword, as in this example:
 6965 
 6966 \begin{verbatim}
 6967   LONGKEY = 'This is a long string value that is contin&'
 6968   CONTINUE  'ued over 2 records' / comment field goes here
 6969 \end{verbatim}
 6970 The format of template lines with CONTINUE keyword is very strict:  3
 6971 spaces must follow CONTINUE and the rest of the line is copied verbatim
 6972 to the FITS file.
 6973 
 6974 The start of the optional COMMENT field must be preceded by "/", which
 6975 is used to separate it from the keyword value field. Exceptions are if
 6976 the KEYWORD name field contains COMMENT, HISTORY, CONTINUE, or if the
 6977 first 8 characters of the template line are blanks.
 6978 
 6979 More than one Header-Data Unit (HDU) may be defined in the template
 6980 file.  The start of an HDU definition is denoted with a SIMPLE or
 6981 XTENSION template line:
 6982 
 6983 1) SIMPLE begins a Primary HDU definition. SIMPLE may only appear as
 6984 the  first keyword in the template file. If the template file begins
 6985 with XTENSION instead of SIMPLE, then a default empty Primary HDU is
 6986 created, and the template is then assumed to define the keywords
 6987 starting with the first extension following the Primary HDU.
 6988 
 6989 2) XTENSION marks the beginning of a new extension HDU definition.  The
 6990 previous HDU will be closed at this point and processing of the next
 6991 extension begins.
 6992 
 6993 
 6994 \section{Auto-indexing of Keywords}
 6995 
 6996 If a template keyword name ends with a "\#" character, it is said to be
 6997 'auto-indexed'.   Each "\#" character will be replaced by the current
 6998 integer index value, which gets reset = 1 at the start of each new HDU
 6999 in the file (or 7 in the special case of a GROUP definition).  The
 7000 FIRST indexed keyword in each template HDU definition is used as the
 7001 'incrementor';  each subsequent occurrence of this SAME keyword will
 7002 cause the index value to be incremented.  This behavior can be rather
 7003 subtle, as illustrated in the following examples in which the TTYPE
 7004 keyword is the incrementor in both cases:
 7005 
 7006 \begin{verbatim}
 7007   TTYPE# = TIME
 7008   TFORM# = 1D
 7009   TTYPE# = RATE
 7010   TFORM# = 1E
 7011 \end{verbatim}
 7012 will create TTYPE1, TFORM1, TTYPE2, and TFORM2 keywords.  But if the
 7013 template looks like,
 7014 
 7015 \begin{verbatim}
 7016   TTYPE# = TIME
 7017   TTYPE# = RATE
 7018   TFORM# = 1D
 7019   TFORM# = 1E
 7020 \end{verbatim}
 7021 this results in a FITS files with  TTYPE1, TTYPE2, TFORM2, and TFORM2,
 7022 which is probably not what was intended!
 7023 
 7024 
 7025 \section{Template Parser Directives}
 7026 
 7027 In addition to the template lines which define individual keywords, the
 7028 template parser recognizes 3 special directives which are each preceded
 7029 by the backslash character:  \verb+ \include, \group+, and \verb+ \end+.
 7030 
 7031 The 'include' directive must be followed by a filename. It forces the
 7032 parser to temporarily stop reading the current template file and begin
 7033 reading the include file. Once the parser reaches the end of the
 7034 include file it continues parsing the current template file.  Include
 7035 files can be nested, and HDU definitions can span multiple template
 7036 files.
 7037 
 7038 The start of a GROUP definition is denoted with the 'group' directive,
 7039 and the end of a GROUP definition is denoted with the 'end' directive.
 7040 Each GROUP contains 0 or more member blocks (HDUs or GROUPs). Member
 7041 blocks of type GROUP can contain their own member blocks. The GROUP
 7042 definition itself occupies one FITS file HDU of special type (GROUP
 7043 HDU), so if a template specifies 1 group with 1 member HDU like:
 7044 
 7045 \begin{verbatim}
 7046 \group
 7047 grpdescr = 'demo'
 7048 xtension bintable
 7049 # this bintable has 0 cols, 0 rows
 7050 \end
 7051 \end{verbatim}
 7052 then the parser creates a FITS file with 3 HDUs :
 7053 
 7054 \begin{verbatim}
 7055 1) dummy PHDU
 7056 2) GROUP HDU (has 1 member, which is bintable in HDU number 3)
 7057 3) bintable (member of GROUP in HDU number 2)
 7058 \end{verbatim}
 7059 Technically speaking, the GROUP HDU is a BINTABLE with 6 columns. Applications
 7060 can define additional columns in a GROUP HDU using TFORMn and TTYPEn
 7061 (where n is 7, 8, ....) keywords or their auto-indexing equivalents.
 7062 
 7063 For a more complicated example of a template file using the group directives,
 7064 look at the sample.tpl file that is included in the CFITSIO distribution.
 7065 
 7066 
 7067 \section{Formal Template Syntax}
 7068 
 7069 The template syntax can formally be defined as follows:
 7070 
 7071 \begin{verbatim}
 7072     TEMPLATE = BLOCK [ BLOCK ... ]
 7073 
 7074        BLOCK = { HDU | GROUP }
 7075 
 7076        GROUP = \GROUP [ BLOCK ... ] \END
 7077 
 7078          HDU = XTENSION [ LINE ... ] { XTENSION | \GROUP | \END | EOF }
 7079 
 7080         LINE = [ KEYWORD [ = ] ] [ VALUE ] [ / COMMENT ]
 7081 
 7082     X ...     - X can be present 1 or more times
 7083     { X | Y } - X or Y
 7084     [ X ]     - X is optional
 7085 \end{verbatim}
 7086 
 7087 At the topmost level, the template defines 1 or more template blocks. Blocks
 7088 can be either HDU (Header Data Unit) or a GROUP. For each block the parser
 7089 creates 1 (or more for GROUPs) FITS file HDUs.
 7090 
 7091 
 7092 
 7093 \section{Errors}
 7094 
 7095 In general the fits\_execute\_template() function tries to be as atomic
 7096 as possible, so either everything is done or nothing is done. If an
 7097 error occurs during parsing of the template, fits\_execute\_template()
 7098 will (try to) delete the top level BLOCK (with all its children if any)
 7099 in which the error occurred, then it will stop reading the template file
 7100 and it will return with an error.
 7101 
 7102 
 7103 \section{Examples}
 7104 
 7105 1. This template file will create a 200 x 300 pixel image, with 4-byte
 7106 integer pixel values, in the primary HDU:
 7107 
 7108 \begin{verbatim}
 7109   SIMPLE = T
 7110   BITPIX = 32
 7111   NAXIS = 2     / number of dimensions
 7112   NAXIS1 = 100  / length of first axis
 7113   NAXIS2 = 200  / length of second axis
 7114   OBJECT = NGC 253 / name of observed object
 7115 \end{verbatim}
 7116 The allowed values of BITPIX are 8, 16, 32, -32, or -64,
 7117 representing, respectively, 8-bit integer, 16-bit integer, 32-bit
 7118 integer, 32-bit floating point, or 64 bit floating point pixels.
 7119 
 7120 2.  To create a FITS  table, the template first needs to include
 7121