November 20, 1998

			    ===== SUMMARY =====

This document contains information about the FTOOLS package,
version 4.2, with emphasis on changes to the package since the
last release, FTOOLS version 4.1.  For online information, please
see our website at:

For correspondence regarding the subpackage XRONOS ONLY, please

For online information on the HEASARC, including other software
packages such as XANADU, please see:

			===== SUPPORT FOR WINDOWS =====

By far the most significant new development in FTOOLS V4.2 is the
addition of support for the MS Windows NT/95/98 operating system
family.  This was accomplished by layering the FTOOLS on top of the
Cygwin tools, a UNIX-like API for Windows.  For more information on
the Cygwin Project, see their web site:

The Windows version of the FTOOLS is available in binary form
only; it was built from source at the HEASARC using the versions
of the GNU development tools which are bundled with the Cygwin
tools.  The source code is identical to the UNIX version, and may
be separately obtained for reference, but installation from
source code is not supported.  For information on installing
the Windows version of FTOOLS 4.2, please see the file

		    ===== YEAR 2000 (Y2K) COMPLIANCE =====

    With release 4.2, we believe that the FTOOLS are ready for 2000.
In particular, we have transitioned them to the new format for FITS
dates, YYYY-MM-DD.  All programs and library routines should now
understand both this and the old DD/MM/YY format (which in accordance
with the FITS standard will be interpretted as 19YY, usually), but in
general they will write only new-format dates.  Our intention is that
old data files should be usable without conversion; please let us know
if you run into trouble.

    Date/time keyword pairs (e.g., DATE-OBS/TIME-OBS, DATE-END/TIME-END)
have *not* been combined into the full FITS date/time format
("yyyy-mm-ddThh:mm:ss.s"); they will remain as separate keywords for
the date and the time.  However, the file-creation DATE keywords and
many HISTORY keywords *do* now use the combined format.

    Date keywords that are merely copied from an input file are not
usually converted to the new format, so in some cases it is possible
to have, for instance, DATE-OBS in the old format and DATE-END in the
new one.  A few FTOOLS will write old-format dates for 1900 <= year <=
1998, and new-format ones for other years; these include sf2pha,
ascii2pha, eaddmap, fesdb2rdf, fbbft2pha, and fbdrm2rmf.  ascalin will
write HISTORY keywords with old-format dates until we can wean its
author off CFITSIO version 1.

    FTOOLS for some old, long-inactive missions, such as Vela-5B, will
continue to write old-format DATE-OBS and DATE-END strings (although
new-format file-creation dates).  This is so that users' seldom-used,
non-FTOOL, analysis programs will not have to be changed.  Since these
missions ended long before 2000, we believe that there is no
possibility of misinterpretation or an overflow.  Where these FTOOLS
take user-input dates, either format may be used.

    These changes required modifications in many source files
throughout the FTOOLS.  While we think we found them all, it is
possible that we missed some.  If you find any incompatibilities or
stray old-format dates, please send the details to us at, and we wish you an enjoyable

			 ===== SPECIFIC CHANGES =====

For each of the FTOOLS subpackages below are listed the
tools which are new in v4.2 as well as brief descriptions
of the major changes to preexisting tools.  After the
FTOOLS package is installed, more information on any
FTOOL can be obtained by typing "fhelp ".
Type "fhelp ftools" to obtain a full listing of all the
tools available in v4.2, or "fhelp " to list
all of the tools in a particular subpackage.

			 ===== CFITSIO/FITSIO =====

This release of ftools uses the new CFITSIO 2.0 library which provides
the following new features to all the ftools tasks:

	Any FITS file on the internet can be opened by giving the full
	ftp or http URL.

	Rows in FITS tables may be filtered/selected  on the fly as
	they are read by CFITSIO using a user-supplied expression.  The
	application program then only sees the selected rows.

	Columns in FITS tables may be created, modified, or deleted on
	the fly when the file is opened based on a user-supplied

	Columns in a table may be binned/histogrammed on the fly as the
	file is opened.  The application program then only sees the
	binned image and not the original table.

	IRAF format image files (.imh files) may be read, as well as
	FITS files.

	A FITS file may be opened more than once simultaneously by a
	program, and data may be read or written to two or more
	different extensions in the file at the same time.

	Numerical overflows when reading FITS keywords now result in a
	returned error status instead of being ignored.

Type 'fhelp filenames' for more information about the extended filename
syntax now supported by all the FTOOLS tasks.

                              ===== FV =====
===> New since v4.1 <===

   - Internet support has been added.  Files can be read via the http and
     ftp protocols.  Ftp sites can be browsed with the "Open File" dialog

   - Filename completion has been added to the "Open File" dialog box.
     Type the initial characters of a file name and press TAB.  Fv will
     look for a file starting with those characters.

   - Basic fv functions (open, display, and plot data) can be controlled
     with simple TCL scripts.

   - New, empty FITS files can be created.  Empty extensions of any of
     the 3 types (image, ASCII Table, Binary Table) can be appended to
     existing files.

   - Checksum keywords can be created or updated when a file is modified.

   - Keyboard shortcuts (ctrl-c and ctrl-v) have been added for copying
     and pasteing data in the table display window.

   - When displaying an image in POW, double-clicking the image will cause
     fv to open the corresponding FITS extension as a table and highlight
     the clicked pixel.

   - POW can create contour maps of images.

   - More curve plotting options have been added to POW.  Each curve can
     have its own line style/width, point shape/size, and color.

   - The Edit Graph dialog boxes have been modified to make them simpler,
     more intuitive, and more powerful.  One can easily control the contents
     of a given graph, the plotting styles of its curves, and the axis
     parameters (label, bounds, etc) from a single window.

   - Graphs containing images can be rescaled to arbitrary sizes in both
     the X and Y directions.  (No more snapping to integral magsteps.)

   - Removed restriction on the production of mosaics from images with
     different pixel sizes.

                             ===== ASCA =====

(*) For complete details and up-to-date information on using FTOOLS v4.2
    to analyze ASCA data, please refer to:

===> New since v4.1 <===

        gis2bitfix - Perl version of gis3bitfix.e tool, fixes
                     science files affected by the GIS3 3 bit
                     LSB error

===> Bug Fixes and Minor changes since v4.1 <===

        addascaspec - Now works with previously added response files.

        ascaarf - Fixed bug in generating arfs for GIS at 64x64 resolution.
                  Fixed bug that caused a crash if the GIS WMAP region was
                  expanded to the whole detector (256 bins).

        ascaeffmap - Fixed bugs in generating efficiency maps for SIS.

        correctrdd - Fixed a bug in writing an output keyword, RDDCOR_V.

        mkfilter2 - If Euler angles can't be set from the attitude
                    file, set them to `undefined' (-99.999) instead
                    of user input angles.  Get the orbital element
                    epoch from the HK file header, not the filename.
                    Warn if orbit file extrapolated more than 15 days.
                    Fixed a bug in calculating the sun elevation that
                    could give sqrt() domain errors.  Spell header
                    comments correctly.

===> Major changes since v4.1 <===

     * Extrapolate the attitude file up to the time given by new
       parameter `attmargin' (default 32 seconds)
     * New parameter `redosatf' (default yes) gives user option to not
       recalculate the SIS saturation flags (previously always were)
     * Output .mkf file START column now 23 characters wide and contains
       a FITS-standard new-format date/time string.  MJD-OBS and checksum
       keywords are written.

                          ===== CALTOOLS ===== 

===> No changes since v4.1 <===

                           ===== EINSTEIN =====
===> No changes since v4.1 <===

                            ===== EXAMPLES =====

===> No changes since v4.1 <===

                             ===== EXOSAT =====

 These are new tools to analyze the EXOSAT CMA data reformatted in FITS
 format.  These tools work on the EXOSAT CMA FITS files as available in
 the HEASARC archive.  Further information about the EXOSAT mission, archive
 and software will be available in the near future from

===> New since v4.1 <===

    automerge  -- Create a list of compatible event files for a given
                  observation, and output a merged event file by running
    cmadead    -- Correct EXOSAT CMA lightcurves and images for deadtime.
    exoleuv    -- Estimate the stellar UV count rate for different CMA filters
    exomerge   -- Merge files from a given observation.  The output can be
                  used in xselect.
    exopha     -- Create one channel spectrum for the EXOSAT CMA
    exovig     -- Give the vignetting correction factor for the EXOSAT LE
    tkexomerge -- Create a list of event files via tk interface & run exomerge

                            ===== FIMAGE =====

===> Major changes since v4.1 <===

     * Rewritten in C to support new command-line filtering and improve
       speed 2-3 times
     * cpprim and cphead parameters no longer supported 

                            ===== FUTILS =====

===> New since v4.1 <===

     cphead -- Copy keywords from an HDU of an input file to an HDU of an
               output file.

    fcollen -- Modify the vector length of a column in a binary table
               extension of a fits file.

      fcopy -- Copy the contents of a FITS file to a new file (for use with
               new command-line filtering).

      fdiff -- Display differences between pairs of fits file.

   xfverify -- Verify that a FITS file conforms to the FITS Standard.
               (This is a faster, more capable replacement for fverify.)

===> Major changes since v4.1 <===

     * New arithmetic parser implemented, speeding operations by 10-40 times
     * File-based filters for SAO regions and GTI extensions added (see
       help file for details)
     * Expression can evaluate to BIT or STRING values

     * Rewritten in C to support new command-line filtering and improve
       speed 2-3 times
     * cpprim and cphead parameters no longer supported

     * New arithmetic parser implemented, speeding operations by 10-40 times
     * File-based filters for SAO regions and GTI extensions added (see
       help file for details)
     * % done progess report eliminated (due to speedup and problems with
       FITS file piping)

===> Bug Fixes and Minor changes since v4.1 <===

      fdump -- Unsigned integer columns with huge values handled properly

   ffilecat -- Output filename column retains extension number and any
               command-line filtering commands.

   fmemsort -- Bug Fix: Heap sort on table with 1 row no longer crashes

     fmerge -- Bug Fix: Column data types D and 1D now considered equal

      fsort -- Bug Fix: Null values recognized

                              ===== GRO =====

===> New since v4.1 <===

    bcmppha -- This ftool reads a standard OGIP PHA-II (multiple
               spectra) file as its input, and writes a PHA-I file
               (single spectrum) as its output.  The output
               spectrum is an average over a user-specfied set of
               rows spectra) from the input file.  The purpose is
               to construct source and background spectral data
               files for analysis of CGRO BATSE gamma-ray burst

    emapgen -- This ftool constructs counts maps from an
               EGRET photon list (qvp fits file).  The user can
               select energy ranges, bin sizes, time intervals
               and several other parameters.  This program is
               directly based on the EGRET science team program

                        ===== HEASARC =====

===> New since v4.1 <===

     gtisum -- This tool is designed to report on the total
               amount of good time in any or all of the GTI
               extensions in a valid FITS file.  Valid GTI
               extensions are designated by the presence of
               a HDUCLAS1 keyword containing the string "GTI".

===> Major changes since v4.1 <===

        extractor - Fixed detector images so that CTYPE do not imply RA & Dec
                       and comments do not mention degrees.
                    Added support for regions in WCS coordinates (as written
                       by eg SAOtng).
                    Changed the way the WMAP is handled in the case when the
                       region filter is not in detector coordinates - now no
                       longer has the problem that pixels with no events are
                       flagged as outside the selected region.
                    Added Y2K compatibility.
                    Fixed bug that always zeroed out the first channel of the
                       output spectrum.
                    Fixed bug in WMAP when WMAP binning differs from image
                    If a GTI filter file only has one table then assume that
                       it is the correct one whatever the EXTNAME value.
                    Sped up GTI filtering.
                    Fixed bug causing WMAP CDELT to be set incorrectly to the
                       image CDELT.

                             ===== OSO8 =====

These are new tools which allow to extract lightcurves for the B and C
detectors on the OSO8 Goddard Cosmic X-ray Spectrometer Experiment.
These tools work on the OSO8 rate data files in fits format as available
in the HEASARC archive.  Further information about the OSO8 mission, archive
and software will be available in the near future from:

===> New since v4.1 <===

    osofindfast  -- Give a file list of the OSO8 raw rate files
                    for a given sky position.

    osorat       -- extract a lightcurve from the OSO8 GCXSE B or
                    C detectors for a given sky position.

                             ===== ROSAT =====

===> No changes since v4.1 <===

                            ===== TIME =====

===> Major changes since v4.1 <===

     * New arithmetic parser implemented, speeding operations by 10-40 times
     * File-based filters for SAO regions and GTI extensions added (see
       help file for details)
     * (Bug) Lines longer than 80 characters in expression file (@expr) will
       not get truncated in the HISTORY keywords.

===> Bug Fixes and Minor changes since v4.1 <===

     fltime -- Bug Fix: TSTOP keyword properly set to last GTI STOP and
                        TELAPSE keyword calculated properly

     mgtime -- User warned about empty GTIs which are ignored

                           ===== VELA5B =====

===> No changes since v4.1 <===

                           ===== XRONOS =====

===> No Major changes since v4.1 <===

===> Bug Fixes and Minor changes since v4.1 <===

      rbf2fits  -- Y2k update

      earth2sun -- leap seconds update

      - Add half bin integration time to TSTART and TSTOP keywords
        in the lcurve output.

                           ===== XSELECT =====

	The latest version of the Xselect user's guide is available
	online at:

        Added support for XTE PCA Standard2 data.  Main change is
        to add detector option to the filter command to allow
        the user to select PCUs, layers, and anode sides.
        Added preliminary support for XMM EPIC.
        No longer require an @ in front of the filename of a list
        of files for the read command.

                              ===== XTE =====

For complete details and up-to-date information on using FTOOLS v4.2
to analyze RXTE data, please refer to:

===> New since v4.1 <===

   closereturn --- Uses the method of close returns to aid the user in
                   detecting unstable periodic orbits embedded in the
                   evolution of a time series.  Uses light curves as
                   input and displays the result as a two dimensional
                   image, as well as stores the image in an output file.

      decodeevt -- Decodes event keywords in XTE Science Event files and
                   generates  an  output  file  with  separate  columns
                   for TIME, CHANNEL, PCUID,  ANODE,  and  PROPANE.

       dyenspec -- Generates  dynamic  energy  spectrum for each row of
                   the input XTE Science Array data (mode 2), and then
                   displays  this  two dimensional image  on  the screen
                   as well as stores the image in an output file.  Users
                   can  look  at  the  spectrum  for  each  row by
                   clicking on the image.

===> Major changes since v4.1 <===

     Fixed bug that caused wrong channel-binning for some Event modes;
     now can use JPL DE405 ephemeris though default is still DE200;
     Linux-specific bugs fixed.

     Can collect scalar quantities from PCA science files and cycle over
     multiple files.  Calculates the additional quantities TIME_SINCE_SAA
     and ELECTRON[0-4] when the new appidlist is used (ck.  "xtefilt -h")

     TSTART/TSTOP now always correspond to first and last values in "Time"
     column.  TIMEPIXR keyword now present in filter files.  Now handles
     mixed production and realtime data in the same directory.

     This tool has been disabled in FTOOLS v4.2 due to incompatibilities
     with the current version of hxtdead.  A revised version will be
     released as part of an update to FTOOLS v4.2 in the near future.
     Please check our web site for up-to-date information on the release
     schedule for software updates.

     Uses an additional parameter, "saafile".
     (CHANGE MADE IN THE XTE v4.1.1 UPDATE, 26 JUNE 1998)

     CALDB removed as default for model files parameter (see for
     model file instructions); "syserr" parameter is now hidden and not
     recommended; correction applied for slow gain drift; fixed bugs
     on DEC Alphas; interpolation to 256 channels improved; documents
     which saa_history file used.

     Added options to specify alternate RA/DEC, in case of off-source pointings.

     Bug fixed which caused the tool to produce error messages and generate
     an incorrect output ascii channel file whenever the CPIXn keyword was
     longer than one line in the FITS header of the input .pha file.
     (CHANGE MADE IN THE XTE v4.1.1 UPDATE, 26 JUNE 1998)

     Major revisions related to making output acceptable to SAEXTRCT
     (1DELT2, 1CTYP2, TDDES2, ModeSpecific); XeCnt counts handled

===> Bug Fixes and Minor changes since v4.1 <===

Fixed pervasive bug performing formatted writes without specifying field
width; this only affected FTOOLS compiled from source distribution by
users with the most recent versions of g77 (ie, Linux only).  In the XTE
subpackage this applied to hxtarf, xpcaarf, pcaclrsp, and xtecol only.

     Removed case-sensitivity in input parameters.

     Made more robust; documentation improved.

     Bug fixed which caused crashes on some systems.
     (CHANGE MADE IN THE XTE v4.1.1 UPDATE, 26 JUNE 1998)

     Bug fixed which caused crashes on some systems.
     (CHANGE MADE IN THE XTE v4.1.1 UPDATE, 26 JUNE 1998)

     Time format increased to allow Time .ge.  1e08; bug fixed in handling
     null values while accumulating avg and std dev; fixed bug related
     to CALDB access

     IRIX-specific bug fixed; TUNIT2 keyword added to output file.

     Bug in retrieving energy-to-channel info from CALDB fixed.

     Change in handling of 1CPIX keyword; changed EXPOSURE computation.

     Bug fixed in Check_and_Write_Info subroutine which caused crashes
     in some circumstances.