ADC FITS Table Browser, Version 3.0 This program reads standard FITS ASCII tables and allows the user to interactively browse through them and selectively display any field or record in a table. File extraction allows for writing all or part of the input table to disk in FITS or text file format. Copies of the program for MS-DOS and Unix are available by anonymous FTP on hypatia.gsfc.nasa.gov, in directory /pub/software/ftb. Version 1 of the program was written in Turbo Pascal and was released along with the ADC CD-ROM Test Disk. Version 2 was mainly a rewrite of Version 1 in Turbo C and was limited to MS-DOS platforms. This version uses the curses screen management package, and has been compiled and run on MS-DOS 4.01 and 5.0, Silicon Graphics IRIX 4.0.1 (System V), Sun Microsystems SunOS 4.1.2 (BSD), DECstation 5000 Ultrix 2.4 (BSD), and Linux 0.99pl8 (System V, mostly). The look and feel is similar to Version 2, being a command-based interface (loosely modelled on the KEDIT text editor, for those PC users familiar with that product). GETTING STARTED -- MS-DOS Get the file FTB3.ZIP by anonymous FTP from hypatia.gsfc.nasa.gov in directory /pub/software/ftb. Create a directory on your hard disk called FTB and unzip the contents of this file into that directory. For example, (assuming the FTB3.ZIP is in the root directory of drive C:), C:\> MKDIR FTB C:\> CD FTB C:\FTB> PKUNZIP ..\FTB3 Source code for FTB 3.0 is contained in the file FTB3SRC.ZIP (included inside the main ZIP archive). To compile FTB on an MS-DOS platform, you will need Borland C and a set of curses libraries. The libraries I used for development are in the file PCCURS14.ZIP in the same directory on Hypatia where FTB was found. Diffs and makefile changes to compile FTB using Microsoft C would be greatly appreciated. Before running FTB, it is best to add the FTB directory to your path by editing the PATH statement in your AUTOEXEC.BAT file. At startup, FTB looks for its help file by first looking in the directory pointed to by an environment variable called "FTB", and then by inspecting the path. To ensure proper operation of FTB add the following two lines to the bottom of your AUTOEXEC.BAT file and reboot the computer: SET FTB=C:\FTB PATH=%PATH%;%FTB% GETTING STARTED -- Unix First of all you will need an ANSI C compiler. I make no apologies for writing ANSI code, and GCC is available for just about any platform. If you don't have access to an ANSI compiler and are using an SGI 4D or Indigo, Sun SPARC, or DECstation MIPS machine, I can arrange to send you a binary. Get the file ftb3.tar.Z by anonymous FTP from hypatia.gsfc.nasa.gov in directory /pub/software/ftb. The following command will uncompress and untar the source code into a subdirectory called 'ftb': $ zcat ../ftb3.tar | tar xf - Bring the Makefile into your favorite editor and look over the definitions for the CC, CFLAGS and LFLAGS macros. Examples for SGI, Sun, Ultrix and Linux are given; adjust to taste (please tell me about any changes so that I can incorporate them into subsequent releases, especially on the Sun, where I had to fiddle with the library and include paths to get to System V curses). Then just type 'make' and see what happens. If the compile finished successfully, you should set an environment variable to point to the FTB directory and add the FTB directory to your path. Without the environment variable, the ftb executable and the help file, ftb.hlp, have to be in a directory on the path. An example from my .login file under csh and Ultrix 4.2 is: setenv FTB ~/ftb set path = ($path $FTB) An example from my .profile under bash (the Bourne-Again Shell) and Linux: set FTB=~/ftb set PATH=$PATH:$FTB Note that in both cases the redefinition of the PATH variable takes place after any other PATH settings. I generally put these statements last in the startup script. RUNNING FTB Once the program is installed, the MS-DOS and Unix versions operate identically. When the program is started up, you should see a screen like: =============================================================================== Path: /home/leb/ftb Files: 0 Tables: 0 Lines: 1/17 FTB> ----+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8 ADC FITS Table Browser, Version 3.0 Written by: Lee E. Brotzman Hughes STX Astronomical Data Center NASA Goddard Space Flight Center Work performed under Contract NAS5-30960 This program is Public Domain, but no warranty, expressed or implied, is made by NASA or the ADC as to the accuracy and functioning of the software. =============================================================================== The top line, also known as the status line, gives the current path, the number of files currently open, the total number of tables contained in those files, and the size of the current screen buffer (17 lines total and the top line is line 1). FTB commands are blank-delimited, case-insensitive strings. You only have to give enough characters of the command to make it unique; 'HELP', 'Help', and 'h' are all equivalent to 'help', whereas 'l' means 'left' and 'li' means 'list'. The shorthand may be confusing at first, but it makes typing commands a lot easier once you are familiar with it. Any command that FTB doesn't understand it simply passes on to the operating system, so you can use 'dir' under MS-DOS or 'ls' under Unix to get directory listings, etc. If the name of an OS command conflicts with an FTB command you can still execute it with the 'system' command, e.g. 'system list ftb.hlp' would invoke the 'list' program from an OS command shell. The first command you should enter is 'help'. This will show you all the commands available to FTB. The commands 'up', 'down', 'left', 'right', 'top' and 'bottom' will scroll through the screen text. FTB has a default command that is executed by just hitting a carriage return. The default command is initially 'down half', meaning that the display should scroll down half a 'page'. So, you can scroll through the help text returned by the 'help' command just by hitting a few carriage returns. The 'set' command can be used to reset the default command and a few other options. Enter 'help set' to get a description. FTB is distributed with a small FITS file to use for testing. This is the file pln.fit which is the Strasbourg Planetary Nebulae catalog. You open a FITS file with the command, 'open '. Saying 'open pln.fit' will open the file, decode the FITS header information and display a listing of the COMMENT keywords found in the primary header. =============================================================================== *** NOTE *** FTB is tailored to work best with the FITS tables found on the ADC CD-ROM, Selected Astronomical Catalogs, Volume I. Those tables have overall descriptions of the catalog in COMMENT keywords in the primary header, hence the behavior of the 'open' command. There are some other features of the CD-ROM FITS tables that I take advantage of, like the tagged field COMMENT cards in the table headers. If FTB acts strangely or crashes while browsing other tables, and if the tables are legal FITS, I would really like to get a copy of that FITS table so that I can fix the problems. If FTB crashes while reading one the ADC CD-ROM FITS tables, well then I'm really in trouble. =============================================================================== Once the table is open, the 'list' command will give you information about the number and names of active tables, information about individual tables, and lists of field descriptions. The output of the 'list' command can be redirected to a disk file. FTB keeps track of tables by setting a pointer to the 'current table'. Initially the current table is set to be the first table of the most recently opened FITS file (FTB can open more than one FITS file and any file can have more than one table, up to a limit of 20 individual tables). The 'list' command marks the current table with an asterisk. Most FTB commands have a 'table' option that defines which table the command should be applied to. This will automatically reset the current table. The 'browse' command displays the records of the table. This puts FTB into BROWSE mode, as noted by the change in the prompt from "FTB>" to "BROWSE>". The 'up', 'down', 'left', 'right', 'top', and 'bottom' commands work as normal, but any other command that writes information to the screen, e.g. 'help', will clear browse mode. The main difference between browse and command modes is how the information on the screen is retrieved. In command mode an entire "internal text file" is built with all the screen text. In browse mode, each record is retrieved individually from the FITS file and displayed immediately. The 'display' command can be used to set which fields to display. For instance, for pln.fit, FTB> display pk rah ram decsign+decd decm v will restrict the display to just the PK number, equatorial coordinates and visual magnitude. The '+' between decsign and decd tells FTB to display those two fields right next to each other, without an intervening blank space. It is also possible to put specific fields into specific screen columns, see 'help display' for more information. The 'select' command is used to restrict which records to display by placing constraints on field values. For example, FTB> select v >= 18 will restrict the display to only those nebulae with visual magnitudes greater than or equal to 18. It is possible to test a field against the "null" value in the TNULL record of the FITS header. For example, using only the following, FTB> select v < 18 will select records with the visual magnitude less than 18. But, since the default, i.e. TNULL, value of the field is blank, default fields convert to 0 and will pass this test, which is probably not what you want. To get only those records with valid visual magnitudes less than 18, enter, FTB> select v < 18 & !null(v) which means to select visual magnitudes less then 18 that are not equal to the null value. The null() "pseudo-function" tests the given field for exact string equality with the value of the corresponding TNULL keyword and returns true for a match and false otherwise. The operators for the select command have alphabetic equivalents (for closet FORTRAN programmers out there like me), so the 'select' command above can also be entered like this: FTB> select v lt 18 and not null(v) Or you can mix and match and add parentheses like: FTB> select (v lt 18) & (not null(v)) Note that after entering a 'select' command, you have to execute 'browse' again to see the selected records. The 'extract' command will write to disk all selected records exactly as they would have been displayed on the screen. For instance if the above 'display' and 'select' commands are in force, FTB> extract test.fit will extract the PK number, equatorial coordinates, and non-null visual magnitudes for all nebulae with V < 18 into the file test.fit, which is in FITS format. Open test.fit and go into browse mode to confirm the operation. It is also possible to extract the data into a plain text file with the command, FTB> extract text test.txt See 'help extract' for more information. FTB has a 'batch mode' that allows you to put a sequence of FTB commands into an ordinary text file and execute them. The 'take' command will accept the name of the batch file, or you can invoke batch mode when the program is started up with the '-t' command line parameter. For example: $ ftb -t pln.ftb will startup FTB and execute the commands in file 'pln.ftb', which is included in the standard distribution. The most important command is 'exit', which has an alias of 'quit'. There are a bunch more features that I leave as an exercise for the HELP file reader. I suggest that you print the help file, ftb.hlp. It's in plain ASCII format and marks the entry for each command with a period in column 1 followed by the command name, for example .BROWSE marks the definition of the browse command. CONTACTING THE AUTHOR I can be contacted by E-mail at leb@hypatia.gsfc.nasa.gov. BUG REPORTS Please use the following form for reporting bugs and other worthless "features". -------------------------------< Cut Here >--------------------------------- FTB 3.0 BUG REPORT Return to: Lee E. Brotzman leb@hypatia.gsfc.nasa.gov Name: E-Mail: Platform: (e.g. Sun, Indigo) Op. Sys.: (e.g. Ultrix 4.2A) Compiler: (e.g. GCC 4.3.3) Shell: (e.g. ksh) FITS File: (by name if on ADC CD-ROM, else describe the file and its source) FTB Command(s): (if possible, give the sequence that generates the error) Description of error -- please be as specific as possible: