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