## "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}
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
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
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
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
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
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}
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
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}
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
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
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"
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
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