1\documentclass[11pt]{book} 2\input{html.sty} 3\htmladdtonavigation 4 {\begin{rawhtml} 5 <A HREF="http://heasarc.gsfc.nasa.gov/docs/software/fitsio/fitsio.html">FITSIO Home</A> 6 \end{rawhtml}} 7%\oddsidemargin=0.25in 8\oddsidemargin=0.00in 9\evensidemargin=0.00in 10\textwidth=6.5in 11%\topmargin=0.0in 12\textheight=8.75in 13\parindent=0cm 14\parskip=0.2cm 15\begin{document} 16\pagenumbering{roman} 17 18\begin{titlepage} 19\normalsize 20\vspace*{4.6cm} 21\begin{center} 22{\Huge \bf FITSIO User's Guide}\\ 23\end{center} 24\medskip 25\medskip 26\begin{center} 27{\LARGE \bf A Subroutine Interface to FITS Format Files}\\ 28\end{center} 29\begin{center} 30{\LARGE \bf for Fortran Programmers}\\ 31\end{center} 32\medskip 33\medskip 34\begin{center} 35{\Large Version 3.0\\} 36\end{center} 37\bigskip 38\vskip 2.5cm 39\begin{center} 40{HEASARC\\ 41Code 662\\ 42Goddard Space Flight Center\\ 43Greenbelt, MD 20771\\ 44USA} 45\end{center} 46 47\vfill 48\bigskip 49\begin{center} 50{\Large April 2016\\} 51\end{center} 52\vfill 53\end{titlepage} 54 55\clearpage 56 57\tableofcontents 58 59\chapter{Introduction } 60\pagenumbering{arabic} 61 62This document describes the Fortran-callable subroutine interface that 63is provided as part of the CFITSIO library (which is written in ANSI 64C). This is a companion document to the CFITSIO User's Guide which 65should be consulted for further information about the underlying 66CFITSIO library. In the remainder of this document, the terms FITSIO 67and CFITSIO are interchangeable and refer to the same library. 68 69FITSIO/CFITSIO is a machine-independent library of routines for reading 70and writing data files in the FITS (Flexible Image Transport System) 71data format. It can also read IRAF format image files and raw binary 72data arrays by converting them on the fly into a virtual FITS format 73file. This library was written to provide a powerful yet simple 74interface for accessing FITS files which will run on most commonly used 75computers and workstations. FITSIO supports all the features described 76in the official definition of the FITS format and can read and 77write all the currently defined types of extensions, including ASCII 78tables (TABLE), Binary tables (BINTABLE) and IMAGE extensions. The 79FITSIO subroutines insulate the programmer from having to deal with the 80complicated formatting details in the FITS file, however, it is assumed 81that users have a general knowledge about the structure and usage of 82FITS files. 83 84The CFITSIO package was initially developed by the HEASARC (High Energy 85Astrophysics Science Archive Research Center) at the NASA Goddard Space 86Flight Center to convert various existing and newly acquired 87astronomical data sets into FITS format and to further analyze data 88already in FITS format. New features continue to be added to CFITSIO 89in large part due to contributions of ideas or actual code from users 90of the package. The Integral Science Data Center in Switzerland, and 91the XMM/ESTEC project in The Netherlands made especially significant 92contributions that resulted in many of the new features that appeared 93in v2.0 of CFITSIO. 94 95The latest version of the CFITSIO source code, documentation, and 96example programs are available on the World-Wide Web or via anonymous 97ftp 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 104Any questions, bug reports, or suggested enhancements related to the CFITSIO 105package 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 111This User's Guide assumes that readers already have a general 112understanding of the definition and structure of FITS format files. 113Further information about FITS formats is available from the FITS Support 114Office at {\tt http://fits.gsfc.nasa.gov}. In particular, the 115'FITS Standard' gives the authoritative definition of the FITS data 116format. Other documents available at that Web site 117provide additional historical background 118and practical advice on using FITS files. 119 120The HEASARC also provides a very sophisticated FITS file analysis 121program called `Fv' which can be used to display and edit the contents 122of any FITS file as well as construct new FITS files from scratch. 123Fv is freely available for 124most Unix platforms, Mac PCs, and Windows PCs. 125CFITSIO users may also be interested in the FTOOLS package of programs 126that can be used to manipulate and analyze FITS format files. 127Fv 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 140To use the FITSIO subroutines one must first build the CFITSIO library, 141which requires a C compiler. gcc is ideal, or most other ANSI-C 142compilers will also work. The CFITSIO code is contained in about 40 C 143source files (*.c) and header files (*.h). On VAX/VMS systems 2 144assembly-code files (vmsieeed.mar and vmsieeer.mar) are also needed. 145 146The Fortran interface subroutines to the C CFITSIO routines are located 147in the f77\_wrap1.c, through f77\_wrap4.c files. These are relatively simple 148'wrappers' that translate the arguments in the Fortran subroutine into 149the appropriate format for the corresponding C routine. This 150translation is performed transparently to the user by a set of C macros 151located in the cfortran.h file. Unfortunately cfortran.h does not 152support every combination of C and Fortran compilers so the Fortran 153interface is not supported on all platforms. (see further notes below). 154 155A standard combination of C and Fortran compilers will be assumed by 156default, but one may also specify a particular Fortran compiler by 157doing: 158 159\begin{verbatim} 160 > setenv CFLAGS -DcompilerName=1 161\end{verbatim} 162(where 'compilerName' is the name of the compiler) before running 163the configure command. The currently recognized compiler 164names 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} 186Alternatively, one may edit the CFLAGS line in the Makefile to add the 187'-DcompilerName' flag after running the './configure' command. 188 189The 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} 197at the operating system prompt. The configure command customizes the 198Makefile for the particular system, then the `make' command compiles the 199source files and builds the library. Type `./configure' and not simply 200`configure' to ensure that the configure script in the current directory 201is run and not some other system-wide configure script. The optional 202'prefix' argument to configure gives the path to the directory where 203the 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} 209will cause the 'make install' command to copy the CFITSIO libcfitsio file 210to /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 212directories). 213 214The optional --enable-sse2 and --enable-ssse3 flags will cause configure to 215attempt to build CFITSIO using faster byte-swapping algorithms. 216See the "Optimizing Programs" section of this manual for 217more information about these options. 218 219By default, the Makefile will be configured to build the set of Fortran-callable 220wrapper routines whose calling sequences are described later in this 221document. 222 223The 'make shared' option builds a shared or dynamic version of the 224CFITSIO library. When using the shared library the executable code is 225not copied into your program at link time and instead the program 226locates the necessary library code at run time, normally through 227LD\_LIBRARY\_PATH or some other method. The advantages of using a shared 228library 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} 241The disadvantages are: 242 243\begin{verbatim} 244 1. More hassle at runtime. You have to either build the programs 245 specially or have LD_LIBRARY_PATH set right. 246 2. There may be a slight start up penalty, depending on where you are 247 reading the shared library and the program from and if your CPU is 248 either really slow or really heavily loaded. 249\end{verbatim} 250 251On HP/UX systems, the environment variable CFLAGS should be set 252to -Ae before running configure to enable "extended ANSI" features. 253 254It may not be possible to statically link programs that use CFITSIO on 255some 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 257make both a dynamic and a static version of the CFITSIO library, but 258network file access will not be possible using the static version. 259 260On VAX/VMS and ALPHA/VMS systems the make\_gfloat.com command file may 261be executed to build the cfitsio.olb object library using the default 262G-floating point option for double variables. The make\_dfloat.com and 263make\_ieee.com files may be used instead to build the library with the 264other floating point options. Note that the getcwd function that is 265used in the group.c module may require that programs using CFITSIO be 266linked with the ALPHA\$LIBRARY:VAXCRTL.OLB library. See the example 267link line in the next section of this document. 268 269On Windows IBM-PC type platforms the situation is more complicated 270because of the wide variety of Fortran compilers that are available and 271because of the inherent complexities of calling the CFITSIO C routines 272from Fortran. Two different versions of the CFITSIO dll library are 273available, compiled with the Borland C++ compiler and the Microsoft 274Visual C++ compiler, respectively, in the files 275cfitsiodll\_2xxx\_borland.zip and cfitsiodll\_3xxx\_vcc.zip, where 276'3xxx' represents the current release number. Both these dll libraries 277contain a set of Fortran wrapper routines which may be compatible with 278some, but probably not all, available Fortran compilers. To test if 279they are compatible, compile the program testf77.f and try linking to 280these dll libraries. If these libraries do not work with a particular 281Fortran compiler, then it may be necessary to modify the file 282"cfortran.h" to support that particular 283combination of C and Fortran compilers, and then rebuild the CFITSIO 284dll library. This will require, however, some expertise in 285mixed language programming. 286 287CFITSIO should be compatible with most current ANCI C and C++ compilers: 288Cray supercomputers are currently not supported. 289 290 291\section{Testing the Library} 292 293The CFITSIO library should be tested by building and running 294the testprog.c program that is included with the release. 295On 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} 311The testprog program should produce a FITS file called `testprog.fit' 312that is identical to the `testprog.std' FITS file included with this 313release. The diagnostic messages (which were piped to the file 314testprog.lis in the Unix example) should be identical to the listing 315contained in the file testprog.out. The 'diff' and 'cmp' commands 316shown above should not report any differences in the files. (There 317may be some minor formatting differences, such as the presence or 318absence of leading zeros, or 3 digit exponents in numbers, 319which can be ignored). 320 321The Fortran wrappers in CFITSIO may be tested with the testf77 322program. On Unix systems the fortran compilation and link command 323may 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} 338On 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 340boundaries to make the fortran-declared variables compatible with C. A 341similar compiler option may be required on other platforms. Failing to 342use this option may cause the program to crash on FITSIO routines that 343read or write double precision variables. 344 345On Windows platforms, linking Fortran programs with a C library 346often depends on the particular compilers involved. Some users have 347found the following commands work when using the Intel Fortran compiler: 348 349\begin{verbatim} 350ifort /libs.dll cfitsio.lib /MD testf77.f /Gm 351 352or possibly, 353 354ifort /libs:dll cfitsio.lib /MD /fpp /extfpp:cfortran.h,fitsio.h 355 /iface:cvf testf77.f 356\end{verbatim} 357Also note that on some systems the output listing of the testf77 358program may differ slightly from the testf77.std template if leading 359zeros are not printed by default before the decimal point when using F 360format. 361 362A 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 379The 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 388When linking applications software with the FITSIO library, several system libraries usually need to be specified on the link comman 389Unix systems, the most reliable way to determine what libraries are required 390is to type 'make testprog' and see what libraries the configure script has 391added. The typical libraries that may need to be added are -lm (the math 392library) and -lnsl and -lsocket (needed only for FTP and HTTP file access). 393These latter 2 libraries are not needed on VMS and Windows platforms, 394because FTP file access is not currently supported on those platforms. 395 396Note that when upgrading to a newer version of CFITSIO it is usually 397necessary to recompile, as well as relink, the programs that use CFITSIO, 398because the definitions in fitsio.h often change. 399 400 401\section{Getting Started with FITSIO} 402 403In order to effectively use the FITSIO library as quickly as possible, 404it is recommended that new users follow these steps: 405 4061. Read the following `FITS Primer' chapter for a brief 407overview of the structure of FITS files. This is especially important 408for users who have not previously dealt with the FITS table and image 409extensions. 410 4112. Write a simple program to read or write a FITS file using the Basic 412Interface routines. 413 4143. Refer to the cookbook.f program that is included with this release 415for examples of routines that perform various common FITS file 416operations. 417 4184. Read Chapters 4 and 5 to become familiar with the conventions and 419advanced features of the FITSIO interface. 420 4215. Scan through the more extensive set of routines that are provided 422in the `Advanced Interface'. These routines perform more specialized 423functions than are provided by the Basic Interface routines. 424 425 426\section{Example Program} 427 428The following listing shows an example of how to use the FITSIO 429routines in a Fortran program. Refer to the cookbook.f program that 430is included with the FITSIO distribution for examples of other 431FITS programs. 432 433\begin{verbatim} 434 program writeimage 435 436C 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 444C Name of the FITS file to be created: 445 filename='ATESTFILE.FITS' 446 447C Get an unused Logical Unit Number to use to create the FITS file 448 call ftgiou(unit,status) 449 450C create the new empty FITS file 451 blocksize=1 452 call ftinit(unit,filename,blocksize,status) 453 454C 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 462C write the required header keywords 463 call ftphpr(unit,simple,bitpix,naxis,naxes,0,1,extend,status) 464 465C 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 472C 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 478C write another optional keyword to the header 479 call ftpkyj(unit,'EXPOSURE',1500,'Total Exposure Time',status) 480 481C 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 490Copyright (Unpublished--all rights reserved under the copyright laws of 491the United States), U.S. Government as represented by the Administrator 492of the National Aeronautics and Space Administration. No copyright is 493claimed in the United States under Title 17, U.S. Code. 494 495Permission to freely use, copy, modify, and distribute this software 496and its documentation without fee is hereby granted, provided that this 497copyright notice and disclaimer of warranty appears in all copies. 498 499DISCLAIMER: 500 501THE SOFTWARE IS PROVIDED 'AS IS' WITHOUT ANY WARRANTY OF ANY KIND, 502EITHER EXPRESSED, IMPLIED, OR STATUTORY, INCLUDING, BUT NOT LIMITED TO, 503ANY WARRANTY THAT THE SOFTWARE WILL CONFORM TO SPECIFICATIONS, ANY 504IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR 505PURPOSE, AND FREEDOM FROM INFRINGEMENT, AND ANY WARRANTY THAT THE 506DOCUMENTATION WILL CONFORM TO THE SOFTWARE, OR ANY WARRANTY THAT THE 507SOFTWARE WILL BE ERROR FREE. IN NO EVENT SHALL NASA BE LIABLE FOR ANY 508DAMAGES, INCLUDING, BUT NOT LIMITED TO, DIRECT, INDIRECT, SPECIAL OR 509CONSEQUENTIAL DAMAGES, ARISING OUT OF, RESULTING FROM, OR IN ANY WAY 510CONNECTED WITH THIS SOFTWARE, WHETHER OR NOT BASED UPON WARRANTY, 511CONTRACT, TORT , OR OTHERWISE, WHETHER OR NOT INJURY WAS SUSTAINED BY 512PERSONS OR PROPERTY OR OTHERWISE, AND WHETHER OR NOT LOSS WAS SUSTAINED 513FROM, OR AROSE OUT OF THE RESULTS OF, OR USE OF, THE SOFTWARE OR 514SERVICES PROVIDED HEREUNDER." 515 516 517\section{Acknowledgments} 518 519The development of many of the powerful features in CFITSIO was made 520possible through collaborations with many people or organizations from 521around the world. The following, in particular, have made especially 522significant contributions: 523 524Programmers from the Integral Science Data Center, Switzerland (namely, 525Jurek Borkowski, Bruce O'Neel, and Don Jennings), designed the concept 526for the plug-in I/O drivers that was introduced with CFITSIO 2.0. The 527use of `drivers' greatly simplified the low-level I/O, which in turn 528made other new features in CFITSIO (e.g., support for compressed FITS 529files and support for IRAF format image files) much easier to 530implement. Jurek Borkowski wrote the Shared Memory driver, and Bruce 531O'Neel wrote the drivers for accessing FITS files over the network 532using the FTP, HTTP, and ROOT protocols. 533 534The ISDC also provided the template parsing routines (written by Jurek 535Borkowski) and the hierarchical grouping routines (written by Don 536Jennings). The ISDC DAL (Data Access Layer) routines are layered on 537top of CFITSIO and make extensive use of these features. 538 539Uwe Lammers (XMM/ESA/ESTEC, The Netherlands) designed the 540high-performance lexical parsing algorithm that is used to do 541on-the-fly filtering of FITS tables. This algorithm essentially 542pre-compiles the user-supplied selection expression into a form that 543can be rapidly evaluated for each row. Peter Wilson (RSTX, NASA/GSFC) 544then wrote the parsing routines used by CFITSIO based on Lammers' 545design, combined with other techniques such as the CFITSIO iterator 546routine to further enhance the data processing throughput. This effort 547also benefited from a much earlier lexical parsing routine that was 548developed by Kent Blackburn (NASA/GSFC). More recently, Craig Markwardt 549(NASA/GSFC) implemented additional functions (median, average, stddev) 550and other enhancements to the lexical parser. 551 552The CFITSIO iterator function is loosely based on similar ideas 553developed for the XMM Data Access Layer. 554 555Peter Wilson (RSTX, NASA/GSFC) wrote the complete set of 556Fortran-callable wrappers for all the CFITSIO routines, which in turn 557rely on the CFORTRAN macro developed by Burkhard Burow. 558 559The syntax used by CFITSIO for filtering or binning input FITS files is 560based on ideas developed for the AXAF Science Center Data Model by 561Jonathan McDowell, Antonella Fruscione, Aneta Siemiginowska and Bill 562Joye. See http://heasarc.gsfc.nasa.gov/docs/journal/axaf7.html for 563further description of the AXAF Data Model. 564 565The file decompression code were taken directly from the gzip (GNU zip) 566program developed by Jean-loup Gailly and others. 567 568Doug Mink, SAO, provided the routines for converting IRAF format 569images into FITS format. 570 571Martin Reinecke (Max Planck Institute, Garching)) provided the modifications to 572cfortran.h that are necessary to support 64-bit integer values when calling 573C routines from fortran programs. The cfortran.h macros were originally developed 574by Burkhard Burow (CERN). 575 576Julian Taylor (ESO, Garching) provided the fast byte-swapping algorithms 577that use the SSE2 and SSSE3 machine instructions available on x86\_64 CPUs. 578 579In addition, many other people have made valuable contributions to the 580development of CFITSIO. These include (with apologies to others that may 581have inadvertently been omitted): 582 583Steve Allen, Carl Akerlof, Keith Arnaud, Morten Krabbe Barfoed, Kent 584Blackburn, G Bodammer, Romke Bontekoe, Lucio Chiappetti, Keith Costorf, 585Robin Corbet, John Davis, Richard Fink, Ning Gan, Emily Greene, Joe 586Harrington, Cheng Ho, Phil Hodge, Jim Ingham, Yoshitaka Ishisaki, Diab 587Jerius, Mark Levine, Todd Karakaskian, Edward King, Scott Koch, Claire 588Larkin, Rob Managan, Eric Mandel, John Mattox, Carsten Meyer, Emi 589Miyata, Stefan Mochnacki, Mike Noble, Oliver Oberdorf, Clive Page, 590Arvind Parmar, Jeff Pedelty, Tim Pearson, Maren Purves, Scott Randall, 591Chris Rogers, Arnold Rots, Barry Schlesinger, Robin Stebbins, Andrew 592Szymkowiak, Allyn Tennant, Peter Teuben, James Theiler, Doug Tody, 593Shiro Ueno, Steve Walton, Archie Warnock, Alan Watson, Dan Whipple, Wim 594Wimmers, Peter Young, Jianjun Xu, and Nelson Zarate. 595 596 597\chapter{ A FITS Primer } 598 599This section gives a brief overview of the structure of FITS files. 600Users should refer to the documentation available from the FITS Support Office, as 601described in the introduction, for more detailed information on FITS 602formats. 603 604FITS was first developed in the late 1970's as a standard data 605interchange format between various astronomical observatories. Since 606then FITS has become the defacto standard data format supported by most 607astronomical data analysis software packages. 608 609A FITS file consists of one or more Header + Data Units (HDUs), where 610the first HDU is called the `Primary HDU', or `Primary Array'. The 611primary array contains an N-dimensional array of pixels, such as a 1-D 612spectrum, a 2-D image, or a 3-D data cube. Six different primary 613datatypes are supported: Unsigned 8-bit bytes, 16, 32, and 64-bit signed 614integers, and 32 and 64-bit floating point reals. FITS also has a 615convention for storing unsigned integers (see the later 616section entitled `Unsigned Integers' for more details). The primary HDU 617may also consist of only a header with a null array containing no 618data pixels. 619 620Any number of additional HDUs may follow the primary array; these 621additional HDUs are called FITS `extensions'. There are currently 3 622types 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 633In each case the HDU consists of an ASCII Header Unit followed by an optional 634Data Unit. For historical reasons, each Header or Data unit must be an 635exact multiple of 2880 8-bit bytes long. Any unused space is padded 636with fill characters (ASCII blanks or zeros). 637 638Each Header Unit consists of any number of 80-character keyword records 639or `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} 645The keyword names may be up to 8 characters long and can only contain 646uppercase letters, the digits 0-9, the hyphen, and the underscore 647character. The keyword name is (usually) followed by an equals sign and 648a space character (= ) in columns 9 - 10 of the record, followed by the 649value of the keyword which may be either an integer, a floating point 650number, a character string (enclosed in single quotes), or a boolean 651value (the letter T or F). A keyword may also have a null or undefined 652value if there is no specified value string, as in the second example. 653 654The last keyword in the header is always the `END' keyword which has no 655value or comment fields. There are many rules governing the exact 656format of a keyword record (see the FITS Standard) so it is better 657to rely on standard interface software like FITSIO to correctly 658construct or to parse the keyword records rather than try to deal 659directly with the raw FITS formats. 660 661Each Header Unit begins with a series of required keywords which depend 662on the type of HDU. These required keywords specify the size and 663format of the following Data Unit. The header may contain other 664optional keywords to describe other aspects of the data, such as the 665units or scaling values. Other COMMENT or HISTORY keywords are also 666frequently added to further document the data file. 667 668The optional Data Unit immediately follows the last 2880-byte block in 669the Header Unit. Some HDUs do not have a Data Unit and only consist of 670the Header Unit. 671 672If there is more than one HDU in the FITS file, then the Header Unit of 673the next HDU immediately follows the last 2880-byte block of the 674previous Data Unit (or Header Unit if there is no Data Unit). 675 676The main required keywords in FITS primary arrays or image extensions are: 677\begin{itemize} 678\item 679BITPIX -- defines the datatype of the array: 8, 16, 32, 64, -32, -64 for 680unsigned 8--bit byte, 16--bit signed integer, 32--bit signed integer, 68164--bit signed integer, 68232--bit IEEE floating point, and 64--bit IEEE double precision floating 683point, respectively. 684\item 685NAXIS -- the number of dimensions in the array, usually 0, 1, 2, 3, or 4. 686\item 687NAXISn -- (n ranges from 1 to NAXIS) defines the size of each dimension. 688\end{itemize} 689 690FITS tables start with the keyword XTENSION = `TABLE' (for ASCII 691tables) or XTENSION = `BINTABLE' (for binary tables) and have the 692following main keywords: 693\begin{itemize} 694\item 695TFIELDS -- number of fields or columns in the table 696\item 697NAXIS2 -- number of rows in the table 698\item 699TTYPEn -- for each column (n ranges from 1 to TFIELDS) gives the 700name of the column 701\item 702TFORMn -- the datatype of the column 703\item 704TUNITn -- the physical units of the column (optional) 705\end{itemize} 706 707Users should refer to the FITS Support Office at {\tt http://fits.gsfc.nasa.gov} 708for further information about the FITS format and related software 709packages. 710 711 712 713\chapter{FITSIO Conventions and Guidelines } 714 715 716\section{CFITSIO Size Limitations} 717 718CFITSIO places few restrictions on the size of FITS files that it 719reads or writes. There are a few limits, however, which may affect 720some extreme cases: 721 7221. The maximum number of FITS files that may be simultaneously opened by 723CFITSIO is set by NMAXFILES, as defined in fitsio2.h. The current default 724value is 1000, but this may be increased if necessary. Note that CFITSIO 725allocates NIOBUF * 2880 bytes of I/O buffer space for each file that is 726opened. The default value of NIOBUF is 40 (defined in fitsio.h), so this 727amounts to more than 115K of memory for each opened file (or 115 MB for 7281000 opened files). Note that the underlying operating system, may have a 729lower limit on the number of files that can be opened simultaneously. 730 7312. By default, CFITSIO can handle FITS files up to 2.1 GB in size (2**31 732bytes). This file size limit is often imposed by 32-bit operating 733systems. More recently, as 64-bit operating systems become more common, an 734industry-wide standard (at least on Unix systems) has been developed to 735support larger sized files (see http://ftp.sas.com/standards/large.file/). 736Starting with version 2.1 of CFITSIO, larger FITS files up to 6 terabytes 737in size may be read and written on supported platforms. In order 738to support these larger files, CFITSIO must be compiled with the 739'-D\_LARGEFILE\_SOURCE' and `-D\_FILE\_OFFSET\_BITS=64' compiler flags. 740Some platforms may also require the `-D\_LARGE\_FILES' compiler flag. 741 This causes the compiler to allocate 8-bytes instead of 7424-bytes for the `off\_t' datatype which is used to store file offset 743positions. It appears that in most cases it is not necessary to 744also include these compiler flags when compiling programs that link to 745the CFITSIO library. 746 747If CFITSIO is compiled with the -D\_LARGEFILE\_SOURCE 748and -D\_FILE\_OFFSET\_BITS=64 flags on a 749platform that supports large files, then it can read and write FITS 750files that contain up to 2**31 2880-byte FITS records, or approximately 7516 terabytes in size. It is still required that the value of the NAXISn 752and PCOUNT keywords in each extension be within the range of a signed 7534-byte integer (max value = 2,147,483,648). Thus, each dimension of an 754image (given by the NAXISn keywords), the total width of a table 755(NAXIS1 keyword), the number of rows in a table (NAXIS2 keyword), and 756the total size of the variable-length array heap in binary tables 757(PCOUNT keyword) must be less than this limit. 758 759Currently, support for large files within CFITSIO has been tested 760on the Linux, Solaris, and IBM AIX operating systems. 761 762 763\section{Multiple Access to the Same FITS File} 764 765CFITSIO supports simultaneous read and write access to multiple HDUs in 766the same FITS file. Thus, one can open the same FITS file twice within 767a single program and move to 2 different HDUs in the file, and then 768read and write data or keywords to the 2 extensions just as if one were 769accessing 2 completely separate FITS files. Since in general it is 770not possible to physically open the same file twice and then expect to 771be able to simultaneously (or in alternating succession) write to 2 772different locations in the file, CFITSIO recognizes when the file to be 773opened (in the call to fits\_open\_file) has already been opened and 774instead of actually opening the file again, just logically links the 775new file to the old file. (This only applies if the file is opened 776more than once within the same program, and does not prevent the same 777file from being simultaneously opened by more than one program). Then 778before CFITSIO reads or writes to either (logical) file, it makes sure 779that any modifications made to the other file have been completely 780flushed from the internal buffers to the file. Thus, in principle, one 781could open a file twice, in one case pointing to the first extension 782and in the other pointing to the 2nd extension and then write data to 783both extensions, in any order, without danger of corrupting the file, 784There may be some efficiency penalties in doing this however, since 785CFITSIO has to flush all the internal buffers related to one file 786before switching to the other, so it would still be prudent to 787minimize the number of times one switches back and forth between doing 788I/O to different HDUs in the same file. 789 790 791\section{Current Header Data Unit (CHDU)} 792 793In general, a FITS file can contain multiple Header Data Units, also 794called extensions. CFITSIO only operates within one HDU at any given 795time, and the currently selected HDU is called the Current Header Data 796Unit (CHDU). When a FITS file is first created or opened the CHDU is 797automatically defined to be the first HDU (i.e., the primary array). 798CFITSIO routines are provided to move to and open any other existing 799HDU within the FITS file or to append or insert a new HDU in the FITS 800file which then becomes the CHDU. 801 802 803\section{Subroutine Names} 804 805All FITSIO subroutine names begin with the letters 'ft' to distinguish 806them from other subroutines and are 5 or 6 characters long. Users should 807not name their own subroutines beginning with 'ft' to avoid conflicts. 808(The SPP interface routines all begin with 'fs'). Subroutines which read 809or get information from the FITS file have names beginning with 810'ftg...'. Subroutines which write or put information into the FITS file 811have names beginning with 'ftp...'. 812 813 814\section{Subroutine Families and Datatypes} 815 816Many of the subroutines come in families which differ only in the 817datatype of the associated parameter(s) . The datatype of these 818subroutines 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 837When dealing with the FITS byte datatype, it is important to remember 838that the raw values (before any scaling by the BSCALE and BZERO, or 839TSCALn and TZEROn keyword values) in byte arrays (BITPIX = 8) or byte 840columns (TFORMn = 'B') are interpreted as unsigned bytes with values 841ranging from 0 to 255. Some Fortran compilers support a non-standard 842byte datatype such as INTEGER*1, LOGICAL*1, or BYTE, which can sometimes 843be used instead of CHARACTER*1 variables. Many machines permit passing a 844numeric datatype (such as INTEGER*1) to the FITSIO subroutines which are 845expecting a CHARACTER*1 datatype, but this technically violates the 846Fortran-77 standard and is not supported on all machines (e.g., on a VAX/VMS 847machine one must use the VAX-specific \%DESCR function). 848 849One 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. 851For 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 853be more efficient to read and write whole bytes at a time, rather than 854reading or writing each individual bit. 855 856The double precision complex datatype is not a standard Fortran-77 857datatype. If a particular Fortran compiler does not directly support 858this datatype, then one may instead pass an array of pairs of double 859precision values to these subroutines. The first value in each pair 860is the real part, and the second is the imaginary part. 861 862 863\section{Implicit Data Type Conversion} 864 865The FITSIO routines that read and write numerical data can perform 866implicit data type conversion. This means that the data type of the 867variable or array in the program does not need to be the same as the 868data type of the value in the FITS file. Data type conversion is 869supported for numerical and string data types (if the string contains a 870valid number enclosed in quotes) when reading a FITS header keyword 871value and for numeric values when reading or writing values in the 872primary array or a table column. CFITSIO returns status = 873NUM\_OVERFLOW if the converted data value exceeds the range of the 874output data type. Implicit data type conversion is not supported 875within binary tables for string, logical, complex, or double complex 876data types. 877 878In addition, any table column may be read as if it contained string values. 879In the case of numeric columns the returned string will be formatted 880using the TDISPn display format if it exists. 881 882 883\section{Data Scaling} 884 885When reading numerical data values in the primary array or a 886table column, the values will be scaled automatically by the BSCALE and 887BZERO (or TSCALn and TZEROn) header keyword values if they are 888present in the header. The scaled data that is returned to the reading 889program 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 895from table columns). In the case of integer output values the floating 896point scaled value is truncated to an integer (not rounded to the 897nearest integer). The ftpscl and fttscl subroutines may be used to 898override the scaling parameters defined in the header (e.g., to turn 899off the scaling so that the program can read the raw unscaled values 900from the FITS file). 901 902When writing numerical data to the primary array or to a table 903column the data values will generally be automatically inversely scaled 904by the value of the BSCALE and BZERO (or TSCALn and TZEROn) header 905keyword values if they they exist in the header. These keywords must 906have been written to the header before any data is written for them to 907have any effect. Otherwise, one may use the ftpscl and fttscl 908subroutines 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 910unscaled values into the FITS file). If scaling is performed, the 911inverse scaled output value that is written into the FITS file will 912have 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 918writing to table columns). Rounding to the nearest integer, rather 919than truncation, is performed when writing integer datatypes to the 920FITS file. 921 922 923\section{Error Status Values and the Error Message Stack} 924 925The last parameter in nearly every FITSIO subroutine is the error 926status value which is both an input and an output parameter. A 927returned positive value for this parameter indicates an error was 928detected. A listing of all the FITSIO status code values is given at 929the end of this document. 930 931The FITSIO library uses an `inherited status' convention for the status 932parameter which means that if a subroutine is called with a positive 933input value of the status parameter, then the subroutine will exit 934immediately without changing the value of the status parameter. Thus, 935if one passes the status value returned from each FITSIO routine as 936input to the next FITSIO subroutine, then whenever an error is detected 937all further FITSIO processing will cease. This convention can simplify 938the error checking in application programs because it is not necessary 939to check the value of the status parameter after every single FITSIO 940subroutine call. If a program contains a sequence of several FITSIO 941calls, one can just check the status value after the last call. Since 942the returned status values are generally distinctive, it should be 943possible to determine which subroutine originally returned the error 944status. 945 946FITSIO also maintains an internal stack of error messages (80-character 947maximum length) which in many cases provide a more detailed explanation 948of the cause of the error than is provided by the error status number 949alone. It is recommended that the error message stack be printed out 950whenever a program detects a FITSIO error. To do this, call the FTGMSG 951routine repeatedly to get the successive messages on the stack. When the 952stack 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 954first by ftgmsg. 955 956 957\section{Variable-Length Array Facility in Binary Tables} 958 959FITSIO provides easy-to-use support for reading and writing data in 960variable length fields of a binary table. The variable length columns 961have TFORMn keyword values of the form `1Pt(len)' or `1Qt(len)' where `t' is the 962datatype code (e.g., I, J, E, D, etc.) and `len' is an integer 963specifying the maximum length of the vector in the table. If the value 964of `len' is not specified when the table is created (e.g., if the TFORM 965keyword value is simply specified as '1PE' instead of '1PE(400) ), then 966FITSIO will automatically scan the table when it is closed to 967determine the maximum length of the vector and will append this value 968to the TFORMn value. 969 970The same routines which read and write data in an ordinary fixed length 971binary table extension are also used for variable length fields, 972however, the subroutine parameters take on a slightly different 973interpretation as described below. 974 975All the data in a variable length field is written into an area called 976the `heap' which follows the main fixed-length FITS binary table. The 977size of the heap, in bytes, is specified with the PCOUNT keyword in the 978FITS header. When creating a new binary table, the initial value of 979PCOUNT should usually be set to zero. FITSIO will recompute the size 980of the heap as the data is written and will automatically update the 981PCOUNT keyword value when the table is closed. When writing variable 982length data to a table, CFITSIO will automatically extend the size 983of the heap area if necessary, so that any following HDUs do not 984get overwritten. 985 986By default the heap data area starts immediately after the last row of 987the fixed-length table. This default starting location may be 988overridden by the THEAP keyword, but this is not recommended. 989If additional rows of data are added to the table, CFITSIO will 990automatically shift the the heap down to make room for the new 991rows, but it is obviously be more efficient to initially 992create the table with the necessary number of blank rows, so that 993the heap does not needed to be constantly moved. 994 995When writing to a variable length field, the entire array of values for 996a given row of the table must be written with a single call to FTPCLx. 997The total length of the array is calculated from (NELEM+FELEM-1). One 998cannot append more elements to an existing field at a later time; any 999attempt to do so will simply overwrite all the data which was previously 1000written. Note also that the new data will be written to a new area of 1001the heap and the heap space used by the previous write cannot be 1002reclaimed. For this reason it is advised that each row of a variable 1003length field only be written once. An exception to this general rule 1004occurs when setting elements of an array as undefined. One must first 1005write a dummy value into the array with FTPCLx, and then call FTPCLU to 1006flag the desired elements as undefined. (Do not use the FTPCNx family 1007of routines with variable length fields). Note that the rows of a table, 1008whether fixed or variable length, do not have to be written 1009consecutively and may be written in any order. 1010 1011When writing to a variable length ASCII character field (e.g., TFORM = 1012'1PA') only a single character string written. FTPCLS writes the whole 1013length of the input string (minus any trailing blank characters), thus 1014the NELEM and FELEM parameters are ignored. If the input string is 1015completely blank then FITSIO will write one blank character to the FITS 1016file. Similarly, FTGCVS and FTGCFS read the entire string (truncated 1017to the width of the character string argument in the subroutine call) 1018and also ignore the NELEM and FELEM parameters. 1019 1020The FTPDES subroutine is useful in situations where multiple rows of a 1021variable length column have the identical array of values. One can 1022simply write the array once for the first row, and then use FTPDES to 1023write the same descriptor values into the other rows (use the FTGDES 1024routine to read the first descriptor value); all the rows will then 1025point to the same storage location thus saving disk space. 1026 1027When reading from a variable length array field one can only read as 1028many elements as actually exist in that row of the table; reading does 1029not automatically continue with the next row of the table as occurs 1030when reading an ordinary fixed length table field. Attempts to read 1031more than this will cause an error status to be returned. One can 1032determine the number of elements in each row of a variable column with 1033the FTGDES subroutine. 1034 1035 1036\section{Support for IEEE Special Values} 1037 1038The ANSI/IEEE-754 floating-point number standard defines certain 1039special values that are used to represent such quantities as 1040Not-a-Number (NaN), denormalized, underflow, overflow, and infinity. 1041(See the Appendix in the FITS standard or the FITS User's 1042Guide for a list of these values). The FITSIO subroutines that read 1043floating point data in FITS files recognize these IEEE special values 1044and by default interpret the overflow and infinity values as being 1045equivalent to a NaN, and convert the underflow and denormalized values 1046into zeros. In some cases programmers may want access to the raw IEEE 1047values, without any modification by FITSIO. This can be done by 1048calling the FTGPVx or FTGCVx routines while specifying 0.0 as the value 1049of the NULLVAL parameter. This will force FITSIO to simply pass the 1050IEEE values through to the application program, without any 1051modification. This does not work for double precision values on 1052VAX/VMS machines, however, where there is no easy way to bypass the 1053default interpretation of the IEEE special values. This is also not 1054supported when reading floating-point images that have been compressed 1055with the FITS tiled image compression convention that is discussed in 1056section 5.6; the pixels values in tile compressed images are 1057represented 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 1064It is not required to know the total size of a FITS data array or table 1065before beginning to write the data to the FITS file. In the case of 1066the primary array or an image extension, one should initially create 1067the array with the size of the highest dimension (largest NAXISn 1068keyword) set to a dummy value, such as 1. Then after all the data have 1069been written and the true dimensions are known, then the NAXISn value 1070should be updated using the fits\_ update\_key routine before moving to 1071another extension or closing the FITS file. 1072 1073When writing to FITS tables, CFITSIO automatically keeps track of the 1074highest row number that is written to, and will increase the size of 1075the table if necessary. CFITSIO will also automatically insert space 1076in the FITS file if necessary, to ensure that the data 'heap', if it 1077exists, and/or any additional HDUs that follow the table do not get 1078overwritten as new rows are written to the table. 1079 1080As a general rule it is best to specify the initial number of rows = 0 1081when the table is created, then let CFITSIO keep track of the number of 1082rows that are actually written. The application program should not 1083manually update the number of rows in the table (as given by the NAXIS2 1084keyword) since CFITSIO does this automatically. If a table is 1085initially created with more than zero rows, then this will usually be 1086considered as the minimum size of the table, even if fewer rows are 1087actually written to the table. Thus, if a table is initially created 1088with NAXIS2 = 20, and CFITSIO only writes 10 rows of data before 1089closing the table, then NAXIS2 will remain equal to 20. If however, 30 1090rows of data are written to this table, then NAXIS2 will be increased 1091from 20 to 30. The one exception to this automatic updating of the 1092NAXIS2 keyword is if the application program directly modifies the 1093value of NAXIS2 (up or down) itself just before closing the table. In this 1094case, CFITSIO does not update NAXIS2 again, since it assumes that the 1095application program must have had a good reason for changing the value 1096directly. This is not recommended, however, and is only provided for 1097backward compatibility with software that initially creates a table 1098with a large number of rows, than decreases the NAXIS2 value to the 1099actual smaller value just before closing the table. 1100 1101 1102\section{Local FITS Conventions supported by FITSIO} 1103 1104CFITSIO supports several local FITS conventions which are not 1105defined in the official FITS standard and which are not 1106necessarily recognized or supported by other FITS software packages. 1107Programmers should be cautious about using these features, especially 1108if the FITS files that are produced are expected to be processed by 1109other software systems which do not use the CFITSIO interface. 1110 1111 1112\subsection{Support for Long String Keyword Values.} 1113 1114The length of a standard FITS string keyword is limited to 68 1115characters because it must fit entirely within a single FITS header 1116keyword record. In some instances it is necessary to encode strings 1117longer than this limit, so FITSIO supports a local convention in which 1118the string value is continued over multiple keywords. This 1119continuation convention uses an ampersand character at the end of each 1120substring to indicate that it is continued on the next keyword, and the 1121continuation keywords all have the name CONTINUE without an equal sign 1122in column 9. The string value may be continued in this way over as many 1123additional CONTINUE keywords as is required. The following lines 1124illustrate this continuation convention which is used in the value of 1125the STRKEY keyword: 1126 1127\begin{verbatim} 1128LONGSTRN= 'OGIP 1.0' / The OGIP Long String Convention may be used. 1129STRKEY = 'This is a very long string keyword&' / Optional Comment 1130CONTINUE ' value that is continued over 3 keywords in the & ' 1131CONTINUE 'FITS header.' / This is another optional comment. 1132\end{verbatim} 1133It is recommended that the LONGSTRN keyword, as shown 1134here, always be included in any HDU that uses this longstring 1135convention. A subroutine called FTPLSW 1136has been provided in CFITSIO to write this keyword if it does not 1137already exist. 1138 1139This long string convention is supported by the following FITSIO 1140subroutines 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} 1150These routines will transparently read, write, or delete a long string 1151value in the FITS file, so programmers in general do not have to be 1152concerned about the details of the convention that is used to encode 1153the long string in the FITS header. When reading a long string, one 1154must ensure that the character string parameter used in these 1155subroutine calls has been declared long enough to hold the entire 1156string, otherwise the returned string value will be truncated. 1157 1158Note that the more commonly used FITSIO subroutine to write string 1159valued keywords (FTPKYS) does NOT support this long string convention 1160and only supports strings up to 68 characters in length. This has been 1161done deliberately to prevent programs from inadvertently writing 1162keywords using this non-standard convention without the explicit intent 1163of the programmer or user. The FTPKLS subroutine must be called 1164instead to write long strings. This routine can also be used to write 1165ordinary string values less than 68 characters in length. 1166 1167 1168\subsection{Arrays of Fixed-Length Strings in Binary Tables} 1169 1170CFITSIO supports 2 ways to specify that a character column in a binary 1171table contains an array of fixed-length strings. The first way, which 1172is officially supported by the FITS Standard document, uses the TDIMn keyword. 1173For example, if TFORMn = '60A' and TDIMn = '(12,5)' then that 1174column will be interpreted as containing an array of 5 strings, each 12 1175characters long. 1176 1177FITSIO also supports a 1178local 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 1180of the column, and 'w' is an integer specifying the (fixed) length of 1181an individual unit string within the vector. For example, TFORM1 = 1182'120A10' would indicate that the binary table column is 120 characters 1183wide and consists of 12 10-character length strings. This convention 1184is recognized by the FITSIO subroutines that read or write strings in 1185binary tables. The Binary Table definition document specifies that 1186other optional characters may follow the datatype code in the TFORM 1187keyword, so this local convention is in compliance with the 1188FITS standard, although other FITS readers are not required to 1189recognize this convention. 1190 1191 1192\subsection{Keyword Units Strings} 1193 1194One deficiency of the current FITS Standard is that it does not define 1195a specific convention for recording the physical units of a keyword 1196value. The TUNITn keyword can be used to specify the physical units of 1197the values in a table column, but there is no analogous convention for 1198keyword values. The comment field of the keyword is often used for 1199this purpose, but the units are usually not specified in a well defined 1200format that FITS readers can easily recognize and extract. 1201 1202To solve this deficiency, FITSIO uses a local convention in which the 1203keyword units are enclosed in square brackets as the first token in the 1204keyword comment field; more specifically, the opening square bracket 1205immediately follows the slash '/' comment field delimiter and a single 1206space character. The following examples illustrate keywords that use 1207this convention: 1208 1209 1210\begin{verbatim} 1211EXPOSURE= 1800.0 / [s] elapsed exposure time 1212V_HELIO = 16.23 / [km s**(-1)] heliocentric velocity 1213LAMBDA = 5400. / [angstrom] central wavelength 1214FLUX = 4.9033487787637465E-30 / [J/cm**2/s] average flux 1215\end{verbatim} 1216 1217In general, the units named in the IAU(1988) Style Guide are 1218recommended, with the main exception that the preferred unit for angle 1219is 'deg' for degrees. 1220 1221The FTPUNT and FTGUNT subroutines in FITSIO write and read, 1222respectively, the keyword unit strings in an existing keyword. 1223 1224 1225\subsection{HIERARCH Convention for Extended Keyword Names} 1226 1227CFITSIO supports the HIERARCH keyword convention which allows keyword 1228names that are longer than 8 characters. This convention 1229was developed at the European Southern Observatory (ESO) and allows characters 1230consisting of digits 0-9, upper case letters A-Z, the dash '-' and the underscore '\_'. 1231The components of hierarchical keywords are separated by a single ASCII space charater. 1232For instance: 1233 1234\begin{verbatim} 1235HIERARCH ESO INS FOCU POS = -0.00002500 / Focus position 1236\end{verbatim} 1237Basically, this convention uses the FITS keyword 'HIERARCH' to indicate 1238that this convention is being used, then the actual keyword name 1239({\tt'ESO INS FOCU POS'} in this example) begins in column 10. The 1240equals sign marks the end of the keyword name and is followed by the 1241usual value and comment fields just as in standard FITS keywords. 1242Further details of this convention are described at 1243http://fits.gsfc.nasa.gov/registry/hierarch\_keyword.html 1244and in Section 4.4 of the ESO Data Interface Control Document that 1245is linked to from 1246http://archive.eso.org/cms/tools-documentation/eso-data-interface-control.html. 1247 1248This convention allows a broader range of keyword names 1249than is allowed by the FITS Standard. Here are more examples 1250of such keywords: 1251 1252\begin{verbatim} 1253HIERARCH LONGKEYWORD = 47.5 / Keyword has > 8 characters 1254HIERARCH LONG-KEY_WORD2 = 52.3 / Long keyword with hyphen, underscore and digit 1255HIERARCH EARTH IS A STAR = F / Keyword contains embedded spaces 1256\end{verbatim} 1257CFITSIO will transparently read and write these keywords, so application 1258programs do not in general need to know anything about the specific 1259implementation details of the HIERARCH convention. In particular, 1260application programs do not need to specify the `HIERARCH' part of the 1261keyword name when reading or writing keywords (although it 1262may be included if desired). When writing a keyword, CFITSIO first 1263checks 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 1265a minus sign or underscore). If so it writes it as a standard FITS 1266keyword, otherwise it uses the hierarch convention to write the 1267keyword. The maximum keyword name length is 67 characters, which 1268leaves only 1 space for the value field. A more practical limit is 1269about 40 characters, which leaves enough room for most keyword values. 1270CFITSIO returns an error if there is not enough room for both the 1271keyword name and the keyword value on the 80-character card, except for 1272string-valued keywords which are simply truncated so that the closing 1273quote character falls in column 80. A space is also required on either 1274side of the equal sign. 1275 1276 1277\section{Optimizing Code for Maximum Processing Speed} 1278 1279CFITSIO has been carefully designed to obtain the highest possible 1280speed when reading and writing FITS files. In order to achieve the 1281best performance, however, application programmers must be careful to 1282call the CFITSIO routines appropriately and in an efficient sequence; 1283inappropriate usage of CFITSIO routines can greatly slow down the 1284execution speed of a program. 1285 1286The maximum possible I/O speed of CFITSIO depends of course on the type 1287of computer system that it is running on. To get a general idea of what 1288data I/O speeds are possible on a particular machine, build the speed.c 1289program that is distributed with CFITSIO (type 'make speed' in the CFITSIO 1290directory). This diagnostic program measures the speed of writing and reading 1291back a test FITS image, a binary table, and an ASCII table. 1292 1293The following 2 sections provide some background on how CFITSIO 1294internally manages the data I/O and describes some strategies that may 1295be used to optimize the processing speed of software that uses 1296CFITSIO. 1297 1298 1299\subsection{Background Information: How CFITSIO Manages Data I/O} 1300 1301Many CFITSIO operations involve transferring only a small number of 1302bytes to or from the FITS file (e.g, reading a keyword, or writing a 1303row in a table); it would be very inefficient to physically read or 1304write such small blocks of data directly in the FITS file on disk, 1305therefore CFITSIO maintains a set of internal Input--Output (IO) 1306buffers in RAM memory that each contain one FITS block (2880 bytes) of 1307data. Whenever CFITSIO needs to access data in the FITS file, it first 1308transfers the FITS block containing those bytes into one of the IO 1309buffers in memory. The next time CFITSIO needs to access bytes in the 1310same block it can then go to the fast IO buffer rather than using a 1311much slower system disk access routine. The number of available IO 1312buffers is determined by the NIOBUF parameter (in fitsio2.h) and is 1313currently set to 40. 1314 1315Whenever CFITSIO reads or writes data it first checks to see if that 1316block of the FITS file is already loaded into one of the IO buffers. 1317If not, and if there is an empty IO buffer available, then it will load 1318that block into the IO buffer (when reading a FITS file) or will 1319initialize a new block (when writing to a FITS file). If all the IO 1320buffers are already full, it must decide which one to reuse (generally 1321the one that has been accessed least recently), and flush the contents 1322back to disk if it has been modified before loading the new block. 1323 1324The one major exception to the above process occurs whenever a large 1325contiguous set of bytes are accessed, as might occur when reading or 1326writing a FITS image. In this case CFITSIO bypasses the internal IO 1327buffers and simply reads or writes the desired bytes directly in the 1328disk file with a single call to a low-level file read or write 1329routine. The minimum threshold for the number of bytes to read or 1330write this way is set by the MINDIRECT parameter and is currently set 1331to 3 FITS blocks = 8640 bytes. This is the most efficient way to read 1332or write large chunks of data. Note that this fast direct IO process is not 1333applicable when accessing columns of data in a FITS table because the 1334bytes are generally not contiguous since they are interleaved by the 1335other columns of data in the table. This explains why the speed for 1336accessing FITS tables is generally slower than accessing 1337FITS images. 1338 1339Given this background information, the general strategy for efficiently 1340accessing FITS files should now be apparent: when dealing with FITS 1341images, read or write large chunks of data at a time so that the direct 1342IO mechanism will be invoked; when accessing FITS headers or FITS 1343tables, on the other hand, once a particular FITS block has been 1344loading into one of the IO buffers, try to access all the needed 1345information in that block before it gets flushed out of the IO buffer. 1346It is important to avoid the situation where the same FITS block is 1347being read then flushed from a IO buffer multiple times. 1348 1349The following section gives more specific suggestions for optimizing 1350the use of CFITSIO. 1351 1352 1353\subsection{Optimization Strategies} 1354 13551. Because the data in FITS files is always stored in "big-endian" byte order, 1356where the first byte of numeric values contains the most significant bits and the 1357last byte contains the least significant bits, CFITSIO must swap the order of the bytes 1358when reading or writing FITS files when running on little-endian machines (e.g., 1359Linux and Microsoft Windows operating systems running on PCs with x86 CPUs). 1360 1361On fairly new CPUs that support "SSSE3" machine instructions 1362(e.g., starting with Intel Core 2 CPUs in 2007, and in AMD CPUs 1363beginning in 2011) significantly faster 4-byte and 8-byte swapping 1364algorithms are available. These faster byte swapping functions are 1365not used by default in CFITSIO (because of the potential code 1366portablility issues), but users can enable them on supported 1367platforms by adding the appropriate compiler flags (-mssse3 with gcc 1368or icc on linux) when compiling the swapproc.c source file, which will 1369allow the compiler to generate code using the SSSE3 instruction set. 1370A convenient way to do this is to configure the CFITSIO library 1371with the following command: 1372 1373\begin{verbatim} 1374 > ./configure --enable-ssse3 1375\end{verbatim} 1376Note, however, that a binary executable file that is 1377created using these faster functions will only run on 1378machines that support the SSSE3 machine instructions. It will 1379crash on machines that do not support them. 1380 1381For faster 2-byte swaps on virtually all x86-64 CPUs (even those that 1382do not support SSSE3), a variant using only SSE2 instructions exists. 1383SSE2 is enabled by default on x86\_64 CPUs with 64-bit operating systems 1384(and is also automatically enabled by the --enable-ssse3 flag). 1385When running on x86\_64 CPUs with 32-bit operating systems, these faster 13862-byte swapping algorithms are not used by default in CFITSIO, but can be 1387enabled explicitly with: 1388 1389\begin{verbatim} 1390./configure --enable-sse2 1391\end{verbatim} 1392Preliminary testing indicates that these SSSE3 and SSE2 based 1393byte-swapping algorithms can boost the CFITSIO performance when 1394reading or writing FITS images by 20\% - 30\% or more. 1395It is important to note, however, that compiler optimization must be 1396turned on (e.g., by using the -O1 or -O2 flags in gcc) when building 1397programs that use these fast byte-swapping algorithms in order 1398to reap the full benefit of the SSSE3 and SSE2 instructions; without 1399optimization, the code may actually run slower than when using 1400more traditional byte-swapping techniques. 1401 14022. When dealing with a FITS primary array or IMAGE extension, it is 1403more 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 1405will be used as described in the previous section. Smaller chunks of 1406data are read or written via the IO buffers, which is somewhat less 1407efficient because of the extra copy operation and additional 1408bookkeeping steps that are required. In principle it is more efficient 1409to read or write as big an array of image pixels at one time as 1410possible, however, if the array becomes so large that the operating 1411system cannot store it all in RAM, then the performance may be degraded 1412because of the increased swapping of virtual memory to disk. 1413 14143. When dealing with FITS tables, the most important efficiency factor 1415in the software design is to read or write the data in the FITS file in 1416a single pass through the file. An example of poor program design 1417would be to read a large, 3-column table by sequentially reading the 1418entire first column, then going back to read the 2nd column, and 1419finally the 3rd column; this obviously requires 3 passes through the 1420file which could triple the execution time of an I/O limited program. 1421For small tables this is not important, but when reading multi-megabyte 1422sized tables these inefficiencies can become significant. The more 1423efficient procedure in this case is to read or write only as many rows 1424of the table as will fit into the available internal I/O buffers, then 1425access all the necessary columns of data within that range of rows. 1426Then after the program is completely finished with the data in those 1427rows it can move on to the next range of rows that will fit in the 1428buffers, continuing in this way until the entire file has been 1429processed. By using this procedure of accessing all the columns of a 1430table in parallel rather than sequentially, each block of the FITS file 1431will only be read or written once. 1432 1433The optimal number of rows to read or write at one time in a given 1434table depends on the width of the table row, on the number of I/O 1435buffers that have been allocated in FITSIO, and also on the number of 1436other FITS files that are open at the same time (since one I/O buffer 1437is always reserved for each open FITS file). Fortunately, a FITSIO 1438routine is available that will return the optimal number of rows for a 1439given table: call ftgrsz(unit, nrows, status). It is not critical to 1440use exactly the value of nrows returned by this routine, as long as one 1441does not exceed it. Using a very small value however can also lead to 1442poor performance because of the overhead from the larger number of 1443subroutine calls. 1444 1445The optimal number of rows returned by ftgrsz is valid only as long as 1446the application program is only reading or writing data in the 1447specified table. Any other calls to access data in the table header 1448would cause additional blocks of data to be 1449loaded into the I/O buffers displacing data from the original table, 1450and should be avoided during the critical period while the table is 1451being read or written. 1452 14534. Use binary table extensions rather than ASCII table 1454extensions for better efficiency when dealing with tabular data. The 1455I/O to ASCII tables is slower because of the overhead in formatting or 1456parsing the ASCII data fields, and because ASCII tables are about twice 1457as large as binary tables with the same information content. 1458 14595. Design software so that it reads the FITS header keywords in the 1460same order in which they occur in the file. When reading keywords, 1461FITSIO searches forward starting from the position of the last keyword 1462that was read. If it reaches the end of the header without finding the 1463keyword, it then goes back to the start of the header and continues the 1464search down to the position where it started. In practice, as long as 1465the entire FITS header can fit at one time in the available internal I/O 1466buffers, then the header keyword access will be very fast and it makes 1467little difference which order they are accessed. 1468 14696. Avoid the use of scaling (by using the BSCALE and BZERO or TSCAL and 1470TZERO keywords) in FITS files since the scaling operations add to the 1471processing time needed to read or write the data. In some cases it may 1472be more efficient to temporarily turn off the scaling (using ftpscl or 1473fttscl) and then read or write the raw unscaled values in the FITS 1474file. 1475 14767. Avoid using the 'implicit datatype conversion' capability in 1477FITSIO. For instance, when reading a FITS image with BITPIX = -32 1478(32-bit floating point pixels), read the data into a single precision 1479floating point data array in the program. Forcing FITSIO to convert 1480the data to a different datatype can significantly slow the program. 1481 14828. Where feasible, design FITS binary tables using vector column 1483elements so that the data are written as a contiguous set of bytes, 1484rather than as single elements in multiple rows. For example, it is 1485faster to access the data in a table that contains a single row 1486and 2 columns with TFORM keywords equal to '10000E' and '10000J', than 1487it is to access the same amount of data in a table with 10000 rows 1488which has columns with the TFORM keywords equal to '1E' and '1J'. In 1489the former case the 10000 floating point values in the first column are 1490all written in a contiguous block of the file which can be read or 1491written quickly, whereas in the second case each floating point value 1492in the first column is interleaved with the integer value in the second 1493column of the same row so CFITSIO has to explicitly move to the 1494position of each element to be read or written. 1495 14969. Avoid the use of variable length vector columns in binary tables, 1497since any reading or writing of these data requires that CFITSIO first 1498look up or compute the starting address of each row of data in the 1499heap. In practice, this is probably not a significant efficiency issue. 1500 150110. When copying data from one FITS table to another, it is faster to 1502transfer the raw bytes instead of reading then writing each column of 1503the table. The FITSIO subroutines FTGTBS and FTPTBS (for ASCII 1504tables), and FTGTBB and FTPTBB (for binary tables) will perform 1505low-level reads or writes of any contiguous range of bytes in a table 1506extension. These routines can be used to read or write a whole row (or 1507multiple rows) of a table with a single subroutine call. These 1508routines are fast because they bypass all the usual data scaling, error 1509checking and machine dependent data conversion that is normally done by 1510FITSIO, and they allow the program to write the data to the output file 1511in exactly the same byte order. For these same reasons, use of these 1512routines can be somewhat risky because no validation or machine 1513dependent conversion is performed by these routines. In general these 1514routines are only recommended for optimizing critical pieces of code 1515and should only be used by programmers who thoroughly understand the 1516internal byte structure of the FITS tables they are reading or 1517writing. 1518 151911. Another strategy for improving the speed of writing a FITS table, 1520similar to the previous one, is to directly construct the entire byte 1521stream for a whole table row (or multiple rows) within the application 1522program and then write it to the FITS file with 1523ftptbb. This avoids all the overhead normally present 1524in the column-oriented CFITSIO write routines. This technique should 1525only be used for critical applications, because it makes the code more 1526difficult to understand and maintain, and it makes the code more system 1527dependent (e.g., do the bytes need to be swapped before writing to the 1528FITS file?). 1529 153012. Finally, external factors such as the type of magnetic disk 1531controller (SCSI or IDE), the size of the disk cache, the average seek 1532speed of the disk, the amount of disk fragmentation, and the amount of 1533RAM available on the system can all have a significant impact on 1534overall I/O efficiency. For critical applications, a system 1535administrator should review the proposed system hardware to identify any 1536potential I/O bottlenecks. 1537 1538 1539 1540\chapter{ Basic Interface Routines } 1541 1542This section defines a basic set of subroutines that can be 1543used to perform the most common types of read and write operations 1544on FITS files. New users should start with these subroutines and 1545then, as needed, explore the more advance routines described in 1546the following chapter to perform more complex or specialized operations. 1547 1548A right arrow symbol ($>$) is used to separate the input parameters from 1549the output parameters in the definition of each routine. This symbol 1550is not actually part of the calling sequence. Note that 1551the status parameter is both an input and an output parameter 1552and must be initialized = 0 prior to calling the FITSIO subroutines. 1553 1554Refer to Chapter 9 for the definition of all the parameters 1555used 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 1839The following routines read or write data values in the current HDU of 1840the FITS file. Automatic datatype conversion 1841will be attempted for numerical datatypes if the specified datatype is 1842different 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 1926This chapter defines all the available subroutines in the FITSIO user 1927interface. For completeness, the basic subroutines described in the 1928previous chapter are also repeated here. A right arrow symbol is used 1929here to separate the input parameters from the output parameters in the 1930definition of each subroutine. This symbol is not actually part of the 1931calling sequence. An alphabetical list and definition of all the 1932parameters 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 1940FTDKOPN routine simply opens the specified file without trying to 1941interpret the filename using the extended filename syntax. FTDOPN opens 1942the file and 1943also moves to the first HDU containing significant data, if no specific 1944HDU is specified as part of the filename. FTTOPN and FTIOPN are similar 1945except that they will move to the first table HDU or image HDU, respectively, 1946if 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 2074pointer value, or vice versa. These 2 C routines may be useful in 2075mixed language programs where both C and Fortran subroutines need 2076to access the same file. For example, if a FITS file is opened 2077with unit 12 by a Fortran subroutine, then a C routine within the 2078same program could get the fitfile pointer value to access the same file 2079by calling 'fptr = CUnit2FITS(12)'. These routines return a value 2080of 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 2091moved to if the file were opened with FTNOPN. The returned HDU 2092number begins with 1 for the primary array, so for example, if the 2093input filename = `myfile.fits[2]' then hdunum = 3 will be returned. 2094FITSIO does not open the file to check if the extension actually exists 2095if an extension number is specified. If an extension *name* is included 2096in the file name specification (e.g. `myfile.fits[EVENTS]' then this 2097routine will have to open the FITS file and look for the position of 2098the named extension, then close file again. This is not possible if 2099the file is being read from the stdin stream, and an error will be 2100returned in this case. If the filename does not specify an explicit 2101extension (e.g. 'myfile.fits') then hdunum = -99 will be returned, 2102which is functionally equivalent to hdunum = 1. This routine is mainly 2103used for backward compatibility in the ftools software package and is 2104not recommended for general use. It is generally better and more 2105efficient to first open the FITS file with FTNOPN, then use FTGHDN to 2106determine 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 2141type (file://, ftp://, http://, etc), the base input file name, the 2142name of the output file that the input file is to be copied to prior 2143to opening, the HDU or extension specification, the filtering 2144specifier, the binning specifier, and the column specifier. Blank 2145strings will be returned for any components that are not present 2146in 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 2156name includes the file type if specified, (e.g. 'ftp://' or 'http://') 2157and the full path name, to the extent that it is specified in the input 2158filename. It does not include the HDU name or number, or any filtering 2159specifications. 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 2169a .gz, .Z, .z, or .zip extension) exists on disk. The returned value of 2170the '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 2188When a FITS file is first opened or created, the internal buffers in 2189FITSIO automatically point to the first HDU in the file. The following 2190routines may be used to move to another HDU in the file. Note that 2191the HDU numbering convention used in FITSIO denotes the primary array 2192as the first HDU, the first extension in a FITS file is the second HDU, 2193and 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 2430It should rarely be necessary to call the subroutines in this section. 2431FITSIO internally calls these routines whenever necessary, so any calls 2432to 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 2564These subroutines provide a simple method of reading or writing most of 2565the keyword values that are normally required in a FITS files. These 2566subroutines are provided for convenience only and are not required to 2567be used. If preferred, users may call the lower-level subroutines 2568described in the previous section to individually read or write the 2569required keywords. Note that in most cases, the required keywords such 2570as NAXIS, TFIELD, TTYPEn, etc, which define the structure of the HDU 2571must be written to the header before any data can be written to the 2572image or table. 2573 2574 2575\begin{description} 2576\item[1 ] Put the primary header or IMAGE extension keywords into the CHU. 2577There are 2 available routines: The simpler FTPHPS routine is 2578equivalent to calling ftphpr with the default values of SIMPLE = true, 2579pcount = 0, gcount = 1, and EXTEND = true. PCOUNT, GCOUNT and EXTEND 2580keywords are not required in the primary header and are only written if 2581pcount is not equal to zero, gcount is not equal to zero or one, and if 2582extend is TRUE, respectively. When writing to an IMAGE extension, the 2583SIMPLE 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 2605TUNITn and EXTNAME keywords are written only if the input string 2606values 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 2856These routines return the value of the specified keyword(s). Wild card 2857characters (*, ?, or \#) may be used when specifying the name of the keyword 2858to be read: a '?' will match any single character at that position in the 2859keyword name and a '*' will match any length (including zero) string of 2860characters. The '\#' character will match any consecutive string of 2861decimal digits (0 - 9). Note that when a wild card is used in the input 2862keyword name, the routine will only search for a match from the current 2863header position to the end of the header. It will not resume the search 2864from the top of the header back to the original header position as is done 2865when no wildcards are included in the keyword name. If the desired 2866keyword string is 8-characters long (the maximum length of a keyword 2867name) then a '*' may be appended as the ninth character of the input 2868name 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 2870ffgrec routine may be used to set the starting position when doing 2871wild 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 3001Wild card characters, as described in the Read Keyword section, above, 3002may 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 3140These subroutines define or modify the internal parameters used by 3141FITSIO to either scale the data or to represent undefined pixels. 3142Generally FITSIO will scale the data according to the values of the BSCALE 3143and BZERO (or TSCALn and TZEROn) keywords, however these subroutines 3144may be used to override the keyword values. This may be useful when 3145one wants to read or write the raw unscaled values in the FITS file. 3146Similarly, FITSIO generally uses the value of the BLANK or TNULLn 3147keyword to signify an undefined pixel, but these routines may be used 3148to override this value. These subroutines do not create or modify the 3149corresponding 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 3223data array is represented as a single one-dimensional array of 3224pixels regardless of the actual dimensionality of the array, and the 3225FPIXEL parameter gives the position within this 1-D array of the first 3226pixel to read or write. Automatic data type conversion is performed 3227for numeric data (except for complex data types) if the data type of 3228the primary array (defined by the BITPIX keyword) differs from the data 3229type of the array in the calling subroutine. The data values are also 3230scaled by the BSCALE and BZERO header values as they are being written 3231or read from the FITS array. The ftpscl subroutine MUST be 3232called to define the scaling parameters when writing data to the FITS 3233array or to override the default scaling value given in the header when 3234reading the FITS array. 3235 3236 Two sets of subroutines are provided to read the data array which 3237differ in the way undefined pixels are handled. The first set of 3238routines (FTGPVx) simply return an array of data elements in which 3239undefined pixels are set equal to a value specified by the user in the 3240'nullval' parameter. An additional feature of these subroutines is 3241that if the user sets nullval = 0, then no checks for undefined pixels 3242will be performed, thus increasing the speed of the program. The 3243second set of routines (FTGPFx) returns the data element array and, in 3244addition, a logical array which defines whether the corresponding data 3245pixel is undefined. The latter set of subroutines may be more 3246convenient to use in some circumstances, however, it requires an 3247additional array of logical values which can be unwieldy when working 3248with large data arrays. Also for programmer convenience, sets of 3249subroutines to directly read or write 2 and 3 dimensional arrays have 3250been provided, as well as a set of subroutines to read or write any 3251contiguous 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} 3373The following 4 subroutines transfer FITS images with 2 or 3 dimensions 3374to or from a data array which has been declared in the calling program. 3375The dimensionality of the FITS image is passed by the naxis1, naxis2, 3376and naxis3 parameters and the declared dimensions of the program array 3377are passed in the dim1 and dim2 parameters. Note that the program array 3378does not have to have the same dimensions as the FITS array, but must 3379be at least as big. For example if a FITS image with NAXIS1 = NAXIS2 = 400 3380is read into a program array which is dimensioned as 512 x 512 pixels, 3381then the image will just fill the lower left corner of the array 3382with pixels in the range 1 - 400 in the X an Y directions. This has 3383the effect of taking a contiguous set of pixel value in the FITS array 3384and 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 3386in 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 3428The following subroutines transfer a rectangular subset of the pixels 3429in a FITS N-dimensional image to or from an array which has been 3430declared in the calling program. The fpixels and lpixels parameters 3431are integer arrays which specify the starting and ending pixels in each 3432dimension of the FITS image that are to be read or written. (Note that 3433these are the starting and ending pixels in the FITS image, not in the 3434declared array). The array parameter is treated simply as a large 3435one-dimensional array of the appropriate datatype containing the pixel 3436values; The pixel values in the FITS array are read/written from/to 3437this program array in strict sequence without any gaps; it is up to 3438the calling routine to correctly interpret the dimensionality of this 3439array. The two families of FITS reading routines (FTGSVx and FTGSFx 3440subroutines) also have an 'incs' parameter which defines the 3441data sampling interval in each dimension of the FITS array. For 3442example, if incs(1)=2 and incs(2)=3 when reading a 2-dimensional 3443FITS image, then only every other pixel in the first dimension 3444and every 3rd pixel in the second dimension will be returned in 3445the 'array' parameter. [Note: the FTGSSx family of routines which 3446were present in previous versions of FITSIO have been superseded 3447by 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 3505matches an input template name. The table column names are defined by 3506the TTYPEn keywords in the FITS header. If a column does not have a 3507TTYPEn keyword, then these routines assume that the name consists of 3508all blank characters. These 2 subroutines perform the same function 3509except that FTGCNO only returns the number of the matching column whereas 3510FTGCNN also returns the name of the column. If CASESEN = .true. then 3511the column name match will be case-sensitive. 3512 3513The input column name template (COLTEMPLATE) is (1) either the exact 3514name of the column to be searched for, or (2) it may contain wild cards 3515characters (*, ?, or \#), or (3) it may contain the number of the desired 3516column (where the number is expressed as ASCII digits). The first 2 wild 3517cards behave similarly to UNIX filename matching: the '*' character matches 3518any sequence of characters (including zero characters) and the '?' 3519character matches any single character. The \# wildcard will match 3520any consecutive string of decimal digits (0-9). As an example, the template 3521strings '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 3523template string, then the first match is returned and the status value 3524will be set to 237 as a warning that a unique match was not found. To 3525find the other cases that match the template, simply call the 3526subroutine again leaving the input status value equal to 237 and the 3527next matching name will then be returned. Repeat this process until a 3528status = 219 (column name not found) is returned. If these subroutines 3529fail to match the template to any of the columns in the table, they 3530lastly check if the template can be interpreted as a simple positive 3531integer (e.g., '7', or '512') and if so, they return that column 3532number. If no matches are found then a status = 219 error is 3533returned. 3534 3535Note that the FITS Standard recommends that only letters, digits, and 3536the underscore character be used in column names (with no embedded 3537spaces 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 3668The following subroutines provide low-level access to the data in ASCII 3669or binary tables and are mainly useful as an efficient way to copy all 3670or part of a table from one location to another. These routines simply 3671read or write the specified number of consecutive bytes in an ASCII or 3672binary table, without regard for column boundaries or the row length in 3673the table. The first two subroutines read or write consecutive bytes 3674in a table to or from a character string variable, while the last two 3675subroutines read or write consecutive bytes to or from a variable 3676declared as a numeric data type (e.g., INTEGER, INTEGER*2, REAL, DOUBLE 3677PRECISION). These routines do not perform any machine dependent data 3678conversion or byte swapping, except that conversion to/from ASCII 3679format is performed by the FTGTBS and FTPTBS routines on machines which 3680do 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 3835These subroutines put or get data values in the current ASCII or Binary table 3836extension. Automatic data type conversion is performed for numerical data 3837types (B,I,J,E,D) if the data type of the column (defined by the TFORM keyword) 3838differs from the data type of the calling subroutine. The data values are also 3839scaled by the TSCALn and TZEROn header values as they are being written to 3840or read from the FITS array. The fttscl subroutine MUST be used to define the 3841scaling parameters when writing data to the table or to override the default 3842scaling values given in the header when reading from the table. 3843Note that it is *not* necessary to insert rows in a table before 3844writing data to those rows (indeed, it would be inefficient to do so). 3845Instead, one may simply write data to any row of the table, whether that 3846row of data already exists or not. 3847 3848 In the case of binary tables with vector elements, the 'felem' 3849parameter defines the starting pixel within the element vector. This 3850parameter is ignored with ASCII tables. Similarly, in the case of 3851binary tables the 'nelements' parameter specifies the total number of 3852vector values read or written (continuing on subsequent rows if 3853required) and not the number of table elements. Two sets of 3854subroutines are provided to get the column data which differ in the way 3855undefined pixels are handled. The first set of routines (FTGCV) 3856simply return an array of data elements in which undefined pixels are 3857set equal to a value specified by the user in the 'nullval' parameter. 3858An additional feature of these subroutines is that if the user sets 3859nullval = 0, then no checks for undefined pixels will be performed, 3860thus increasing the speed of the program. The second set of routines 3861(FTGCF) returns the data element array and in addition a logical array 3862of 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 4106These routines all parse and evaluate an input string containing a user 4107defined arithmetic expression. The first 3 routines select rows in a 4108FITS table, based on whether the expression evaluates to true (not 4109equal to zero) or false (zero). The other routines evaluate the 4110expression and calculate a value for each row of the table. The 4111allowed expression syntax is described in the row filter section in the 4112earlier `Extended File Name Syntax' chapter of this document. The 4113expression may also be written to a text file, and the name of the 4114file, prepended with a '@' character may be supplied for the 'expr' 4115parameter (e.g. '@filename.txt'). The expression in the file can 4116be arbitrarily complex and extend over multiple lines of the file. 4117Lines that begin with 2 slash characters ('//') will be ignored and 4118may 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 4140files are not the same, copy the TRUE rows to the output file; if the output 4141table is not empty, then this routine will append the new 4142selected rows after the existing rows. If the 4143files 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 4152the results, cast as datatype (TSHORT, TDOUBLE, etc), in array. If 4153nulval==NULL, UNDEFs will be zeroed out. For vector results, the number 4154of elements returned may be less than nelements if nelements is not an 4155even multiple of the result dimension. Call FTTEXP to obtain 4156the 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 4166the expression is a function of other columns in the table) or to a 4167keyword (if the expression evaluates to a constant and is not a 4168function of other columns in the table). In the former case, the 4169parName parameter is the name of the column (which may or may not already 4170exist) into which to write the results, and parInfo contains an 4171optional TFORM keyword value if a new column is being created. If a 4172TFORM value is not specified then a default format will be used, 4173depending on the expression. If the expression evaluates to a constant, 4174then the result will be written to the keyword name given by the 4175parName parameter, and the parInfo parameter may be used to supply an 4176optional comment for the keyword. If the keyword does not already 4177exist, then the name of the keyword must be preceded with a '\#' character, 4178otherwise 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 4188that the expression is only evaluated over the specified 4189row ranges. nranges specifies the number of row ranges, and firstrow 4190and 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 4200on the result. The returned dimensions correspond to a single row entry 4201of the requested expression, and are equivalent to the result of fits\_read\_tdim(). 4202Note that strings are considered to be one element regardless of string length. 4203If 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 4214The FITS community has adopted a set of keyword conventions that define 4215the transformations needed to convert between pixel locations in an 4216image and the corresponding celestial coordinates on the sky, or more 4217generally, that define world coordinates that are to be associated with 4218any pixel location in an n-dimensional FITS array. CFITSIO is distributed 4219with a couple of self-contained World Coordinate System (WCS) routines, 4220however, these routines DO NOT support all the latest WCS conventions, 4221so it is STRONGLY RECOMMENDED that software developers use a more robust 4222external 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 4230More information about the WCS keyword conventions and links to all of 4231these WCS libraries can be found on the FITS Support Office web site at 4232http://fits.gsfc.nasa.gov under the WCS link. 4233 4234The functions provided in these external WCS libraries will need access to 4235the WCS information contained in the FITS file headers. One convenient 4236way to pass this information to the external library is to use FITSIO 4237to copy the header keywords into one long character string, and then 4238pass this string to an interface routine in the external library that 4239will extract the necessary WCS information (e.g., see the astFitsChan 4240and astPutCards routines in the Starlink AST library). 4241 4242The following FITSIO routines DO NOT support the more recent WCS conventions 4243that have been approved as part of the FITS standard. Consequently, 4244the following routines ARE NOW DEPRECATED. It is STRONGLY RECOMMENDED 4245that software developers not use these routines, and instead use an 4246external WCS library, as described above. 4247 4248These routines are included mainly for backward compatibility with 4249existing software. They support the following standard map 4250projections: -SIN, -TAN, -ARC, -NCP, -GLS, -MER, and -AIT (these are the 4251legal values for the coordtype parameter). These routines are based 4252on similar functions in Classic AIPS. All the angular quantities are 4253given 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 4321The following routines either compute or validate the checksums for the 4322CHDU. The DATASUM keyword is used to store the numerical value of the 432332-bit, 1's complement checksum for the data unit alone. If there is 4324no data unit then the value is set to zero. The numerical value is 4325stored as an ASCII string of digits, enclosed in quotes, because the 4326value may be too large to represent as a 32-bit signed integer. The 4327CHECKSUM keyword is used to store the ASCII encoded COMPLEMENT of the 4328checksum for the entire HDU. Storing the complement, rather than the 4329actual checksum, forces the checksum for the whole HDU to equal zero. 4330If the file has been modified since the checksums were computed, then 4331the HDU checksum will usually not equal zero. These checksum keyword 4332conventions are based on a paper by Rob Seaman published in the 4333proceedings of the ADASS IV conference in Baltimore in November 1994 4334and 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 4414The following routines help to construct or parse the FITS date/time 4415strings. Starting in the year 2000, the FITS DATE keyword values (and 4416the 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 4418number of decimal places in the seconds value is optional. These times 4419are in UTC. The older 'dd/mm/yy' date format may not be used for dates 4420after 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'). 4435The time will be in UTC/GMT if available, as indicated by a returned timeref 4436value = 0. If the returned value of timeref = 1 then this indicates that 4437it was not possible to convert the local time to UTC, and thus the local 4438time 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 4448is between 1900 and 1998, inclusive, then the returned date string will 4449have the old FITS format ('dd/mm/yy'), otherwise the date string will 4450have 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 4475in 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 4486string may be in either the old or new FITS format. The returned hours, 4487minutes, and seconds values will be set to zero if the input string 4488does not include the time ('dd/mm/yy' or 'YYYY-MM-DD') . Similarly, 4489the returned year, month, and date values will be set to zero if the 4490date 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 4500The 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 4873The fits\_iterate\_data function in CFITSIO provides a unique method of 4874executing an arbitrary user-supplied `work' function that operates on 4875rows of data in FITS tables or on pixels in FITS images. Rather than 4876explicitly reading and writing the FITS images or columns of data, one 4877instead calls the CFITSIO iterator routine, passing to it the name of 4878the user's work function that is to be executed along with a list of 4879all the table columns or image arrays that are to be passed to the work 4880function. The CFITSIO iterator function then does all the work of 4881allocating memory for the arrays, reading the input data from the FITS 4882file, passing them to the work function, and then writing any output 4883data back to the FITS file after the work function exits. Because 4884it is often more efficient to process only a subset of the total table 4885rows at one time, the iterator function can determine the optimum 4886amount of data to pass in each iteration and repeatedly call the work 4887function until the entire table been processed. 4888 4889For many applications this single CFITSIO iterator function can 4890effectively replace all the other CFITSIO routines for reading or 4891writing data in FITS images or tables. Using the iterator has several 4892important advantages over the traditional method of reading and writing 4893FITS data files: 4894 4895\begin{itemize} 4896\item 4897It cleanly separates the data I/O from the routine that operates on 4898the data. This leads to a more modular and `object oriented' 4899programming style. 4900 4901\item 4902It simplifies the application program by eliminating the need to allocate 4903memory for the data arrays and eliminates most of the calls to the CFITSIO 4904routines that explicitly read and write the data. 4905 4906\item 4907It ensures that the data are processed as efficiently as possible. 4908This is especially important when processing tabular data since 4909the iterator function will calculate the most efficient number 4910of rows in the table to be passed at one time to the user's work 4911function on each iteration. 4912 4913\item 4914Makes it possible for larger projects to develop a library of work 4915functions that all have a uniform calling sequence and are all 4916independent of the details of the FITS file format. 4917 4918\end{itemize} 4919 4920There are basically 2 steps in using the CFITSIO iterator function. 4921The first step is to design the work function itself which must have a 4922prescribed set of input parameters. One of these parameters is a 4923structure containing pointers to the arrays of data; the work function 4924can perform any desired operations on these arrays and does not need to 4925worry about how the input data were read from the file or how the 4926output data get written back to the file. 4927 4928The second step is to design the driver routine that opens all the 4929necessary FITS files and initializes the input parameters to the 4930iterator function. The driver program calls the CFITSIO iterator 4931function which then reads the data and passes it to the user's work 4932function. 4933 4934Further details on using the iterator function can be found in the 4935companion CFITSIO User's Guide, and in the iter\_a.f, iter\_b.f and 4936iter\_c.f example programs. 4937 4938 4939 4940\chapter{ Extended File Name Syntax } 4941 4942 4943\section{Overview} 4944 4945CFITSIO supports an extended syntax when specifying the name of the 4946data file to be opened or created that includes the following 4947features: 4948 4949\begin{itemize} 4950\item 4951CFITSIO can read IRAF format images which have header file names that 4952end with the '.imh' extension, as well as reading and writing FITS 4953files, This feature is implemented in CFITSIO by first converting the 4954IRAF image into a temporary FITS format file in memory, then opening 4955the FITS file. Any of the usual CFITSIO routines then may be used to 4956read the image header or data. Similarly, raw binary data arrays can 4957be read by converting them on the fly into virtual FITS images. 4958 4959\item 4960FITS files on the Internet can be read (and sometimes written) using the FTP, 4961HTTP, or ROOT protocols. 4962 4963\item 4964FITS files can be piped between tasks on the stdin and stdout streams. 4965 4966\item 4967FITS files can be read and written in shared memory. This can potentially 4968achieve much better data I/O performance compared to reading and 4969writing the same FITS files on magnetic disk. 4970 4971\item 4972Compressed FITS files in gzip or Unix COMPRESS format can be directly read. 4973 4974\item 4975Output FITS files can be written directly in compressed gzip format, 4976thus saving disk space. 4977 4978\item 4979FITS table columns can be created, modified, or deleted 'on-the-fly' as 4980the table is opened by CFITSIO. This creates a virtual FITS file containing 4981the modifications that is then opened by the application program. 4982 4983\item 4984Table rows may be selected, or filtered out, on the fly when the table 4985is opened by CFITSIO, based on an arbitrary user-specified expression. 4986Only rows for which the expression evaluates to 'TRUE' are retained 4987in the copy of the table that is opened by the application program. 4988 4989\item 4990Histogram images may be created on the fly by binning the values in 4991table columns, resulting in a virtual N-dimensional FITS image. The 4992application program then only sees the FITS image (in the primary 4993array) instead of the original FITS table. 4994\end{itemize} 4995 4996The latter 3 features in particular add very powerful data processing 4997capabilities directly into CFITSIO, and hence into every task that uses 4998CFITSIO to read or write FITS files. For example, these features 4999transform a very simple program that just copies an input FITS file to 5000a new output file (like the `fitscopy' program that is distributed with 5001CFITSIO) into a multipurpose FITS file processing tool. By appending 5002fairly simple qualifiers onto the name of the input FITS file, the user 5003can perform quite complex table editing operations (e.g., create new 5004columns, or filter out rows in a table) or create FITS images by 5005binning or histogramming the values in table columns. In addition, 5006these functions have been coded using new state-of-the art algorithms 5007that are, in some cases, 10 - 100 times faster than previous widely 5008used implementations. 5009 5010Before describing the complete syntax for the extended FITS file names 5011in the next section, here are a few examples of FITS file names that 5012give 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 5017directory. 5018 5019\item 5020{\tt 'myfile.imh'}: opens an IRAF format image file and converts it on the 5021fly into a temporary FITS format image in memory which can then be read with 5022any other CFITSIO routine. 5023 5024\item 5025{\tt rawfile.dat[i512,512]}: opens a raw binary data array (a 512 x 512 5026short integer array in this case) and converts it on the fly into a 5027temporary FITS format image in memory which can then be read with any 5028other CFITSIO routine. 5029 5030\item 5031{\tt myfile.fits.gz}: if this is the name of a new output file, the '.gz' 5032suffix will cause it to be compressed in gzip format when it is written to 5033disk. 5034 5035\item 5036{\tt 'myfile.fits.gz[events, 2]'}: opens and uncompresses the gzipped file 5037myfile.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 5042from the stdin file stream, or that the output file is to be written to 5043the stdout stream. 5044 5045\item 5046{\tt 'ftp://legacy.gsfc.nasa.gov/test/vela.fits'}: FITS files in any ftp 5047archive site on the Internet may be directly opened with read-only 5048access. 5049 5050\item 5051{\tt 'http://legacy.gsfc.nasa.gov/software/test.fits'}: any valid URL to a 5052FITS 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 5056except that it provides write as well as read access to the files 5057across 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 5061moves to the EVENTS extension. 5062 5063\item 5064{\tt 'mem://'}: creates a scratch output file in core computer memory. The 5065resulting 'file' will disappear when the program exits, so this 5066is mainly useful for testing purposes when one does not want a 5067permanent copy of the output file. 5068 5069\item 5070{\tt 'myfile.fits[3; Images(10)]'}: opens a copy of the image contained in the 507110th row of the 'Images' column in the binary table in the 3th extension 5072of the FITS file. The application just sees this single image as the 5073primary array. 5074 5075\item 5076{\tt 'myfile.fits[1:512:2, 1:512:2]'}: opens a section of the input image 5077ranging from the 1st to the 512th pixel in X and Y, and selects every 5078second pixel in both dimensions, resulting in a 256 x 256 pixel image 5079in this case. 5080 5081\item 5082{\tt 'myfile.fits[EVENTS][col Rad = sqrt(X**2 + Y**2)]'}: creates and opens 5083a temporary file on the fly (in memory or on disk) that is identical to 5084myfile.fits except that it will contain a new column in the EVENTS 5085extension called 'Rad' whose value is computed using the indicated 5086expression 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 5090files that is identical to 'myfile.fits' except that the EVENTS table 5091will only contain the rows that have values of the PHA column greater 5092than 5. In general, any arbitrary boolean expression using a C or 5093Fortran-like syntax, which may combine AND and OR operators, 5094may 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 5098primary array image which is computed on the fly by binning (i.e, 5099computing the 2-dimensional histogram) of the values in the X and Y 5100columns of the EVENTS extension. In this case the X and Y coordinates 5101range from 1 to 2048 and the image pixel size is 4 units in both 5102dimensions, so the resulting image is 512 x 512 pixels in size. 5103 5104\item 5105The final example combines many of these feature into one complex 5106expression (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} 5113In this case, CFITSIO (1) copies and uncompresses the FITS file from 5114the ftp site on the legacy machine, (2) moves to the 'EVENTS' 5115extension, (3) calculates a new column called 'phacorr', (4) selects 5116the rows in the table that have phacorr in the range 5 to 14, and 5117finally (5) bins the remaining rows on the X and Y column coordinates, 5118using a pixel size = 32 to create a 2D image. All this processing is 5119completely transparent to the application program, which simply sees 5120the final 2-D image in the primary array of the opened file. 5121\end{itemize} 5122 5123The full extended CFITSIO FITS file name can contain several different 5124components depending on the context. These components are described in 5125the following sections: 5126 5127\begin{verbatim} 5128When creating a new file: 5129 filetype://BaseFilename(templateName) 5130 5131When opening an existing primary array or image HDU: 5132 filetype://BaseFilename(outName)[HDUlocation][ImageSection] 5133 5134When opening an existing table HDU: 5135 filetype://BaseFilename(outName)[HDUlocation][colFilter][rowFilter][binSpec] 5136\end{verbatim} 5137The filetype, BaseFilename, outName, HDUlocation, and ImageSection 5138components, if present, must be given in that order, but the colFilter, 5139rowFilter, and binSpec specifiers may follow in any order. Regardless 5140of the order, however, the colFilter specifier, if present, will be 5141processed first by CFITSIO, followed by the rowFilter specifier, and 5142finally by the binSpec specifier. 5143 5144 5145Multiple colFilter or rowFilter specifications may appear as separated 5146bracketed expressions, in any order. Multiple colFilter or rowFilter 5147expressions are treated internally as a single effective expression, 5148with order of operations determined from left to right. CFITSIO does 5149not support the @filename.txt complex syntax option if multiple 5150expressions are also used. 5151 5152\section{Filetype} 5153 5154The 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 5156CFITSIO 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} 5182If the filetype is not specified, then type file:// is assumed. 5183The double slashes '//' are optional and may be omitted in most cases. 5184 5185 5186\subsection{Notes about HTTP proxy servers} 5187 5188A proxy HTTP server may be used by defining the address (URL) and port 5189number of the proxy server with the http\_proxy environment variable. 5190For example 5191 5192\begin{verbatim} 5193 setenv http_proxy http://heasarc.gsfc.nasa.gov:3128 5194\end{verbatim} 5195will cause CFITSIO to use port 3128 on the heasarc proxy server whenever 5196reading a FITS file with HTTP. 5197 5198 5199\subsection{Notes about the stream filetype driver} 5200 5201The stream driver can be used to efficiently read a FITS file from the stdin 5202file stream or write a FITS to the stdout file stream. However, because these 5203input and output streams must be accessed sequentially, the FITS file reading or 5204writing application must also read and write the file sequentially, at least 5205within the tolerances described below. 5206 5207CFITSIO supports 2 different methods for accessing FITS files on the stdin and 5208stdout streams. The original method, which is invoked by specifying a dash 5209character, "-", as the name of the file when opening or creating it, works by 5210storing a complete copy of the entire FITS file in memory. In this case, when 5211reading from stdin, CFITSIO will copy the entire stream into memory before doing 5212any processing of the file. Similarly, when writing to stdout, CFITSIO will 5213create a copy of the entire FITS file in memory, before finally flushing it out 5214to the stdout stream when the FITS file is closed. Buffering the entire FITS 5215file in this way allows the application to randomly access any part of the FITS 5216file, in any order, but it also requires that the user have sufficient available 5217memory (or virtual memory) to store the entire file, which may not be possible 5218in the case of very large files. 5219 5220The newer stream filetype provides a more memory-efficient method of accessing 5221FITS files on the stdin or stdout streams. Instead of storing a copy of the 5222entire FITS file in memory, CFITSIO only uses a set of internal buffer which by 5223default can store 40 FITS blocks, or about 100K bytes of the FITS file. The 5224application program must process the FITS file sequentially from beginning to 5225end, within this 100K buffer. Generally speaking the application program must 5226conform to the following restrictions: 5227 5228\begin{itemize} 5229\item 5230The program must finish reading or writing the header keywords 5231before reading or writing any data in the HDU. 5232\item 5233The HDU can contain at most about 1400 header keywords. This is the 5234maximum that can fit in the nominal 40 FITS block buffer. In principle, 5235this limit could be increased by recompiling CFITSIO with a larger 5236buffer limit, which is set by the NIOBUF parameter in fitsio2.h. 5237\item 5238The program must read or write the data in a sequential manner from the 5239beginning to the end of the HDU. Note that CFITSIO's internal 5240100K buffer allows a little latitude in meeting this requirement. 5241\item 5242The program cannot move back to a previous HDU in the FITS file. 5243\item 5244Reading or writing of variable length array columns in binary tables is not 5245supported on streams, because this requires moving back and forth between the 5246fixed-length portion of the binary table and the following heap area where the 5247arrays are actually stored. 5248\item 5249Reading or writing of tile-compressed images is not supported on streams, 5250because the images are internally stored using variable length arrays. 5251\end{itemize} 5252 5253 5254\subsection{Notes about the gsiftp filetype} 5255 5256DEPENDENCIES: Globus toolkit (2.4.3 or higher) (GT) should be installed. 5257There are two different ways to install GT: 5258 52591) goto the globus toolkit web page www.globus.org and follow the 5260 download and compilation instructions; 5261 52622) goto the Virtual Data Toolkit web page http://vdt.cs.wisc.edu/ 5263 and follow the instructions (STRONGLY SUGGESTED); 5264 5265Once a globus client has been installed in your system with a specific flavour 5266it is possible to compile and install the CFITSIO libraries. 5267Specific configuration flags must be used: 5268 52691) --with-gsiftp[[=PATH]] Enable Globus Toolkit gsiftp protocol support 5270 PATH=GLOBUS\_LOCATION i.e. the location of your globus installation 5271 52722) --with-gsiftp-flavour[[=PATH] defines the specific Globus flavour 5273 ex. gcc32 5274 5275Both the flags must be used and it is mandatory to set both the PATH and the 5276flavour. 5277 5278USAGE: To access files on a gridftp server it is necessary to use a gsiftp prefix: 5279 5280example: gsiftp://remote\_server\_fqhn/directory/filename 5281 5282The gridftp driver uses a local buffer on a temporary file the file is located 5283in the /tmp directory. If you have special permissions on /tmp or you do not have a /tmp 5284directory, it is possible to force another location setting the GSIFTP\_TMPFILE environment 5285variable (ex. export GSIFTP\_TMPFILE=/your/location/yourtmpfile). 5286 5287Grid FTP supports multi channel transfer. By default a single channel transmission is 5288available. However, it is possible to modify this behavior setting the GSIFTP\_STREAMS 5289environment variable (ex. export GSIFTP\_STREAMS=8). 5290 5291 5292\subsection{Notes about the root filetype} 5293 5294The original rootd server can be obtained from: 5295\verb-ftp://root.cern.ch/root/rootd.tar.gz- 5296but, for it to work correctly with CFITSIO one has to use a modified 5297version which supports a command to return the length of the file. 5298This modified version is available in rootd subdirectory 5299in 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 5305This small server is started either by inetd when a client requests a 5306connection to a rootd server or by hand (i.e. from the command line). 5307The rootd server works with the ROOT TNetFile class. It allows remote 5308access to ROOT database files in either read or write mode. By default 5309TNetFile assumes port 432 (which requires rootd to be started as root). 5310To run rootd via inetd add the following line to /etc/services: 5311 5312\begin{verbatim} 5313 rootd 432/tcp 5314\end{verbatim} 5315and 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} 5320Force inetd to reread its conf file with "kill -HUP <pid inetd>". 5321You can also start rootd by hand running directly under your private 5322account (no root system privileges needed). For example to start 5323rootd listening on port 5151 just type: \verb+rootd -p 5151+ 5324Notice: 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} 5336Rootd can also be configured for anonymous usage (like anonymous ftp). 5337To setup rootd to accept anonymous logins do the following (while being 5338logged 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} 5368That's all. Several additional remarks: you can login to an anonymous 5369server either with the names "anonymous" or "rootd". The password should 5370be of type user@host.do.main. Only the @ is enforced for the time 5371being. In anonymous mode the top of the file tree is set to the rootd 5372home directory, therefore only files below the home directory can be 5373accessed. Anonymous mode only works when the server is started via 5374inetd. 5375 5376 5377\subsection{Notes about the shmem filetype:} 5378 5379Shared memory files are currently supported on most Unix platforms, 5380where the shared memory segments are managed by the operating system 5381kernel and `live' independently of processes. They are not deleted (by 5382default) when the process which created them terminates, although they 5383will disappear if the system is rebooted. Applications can create 5384shared memory files in CFITSIO by calling: 5385 5386\begin{verbatim} 5387 fit_create_file(&fitsfileptr, "shmem://h2", &status); 5388\end{verbatim} 5389where 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 5391SHARED\_MAXSEG (equal to 16 by default). This is a prototype 5392implementation of the shared memory interface and a more robust 5393interface, which will have fewer restrictions on the number of files 5394and on their names, may be developed in the future. 5395 5396When opening an already existing FITS file in shared memory one calls 5397the usual CFITSIO routine: 5398 5399\begin{verbatim} 5400 fits_open_file(&fitsfileptr, "shmem://h7", mode, &status) 5401\end{verbatim} 5402The file mode can be READWRITE or READONLY just as with disk files. 5403More than one process can operate on READONLY mode files at the same 5404time. CFITSIO supports proper file locking (both in READONLY and 5405READWRITE modes), so calls to fits\_open\_file may be locked out until 5406another other process closes the file. 5407 5408When an application is finished accessing a FITS file in a shared 5409memory segment, it may close it (and the file will remain in the 5410system) with fits\_close\_file, or delete it with fits\_delete\_file. 5411Physical deletion is postponed until the last process calls 5412ffclos/ffdelt. fits\_delete\_file tries to obtain a READWRITE lock on 5413the file to be deleted, thus it can be blocked if the object was not 5414opened in READWRITE mode. 5415 5416A shared memory management utility program called `smem', is included 5417with the CFITSIO distribution. It can be built by typing `make smem'; 5418then type `smem -h' to get a list of valid options. Executing smem 5419without any options causes it to list all the shared memory segments 5420currently residing in the system and managed by the shared memory 5421driver. To get a list of all the shared memory objects, run the system 5422utility program `ipcs [-a]'. 5423 5424 5425\section{Base Filename} 5426 5427The base filename is the name of the file optionally including the 5428director/subdirectory path, and in the case of `ftp', `http', and `root' 5429filetypes, 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 5438When creating a new output file on magnetic disk (of type file://) if 5439the base filename begins with an exclamation point (!) then any 5440existing file with that same basename will be deleted prior to creating 5441the new FITS file. Otherwise if the file to be created already exists, 5442then CFITSIO will return an error and will not overwrite the existing 5443file. Note that the exclamation point, '!', is a special UNIX character, 5444so if it is used on the command line rather than entered at a task 5445prompt, it must be preceded by a backslash to force the UNIX 5446shell to pass it verbatim to the application program. 5447 5448If the output disk file name ends with the suffix '.gz', then CFITSIO 5449will compress the file using the gzip compression algorithm before 5450writing it to disk. This can reduce the amount of disk space used by 5451the file. Note that this feature requires that the uncompressed file 5452be constructed in memory before it is compressed and written to disk, 5453so it can fail if there is insufficient available memory. 5454 5455An input FITS file may be compressed with the gzip or Unix compress 5456algorithms, in which case CFITSIO will uncompress the file on the fly 5457into a temporary file (in memory or on disk). Compressed files may 5458only be opened with read-only permission. When specifying the name of 5459a 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 5461without the suffix, then it will automatically search for a compressed 5462file with the same root name. In the case of reading ftp and http type 5463files, CFITSIO generally looks for a compressed version of the file 5464first, before trying to open the uncompressed file. By default, 5465CFITSIO copies (and uncompressed if necessary) the ftp or http FITS 5466file into memory on the local machine before opening it. This will 5467fail if the local machine does not have enough memory to hold the whole 5468FITS file, so in this case, the output filename specifier (see the next 5469section) can be used to further control how CFITSIO reads ftp and http 5470files. 5471 5472If the input file is an IRAF image file (*.imh file) then CFITSIO will 5473automatically convert it on the fly into a virtual FITS image before it 5474is opened by the application program. IRAF images can only be opened 5475with READONLY file access. 5476 5477Similarly, if the input file is a raw binary data array, then CFITSIO 5478will convert it on the fly into a virtual FITS image with the basic set 5479of required header keywords before it is opened by the application 5480program (with READONLY access). In this case the data type and 5481dimensions of the image must be specified in square brackets following 5482the filename (e.g. rawfile.dat[ib512,512]). The first character (case 5483insensitive) 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} 5493An optional second character specifies the byte order of the array 5494values: b or B indicates big endian (as in FITS files and the native 5495format of SUN UNIX workstations and Mac PCs) and l or L indicates 5496little endian (native format of DEC OSF workstations and IBM PCs). If 5497this character is omitted then the array is assumed to have the native 5498byte order of the local machine. These datatype characters are then 5499followed by a series of one or more integer values separated by commas 5500which define the size of each dimension of the raw array. Arrays with 5501up to 5 dimensions are currently supported. Finally, a byte offset to 5502the position of the first pixel in the data file may be specified by 5503separating it with a ':' from the last dimension value. If omitted, it 5504is assumed that the offset = 0. This parameter may be used to skip 5505over any header information in the file that precedes the binary data. 5506Further 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 5515One special case of input file is where the filename = `-' (a dash or 5516minus sign) or 'stdin' or 'stdout', which signifies that the input file 5517is to be read from the stdin stream, or written to the stdout stream if 5518a new output file is being created. In the case of reading from stdin, 5519CFITSIO first copies the whole stream into a temporary FITS file (in 5520memory or on disk), and subsequent reading of the FITS file occurs in 5521this copy. When writing to stdout, CFITSIO first constructs the whole 5522file in memory (since random access is required), then flushes it out 5523to the stdout stream when the file is closed. In addition, if the 5524output filename = '-.gz' or 'stdout.gz' then it will be gzip compressed 5525before being written to stdout. 5526 5527This ability to read and write on the stdin and stdout steams allows 5528FITS files to be piped between tasks in memory rather than having to 5529create temporary intermediate FITS files on disk. For example if task1 5530creates an output FITS file, and task2 reads an input FITS file, the 5531FITS file may be piped between the 2 tasks by specifying 5532 5533\begin{verbatim} 5534 task1 - | task2 - 5535\end{verbatim} 5536where the vertical bar is the Unix piping symbol. This assumes that the 2 5537tasks 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 5542An optional output filename may be specified in parentheses immediately 5543following the base file name to be opened. This is mainly useful in 5544those cases where CFITSIO creates a temporary copy of the input FITS 5545file before it is opened and passed to the application program. This 5546happens by default when opening a network FTP or HTTP-type file, when 5547reading a compressed FITS file on a local disk, when reading from the 5548stdin stream, or when a column filter, row filter, or binning specifier 5549is included as part of the input file specification. By default this 5550temporary file is created in memory. If there is not enough memory to 5551create the file copy, then CFITSIO will exit with an error. In these 5552cases one can force a permanent file to be created on disk, instead of 5553a temporary file in memory, by supplying the name in parentheses 5554immediately following the base file name. The output filename can 5555include the '!' clobber flag. 5556 5557Thus, if the input filename to CFITSIO is: 5558\verb+file1.fits.gz(file2.fits)+ 5559then CFITSIO will uncompress `file1.fits.gz' into the local disk file 5560`file2.fits' before opening it. CFITSIO does not automatically delete 5561the output file, so it will still exist after the application program 5562exits. 5563 5564In some cases, several different temporary FITS files will be created 5565in sequence, for instance, if one opens a remote file using FTP, then 5566filters rows in a binary table extension, then create an image by 5567binning a pair of columns. In this case, the remote file will be 5568copied to a temporary local file, then a second temporary file will be 5569created containing the filtered rows of the table, and finally a third 5570temporary file containing the binned image will be created. In cases 5571like this where multiple files are created, the outfile specifier will 5572be interpreted the name of the final file as described below, in descending 5573priority: 5574 5575\begin{itemize} 5576\item 5577as the name of the final image file if an image within a single binary 5578table cell is opened or if an image is created by binning a table column. 5579\item 5580as the name of the file containing the filtered table if a column filter 5581and/or a row filter are specified. 5582\item 5583as the name of the local copy of the remote FTP or HTTP file. 5584\item 5585as the name of the uncompressed version of the FITS file, if a 5586compressed FITS file on local disk has been opened. 5587\item 5588otherwise, the output filename is ignored. 5589\end{itemize} 5590 5591 5592The output file specifier is useful when reading FTP or HTTP-type 5593FITS files since it can be used to create a local disk copy of the file 5594that can be reused in the future. If the output file name = `*' then a 5595local file with the same name as the network file will be created. 5596Note that CFITSIO will behave differently depending on whether the 5597remote 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 5601file is copied to the local compressed file `myfile.fits.gz', which 5602is then uncompressed in local memory before being opened and passed 5603to the application program. 5604 5605\item 5606`ftp://remote.machine/tmp/myfile.fits.gz(myfile.fits)' - the remote 5607compressed file is copied and uncompressed into the local file 5608`myfile.fits'. This example requires less local memory than the 5609previous example since the file is uncompressed on disk instead of 5610in memory. 5611 5612\item 5613`ftp://remote.machine/tmp/myfile.fits(myfile.fits.gz)' - this will 5614usually produce an error since CFITSIO itself cannot compress files. 5615\end{itemize} 5616 5617The exact behavior of CFITSIO in the latter case depends on the type of 5618ftp server running on the remote machine and how it is configured. In 5619some cases, if the file `myfile.fits.gz' exists on the remote machine, 5620then the server will copy it to the local machine. In other cases the 5621ftp server will automatically create and transmit a compressed version 5622of the file if only the uncompressed version exists. This can get 5623rather confusing, so users should use a certain amount of caution when 5624using the output file specifier with FTP or HTTP file types, to make 5625sure they get the behavior that they expect. 5626 5627 5628\section{Template File Name when Creating a New File} 5629 5630When a new FITS file is created with a call to fits\_create\_file, the 5631name of a template file may be supplied in parentheses immediately 5632following the name of the new file to be created. This template is 5633used to define the structure of one or more HDUs in the new file. The 5634template file may be another FITS file, in which case the newly created 5635file will have exactly the same keywords in each HDU as in the template 5636FITS file, but all the data units will be filled with zeros. The 5637template file may also be an ASCII text file, where each line (in 5638general) describes one FITS keyword record. The format of the ASCII 5639template file is described below. 5640 5641 5642\section{Image Tile-Compression Specification} 5643 5644When specifying the name of the output FITS file to be created, the 5645user can indicate that images should be written in tile-compressed 5646format (see section 5.5, ``Primary Array or IMAGE Extension I/O 5647Routines'') by enclosing the compression parameters in square brackets 5648following the root disk file name. Here are some examples of the 5649syntax 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 5665The optional HDU location specifier defines which HDU (Header-Data 5666Unit, also known as an `extension') within the FITS file to initially 5667open. It must immediately follow the base file name (or the output 5668file name if present). If it is not specified then the first HDU (the 5669primary array) is opened. The HDU location specifier is required if 5670the colFilter, rowFilter, or binSpec specifiers are present, because 5671the primary array is not a valid HDU for these operations. The HDU may 5672be specified either by absolute position number, starting with 0 for 5673the primary array, or by reference to the HDU name, and optionally, the 5674version number and the HDU type of the desired extension. The location 5675of an image within a single cell of a binary table may also be 5676specified, as described below. 5677 5678The absolute position of the extension is specified either by enclosed 5679the number in square brackets (e.g., `[1]' = the first extension 5680following 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 5683extension version number (value of the EXTVER keyword) and the 5684extension type (value of the XTENSION keyword: IMAGE, ASCII or TABLE, 5685or BINTABLE), separated by commas and all enclosed in square brackets. 5686If the value of EXTVER and XTENSION are not specified, then the first 5687extension with the correct value of EXTNAME is opened. The extension 5688name and type are not case sensitive, and the extension type may be 5689abbreviated to a single letter (e.g., I = IMAGE extension or primary 5690array, A or T = ASCII table extension, and B = binary table BINTABLE 5691extension). If the HDU location specifier is equal to `[PRIMARY]' or 5692`[P]', then the primary array (the first HDU) will be opened. 5693 5694FITS images are most commonly stored in the primary array or an image 5695extension, but images can also be stored as a vector in a single cell 5696of a binary table (i.e. each row of the vector column contains a 5697different image). Such an image can be opened with CFITSIO by 5698specifying the desired column name and the row number after the binary 5699table HDU specifier as shown in the following examples. The column name 5700is separated from the HDU specifier by a semicolon and the row number 5701is enclosed in parentheses. In this case CFITSIO copies the image from 5702the table cell into a temporary primary array before it is opened. The 5703application program then just sees the image in the primary array, 5704without any extensions. The particular row to be opened may be 5705specified either by giving an absolute integer row number (starting 5706with 1 for the first row), or by specifying a boolean expression that 5707evaluates to TRUE for the desired row. The first row that satisfies 5708the expression will be used. The row selection expression has the same 5709syntax 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 5729A virtual file containing a rectangular subsection of an image can be 5730extracted and opened by specifying the range of pixels (start:end) 5731along each axis to be extracted from the original image. One can also 5732specify an optional pixel increment (start:end:step) for each axis of 5733the input image. A pixel step = 1 will be assumed if it is not 5734specified. If the start pixel is larger then the end pixel, then the 5735image will be flipped (producing a mirror image) along that dimension. 5736An asterisk, '*', may be used to specify the entire range of an axis, 5737and '-*' will flip the entire axis. The input image can be in the 5738primary array, in an image extension, or contained in a vector cell of 5739a binary table. In the later 2 cases the extension name or number must 5740be 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 5770When CFITSIO opens an image section it first creates a temporary file 5771containing the image section plus a copy of any other HDUs in the 5772file. This temporary file is then opened by the application program, 5773so it is not possible to write to or modify the input file when 5774specifying an image section. Note that CFITSIO automatically updates 5775the world coordinate system keywords in the header of the image 5776section, if they exist, so that the coordinate associated with each 5777pixel in the image section will be computed correctly. 5778 5779 5780\section{Image Transform Filters} 5781 5782CFITSIO can apply a user-specified mathematical function to the value 5783of every pixel in a FITS image, thus creating a new virtual image 5784in computer memory that is then opened and read by the application 5785program. The original FITS image is not modified by this process. 5786 5787The image transformation specifier is appended to the input 5788FITS file name and is enclosed in square brackets. It begins with the 5789letters 'PIX' to distinguish it from other types of FITS file filters 5790that are recognized by CFITSIO. The image transforming function may 5791use any of the mathematical operators listed in the following 5792'Row Filtering Specification' section of this document. 5793Some 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} 5803Use the letter 'X' in the expression to represent the current pixel value 5804in the image. The expression is evaluated 5805independently for each pixel in the image and may be a function of 1) the 5806original pixel value, 2) the value of other pixels in the image at 5807a given relative offset from the position of the pixel that is being 5808evaluated, and 3) the value of 5809any header keywords. Header keyword values are represented 5810by the name of the keyword preceded by the '\#' sign. 5811 5812 5813To access the the value of adjacent pixels in the image, 5814specify the (1-D) offset from the current pixel in curly brackets. 5815For example 5816 5817\begin{verbatim} 5818 [pix (x{-1} + x + x{+1}) / 3] 5819\end{verbatim} 5820will replace each pixel value with the running mean of the values of that 5821pixel and it's 2 neighboring pixels. Note that in this notation the image 5822is treated as a 1-D array, where each row of the image (or higher dimensional 5823cube) is appended one after another in one long array of pixels. 5824It is possible to refer to pixels 5825in the rows above or below the current pixel by using the value of the 5826NAXIS1 header keyword. For example 5827 5828\begin{verbatim} 5829 [pix (x{-#NAXIS1} + x + x{#NAXIS1}) / 3] 5830\end{verbatim} 5831will compute the mean of each image pixel and the pixels immediately 5832above and below it in the adjacent rows of the image. 5833The following more complex example 5834creates a smoothed virtual image where each pixel 5835is 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} 5842If the pixel offset 5843extends beyond the first or last pixel in the image, the function will 5844evaluate to undefined, or NULL. 5845 5846For complex or commonly used image filtering operations, 5847one can write the expression into an external text file and 5848then import it into the 5849filter using the syntax '[pix @filename.txt]'. The mathematical 5850expression can 5851extend over multiple lines of text in the file. 5852Any lines in the external text file 5853that begin with 2 slash characters ('//') will be ignored and may be 5854used to add comments into the file. 5855 5856When using column filtering to open a file ``on the fly,'' it is permitted 5857to use multiple column filtering expressions. For example, the 5858syntax 5859\begin{verbatim} 5860 filename.fits[col *][col -Y][col Z=X+1] 5861\end{verbatim} 5862would be treated as equivalent to joining the expressions with semicolons, 5863or 5864\begin{verbatim} 5865 filename.fits[col *; -Y;col Z=X+1] 5866\end{verbatim} 5867Please note that if multiple column filtering expressions are used, it is 5868not permitted to also use the \verb+[col @filename.txt]+ syntax in any 5869of the individual expressions. 5870 5871By default, the datatype of the resulting image will be the same as 5872the original image, but one may force a different datatype by appended 5873a 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} 5882Also by default, any other HDUs in the input file will be copied without 5883change to the 5884output virtual FITS file, but one may discard the other HDUs by adding 5885the number '1' to the 'pix' keyword (and following any optional datatype code 5886letter). For example: 5887 5888\begin{verbatim} 5889 myfile.fits[3][pixr1 sqrt(X)] 5890\end{verbatim} 5891will create a virtual FITS file containing only a primary array image 5892with 32-bit floating point pixels that have a value equal to the square 5893root of the pixels in the image that is in the 3rd extension 5894of the 'myfile.fits' file. 5895 5896 5897 5898 5899\section{Column and Keyword Filtering Specification} 5900 5901The optional column/keyword filtering specifier is used to modify the 5902column structure and/or the header keywords in the HDU that was 5903selected with the previous HDU location specifier. This filtering 5904specifier must be enclosed in square brackets and can be distinguished 5905from a general row filter specifier (described below) by the fact that 5906it begins with the string 'col ' and is not immediately followed by an 5907equals sign. The original file is not changed by this filtering 5908operation, and instead the modifications are made on a copy of the 5909input FITS file (usually in memory), which also contains a copy of all 5910the other HDUs in the file. This temporary file is passed to the 5911application program and will persist only until the file is closed or 5912until the program exits, unless the outfile specifier (see above) is 5913also supplied. 5914 5915The column/keyword filter can be used to perform the following 5916operations. More than one operation may be specified by separating 5917them with commas or semi-colons. 5918 5919\begin{itemize} 5920 5921\item 5922Copy only a specified list of columns columns to the filtered input file. 5923The list of column name should be separated by commas or semi-colons. Wild card 5924characters may be used in the column names to match multiple columns. 5925If the expression contains both a list of columns to be included and 5926columns to be deleted, then all the columns in the original table 5927except the explicitly deleted columns will appear in the filtered 5928table (i.e., there is no need to explicitly list the columns to 5929be included if any columns are being deleted). 5930 5931\item 5932Delete a column or keyword by listing the name preceded by a minus 5933sign or an exclamation mark (!), e.g., '-TIME' will delete the TIME 5934column if it exists, otherwise the TIME keyword. An error is returned 5935if neither a column nor keyword with this name exists. Note that the 5936exclamation point, '!', is a special UNIX character, so if it is used 5937on the command line rather than entered at a task prompt, it must be 5938preceded by a backslash to force the UNIX shell to ignore it. 5939 5940\item 5941Rename an existing column or keyword with the syntax 'NewName == 5942OldName'. An error is returned if neither a column nor keyword with 5943this name exists. 5944 5945\item 5946Append a new column or keyword to the table. To create a column, 5947give the new name, optionally followed by the datatype in parentheses, 5948followed by a single equals sign and an expression to be used to 5949compute the value (e.g., 'newcol(1J) = 0' will create a new 32-bit 5950integer column called 'newcol' filled with zeros). The datatype is 5951specified using the same syntax that is allowed for the value of the 5952FITS TFORMn keyword (e.g., 'I', 'J', 'E', 'D', etc. for binary tables, 5953and 'I8', F12.3', 'E20.12', etc. for ASCII tables). If the datatype is 5954not specified then an appropriate datatype will be chosen depending on 5955the form of the expression (may be a character string, logical, bit, long 5956integer, or double column). An appropriate vector count (in the case 5957of binary tables) will also be added if not explicitly specified. 5958 5959When creating a new keyword, the keyword name must be preceded by a 5960pound sign '\#', and the expression must evaluate to a scalar 5961(i.e., cannot have a column name in the expression). The comment 5962string for the keyword may be specified in parentheses immediately 5963following the keyword name (instead of supplying a datatype as in 5964the case of creating a new column). If the keyword name ends with a 5965pound sign '\#', then cfitsio will substitute the number of the 5966most recently referenced column for the \# character . 5967This is especially useful when writing 5968a column-related keyword like TUNITn for a newly created column, 5969as shown in the following examples. 5970 5971COMMENT 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} 5977Note that the equal sign and the quote characters will be removed, so 5978that 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} 5984These two special keywords are always appended to the end of the header 5985and will not affect any previously existing COMMENT or HISTORY keywords. 5986 5987\item 5988Recompute (overwrite) the values in an existing column or keyword by 5989giving the name followed by an equals sign and an arithmetic 5990expression. 5991\end{itemize} 5992 5993The expression that is used when appending or recomputing columns or 5994keywords can be arbitrarily complex and may be a function of other 5995header keyword values and other columns (in the same row). The full 5996syntax and available functions for the expression are described below 5997in the row filter specification section. 5998 5999If the expression contains both a list of columns to be included and 6000columns to be deleted, then all the columns in the original table 6001except the explicitly deleted columns will appear in the filtered 6002table. If no columns to be deleted are specified, then only the 6003columns that are explicitly listed will be included in the filtered 6004output table. To include all the columns, add the '*' wildcard 6005specifier at the end of the list, as shown in the examples. 6006 6007For complex or commonly used operations, one can also place the 6008operations into an external text file and import it into the column 6009filter using the syntax '[col @filename.txt]'. The operations can 6010extend over multiple lines of the file, but multiple operations must 6011still be separated by commas or semi-colons. Any lines in the external text file 6012that begin with 2 slash characters ('//') will be ignored and may be 6013used to add comments into the file. 6014 6015Examples: 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} 6111would be treated as equivalent to joining the expressions with logical ``and'' 6112like this, 6113\begin{verbatim} 6114 filename.fits[(#ROW > 5)&&(X.gt.7)] 6115\end{verbatim} 6116Please note that if multiple row filtering expressions are used, it is 6117not permitted to also use the \verb+[@filename.txt]+ syntax in any 6118of the individual expressions. 6119 6120 6121%% <!-- IMPORTANT NOTE IMPORTANT NOTE IMPORTANT NOTE --> 6122%% <!-- If you edit this file then you must also edit 6123%% the following other locations where calculator 6124%% expressions are documented: 6125%% heacore/cfitsio/docs/cfitsio.tex 6126%% heacore/cfitsio/docs/fitsio.tex 6127%% heatools/help/rowfilter.html 6128%% heatools/help/colfilter.html 6129%% heatools/help/calc_express.html 6130%% heatools/ftcalc/ftcalc.html 6131%% heatools/ftselect/ftselect.html 6132%% ftools/futils/tasks/fselect/fselect.hlp 6133%% ftools/futils/tasks/fcalc/fcalc.hlp 6134%% ftools/guis/fv/doc/expressions.html 6135%% --> 6136 6137 Boolean operators can be used in the expression in either their 6138 Fortran or C forms. The following boolean operators are available: 6139 6140\begin{verbatim} 6141 "equal" .eq. .EQ. == "not equal" .ne. .NE. != 6142 "less than" .lt. .LT. < "less than/equal" .le. .LE. <= =< 6143 "greater than" .gt. .GT. > "greater than/equal" .ge. .GE. >= => 6144 "or" .or. .OR. || "and" .and. .AND. && 6145 "negation" .not. .NOT. ! "approx. equal(1e-7)" ~ 6146\end{verbatim} 6147 6148Note that the exclamation point, '!', is a special UNIX character, so 6149if it is used on the command line rather than entered at a task 6150prompt, it must be preceded by a backslash to force the UNIX shell to 6151ignore it. 6152 6153The expression may also include arithmetic operators and functions. 6154Trigonometric functions use radians, not degrees. The following 6155arithmetic operators and functions can be used in the expression 6156(function names are case insensitive). A null value will be returned 6157in case of illegal operations such as divide by zero, sqrt(negative) 6158log(negative), log10(negative), arccos(.gt. 1), arcsin(.gt. 1). 6159 6160\begin{verbatim} 6161 "addition" + "subtraction" - 6162 "multiplication" * "division" / 6163 "negation" - "exponentiation" ** ^ 6164 "absolute value" abs(x) "cosine" cos(x) 6165 "sine" sin(x) "tangent" tan(x) 6166 "arc cosine" arccos(x) "arc sine" arcsin(x) 6167 "arc tangent" arctan(x) "arc tangent" arctan2(y,x) 6168 "hyperbolic cos" cosh(x) "hyperbolic sin" sinh(x) 6169 "hyperbolic tan" tanh(x) "round to nearest int" round(x) 6170 "round down to int" floor(x) "round up to int" ceil(x) 6171 "exponential" exp(x) "square root" sqrt(x) 6172 "natural log" log(x) "common log" log10(x) 6173 "modulus" x % y 6174 "bitwise AND" x & y "bitwise OR" x | y 6175 "bitwise XOR" x ^^ y (bitwise operators are 32-bit int only) 6176 "random # [0.0,1.0)" random() 6177 "random Gaussian" randomn() "random Poisson" randomp(x) 6178 "minimum" min(x,y) "maximum" max(x,y) 6179 "cumulative sum" accum(x) "sequential difference" seqdiff(x) 6180 "if-then-else" b?x:y 6181 "angular separation" angsep(ra1,dec1,ra2,de2) (all in degrees) 6182 "substring" strmid(s,p,n) "string search" strstr(s,r) 6183\end{verbatim} 6184The bitwise operators for AND, OR and XOR operate upon 32-bit integer 6185expressions only. 6186 6187Three different random number functions are provided: random(), with 6188no arguments, produces a uniform random deviate between 0 and 1; 6189randomn(), also with no arguments, produces a normal (Gaussian) random 6190deviate with zero mean and unit standard deviation; randomp(x) 6191produces a Poisson random deviate whose expected number of counts is 6192X. X may be any positive real number of expected counts, including 6193fractional values, but the return value is an integer. 6194 6195When the random functions are used in a vector expression, by default 6196the same random value will be used when evaluating each element of the 6197vector. If different random numbers are desired, then the name of a 6198vector column should be supplied as the single argument to the random 6199function (e.g., "flux + 0.1 * random(flux)", where "flux" is the name 6200of a vector column). This will create a vector of random numbers that 6201will be used in sequence when evaluating each element of the vector 6202expression. 6203 6204An alternate syntax for the min and max functions has only a single 6205argument which should be a vector value (see below). The result 6206will be the minimum/maximum element contained within the vector. 6207 6208The accum(x) function forms the cumulative sum of x, element by 6209element. Vector columns are supported simply by performing the 6210summation process through all the values. Null values are treated as 62110. The seqdiff(x) function forms the sequential difference of x, 6212element by element. The first value of seqdiff is the first value of 6213x. A single null value in x causes a pair of nulls in the output. 6214The seqdiff and accum functions are functional inverses, i.e., 6215seqdiff(accum(x)) == x as long as no null values are present. 6216 6217In the if-then-else expression, "b?x:y", b is an explicit boolean 6218value or expression. There is no automatic type conversion from 6219numeric to boolean values, so one needs to use "iVal!=0" instead of 6220merely "iVal" as the boolean argument. x and y can be any scalar data 6221type (including string). 6222 6223The angsep function computes the angular separation in degrees between 62242 celestial positions, where the first 2 parameters give the RA-like 6225and Dec-like coordinates (in decimal degrees) of the first position, 6226and the 3rd and 4th parameters give the coordinates of the second 6227position. 6228 6229The substring function strmid(S,P,N) extracts a substring from S, 6230starting at string position P, with a substring length N. The first 6231character position in S is labeled as 1. If P is 0, or refers to a 6232position beyond the end of S, then the extracted substring will be 6233NULL. S, P, and N may be functions of other columns. 6234 6235The string search function strstr(S,R) searches for the first 6236occurrence of the substring R in S. The result is an integer, 6237indicating the character position of the first match (where 1 is the 6238first character position of S). If no match is found, then strstr() 6239returns a NULL value. 6240 6241The following type casting operators are available, where the 6242enclosing parentheses are required and taken from the C language 6243usage. 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\end{verbatim} 6298 The former 6299 returns a boolean value of TRUE if the argument x is NULL. The 6300 later "defines" a value to be substituted for NULL values; it 6301 returns the value of x if x is not NULL, otherwise it returns the 6302 value of y. 6303 6304 6305\subsection{Bit Masks} 6306 6307 Bit masks can be used to select out rows from bit columns (TFORMn = 6308 \#X) in FITS files. To represent the mask, binary, octal, and hex 6309 formats are allowed: 6310 6311 6312\begin{verbatim} 6313 binary: b0110xx1010000101xxxx0001 6314 octal: o720x1 -> (b111010000xxx001) 6315 hex: h0FxD -> (b00001111xxxx1101) 6316\end{verbatim} 6317 6318 In all the representations, an x or X is allowed in the mask as a 6319 wild card. Note that the x represents a different number of wild 6320 card bits in each representation. All representations are case 6321 insensitive. Although bitmasks may be of arbitrary length and contain 6322 a wildcard, they may only be used in logical expressions, unlike 6323 integer constants (see above) which may be used in any arithmetic 6324 expression. 6325 6326 To construct the boolean expression using the mask as the boolean 6327 equal operator described above on a bit table column. For example, 6328 if you had a 7 bit column named flags in a FITS table and wanted 6329 all rows having the bit pattern 0010011, the selection expression 6330 would be: 6331 6332 6333\begin{verbatim} 6334 flags == b0010011 6335 or 6336 flags .eq. b10011 6337\end{verbatim} 6338 6339 It is also possible to test if a range of bits is less than, less 6340 than equal, greater than and greater than equal to a particular 6341 boolean value: 6342 6343 6344\begin{verbatim} 6345 flags <= bxxx010xx 6346 flags .gt. bxxx100xx 6347 flags .le. b1xxxxxxx 6348\end{verbatim} 6349 6350 Notice the use of the x bit value to limit the range of bits being 6351 compared. 6352 6353 It is not necessary to specify the leading (most significant) zero 6354 (0) bits in the mask, as shown in the second expression above. 6355 6356 Bit wise AND, OR and NOT operations are also possible on two or 6357 more bit fields using the '\&'(AND), '$|$'(OR), and the '!'(NOT) 6358 operators. All of these operators result in a bit field which can 6359 then be used with the equal operator. For example: 6360 6361 6362\begin{verbatim} 6363 (!flags) == b1101100 6364 (flags & b1000001) == bx000001 6365\end{verbatim} 6366 6367 Bit fields can be appended as well using the '+' operator. Strings 6368 can be concatenated this way, too. 6369 6370 6371\subsection{Vector Columns} 6372 6373 Vector columns can also be used in building the expression. No 6374 special syntax is required if one wants to operate on all elements 6375 of the vector. Simply use the column name as for a scalar column. 6376 Vector columns can be freely intermixed with scalar columns or 6377 constants in virtually all expressions. The result will be of the 6378 same dimension as the vector. Two vectors in an expression, though, 6379 need to have the same number of elements and have the same 6380 dimensions. The only places a vector column cannot be used (for 6381 now, anyway) are the SAO region functions and the NEAR boolean 6382 function. 6383 6384 Arithmetic and logical operations are all performed on an element by 6385 element basis. Comparing two vector columns, eg "COL1 == COL2", 6386 thus results in another vector of boolean values indicating which 6387 elements of the two vectors are equal. 6388 6389 Eight functions are available that operate on a vector and return a 6390 scalar result: 6391 6392\begin{verbatim} 6393 "minimum" MIN(V) "maximum" MAX(V) 6394 "average" AVERAGE(V) "median" MEDIAN(V) 6395 "summation" SUM(V) "standard deviation" STDDEV(V) 6396 "# of values" NELEM(V) "# of non-null values" NVALID(V) 6397\end{verbatim} 6398 where V represents the name of a vector column or a manually 6399 constructed vector using curly brackets as described below. The 6400 first 6 of these functions ignore any null values in the vector when 6401 computing the result. The STDDEV() function computes the sample 6402 standard deviation, i.e. it is proportional to 1/SQRT(N-1) instead 6403 of 1/SQRT(N), where N is NVALID(V). 6404 6405 The SUM function literally sums all the elements in x, returning a 6406 scalar value. If x is a boolean vector, SUM returns the number 6407 of TRUE elements. The NELEM function returns the number of elements 6408 in vector x whereas NVALID return the number of non-null elements in 6409 the vector. (NELEM also operates on bit and string columns, 6410 returning their column widths.) As an example, to test whether all 6411 elements of two vectors satisfy a given logical comparison, one can 6412 use the expression 6413 6414\begin{verbatim} 6415 SUM( COL1 > COL2 ) == NELEM( COL1 ) 6416\end{verbatim} 6417 6418 which will return TRUE if all elements of COL1 are greater than 6419 their corresponding elements in COL2. 6420 6421 To specify a single element of a vector, give the column name 6422 followed by a comma-separated list of coordinates enclosed in 6423 square brackets. For example, if a vector column named PHAS exists 6424 in the table as a one dimensional, 256 component list of numbers 6425 from which you wanted to select the 57th component for use in the 6426 expression, then PHAS[57] would do the trick. Higher dimensional 6427 arrays of data may appear in a column. But in order to interpret 6428 them, the TDIMn keyword must appear in the header. Assuming that a 6429 (4,4,4,4) array is packed into each row of a column named ARRAY4D, 6430 the (1,2,3,4) component element of each row is accessed by 6431 ARRAY4D[1,2,3,4]. Arrays up to dimension 5 are currently 6432 supported. Each vector index can itself be an expression, although 6433 it must evaluate to an integer value within the bounds of the 6434 vector. Vector columns which contain spaces or arithmetic operators 6435 must have their names enclosed in "\$" characters as with 6436 \$ARRAY-4D\$[1,2,3,4]. 6437 6438 A more C-like syntax for specifying vector indices is also 6439 available. The element used in the preceding example alternatively 6440 could be specified with the syntax ARRAY4D[4][3][2][1]. Note the 6441 reverse order of indices (as in C), as well as the fact that the 6442 values are still ones-based (as in Fortran -- adopted to avoid 6443 ambiguity for 1D vectors). With this syntax, one does not need to 6444 specify all of the indices. To extract a 3D slice of this 4D 6445 array, use ARRAY4D[4]. 6446 6447 Variable-length vector columns are not supported. 6448 6449 Vectors can be manually constructed within the expression using a 6450 comma-separated list of elements surrounded by curly braces ('\{\}'). 6451 For example, '\{1,3,6,1\}' is a 4-element vector containing the values 6452 1, 3, 6, and 1. The vector can contain only boolean, integer, and 6453 real values (or expressions). The elements will be promoted to the 6454 highest datatype present. Any elements which are themselves 6455 vectors, will be expanded out with each of its elements becoming an 6456 element in the constructed vector. 6457 6458 6459\subsection{Good Time Interval Filtering} 6460 6461 A common filtering method involves selecting rows which have a time 6462 value which lies within what is called a Good Time Interval or GTI. 6463 The time intervals are defined in a separate FITS table extension 6464 which contains 2 columns giving the start and stop time of each 6465 good interval. The filtering operation accepts only those rows of 6466 the input table which have an associated time which falls within 6467 one of the time intervals defined in the GTI extension. A high 6468 level function, gtifilter(a,b,c,d), is available which evaluates 6469 each row of the input table and returns TRUE or FALSE depending 6470 whether the row is inside or outside the good time interval. The 6471 syntax is 6472 6473\begin{verbatim} 6474 gtifilter( [ "gtifile" [, expr [, "STARTCOL", "STOPCOL" ] ] ] ) 6475\end{verbatim} 6476 where each "[]" demarks optional parameters. Note that the quotes 6477 around the gtifile and START/STOP column are required. Either single 6478 or double quotes may be used. In cases where this expression is 6479 entered on the Unix command line, enclose the entire expression in 6480 double quotes, and then use single quotes within the expression to 6481 enclose the 'gtifile' and other terms. It is also usually possible 6482 to do the reverse, and enclose the whole expression in single quotes 6483 and then use double quotes within the expression. The gtifile, 6484 if specified, can be blank ("") which will mean to use the first 6485 extension with the name "*GTI*" in the current file, a plain 6486 extension specifier (eg, "+2", "[2]", or "[STDGTI]") which will be 6487 used to select an extension in the current file, or a regular 6488 filename with or without an extension specifier which in the latter 6489 case will mean to use the first extension with an extension name 6490 "*GTI*". Expr can be any arithmetic expression, including simply 6491 the time column name. A vector time expression will produce a 6492 vector boolean result. STARTCOL and STOPCOL are the names of the 6493 START/STOP columns in the GTI extension. If one of them is 6494 specified, they both must be. 6495 6496 In its simplest form, no parameters need to be provided -- default 6497 values will be used. The expression "gtifilter()" is equivalent to 6498 6499\begin{verbatim} 6500 gtifilter( "", TIME, "*START*", "*STOP*" ) 6501\end{verbatim} 6502 This will search the current file for a GTI extension, filter the 6503 TIME column in the current table, using START/STOP times taken from 6504 columns in the GTI extension with names containing the strings 6505 "START" and "STOP". The wildcards ('*') allow slight variations in 6506 naming conventions such as "TSTART" or "STARTTIME". The same 6507 default values apply for unspecified parameters when the first one 6508 or two parameters are specified. The function automatically 6509 searches for TIMEZERO/I/F keywords in the current and GTI 6510 extensions, applying a relative time offset, if necessary. 6511 6512 6513\subsection{Spatial Region Filtering} 6514 6515 Another common filtering method selects rows based on whether the 6516 spatial position associated with each row is located within a given 6517 2-dimensional region. The syntax for this high-level filter is 6518 6519\begin{verbatim} 6520 regfilter( "regfilename" [ , Xexpr, Yexpr [ , "wcs cols" ] ] ) 6521\end{verbatim} 6522 where each "[]" demarks optional parameters. The region file name 6523 is required and must be enclosed in quotes. The remaining 6524 parameters are optional. There are 2 supported formats for the 6525 region file: ASCII file or FITS binary table. The region file 6526 contains a list of one or more geometric shapes (circle, 6527 ellipse, box, etc.) which defines a region on the celestial sphere 6528 or an area within a particular 2D image. The region file is 6529 typically generated using an image display program such as fv/POW 6530 (distribute by the HEASARC), or ds9 (distributed by the Smithsonian 6531 Astrophysical Observatory). Users should refer to the documentation 6532 provided with these programs for more details on the syntax used in 6533 the region files. The FITS region file format is defined in a document 6534 available from the FITS Support Office at 6535 http://fits.gsfc.nasa.gov/ registry/ region.html 6536 6537 In its simplest form, (e.g., regfilter("region.reg") ) the 6538 coordinates in the default 'X' and 'Y' columns will be used to 6539 determine if each row is inside or outside the area specified in 6540 the region file. Alternate position column names, or expressions, 6541 may be entered if needed, as in 6542 6543\begin{verbatim} 6544 regfilter("region.reg", XPOS, YPOS) 6545\end{verbatim} 6546 Region filtering can be applied most unambiguously if the positions 6547 in the region file and in the table to be filtered are both give in 6548 terms of absolute celestial coordinate units. In this case the 6549 locations and sizes of the geometric shapes in the region file are 6550 specified in angular units on the sky (e.g., positions given in 6551 R.A. and Dec. and sizes in arcseconds or arcminutes). Similarly, 6552 each row of the filtered table will have a celestial coordinate 6553 associated with it. This association is usually implemented using 6554 a set of so-called 'World Coordinate System' (or WCS) FITS keywords 6555 that define the coordinate transformation that must be applied to 6556 the values in the 'X' and 'Y' columns to calculate the coordinate. 6557 6558 Alternatively, one can perform spatial filtering using unitless 6559 'pixel' coordinates for the regions and row positions. In this 6560 case the user must be careful to ensure that the positions in the 2 6561 files are self-consistent. A typical problem is that the region 6562 file may be generated using a binned image, but the unbinned 6563 coordinates are given in the event table. The ROSAT events files, 6564 for example, have X and Y pixel coordinates that range from 1 - 6565 15360. These coordinates are typically binned by a factor of 32 to 6566 produce a 480x480 pixel image. If one then uses a region file 6567 generated from this image (in image pixel units) to filter the 6568 ROSAT events file, then the X and Y column values must be converted 6569 to corresponding pixel units as in: 6570 6571\begin{verbatim} 6572 regfilter("rosat.reg", X/32.+.5, Y/32.+.5) 6573\end{verbatim} 6574 Note that this binning conversion is not necessary if the region 6575 file is specified using celestial coordinate units instead of pixel 6576 units because CFITSIO is then able to directly compare the 6577 celestial coordinate of each row in the table with the celestial 6578 coordinates in the region file without having to know anything 6579 about how the image may have been binned. 6580 6581 The last "wcs cols" parameter should rarely be needed. If supplied, 6582 this string contains the names of the 2 columns (space or comma 6583 separated) which have the associated WCS keywords. If not supplied, 6584 the filter will scan the X and Y expressions for column names. 6585 If only one is found in each expression, those columns will be 6586 used, otherwise an error will be returned. 6587 6588 These region shapes are supported (names are case insensitive): 6589 6590\begin{verbatim} 6591 Point ( X1, Y1 ) <- One pixel square region 6592 Line ( X1, Y1, X2, Y2 ) <- One pixel wide region 6593 Polygon ( X1, Y1, X2, Y2, ... ) <- Rest are interiors with 6594 Rectangle ( X1, Y1, X2, Y2, A ) | boundaries considered 6595 Box ( Xc, Yc, Wdth, Hght, A ) V within the region 6596 Diamond ( Xc, Yc, Wdth, Hght, A ) 6597 Circle ( Xc, Yc, R ) 6598 Annulus ( Xc, Yc, Rin, Rout ) 6599 Ellipse ( Xc, Yc, Rx, Ry, A ) 6600 Elliptannulus ( Xc, Yc, Rinx, Riny, Routx, Routy, Ain, Aout ) 6601 Sector ( Xc, Yc, Amin, Amax ) 6602\end{verbatim} 6603 where (Xc,Yc) is the coordinate of the shape's center; (X\#,Y\#) are 6604 the coordinates of the shape's edges; Rxxx are the shapes' various 6605 Radii or semi-major/minor axes; and Axxx are the angles of rotation 6606 (or bounding angles for Sector) in degrees. For rotated shapes, the 6607 rotation angle can be left off, indicating no rotation. Common 6608 alternate names for the regions can also be used: rotbox = box; 6609 rotrectangle = rectangle; (rot)rhombus = (rot)diamond; and pie 6610 = sector. When a shape's name is preceded by a minus sign, '-', 6611 the defined region is instead the area *outside* its boundary (ie, 6612 the region is inverted). All the shapes within a single region 6613 file are OR'd together to create the region, and the order is 6614 significant. The overall way of looking at region files is that if 6615 the first region is an excluded region then a dummy included region 6616 of the whole detector is inserted in the front. Then each region 6617 specification as it is processed overrides any selections inside of 6618 that region specified by previous regions. Another way of thinking 6619 about this is that if a previous excluded region is completely 6620 inside of a subsequent included region the excluded region is 6621 ignored. 6622 6623 The positional coordinates may be given either in pixel units, 6624 decimal degrees or hh:mm:ss.s, dd:mm:ss.s units. The shape sizes 6625 may be given in pixels, degrees, arcminutes, or arcseconds. Look 6626 at examples of region file produced by fv/POW or ds9 for further 6627 details of the region file format. 6628 6629 There are three functions that are primarily for use with SAO region 6630 files and the FSAOI task, but they can be used directly. They 6631 return a boolean true or false depending on whether a two 6632 dimensional point is in the region or not: 6633 6634\begin{verbatim} 6635 "point in a circular region" 6636 circle(xcntr,ycntr,radius,Xcolumn,Ycolumn) 6637 6638 "point in an elliptical region" 6639 ellipse(xcntr,ycntr,xhlf_wdth,yhlf_wdth,rotation,Xcolumn,Ycolumn) 6640 6641 "point in a rectangular region" 6642 box(xcntr,ycntr,xfll_wdth,yfll_wdth,rotation,Xcolumn,Ycolumn) 6643 6644 where 6645 (xcntr,ycntr) are the (x,y) position of the center of the region 6646 (xhlf_wdth,yhlf_wdth) are the (x,y) half widths of the region 6647 (xfll_wdth,yfll_wdth) are the (x,y) full widths of the region 6648 (radius) is half the diameter of the circle 6649 (rotation) is the angle(degrees) that the region is rotated with 6650 respect to (xcntr,ycntr) 6651 (Xcoord,Ycoord) are the (x,y) coordinates to test, usually column 6652 names 6653 NOTE: each parameter can itself be an expression, not merely a 6654 column name or constant. 6655\end{verbatim} 6656 6657 6658\subsection{Example Row Filters} 6659 6660\begin{verbatim} 6661 [ binary && mag <= 5.0] - Extract all binary stars brighter 6662 than fifth magnitude (note that 6663 the initial space is necessary to 6664 prevent it from being treated as a 6665 binning specification) 6666 6667 [#row >= 125 && #row <= 175] - Extract row numbers 125 through 175 6668 6669 [IMAGE[4,5] .gt. 100] - Extract all rows that have the 6670 (4,5) component of the IMAGE column 6671 greater than 100 6672 6673 [abs(sin(theta * #deg)) < 0.5] - Extract all rows having the 6674 absolute value of the sine of theta 6675 less than a half where the angles 6676 are tabulated in degrees 6677 6678 [SUM( SPEC > 3*BACKGRND )>=1] - Extract all rows containing a 6679 spectrum, held in vector column 6680 SPEC, with at least one value 3 6681 times greater than the background 6682 level held in a keyword, BACKGRND 6683 6684 [VCOL=={1,4,2}] - Extract all rows whose vector column 6685 VCOL contains the 3-elements 1, 4, and 6686 2. 6687 6688 [@rowFilter.txt] - Extract rows using the expression 6689 contained within the text file 6690 rowFilter.txt 6691 6692 [gtifilter()] - Search the current file for a GTI 6693 extension, filter the TIME 6694 column in the current table, using 6695 START/STOP times taken from 6696 columns in the GTI extension 6697 6698 [regfilter("pow.reg")] - Extract rows which have a coordinate 6699 (as given in the X and Y columns) 6700 within the spatial region specified 6701 in the pow.reg region file. 6702 6703 [regfilter("pow.reg", Xs, Ys)] - Same as above, except that the 6704 Xs and Ys columns will be used to 6705 determine the coordinate of each 6706 row in the table. 6707\end{verbatim} 6708 6709 6710\section{ Binning or Histogramming Specification} 6711 6712The optional binning specifier is enclosed in square brackets and can 6713be distinguished from a general row filter specification by the fact 6714that it begins with the keyword 'bin' not immediately followed by an 6715equals sign. When binning is specified, a temporary N-dimensional FITS 6716primary array is created by computing the histogram of the values in 6717the specified columns of a FITS table extension. After the histogram 6718is computed the input FITS file containing the table is then closed and 6719the temporary FITS primary array is opened and passed to the 6720application program. Thus, the application program never sees the 6721original FITS table and only sees the image in the new temporary file 6722(which has no additional extensions). Obviously, the application 6723program must be expecting to open a FITS image and not a FITS table in 6724this case. 6725 6726The data type of the FITS histogram image may be specified by appending 6727'b' (for 8-bit byte), 'i' (for 16-bit integers), 'j' (for 32-bit 6728integer), 'r' (for 32-bit floating points), or 'd' (for 64-bit double 6729precision floating point) to the 'bin' keyword (e.g. '[binr X]' 6730creates a real floating point image). If the datatype is not 6731explicitly specified then a 32-bit integer image will be created by 6732default, unless the weighting option is also specified in which case 6733the image will have a 32-bit floating point data type by default. 6734 6735The histogram image may have from 1 to 4 dimensions (axes), depending 6736on the number of columns that are specified. The general form of the 6737binning specification is: 6738 6739\begin{verbatim} 6740 [bin{bijrd} Xcol=min:max:binsize, Ycol= ..., Zcol=..., Tcol=...; weight] 6741\end{verbatim} 6742in which up to 4 columns, each corresponding to an axis of the image, 6743are listed. The column names are case insensitive, and the column 6744number may be given instead of the name, preceded by a pound sign 6745(e.g., [bin \#4=1:512]). If the column name is not specified, then 6746CFITSIO will first try to use the 'preferred column' as specified by 6747the CPREF keyword if it exists (e.g., 'CPREF = 'DETX,DETY'), otherwise 6748column names 'X', 'Y', 'Z', and 'T' will be assumed for each of the 4 6749axes, respectively. In cases where the column name could be confused 6750with an arithmetic expression, enclose the column name in parentheses to 6751force the name to be interpreted literally. 6752 6753Each column name may be followed by an equals sign and then the lower 6754and upper range of the histogram, and the size of the histogram bins, 6755separated by colons. Spaces are allowed before and after the equals 6756sign but not within the 'min:max:binsize' string. The min, max and 6757binsize values may be integer or floating point numbers, or they may be 6758the names of keywords in the header of the table. If the latter, then 6759the value of that keyword is substituted into the expression. 6760 6761Default values for the min, max and binsize quantities will be 6762used if not explicitly given in the binning expression as shown 6763in these examples: 6764 6765\begin{verbatim} 6766 [bin x = :512:2] - use default minimum value 6767 [bin x = 1::2] - use default maximum value 6768 [bin x = 1:512] - use default bin size 6769 [bin x = 1:] - use default maximum value and bin size 6770 [bin x = :512] - use default minimum value and bin size 6771 [bin x = 2] - use default minimum and maximum values 6772 [bin x] - use default minimum, maximum and bin size 6773 [bin 4] - default 2-D image, bin size = 4 in both axes 6774 [bin] - default 2-D image 6775\end{verbatim} 6776CFITSIO will use the value of the TLMINn, TLMAXn, and TDBINn keywords, 6777if they exist, for the default min, max, and binsize, respectively. If 6778they do not exist then CFITSIO will use the actual minimum and maximum 6779values in the column for the histogram min and max values. The default 6780binsize will be set to 1, or (max - min) / 10., whichever is smaller, 6781so that the histogram will have at least 10 bins along each axis. 6782 6783A shortcut notation is allowed if all the columns/axes have the same 6784binning specification. In this case all the column names may be listed 6785within parentheses, followed by the (single) binning specification, as 6786in: 6787 6788\begin{verbatim} 6789 [bin (X,Y)=1:512:2] 6790 [bin (X,Y) = 5] 6791\end{verbatim} 6792 6793The optional weighting factor is the last item in the binning specifier 6794and, if present, is separated from the list of columns by a 6795semi-colon. As the histogram is accumulated, this weight is used to 6796incremented the value of the appropriated bin in the histogram. If the 6797weighting factor is not specified, then the default weight = 1 is 6798assumed. The weighting factor may be a constant integer or floating 6799point number, or the name of a keyword containing the weighting value. 6800Or the weighting factor may be the name of a table column in which case 6801the value in that column, on a row by row basis, will be used. 6802 6803In some cases, the column or keyword may give the reciprocal of the 6804actual weight value that is needed. In this case, precede the weight 6805keyword or column name by a slash '/' to tell CFITSIO to use the 6806reciprocal of the value when constructing the histogram. 6807 6808For complex or commonly used histograms, one can also place its 6809description into a text file and import it into the binning 6810specification using the syntax '[bin @filename.txt]'. The file's 6811contents can extend over multiple lines, although it must still 6812conform to the no-spaces rule for the min:max:binsize syntax and each 6813axis specification must still be comma-separated. Any lines in the 6814external text file that begin with 2 slash characters ('//') will be 6815ignored and may be used to add comments into the file. 6816 6817 Examples: 6818 6819 6820\begin{verbatim} 6821 [bini detx, dety] - 2-D, 16-bit integer histogram 6822 of DETX and DETY columns, using 6823 default values for the histogram 6824 range and binsize 6825 6826 [bin (detx, dety)=16; /exposure] - 2-D, 32-bit real histogram of DETX 6827 and DETY columns with a bin size = 16 6828 in both axes. The histogram values 6829 are divided by the EXPOSURE keyword 6830 value. 6831 6832 [bin time=TSTART:TSTOP:0.1] - 1-D lightcurve, range determined by 6833 the TSTART and TSTOP keywords, 6834 with 0.1 unit size bins. 6835 6836 [bin pha, time=8000.:8100.:0.1] - 2-D image using default binning 6837 of the PHA column for the X axis, 6838 and 1000 bins in the range 6839 8000. to 8100. for the Y axis. 6840 6841 [bin @binFilter.txt] - Use the contents of the text file 6842 binFilter.txt for the binning 6843 specifications. 6844 6845\end{verbatim} 6846 6847 6848\chapter{Template Files } 6849 6850When a new FITS file is created with a call to fits\_create\_file, the 6851name of a template file may be supplied in parentheses immediately 6852following the name of the new file to be created. This template is 6853used to define the structure of one or more HDUs in the new file. The 6854template file may be another FITS file, in which case the newly created 6855file will have exactly the same keywords in each HDU as in the template 6856FITS file, but all the data units will be filled with zeros. The 6857template file may also be an ASCII text file, where each line (in 6858general) describes one FITS keyword record. The format of the ASCII 6859template file is described in the following sections. 6860 6861 6862\section{Detailed Template Line Format} 6863 6864The format of each ASCII template line closely follows the format of a 6865FITS keyword record: 6866 6867\begin{verbatim} 6868 KEYWORD = KEYVALUE / COMMENT 6869\end{verbatim} 6870except that free format may be used (e.g., the equals sign may appear 6871at any position in the line) and TAB characters are allowed and are 6872treated the same as space characters. The KEYVALUE and COMMENT fields 6873are optional. The equals sign character is also optional, but it is 6874recommended that it be included for clarity. Any template line that 6875begins with the pound '\#' character is ignored by the template parser 6876and may be use to insert comments into the template file itself. 6877 6878The KEYWORD name field is limited to 8 characters in length and only 6879the letters A-Z, digits 0-9, and the hyphen and underscore characters 6880may be used, without any embedded spaces. Lowercase letters in the 6881template keyword name will be converted to uppercase. Leading spaces 6882in the template line preceding the keyword name are generally ignored, 6883except if the first 8 characters of a template line are all blank, then 6884the entire line is treated as a FITS comment keyword (with a blank 6885keyword name) and is copied verbatim into the FITS header. 6886 6887The KEYVALUE field may have any allowed FITS data type: character 6888string, logical, integer, real, complex integer, or complex real. Integer 6889values must be within the allowed range of a 'signed long' variable; 6890some C compilers only suppport 4-byte long integers with a range 6891from -2147483648 to +2147483647, whereas other C compilers support 8-byte 6892integers with a range of plus or minus 2**63. 6893 6894The character string values need not be enclosed in single quote characters 6895unless they are necessary to distinguish the string from a different 6896data type (e.g. 2.0 is a real but '2.0' is a string). The keyword has 6897an undefined (null) value if the template record only contains blanks 6898following the "=" or between the "=" and the "/" comment field 6899delimiter. 6900 6901String keyword values longer than 68 characters (the maximum length 6902that will fit in a single FITS keyword record) are permitted using the 6903CFITSIO long string convention. They can either be specified as a 6904single long line in the template, or by using multiple lines where the 6905continuing lines contain the 'CONTINUE' keyword, as in this example: 6906 6907\begin{verbatim} 6908 LONGKEY = 'This is a long string value that is contin&' 6909 CONTINUE 'ued over 2 records' / comment field goes here 6910\end{verbatim} 6911The format of template lines with CONTINUE keyword is very strict: 3 6912spaces must follow CONTINUE and the rest of the line is copied verbatim 6913to the FITS file. 6914 6915The start of the optional COMMENT field must be preceded by "/", which 6916is used to separate it from the keyword value field. Exceptions are if 6917the KEYWORD name field contains COMMENT, HISTORY, CONTINUE, or if the 6918first 8 characters of the template line are blanks. 6919 6920More than one Header-Data Unit (HDU) may be defined in the template 6921file. The start of an HDU definition is denoted with a SIMPLE or 6922XTENSION template line: 6923 69241) SIMPLE begins a Primary HDU definition. SIMPLE may only appear as 6925the first keyword in the template file. If the template file begins 6926with XTENSION instead of SIMPLE, then a default empty Primary HDU is 6927created, and the template is then assumed to define the keywords 6928starting with the first extension following the Primary HDU. 6929 69302) XTENSION marks the beginning of a new extension HDU definition. The 6931previous HDU will be closed at this point and processing of the next 6932extension begins. 6933 6934 6935\section{Auto-indexing of Keywords} 6936 6937If a template keyword name ends with a "\#" character, it is said to be 6938'auto-indexed'. Each "\#" character will be replaced by the current 6939integer index value, which gets reset = 1 at the start of each new HDU 6940in the file (or 7 in the special case of a GROUP definition). The 6941FIRST indexed keyword in each template HDU definition is used as the 6942'incrementor'; each subsequent occurrence of this SAME keyword will 6943cause the index value to be incremented. This behavior can be rather 6944subtle, as illustrated in the following examples in which the TTYPE 6945keyword is the incrementor in both cases: 6946 6947\begin{verbatim} 6948 TTYPE# = TIME 6949 TFORM# = 1D 6950 TTYPE# = RATE 6951 TFORM# = 1E 6952\end{verbatim} 6953will create TTYPE1, TFORM1, TTYPE2, and TFORM2 keywords. But if the 6954template looks like, 6955 6956\begin{verbatim} 6957 TTYPE# = TIME 6958 TTYPE# = RATE 6959 TFORM# = 1D 6960 TFORM# = 1E 6961\end{verbatim} 6962this results in a FITS files with TTYPE1, TTYPE2, TFORM2, and TFORM2, 6963which is probably not what was intended! 6964 6965 6966\section{Template Parser Directives} 6967 6968In addition to the template lines which define individual keywords, the 6969template parser recognizes 3 special directives which are each preceded 6970by the backslash character: \verb+ \include, \group+, and \verb+ \end+. 6971 6972The 'include' directive must be followed by a filename. It forces the 6973parser to temporarily stop reading the current template file and begin 6974reading the include file. Once the parser reaches the end of the 6975include file it continues parsing the current template file. Include 6976files can be nested, and HDU definitions can span multiple template 6977files. 6978 6979The start of a GROUP definition is denoted with the 'group' directive, 6980and the end of a GROUP definition is denoted with the 'end' directive. 6981Each GROUP contains 0 or more member blocks (HDUs or GROUPs). Member 6982blocks of type GROUP can contain their own member blocks. The GROUP 6983definition itself occupies one FITS file HDU of special type (GROUP 6984HDU), so if a template specifies 1 group with 1 member HDU like: 6985 6986\begin{verbatim} 6987\group 6988grpdescr = 'demo' 6989xtension bintable 6990# this bintable has 0 cols, 0 rows 6991\end 6992\end{verbatim} 6993then the parser creates a FITS file with 3 HDUs : 6994 6995\begin{verbatim} 69961) dummy PHDU 69972) GROUP HDU (has 1 member, which is bintable in HDU number 3) 69983) bintable (member of GROUP in HDU number 2) 6999\end{verbatim} 7000Technically speaking, the GROUP HDU is a BINTABLE with 6 columns. Applications 7001can define additional columns in a GROUP HDU using TFORMn and TTYPEn 7002(where n is 7, 8, ....) keywords or their auto-indexing equivalents. 7003 7004For a more complicated example of a template file using the group directives, 7005look at the sample.tpl file that is included in the CFITSIO distribution. 7006 7007 7008\section{Formal Template Syntax} 7009 7010The template syntax can formally be defined as follows: 7011 7012\begin{verbatim} 7013 TEMPLATE = BLOCK [ BLOCK ... ] 7014 7015 BLOCK = { HDU | GROUP } 7016 7017 GROUP = \GROUP [ BLOCK ... ] \END 7018 7019 HDU = XTENSION [ LINE ... ] { XTENSION | \GROUP | \END | EOF } 7020 7021 LINE = [ KEYWORD [ = ] ] [ VALUE ] [ / COMMENT ] 7022 7023 X ... - X can be present 1 or more times 7024 { X | Y } - X or Y 7025 [ X ] - X is optional 7026\end{verbatim} 7027 7028At the topmost level, the template defines 1 or more template blocks. Blocks 7029can be either HDU (Header Data Unit) or a GROUP. For each block the parser 7030creates 1 (or more for GROUPs) FITS file HDUs. 7031 7032 7033 7034\section{Errors} 7035 7036In general the fits\_execute\_template() function tries to be as atomic 7037as possible, so either everything is done or nothing is done. If an 7038error occurs during parsing of the template, fits\_execute\_template() 7039will (try to) delete the top level BLOCK (with all its children if any) 7040in which the error occurred, then it will stop reading the template file 7041and it will return with an error. 7042 7043 7044\section{Examples} 7045 70461. This template file will create a 200 x 300 pixel image, with 4-byte 7047integer pixel values, in the primary HDU: 7048 7049\begin{verbatim} 7050 SIMPLE = T 7051 BITPIX = 32 7052 NAXIS = 2 / number of dimensions 7053 NAXIS1 = 100 / length of first axis 7054 NAXIS2 = 200 / length of second axis 7055 OBJECT = NGC 253 / name of observed object 7056\end{verbatim} 7057The allowed values of BITPIX are 8, 16, 32, -32, or -64, 7058representing, respectively, 8-bit integer, 16-bit integer, 32-bit 7059integer, 32-bit floating point, or 64 bit floating point pixels. 7060 70612. To create a FITS table, the template first needs to include 7062XTENSION = TABLE or BINTABLE to define whether it is an ASCII or binary 7063table, and NAXIS2 to define the number of rows in the table. Two 7064template lines are then needed to define the name (TTYPEn) and FITS data 7065format (TFORMn) of the columns, as in this example: 7066 7067\begin{verbatim} 7068 xtension = bintable 7069 naxis2 = 40 7070 ttype# = Name 7071 tform# = 10a 7072 ttype# = Npoints 7073 tform# = j 7074 ttype# = Rate 7075 tunit# = counts/s 7076 tform# = e 7077\end{verbatim} 7078The above example defines a null primary array followed by a 40-row 7079binary table extension with 3 columns called 'Name', 'Npoints', and 7080'Rate', with data formats of '10A' (ASCII character string), '1J' 7081(integer) and '1E' (floating point), respectively. Note that the other 7082required FITS keywords (BITPIX, NAXIS, NAXIS1, PCOUNT, GCOUNT, TFIELDS, 7083and END) do not need to be explicitly defined in the template because 7084their values can be inferred from the other keywords in the template. 7085This example also illustrates that the templates are generally 7086case-insensitive (the keyword names and TFORMn values are converted to 7087upper-case in the FITS file) and that string keyword values generally 7088do not need to be enclosed in quotes. 7089 7090 7091\chapter{ Summary of all FITSIO User-Interface Subroutines } 7092 7093 Error Status Routines page~\pageref{FTVERS} 7094 7095\begin{verbatim} 7096 FTVERS( > version) 7097 FTGERR(status, > errtext) 7098 FTGMSG( > errmsg) 7099 FTRPRT (stream, > status) 7100 FTPMSG(errmsg) 7101 FTPMRK 7102 FTCMSG 7103 FTCMRK 7104\end{verbatim} 7105 FITS File Open and Close Subroutines: page~\pageref{FTOPEN} 7106 7107\begin{verbatim} 7108 FTOPEN(unit,filename,rwmode, > blocksize,status) 7109 FTDKOPN(unit,filename,rwmode, > blocksize,status) 7110 FTNOPN(unit,filename,rwmode, > status) 7111 FTDOPN(unit,filename,rwmode, > status) 7112 FTTOPN(unit,filename,rwmode, > status) 7113 FTIOPN(unit,filename,rwmode, > status) 7114 FTREOPEN(unit, > newunit, status) 7115 FTINIT(unit,filename,blocksize, > status) 7116 FTDKINIT(unit,filename,blocksize, > status) 7117 FTTPLT(unit, filename, tplfilename, > status) 7118 FTFLUS(unit, > status) 7119 FTCLOS(unit, > status) 7120 FTDELT(unit, > status) 7121 FTGIOU( > iounit, status) 7122 FTFIOU(iounit, > status) 7123 CFITS2Unit(fitsfile *ptr) (C routine) 7124 CUnit2FITS(int unit) (C routine) 7125 FTEXTN(filename, > nhdu, status) 7126 FTFLNM(unit, > filename, status) 7127 FTFLMD(unit, > iomode, status) 7128 FTURLT(unit, > urltype, status) 7129 FTIURL(filename, > filetype, infile, outfile, extspec, filter, 7130 binspec, colspec, status) 7131 FTRTNM(filename, > rootname, status) 7132 FTEXIST(filename, > exist, status) 7133\end{verbatim} 7134 HDU-Level Operations: page~\pageref{FTMAHD} 7135 7136\begin{verbatim} 7137 FTMAHD(unit,nhdu, > hdutype,status) 7138 FTMRHD(unit,nmove, > hdutype,status) 7139 FTGHDN(unit, > nhdu) 7140 FTMNHD(unit, hdutype, extname, extver, > status) 7141 FTGHDT(unit, > hdutype, status) 7142 FTTHDU(unit, > hdunum, status) 7143 FTCRHD(unit, > status) 7144 FTIIMG(unit,bitpix,naxis,naxes, > status) 7145 FTITAB(unit,rowlen,nrows,tfields,ttype,tbcol,tform,tunit,extname, > 7146 status) 7147 FTIBIN(unit,nrows,tfields,ttype,tform,tunit,extname,varidat > status) 7148 FTRSIM(unit,bitpix,naxis,naxes,status) 7149 FTDHDU(unit, > hdutype,status) 7150 FTCPFL(iunit,ounit,previous, current, following, > status) 7151 FTCOPY(iunit,ounit,morekeys, > status) 7152 FTCPHD(inunit, outunit, > status) 7153 FTCPDT(iunit,ounit, > status) 7154\end{verbatim} 7155 Subroutines to specify or modify the structure of the CHDU: page~\pageref{FTRDEF} 7156 7157\begin{verbatim} 7158 FTRDEF(unit, > status) (DEPRECATED) 7159 FTPDEF(unit,bitpix,naxis,naxes,pcount,gcount, > status) (DEPRECATED) 7160 FTADEF(unit,rowlen,tfields,tbcol,tform,nrows > status) (DEPRECATED) 7161 FTBDEF(unit,tfields,tform,varidat,nrows > status) (DEPRECATED) 7162 FTDDEF(unit,bytlen, > status) (DEPRECATED) 7163 FTPTHP(unit,theap, > status) 7164\end{verbatim} 7165 Header Space and Position Subroutines: page~\pageref{FTHDEF} 7166 7167\begin{verbatim} 7168 FTHDEF(unit,morekeys, > status) 7169 FTGHSP(iunit, > keysexist,keysadd,status) 7170 FTGHPS(iunit, > keysexist,key_no,status) 7171\end{verbatim} 7172 Read or Write Standard Header Subroutines: page~\pageref{FTPHPR} 7173 7174\begin{verbatim} 7175 FTPHPS(unit,bitpix,naxis,naxes, > status) 7176 FTPHPR(unit,simple,bitpix,naxis,naxes,pcount,gcount,extend, > status) 7177 FTGHPR(unit,maxdim, > simple,bitpix,naxis,naxes,pcount,gcount,extend, 7178 status) 7179 FTPHTB(unit,rowlen,nrows,tfields,ttype,tbcol,tform,tunit,extname, > 7180 status) 7181 FTGHTB(unit,maxdim, > rowlen,nrows,tfields,ttype,tbcol,tform,tunit, 7182 extname,status) 7183 FTPHBN(unit,nrows,tfields,ttype,tform,tunit,extname,varidat > status) 7184 FTGHBN(unit,maxdim, > nrows,tfields,ttype,tform,tunit,extname,varidat, 7185 status) 7186\end{verbatim} 7187 Write Keyword Subroutines: page~\pageref{FTPREC} 7188 7189\begin{verbatim} 7190 FTPREC(unit,card, > status) 7191 FTPCOM(unit,comment, > status) 7192 FTPHIS(unit,history, > status) 7193 FTPDAT(unit, > status) 7194 FTPKY[JKLS](unit,keyword,keyval,comment, > status) 7195 FTPKY[EDFG](unit,keyword,keyval,decimals,comment, > status) 7196 FTPKLS(unit,keyword,keyval,comment, > status) 7197 FTPLSW(unit, > status) 7198 FTPKYU(unit,keyword,comment, > status) 7199 FTPKN[JKLS](unit,keyroot,startno,no_keys,keyvals,comments, > status) 7200 FTPKN[EDFG](unit,keyroot,startno,no_keys,keyvals,decimals,comments, > 7201 status) 7202 FTCPKYinunit, outunit, innum, outnum, keyroot, > status) 7203 FTPKYT(unit,keyword,intval,dblval,comment, > status) 7204 FTPKTP(unit, filename, > status) 7205 FTPUNT(unit,keyword,units, > status) 7206\end{verbatim} 7207 Insert Keyword Subroutines: page~\pageref{FTIREC} 7208 7209\begin{verbatim} 7210 FTIREC(unit,key_no,card, > status) 7211 FTIKY[JKLS](unit,keyword,keyval,comment, > status) 7212 FTIKLS(unit,keyword,keyval,comment, > status) 7213 FTIKY[EDFG](unit,keyword,keyval,decimals,comment, > status) 7214 FTIKYU(unit,keyword,comment, > status) 7215\end{verbatim} 7216 Read Keyword Subroutines: page~\pageref{FTGREC} 7217 7218\begin{verbatim} 7219 FTGREC(unit,key_no, > card,status) 7220 FTGKYN(unit,key_no, > keyword,value,comment,status) 7221 FTGCRD(unit,keyword, > card,status) 7222 FTGNXK(unit,inclist,ninc,exclist,nexc, > card,status) 7223 FTGKEY(unit,keyword, > value,comment,status) 7224 FTGKY[EDJKLS](unit,keyword, > keyval,comment,status) 7225 FTGKSL(unit,keyword, > length,status) 7226 FTGSKY(unit,keyword,firstchar,maxchar,> keyval,length,comment,status) 7227 FTGKN[EDJKLS](unit,keyroot,startno,max_keys, > keyvals,nfound,status) 7228 FTGKYT(unit,keyword, > intval,dblval,comment,status) 7229 FTGUNT(unit,keyword, > units,status) 7230\end{verbatim} 7231 Modify Keyword Subroutines: page~\pageref{FTMREC} 7232 7233\begin{verbatim} 7234 FTMREC(unit,key_no,card, > status) 7235 FTMCRD(unit,keyword,card, > status) 7236 FTMNAM(unit,oldkey,keyword, > status) 7237 FTMCOM(unit,keyword,comment, > status) 7238 FTMKY[JKLS](unit,keyword,keyval,comment, > status) 7239 FTMKLS(unit,keyword,keyval,comment, > status) 7240 FTMKY[EDFG](unit,keyword,keyval,decimals,comment, > status) 7241 FTMKYU(unit,keyword,comment, > status) 7242\end{verbatim} 7243 Update Keyword Subroutines: page~\pageref{FTUCRD} 7244 7245\begin{verbatim} 7246 FTUCRD(unit,keyword,card, > status) 7247 FTUKY[JKLS](unit,keyword,keyval,comment, > status) 7248 FTUKLS(unit,keyword,keyval,comment, > status) 7249 FTUKY[EDFG](unit,keyword,keyval,decimals,comment, > status) 7250 FTUKYU(unit,keyword,comment, > status) 7251\end{verbatim} 7252 Delete Keyword Subroutines: page~\pageref{FTDREC} 7253 7254\begin{verbatim} 7255 FTDREC(unit,key_no, > status) 7256 FTDKEY(unit,keyword, > status) 7257\end{verbatim} 7258 Define Data Scaling Parameters and Undefined Pixel Flags: page~\pageref{FTPSCL} 7259 7260\begin{verbatim} 7261 FTPSCL(unit,bscale,bzero, > status) 7262 FTTSCL(unit,colnum,tscal,tzero, > status) 7263 FTPNUL(unit,blank, > status) 7264 FTSNUL(unit,colnum,snull > status) 7265 FTTNUL(unit,colnum,tnull > status) 7266\end{verbatim} 7267 FITS Primary Array or IMAGE Extension I/O Subroutines: page~\pageref{FTPPR} 7268 7269\begin{verbatim} 7270 FTGIDT(unit, > bitpix,status) 7271 FTGIET(unit, > bitpix,status) 7272 FTGIDM(unit, > naxis,status) 7273 FTGISZ(unit, maxdim, > naxes,status) 7274 FTGIPR(unit, maxdim, > bitpix,naxis,naxes,status) 7275 FTPPR[BIJKED](unit,group,fpixel,nelements,values, > status) 7276 FTPPN[BIJKED](unit,group,fpixel,nelements,values,nullval > status) 7277 FTPPRU(unit,group,fpixel,nelements, > status) 7278 FTGPV[BIJKED](unit,group,fpixel,nelements,nullval, > values,anyf,status) 7279 FTGPF[BIJKED](unit,group,fpixel,nelements, > values,flagvals,anyf,status) 7280 FTPGP[BIJKED](unit,group,fparm,nparm,values, > status) 7281 FTGGP[BIJKED](unit,group,fparm,nparm, > values,status) 7282 FTP2D[BIJKED](unit,group,dim1,naxis1,naxis2,image, > status) 7283 FTP3D[BIJKED](unit,group,dim1,dim2,naxis1,naxis2,naxis3,cube, > status) 7284 FTG2D[BIJKED](unit,group,nullval,dim1,naxis1,naxis2, > image,anyf,status) 7285 FTG3D[BIJKED](unit,group,nullval,dim1,dim2,naxis1,naxis2,naxis3, > 7286 cube,anyf,status) 7287 FTPSS[BIJKED](unit,group,naxis,naxes,fpixels,lpixels,array, > status) 7288 FTGSV[BIJKED](unit,group,naxis,naxes,fpixels,lpixels,incs,nullval, > 7289 array,anyf,status) 7290 FTGSF[BIJKED](unit,group,naxis,naxes,fpixels,lpixels,incs, > 7291 array,flagvals,anyf,status) 7292\end{verbatim} 7293 Table Column Information Subroutines: page~\pageref{FTGCNO} 7294 7295\begin{verbatim} 7296 FTGNRW(unit, > nrows, status) 7297 FTGNCL(unit, > ncols, status) 7298 FTGCNO(unit,casesen,coltemplate, > colnum,status) 7299 FTGCNN(unit,casesen,coltemplate, > colnam,colnum,status) 7300 FTGTCL(unit,colnum, > datacode,repeat,width,status) 7301 FTEQTY(unit,colnum, > datacode,repeat,width,status) 7302 FTGCDW(unit,colnum, > dispwidth,status) 7303 FTGACL(unit,colnum, > 7304 ttype,tbcol,tunit,tform,tscal,tzero,snull,tdisp,status) 7305 FTGBCL(unit,colnum, > 7306 ttype,tunit,datatype,repeat,tscal,tzero,tnull,tdisp,status) 7307 FTPTDM(unit,colnum,naxis,naxes, > status) 7308 FTGTDM(unit,colnum,maxdim, > naxis,naxes,status) 7309 FTDTDM(unit,tdimstr,colnum,maxdim, > naxis,naxes, status) 7310 FTGRSZ(unit, > nrows,status) 7311\end{verbatim} 7312 Low-Level Table Access Subroutines: page~\pageref{FTGTBS} 7313 7314\begin{verbatim} 7315 FTGTBS(unit,frow,startchar,nchars, > string,status) 7316 FTPTBS(unit,frow,startchar,nchars,string, > status) 7317 FTGTBB(unit,frow,startchar,nchars, > array,status) 7318 FTPTBB(unit,frow,startchar,nchars,array, > status) 7319\end{verbatim} 7320 Edit Rows or Columns page~\pageref{FTIROW} 7321 7322\begin{verbatim} 7323 FTIROW(unit,frow,nrows, > status) 7324 FTDROW(unit,frow,nrows, > status) 7325 FTDRRG(unit,rowrange, > status) 7326 FTDRWS(unit,rowlist,nrows, > status) 7327 FTICOL(unit,colnum,ttype,tform, > status) 7328 FTICLS(unit,colnum,ncols,ttype,tform, > status) 7329 FTMVEC(unit,colnum,newveclen, > status) 7330 FTDCOL(unit,colnum, > status) 7331 FTCPCL(inunit,outunit,incolnum,outcolnum,createcol, > status); 7332\end{verbatim} 7333 Read and Write Column Data Routines page~\pageref{FTPCLS} 7334 7335\begin{verbatim} 7336 FTPCL[SLBIJKEDCM](unit,colnum,frow,felem,nelements,values, > status) 7337 FTPCN[BIJKED](unit,colnum,frow,felem,nelements,values,nullval > status) 7338 FTPCLX(unit,colnum,frow,fbit,nbit,lray, > status) 7339 FTPCLU(unit,colnum,frow,felem,nelements, > status) 7340 FTGCL(unit,colnum,frow,felem,nelements, > values,status) 7341 FTGCV[SBIJKEDCM](unit,colnum,frow,felem,nelements,nullval, > 7342 values,anyf,status) 7343 FTGCF[SLBIJKEDCM](unit,colnum,frow,felem,nelements, > 7344 values,flagvals,anyf,status) 7345 FTGSV[BIJKED](unit,colnum,naxis,naxes,fpixels,lpixels,incs,nullval, > 7346 array,anyf,status) 7347 FTGSF[BIJKED](unit,colnum,naxis,naxes,fpixels,lpixels,incs, > 7348 array,flagvals,anyf,status) 7349 FTGCX(unit,colnum,frow,fbit,nbit, > lray,status) 7350 FTGCX[IJD](unit,colnum,frow,nrows,fbit,nbit, > array,status) 7351 FTGDES(unit,colnum,rownum, > nelements,offset,status) 7352 FTPDES(unit,colnum,rownum,nelements,offset, > status) 7353\end{verbatim} 7354 Row Selection and Calculator Routines: page~\pageref{FTFROW} 7355 7356\begin{verbatim} 7357 FTFROW(unit,expr,firstrow, nrows, > n_good_rows, row_status, status) 7358 FTFFRW(unit, expr, > rownum, status) 7359 FTSROW(inunit, outunit, expr, > status ) 7360 FTCROW(unit,datatype,expr,firstrow,nelements,nulval, > 7361 array,anynul,status) 7362 FTCALC(inunit, expr, outunit, parName, parInfo, > status) 7363 FTCALC_RNG(inunit, expr, outunit, parName, parInfo, 7364 nranges, firstrow, lastrow, > status) 7365 FTTEXP(unit, expr, > datatype, nelem, naxis, naxes, status) 7366\end{verbatim} 7367 Celestial Coordinate System Subroutines: page~\pageref{FTGICS} 7368 7369\begin{verbatim} 7370 FTGICS(unit, > xrval,yrval,xrpix,yrpix,xinc,yinc,rot,coordtype,status) 7371 FTGTCS(unit,xcol,ycol, > 7372 xrval,yrval,xrpix,yrpix,xinc,yinc,rot,coordtype,status) 7373 FTWLDP(xpix,ypix,xrval,yrval,xrpix,yrpix,xinc,yinc,rot, 7374 coordtype, > xpos,ypos,status) 7375 FTXYPX(xpos,ypos,xrval,yrval,xrpix,yrpix,xinc,yinc,rot, 7376 coordtype, > xpix,ypix,status) 7377\end{verbatim} 7378 File Checksum Subroutines: page~\pageref{FTPCKS} 7379 7380\begin{verbatim} 7381 FTPCKS(unit, > status) 7382 FTUCKS(unit, > status) 7383 FTVCKS(unit, > dataok,hduok,status) 7384 FTGCKS(unit, > datasum,hdusum,status) 7385 FTESUM(sum,complement, > checksum) 7386 FTDSUM(checksum,complement, > sum) 7387 7388\end{verbatim} 7389 Time and Date Utility Subroutines: page~\pageref{FTGSDT} 7390 7391\begin{verbatim} 7392 FTGSDT( > day, month, year, status ) 7393 FTGSTM(> datestr, timeref, status) 7394 FTDT2S( year, month, day, > datestr, status) 7395 FTTM2S( year, month, day, hour, minute, second, decimals, 7396 > datestr, status) 7397 FTS2DT(datestr, > year, month, day, status) 7398 FTS2TM(datestr, > year, month, day, hour, minute, second, status) 7399\end{verbatim} 7400 General Utility Subroutines: page~\pageref{FTGHAD} 7401 7402\begin{verbatim} 7403 FTGHAD(unit, > curaddr,nextaddr) 7404 FTUPCH(string) 7405 FTCMPS(str_template,string,casesen, > match,exact) 7406 FTTKEY(keyword, > status) 7407 FTTREC(card, > status) 7408 FTNCHK(unit, > status) 7409 FTGKNM(unit, > keyword, keylength, status) 7410 FTMKKY(keyword, value,comment, > card, status) 7411 FTPSVC(card, > value,comment,status) 7412 FTKEYN(keyroot,seq_no, > keyword,status) 7413 FTNKEY(seq_no,keyroot, > keyword,status) 7414 FTDTYP(value, > dtype,status) 7415 class = FTGKCL(card) 7416 FTASFM(tform, > datacode,width,decimals,status) 7417 FTBNFM(tform, > datacode,repeat,width,status) 7418 FTGABC(tfields,tform,space, > rowlen,tbcol,status) 7419 FTGTHD(template, > card,hdtype,status) 7420 FTRWRG(rowlist, maxrows, maxranges, > numranges, rangemin, 7421 rangemax, status) 7422\end{verbatim} 7423 7424\chapter{ Parameter Definitions } 7425 7426\begin{verbatim} 7427anyf - (logical) set to TRUE if any of the returned data values are undefined 7428array - (any datatype except character) array of bytes to be read or written. 7429bitpix - (integer) bits per pixel: 8, 16, 32, -32, or -64 7430blank - (integer) value used for undefined pixels in integer primary array 7431blank - (integer*8) value used for undefined pixels in integer primary array 7432blocksize - (integer) 2880-byte logical record blocking factor 7433 (if 0 < blocksize < 11) or the actual block size in bytes 7434 (if 10 < blocksize < 28800). As of version 3.3 of FITSIO, 7435 blocksizes greater than 2880 are no longer supported. 7436bscale - (double precision) scaling factor for the primary array 7437bytlen - (integer) length of the data unit, in bytes 7438bzero - (double precision) zero point for primary array scaling 7439card - (character*80) header record to be read or written 7440casesen - (logical) will string matching be case sensitive? 7441checksum - (character*16) encoded checksum string 7442colname - (character) ASCII name of the column 7443colnum - (integer) number of the column (first column = 1) 7444coltemplate - (character) template string to be matched to column names 7445comment - (character) the keyword comment field 7446comments - (character array) keyword comment fields 7447compid - (integer) the type of computer that the program is running on 7448complement - (logical) should the checksum be complemented? 7449coordtype - (character) type of coordinate projection (-SIN, -TAN, -ARC, 7450 -NCP, -GLS, -MER, or -AIT) 7451cube - 3D data cube of the appropriate datatype 7452curaddr - (integer) starting address (in bytes) of the CHDU 7453current - (integer) if not equal to 0, copy the current HDU 7454datacode - (integer) symbolic code of the binary table column datatype 7455dataok - (integer) was the data unit verification successful (=1) or 7456 not (= -1). Equals zero if the DATASUM keyword is not present. 7457datasum - (double precision) 32-bit 1's complement checksum for the data unit 7458datatype - (character) datatype (format) of the binary table column 7459datestr - (string) FITS date/time string: 'YYYY-MM-DDThh:mm:ss.ddd', 7460 'YYYY-MM-dd', or 'dd/mm/yy' 7461day - (integer) current day of the month 7462dblval - (double precision) fractional part of the keyword value 7463decimals - (integer) number of decimal places to be displayed 7464dim1 - (integer) actual size of the first dimension of the image or cube array 7465dim2 - (integer) actual size of the second dimension of the cube array 7466dispwidth - (integer) - the display width (length of string) for a column 7467dtype - (character) datatype of the keyword ('C', 'L', 'I', or 'F') 7468 C = character string 7469 L = logical 7470 I = integer 7471 F = floating point number 7472errmsg - (character*80) oldest error message on the internal stack 7473errtext - (character*30) descriptive error message corresponding to error number 7474casesen - (logical) true if column name matching is case sensitive 7475exact - (logical) do the strings match exactly, or were wildcards used? 7476exclist (character array) list of names to be excluded from search 7477exists - flag indicating whether the file or compressed file exists on disk 7478extend - (logical) true if there may be extensions following the primary data 7479extname - (character) value of the EXTNAME keyword (if not blank) 7480fbit - (integer) first bit in the field to be read or written 7481felem - (integer) first pixel of the element vector (ignored for ASCII tables) 7482filename - (character) name of the FITS file 7483flagvals - (logical array) True if corresponding data element is undefined 7484following - (integer) if not equal to 0, copy all following HDUs in the input file 7485fparm - (integer) sequence number of the first group parameter to read or write 7486fpixel - (integer) the first pixel position 7487fpixels - (integer array) the first included pixel in each dimension 7488frow - (integer) beginning row number (first row of table = 1) 7489frowll - (integer*8) beginning row number (first row of table = 1) 7490gcount - (integer) value of the GCOUNT keyword (usually = 1) 7491group - (integer) sequence number of the data group (=0 for non-grouped data) 7492hdtype - (integer) header record type: -1=delete; 0=append or replace; 7493 1=append; 2=this is the END keyword 7494hduok - (integer) was the HDU verification successful (=1) or 7495 not (= -1). Equals zero if the CHECKSUM keyword is not present. 7496hdusum - (double precision) 32 bit 1's complement checksum for the entire CHDU 7497hdutype - (integer) type of HDU: 0 = primary array or IMAGE, 1 = ASCII table, 7498 2 = binary table, -1 = any HDU type or unknown type 7499history - (character) the HISTORY keyword comment string 7500hour - (integer) hour from 0 - 23 7501image - 2D image of the appropriate datatype 7502inclist (character array) list of names to be included in search 7503incs - (integer array) sampling interval for pixels in each FITS dimension 7504intval - (integer) integer part of the keyword value 7505iounit - (integer) value of an unused I/O unit number 7506iunit - (integer) logical unit number associated with the input FITS file, 1-300 7507key_no - (integer) sequence number (starting with 1) of the keyword record 7508keylength - (integer) length of the keyword name 7509keyroot - (character) root string for the keyword name 7510keysadd -(integer) number of new keyword records which can fit in the CHU 7511keysexist - (integer) number of existing keyword records in the CHU 7512keyval - value of the keyword in the appropriate datatype 7513keyvals - (array) value of the keywords in the appropriate datatype 7514keyword - (character*8) name of a keyword 7515lray - (logical array) array of logical values corresponding to the bit array 7516lpixels - (integer array) the last included pixel in each dimension 7517match - (logical) do the 2 strings match? 7518maxdim - (integer) dimensioned size of the NAXES, TTYPE, TFORM or TUNIT arrays 7519max_keys - (integer) maximum number of keywords to search for 7520minute - (integer) minute of an hour (0 - 59) 7521month - (integer) current month of the year (1 - 12) 7522morekeys - (integer) will leave space in the header for this many more keywords 7523naxes - (integer array) size of each dimension in the FITS array 7524naxesll - (integer*8 array) size of each dimension in the FITS array 7525naxis - (integer) number of dimensions in the FITS array 7526naxis1 - (integer) length of the X/first axis of the FITS array 7527naxis2 - (integer) length of the Y/second axis of the FITS array 7528naxis3 - (integer) length of the Z/third axis of the FITS array 7529nbit - (integer) number of bits in the field to read or write 7530nchars - (integer) number of characters to read and return 7531ncols - (integer) number of columns 7532nelements - (integer) number of data elements to read or write 7533nelementsll - (integer*8) number of data elements to read or write 7534nexc (integer) number of names in the exclusion list (may = 0) 7535nhdu - (integer) absolute number of the HDU (1st HDU = 1) 7536ninc (integer) number of names in the inclusion list 7537nmove - (integer) number of HDUs to move (+ or -), relative to current position 7538nfound - (integer) number of keywords found (highest keyword number) 7539no_keys - (integer) number of keywords to write in the sequence 7540nparm - (integer) number of group parameters to read or write 7541nrows - (integer) number of rows in the table 7542nrowsll - (integer*8) number of rows in the table 7543nullval - value to represent undefined pixels, of the appropriate datatype 7544nextaddr - (integer) starting address (in bytes) of the HDU following the CHDU 7545offset - (integer) byte offset in the heap to the first element of the array 7546offsetll - (integer*8) byte offset in the heap to the first element of the array 7547oldkey - (character) old name of keyword to be modified 7548ounit - (integer) logical unit number associated with the output FITS file 1-300 7549pcount - (integer) value of the PCOUNT keyword (usually = 0) 7550previous - (integer) if not equal to 0, copy all previous HDUs in the input file 7551repeat - (integer) length of element vector (e.g. 12J); ignored for ASCII table 7552rot - (double precision) celestial coordinate rotation angle (degrees) 7553rowlen - (integer) length of a table row, in characters or bytes 7554rowlenll - (integer*8) length of a table row, in characters or bytes 7555rowlist - (integer array) list of row numbers to be deleted in increasing order 7556rownum - (integer) number of the row (first row = 1) 7557rowrange- (string) list of rows or row ranges to be deleted 7558rwmode - (integer) file access mode: 0 = readonly, 1 = readwrite 7559second (double)- second within minute (0 - 60.9999999999) (leap second!) 7560seq_no - (integer) the sequence number to append to the keyword root name 7561simple - (logical) does the FITS file conform to all the FITS standards 7562snull - (character) value used to represent undefined values in ASCII table 7563space - (integer) number of blank spaces to leave between ASCII table columns 7564startchar - (integer) first character in the row to be read 7565startno - (integer) value of the first keyword sequence number (usually 1) 7566status - (integer) returned error status code (0 = OK) 7567str_template (character) template string to be matched to reference string 7568stream - (character) output stream for the report: either 'STDOUT' or 'STDERR' 7569string - (character) character string 7570sum - (double precision) 32 bit unsigned checksum value 7571tbcol - (integer array) column number of the first character in the field(s) 7572tdisp - (character) Fortran type display format for the table column 7573template-(character) template string for a FITS header record 7574tfields - (integer) number of fields (columns) in the table 7575tform - (character array) format of the column(s); allowed values are: 7576 For ASCII tables: Iw, Aw, Fww.dd, Eww.dd, or Dww.dd 7577 For binary tables: rL, rX, rB, rI, rJ, rA, rAw, rE, rD, rC, rM 7578 where 'w'=width of the field, 'd'=no. of decimals, 'r'=repeat count 7579 Note that the 'rAw' form is non-standard extension to the 7580 TFORM keyword syntax that is not specifically defined in the 7581 Binary Tables definition document. 7582theap - (integer) zero indexed byte offset of starting address of the heap 7583 relative to the beginning of the binary table data 7584tnull - (integer) value used to represent undefined values in binary table 7585tnullll - (integer*8) value used to represent undefined values in binary table 7586ttype - (character array) label for table column(s) 7587tscal - (double precision) scaling factor for table column 7588tunit - (character array) physical unit for table column(s) 7589tzero - (double precision) scaling zero point for table column 7590unit - (integer) logical unit number associated with the FITS file (1-300) 7591units - (character) the keyword units string (e.g., 'km/s') 7592value - (character) the keyword value string 7593values - array of data values of the appropriate datatype 7594varidat - (integer) size in bytes of the 'variable length data area' 7595 following the binary table data (usually = 0) 7596version - (real) current revision number of the library 7597width - (integer) width of the character string field 7598xcol - (integer) number of the column containing the X coordinate values 7599xinc - (double precision) X axis coordinate increment at reference pixel (deg) 7600xpix - (double precision) X axis pixel location 7601xpos - (double precision) X axis celestial coordinate (usually RA) (deg) 7602xrpix - (double precision) X axis reference pixel array location 7603xrval - (double precision) X axis coordinate value at the reference pixel (deg) 7604ycol - (integer) number of the column containing the X coordinate values 7605year - (integer) last 2 digits of the year (00 - 99) 7606yinc - (double precision) Y axis coordinate increment at reference pixel (deg) 7607ypix - (double precision) y axis pixel location 7608ypos - (double precision) y axis celestial coordinate (usually DEC) (deg) 7609yrpix - (double precision) Y axis reference pixel array location 7610yrval - (double precision) Y axis coordinate value at the reference pixel (deg) 7611\end{verbatim} 7612 7613\chapter{ FITSIO Error Status Codes } 7614 7615\begin{verbatim} 7616Status codes in the range -99 to -999 and 1 to 999 are reserved for future 7617FITSIO use. 7618 7619 0 OK, no error 7620101 input and output files are the same 7621103 too many FITS files open at once; all internal buffers full 7622104 error opening existing file 7623105 error creating new FITS file; (does a file with this name already exist?) 7624106 error writing record to FITS file 7625107 end-of-file encountered while reading record from FITS file 7626108 error reading record from file 7627110 error closing FITS file 7628111 internal array dimensions exceeded 7629112 Cannot modify file with readonly access 7630113 Could not allocate memory 7631114 illegal logical unit number; must be between 1 - 300, inclusive 7632115 NULL input pointer to routine 7633116 error seeking position in file 7634 7635121 invalid URL prefix on file name 7636122 tried to register too many IO drivers 7637123 driver initialization failed 7638124 matching driver is not registered 7639125 failed to parse input file URL 7640126 parse error in range list 7641 7642151 bad argument in shared memory driver 7643152 null pointer passed as an argument 7644153 no more free shared memory handles 7645154 shared memory driver is not initialized 7646155 IPC error returned by a system call 7647156 no memory in shared memory driver 7648157 resource deadlock would occur 7649158 attempt to open/create lock file failed 7650159 shared memory block cannot be resized at the moment 7651 7652 7653201 header not empty; can't write required keywords 7654202 specified keyword name was not found in the header 7655203 specified header record number is out of bounds 7656204 keyword value field is blank 7657205 keyword value string is missing the closing quote character 7658206 illegal indexed keyword name (e.g. 'TFORM1000') 7659207 illegal character in keyword name or header record 7660208 keyword does not have expected name. Keyword out of sequence? 7661209 keyword does not have expected integer value 7662210 could not find the required END header keyword 7663211 illegal BITPIX keyword value 7664212 illegal NAXIS keyword value 7665213 illegal NAXISn keyword value: must be 0 or positive integer 7666214 illegal PCOUNT keyword value 7667215 illegal GCOUNT keyword value 7668216 illegal TFIELDS keyword value 7669217 negative ASCII or binary table width value (NAXIS1) 7670218 negative number of rows in ASCII or binary table (NAXIS2) 7671219 column name (TTYPE keyword) not found 7672220 illegal SIMPLE keyword value 7673221 could not find the required SIMPLE header keyword 7674222 could not find the required BITPIX header keyword 7675223 could not find the required NAXIS header keyword 7676224 could not find all the required NAXISn keywords in the header 7677225 could not find the required XTENSION header keyword 7678226 the CHDU is not an ASCII table extension 7679227 the CHDU is not a binary table extension 7680228 could not find the required PCOUNT header keyword 7681229 could not find the required GCOUNT header keyword 7682230 could not find the required TFIELDS header keyword 7683231 could not find all the required TBCOLn keywords in the header 7684232 could not find all the required TFORMn keywords in the header 7685233 the CHDU is not an IMAGE extension 7686234 illegal TBCOL keyword value; out of range 7687235 this operation only allowed for ASCII or BINARY table extension 7688236 column is too wide to fit within the specified width of the ASCII table 7689237 the specified column name template matched more than one column name 7690241 binary table row width is not equal to the sum of the field widths 7691251 unrecognizable type of FITS extension 7692252 unrecognizable FITS record 7693253 END keyword contains non-blank characters in columns 9-80 7694254 Header fill area contains non-blank characters 7695255 Data fill area contains non-blank on non-zero values 7696261 unable to parse the TFORM keyword value string 7697262 unrecognizable TFORM datatype code 7698263 illegal TDIMn keyword value 7699 7700301 illegal HDU number; less than 1 or greater than internal buffer size 7701302 column number out of range (1 - 999) 7702304 attempt to move to negative file record number 7703306 attempted to read or write a negative number of bytes in the FITS file 7704307 illegal starting row number for table read or write operation 7705308 illegal starting element number for table read or write operation 7706309 attempted to read or write character string in non-character table column 7707310 attempted to read or write logical value in non-logical table column 7708311 illegal ASCII table TFORM format code for attempted operation 7709312 illegal binary table TFORM format code for attempted operation 7710314 value for undefined pixels has not been defined 7711317 attempted to read or write descriptor in a non-descriptor field 7712320 number of array dimensions out of range 7713321 first pixel number is greater than the last pixel number 7714322 attempt to set BSCALE or TSCALn scaling parameter = 0 7715323 illegal axis length less than 1 7716 7717340 NOT_GROUP_TABLE 340 Grouping function error 7718341 HDU_ALREADY_MEMBER 7719342 MEMBER_NOT_FOUND 7720343 GROUP_NOT_FOUND 7721344 BAD_GROUP_ID 7722345 TOO_MANY_HDUS_TRACKED 7723346 HDU_ALREADY_TRACKED 7724347 BAD_OPTION 7725348 IDENTICAL_POINTERS 7726349 BAD_GROUP_ATTACH 7727350 BAD_GROUP_DETACH 7728 7729360 NGP_NO_MEMORY malloc failed 7730361 NGP_READ_ERR read error from file 7731362 NGP_NUL_PTR null pointer passed as an argument. 7732 Passing null pointer as a name of 7733 template file raises this error 7734363 NGP_EMPTY_CURLINE line read seems to be empty (used 7735 internally) 7736364 NGP_UNREAD_QUEUE_FULL cannot unread more then 1 line (or single 7737 line twice) 7738365 NGP_INC_NESTING too deep include file nesting (infinite 7739 loop, template includes itself ?) 7740366 NGP_ERR_FOPEN fopen() failed, cannot open template file 7741367 NGP_EOF end of file encountered and not expected 7742368 NGP_BAD_ARG bad arguments passed. Usually means 7743 internal parser error. Should not happen 7744369 NGP_TOKEN_NOT_EXPECT token not expected here 7745 7746401 error attempting to convert an integer to a formatted character string 7747402 error attempting to convert a real value to a formatted character string 7748403 cannot convert a quoted string keyword to an integer 7749404 attempted to read a non-logical keyword value as a logical value 7750405 cannot convert a quoted string keyword to a real value 7751406 cannot convert a quoted string keyword to a double precision value 7752407 error attempting to read character string as an integer 7753408 error attempting to read character string as a real value 7754409 error attempting to read character string as a double precision value 7755410 bad keyword datatype code 7756411 illegal number of decimal places while formatting floating point value 7757412 numerical overflow during implicit datatype conversion 7758413 error compressing image 7759414 error uncompressing image 7760420 error in date or time conversion 7761 7762431 syntax error in parser expression 7763432 expression did not evaluate to desired type 7764433 vector result too large to return in array 7765434 data parser failed not sent an out column 7766435 bad data encounter while parsing column 7767436 parse error: output file not of proper type 7768 7769501 celestial angle too large for projection 7770502 bad celestial coordinate or pixel value 7771503 error in celestial coordinate calculation 7772504 unsupported type of celestial projection 7773505 required celestial coordinate keywords not found 7774506 approximate wcs keyword values were returned 7775\end{verbatim} 7776\end{document} 7777