	Instructions for the FITS Package for Unix

     This file explains how to compile, link, and use the library of routines
in the FITS Package on a Unix machine.  The package supports FITS files 
with NAXIS=2 or 3 and of extension type IMAGE.  If other extension types such
as TABLE are contained in a FITS file, they are at present, ignored.   In the
terminology used in the package, image extensions are referred to as "maps".  
Currently, a maximum of 256 maps are allowed in a FITS file.  
     The package includes the demonstration program testfits.exe which can
carry out the following operations on one or more FITS files:
 1.  Reads all or part of a row 
 2.  Plots a cut through a file
 3.  Reads an xy area
 4.  Displays an image on SAOimage (Enhanced version)
 5.  Writes all or part of a row for a new or existing file
 6.  Writes an xy area for a new or existing file
 7.  Performs simple rotations on a file
 8.  Performs simple arithmetic on a file
 9.  Performs a simple crop on a file
10.  Copies one or more maps (image extensions) from one file to another
11.  Copies a set of maps from one file to a set of planes in another file
12.  Prints the header
13.  Writes a COMMENT or HISTORY keycard to the header of an existing file
14.  Creates or updates a keycard with a string value, e.g., AUTHOR,
     CTYPEn, BUNIT, DATE, DATE-OBS, etc.
15.  Creates or updates the BSCALE and BZERO keycards for an existing file
16.  Replaces a keycard with blanks

     The demonstration program serves as an example of how to use
the package subprograms to create custom applications.  Files created
or modified with the FITS library routines have been tested with the
NASA FITS File Verifier program, accessible at
  http://fits.gsfc.nasa.gov/fits_verify.html
Also included with FITS library package are the plot package programs
plotcom.exe and xyplot_ascii.exe which are used for directing a plot file
to any supported plot device, for plotting data from an ASCII file on
any supported plot device, and for plotting data from one ASCII file
against another.

     To use the compiled versions on a Linux system with Intel processor, or
on Mac OS X system with Intel processor, download fits_linux_executables.tar-gz
or fits_macosintel_executables.tar-gz, respectively from the link at
http://www.chara.gsu.edu/~gudehus/fits_package.html, and then extract the
execute images and other files.  For Mac OS X PC system, download and 
extract the file fits_macosppc_executables.tar.gz.  The compiled versions 
should work on any of the above mentioned systems.

After the executables are on your system, you should define some aliases
which are described further below.

     If you wish or need to recompile, you can download the file
fits_unix_source.tar-gz from the download link at 
http://www.chara.gsu.edu/~gudehus/fits_package.html, and then extract the
source code and other files.
     Once you have fits_unix_source.tar-gz available on your Unix 
machine, just enter
  gzip -d fits_unix_source.tar-gz
  tar -xf fits_unix_source.tar
from a desired directory location.  Set default to the newly created fits
directory and enter
  make linux
for Linux systems, or
  make macosppc
for Mac OS X PPC systems, or
  make macosintel
for Mac OS X Intel systems, or,
  make ultrix
for Ultrix systems, and
  make unix
for other Unix systems.  It is also possible to use the command
  make -f makefile-fits.pgf77
for Linux systems for example.  Ignore any warning messages.

     The programs will compile and link on a DECstation with the
default compiler.  For Linux on Intel processors, and for Mac OS X
on Intel processors, you will need to have installed the Portland 
Group f77 compiler (http://www.pgroup.com).  A free 15-day trial 
version of their compiler is available from their website.  Their 
compiler also works for Solaris on Intel processors, but I have not 
tested this.  Presumably, the linux makefile should work for their 
compiler on Solaris as well.  Other brand compilers may possibly
work with this code but I have not investigated them.  For Mac OS X
PPC you will need to have installed the Absoft Pro Fortran compiler 
(http://www.absoft.com).  A free 30-day trial version of their 
compiler is available from their website.  The Absoft f77 compiler 
doesn't support variable FORMAT expressions which necessitated 
creating a special set of files just for that compiler.  Also, 
the Absoft compiler has a bug with handling %REF with character data.  
A special usrinp.for, i.e., usrinp_char.for, was created to handle 
this problem.  New subroutines for this and other limitations are 
located in the subdirectories mac_os_ppc.  The compiled PPC version 
will also run on Macintoshes which use the Intel processors and are 
able to run Rosetta.  The Portland Group's compiler for Mac OS X 
with Intel will also work with the Linux make file..
     For other Unix flavors the default f77 compiler may or may not work.
A compatible compiler should support BYTE data type, ENCODE, DECODE, %REF,
%VAL, variable FORMAT expressions, CARRIAGECONTROL keyword, and PARAMETER
statement with or without parentheses.  For the C code files, the
built-in compiler will work.

A brief description of the source code files follows.

In the directory fits_package, one should have the files:

   Name         				Description
arithmetic_fits_simple.for	   High-level routine to add a number to a
				   pixel value and multiply the result by
				   another number
binvalfits.for			   Reads/writes the values from keywords
				   CTYPEx, CRPIXx, CRVALx, and CDELTx 
				   from/to a FITS header
chfitsmhc.for			   Returns a comment from a FITS keyword
chfitsmhv.for			   Returns a character value from a FITS
				   keyword
closefits.for			   Closes a previously opened FITS file
copy_fits_maps.for		   High-level routine to copy selected
				   maps from one FITS file to another
				   existing or new FITS file.
copy_fits_records.for		   Routine to copy records from input
				   FITS file maps to output file maps.
crop_fits_simple.for		   High-level routine to crop the dimensions
				   of a map in a FITS file.  All planes are
				   cropped similarly.
display-plotting_availability.dat  List of available display/plot devices
fits_linux_executables.com	   Command file for tarring the executables
				   for linux
fits_mocosintel_executables.com    Like above but for Mac OS X with Intel 
fits_macosppc_executables.com	   Like above but for Mac OS X with Power PC
fits_ultrix_executables.com	   Like above but for Ultrix
fits_unix_executables.com	   Like above but for Unix
fits_maps_to_planes.for		   High-level routine to copy selected
				   maps from a FITS file to a single FITS
				   map with multiple planes.
fits_to_sao.for			   High-level routine to open a FITS file
				   and display it on Enhanced SAOimage.  The
				   entire image is scaled to fit the frame.
get_endian.for			   Routine to determine the system endian
				   and write the results to a common block
get_fits_info.for		   Routine to read a FITS file and put
				   essential information into the
				   FITSFACTS* COMMON blocks
get_input_fits_maps.for		   Routine to both open a FITS file and
				   request a set of maps for reading
get_output_fits_maps.for	   Routine to both open a FITS file and
				   request a set of maps for writing
				   where each map has an optional
				   independent size, number of planes,
				   and data format
i4fitsmhv.for			   Function to return an integer value
				   from a FITS header keyword
linepl_fits.for			   High-level routine to plot a cut
				   through a two-dimensional file
linepl1_fits.for		   Helper routine for linepl.for
linepl2_fits.for		   Helper routine for linepl.for
makefile			   General makefile to compile and 
				   link all the executables
makefile-fits.macosppc		   Makefile for Mac OS X PPC, w/Absoft
				   compiler.
makefile-fits.pgf77		   Makefile for Linux/Mac OS X, Intel
				   w/Portland Group compiler
makefile-fits.ultrix		   Makefile for Ultrix
makefile-fits.unix		   Makefile for other Unix
mhfitscrd.for			   Returns a header line from a FITS file
no_of_fits_maps.for		   Returns the number of maps in a FITS file
open_temp_fits.for		   Routine to open a temporary file when
				   saving to the same map or a different map
				   in the same or a new file.  Reguires the
				   a subsequent call to save_save_as.
openfits.for			   General routine for opening a FITS file
ploterrs.dat			   Plot package error messages
r4fitsmhv.for			   Function to return a REAL*4 value from a
				   FITS header keyword 
r8fitsmhv.for			   Function to return a REAL*8 value from a
				   FITS header keyword
rotate_fits_simple.for		   High-level routine to rotate a FITS file
rwfitsrow.for			   General routine to read/write a row of
				   data from/to a FITS file
rwfitsxy.for			   General routine to read/write an area of
				   data from/to a FITS file
saodels.for			   High-level routine to display a FITS
				   image on Enhanced SAOimage.  A selected
				   part of the image can be placed in a
				   selected part of the frame.
saoload.for			   Medium-level routine to display an
				   array of data on Enhanced SAOimage
save_save_as.for		   Routine for saving to the same file or
				   to a different file.  Requires a previous
				   call to open_temp_fits.
testfits.for			   The main demonstration program for the
				   FITS package
wrfitsmhst.for			   Routine to write keyword strings to FITS
				   headers
wrfitsmhv.for			   Routine to write keyword values to FITS
				   headers
xyplot_setup.dat		   Setup file for plotting from an ascii file
xyplot_setup1.dat		   Setup file for xyplot_ascii.exe in demo
xyplot_setup2.dat		   Setup file for xyplot_ascii.exe in demo

In the directory fits_package/include one should have the files:

   Name						Description
fitsfacts.for			   Include file for FITS file parameters
				   and COMMON blocks
miipspar.for			   Include file for basic array sizes
plotpar.for			   Include file for plotting parameters
sao_default_vlt.for		   Default lookup table for Enhanced SAOimage
saofacts.for			   Include file for Enhanced SAOimage
				   COMMON blocks

In the directory fits_package/mac_os_ppc one should have the files:

   Name                                         Description
copy_fits_records.for		   Mac OS X PPC/Absoft version
fits_to_sao.for			   Mac OS X PPC/Absoft version
get_output_fits_maps.for	   Mac OS X PPC/Absoft version
linepl_fits.for			   Mac OS X PPC/Absoft version
openfits.for			   Mac OS X PPC/Absoft version
testfits.for			   Mac OS X PPC/Absoft version

In the directory fits_package/plot one should have the files:

   Name					Description
alogaxis.for			   Lower level plot routine
alogcode.for			   Lower level plot routine
alogdeccode.for			   Lower level plot routine
alogdecode.for			   Lower level plot routine
apple.for			   Lower level routine for postscript
appleplot.for			   Lower level routine for postscript
arrowhead.for			   Lower level plot routine
axis.for			   Lower level plot routine
color_24_triplet.for		   Lower level plot routine
color_input.for			   Lower level plot routine
colormode.for			   Lower level plot routine
colormode_background.for	   Lower level plot routine
crosshair.for			   Lower level plot routine
datalevel.for			   Lower level plot routine
decode_intervals.for		   Lower level plot routine
delay.for			   Routine to produce a delay
errorbar.for			   Lower level plot routine
fillmode.for			   Lower level plot routine
findplot.for			   Lower level plot routine
get_dp_availability.for		   Lower level plot routine
histogram.for			   Lower level plot routine
imtoolchecksum.for		   Required lower level routine
issubsup.for			   Lower level plot routine
keyboard.for			   Lower level plot routine
limit.for			   Lower level plot routine
line_symbl.for			   Lower level plot routine
line.for			   Lower level plot routine
makefile			   Main makefile for plot files
makefile-fits_plot.macosppc	   Makefile for Mac OS X PPC
makefile-fits_plot.pgf77	   Makefile for Linux/Mac OS X,
				   Intel w/Portland Group compiler
makefile-fits_plot.ultrix	   Makefile for Ultrix
makefile-fits_plot.unix		   Makefile for other Unix
nhint.for			   Required lowel level routine
number.for			   Lower level plot routine
penmode.for			   Lower level plot routine
plot.for			   Lower level plot routine
plot9999ques.for		   Lower level plot routine
plotcom.for			   Program to plot from plot file
plotdevices.for			   Lower level plot routine
plotdevices2.for		   Lower level plot routine
plotdevques.for			   Lower level plot routine
pltdev.for			   Lower level plot routine
pltread.for			   Lower level plot routine
pltwrite.for			   Lower level plot routine
prtmsg.for			   Required lower level routine
resettek.for			   Lower level plot routine
sao.for				   Lower level plot routine
sao_curn.for			   Lower level routine for SAOimage
sao_display_vect.for		   Lower level routine for SAOimage
sao_draw.for			   Lower level routine for SAOimage
sao_erase_cursor.for		   User routine to erase cursors
sao_load_vlt.for		   Lower level routine for SAOimage
sao_vect.for			   Lower level routine for SAOimage
saocaption.for			   Lower level routine for SAOimage
saoconvlt.for			   Lower level routine for SAOimage
saoeras.for			   Lower level routine for SAOimage
saofirst.for			   Lower level routine for SAOimage
saoplot.for			   Lower level plot routine
saostart.for			   Lower level routine for SAOimage
scale_axis.for			   Lower level plot routine
si_subs.c			   Lower level routine for SAOimage
si_subs.h			   Lower level routine for SAOimage
symbol.for			   Lower level plot routine
symgen.for			   Lower level plot routine
symgengr.for			   Lower level plot routine
sys_keyin.c			   Lower level plot routine
tek.for				   Lower level plot routine
tekcon.for			   Lower level plot routine
tekpau.for			   Lower level plot routine
tekplot.for			   Lower level plot routine
textcnch.for			   Lower level plot routine
transparent_mode.for		   Program to go from Tek to terminal
transparent_mode_x.for		   Program to go from Tek to terminal
				   for xterm
transparent_mode_xn.for		   Program to go from Tek to terminal
				   for xterm without erasing plot
transparent_to_tek.for		   Lower level plot routine
vectmode.for			   Lower level plot routine
where.for			   Lower level plot routine
xyplot.for			   High level subroutine for XY plots
xyplot_ascii.for		   Program to plot from one or more ASCII
				   files
xyplot_f.for			   Lower level plot routine
xyplot_setup.for		   Lower level plot routine

In the directory fits_package/plot/mac_os_ppc one should have the files;

   Name                                         Description
apple.for				Mac OS X PPC/Absoft version
crosshair.for				Mac OS X PPC/Absoft version
errobar.for				Mac OS X PPC/Absoft version
imtoolchecksum.for			Mac OS X PPC/Absoft version
line.for				Mac OS X PPC/Absoft version
line_symbl.for				Mac OS X PPC/Absoft version
number.for				Mac OS X PPC/Absoft version
plotcom.for				Mac OS X PPC/Absoft version
plotdevices.for				Mac OS X PPC/Absoft version
pltread.for				Mac OS X PPC/Absoft version
pltwrite.for				Mac OS X PPC/Absoft version
scale_axis.for				Mac OS X PPC/Absoft version
si_subs.c				Mac OS X PPC/Absoft version
si_subs.h				Mac OS X PPC/Absoft version
xyplot.for				Mac OS X PPC/Absoft version
xyplot_ascii.for			Mac OS X PPC/Absoft version
xyplot_setup.for			Mac OS X PPC/Absoft version

In the directory fits_package/utilities one should have the files:

   Name						Description
alpha.for				Character processing routine
bell.for				Routine to ring the bell
dcd.for					Routine to help usrinp.for
do.for					Routine to help usrinp.for
dynamic.for				Routine to obtain dynamic memory
dynamic_c.c				Routine to obtain dynamic memory
error.for				Required lower level routine
get_os_bytes.for			Routine to get OS number of bytes
get_os_bytes_c.c			Routine to get OS number of bytes
get_len_nonblank.for			Routine to return the number of
					characters in a string excluding
					blanks at the end of the string
ibmi2.for				Routine to swap INTEGER*2 bytes 
ibmi4.for				Routine to swap INTEGER*4 bytes
ieeeflt.c				Routine to convert from 32-bit
					IEEE-754 to Unix and vice versa
ieeeflt64.c				Routine to convert from 64-bit
					IEEE-754 to Unix and vice versa
inel.for				Routine to help usrinp.for
makefile				Main makefile for utility files
makefile-utilities.macosppc		Makefile for Mac OS X PPC
makefile-utilities.pgf77		Makefile for Linux/Mac OS X,
					Intel w/Portland Group compiler
makefile-utilities.ultrix		Makefile for Ultrix
makefile-utilities.unix			Makefile for other Unix
message.for				Routine to display messages
nel.for					Routine to help usrinp.for
neld.for				Routine to help usrinp.for
opencf.for				User routine to open a character file
release_memory_c.c			Routine to release dynamic memory
save.for				Routine to help usrinp.for
strkey.for				Routine to help usrinp.for
strludef.for				Required lower level routine
usrinp.for				User input routine

In the directory fits_package/utilities/mac_os_ppc one should have the files:

   Name                                         Description
dcd.for					Mac OS X PPC/Absoft version
nel.for					Mac OS X PPC/Absoft version
neld.for				Mac OS X PPC/Absoft version
opencf.for				Mac OS X PPC/Absoft version
save.for				Mac OS X PPC/Absoft version
usrinp.for				Mac OS X PPC/Absoft version

     The samples files, included in both fits_*_executables.tar-gz
and fits_unix_source.tar-gz, are:

   Name						Description
tst0001.fits				8-bit unsigned byte FITS sample,
					range is 0 to 255
tst0002.fits				16-bit signed integer FITS sample
					with 5 planes, range is 0 to 72
tst0003.fits				32-bit signed integer FITS sample,
					range is 1 to 37127
tst0004.fits				32-bit signed integer FITS sample,
					range is 35.48 to 35.16
tst0005.fits				32-bit IEEE-745 floating point
					sample, range is 135.2 to -135.2
tst0006.fits				64-bit IEEE-745 floating point
					sample, range is 32 to -31.97
ngc1316o.fits				16-bit signed integer image of NGC1316
nicmosn4hk12010_mos.fits		32-bit IEEE-754 floating point and
					16-bit signed integer sample with 5 maps
wfpc2u5780205r_c0fx.fits		32-bit IEEE-754 floating point
					sample, with 4 planes
ascii1.dat				Sample file for xyplot_ascii.exe demo
ascii2.dat				Sample file for xyplot_ascii.exe demo
ascii3.dat				Sample file for xyplot_ascii.exe demo
ascii4.dat				Sample file for xyplot_ascii.exe demo
ascii5.dat				Sample file for xyplot_ascii.exe demo

The sample files are by default placed in the fits_package directory.

The makefile will also create the object libraries, fits_package_u.a,
plot/plot_u.a, and utilities/utilities_u.a which can
be used to link with user written programs if desired.

For whichever method you use to install the executable files, create the
aliases:
  alias a 'transparent_mode.exe'
  alias ax 'transparent_mode_x.exe'
  alias axn 'transparent_mode_xn.exe'
  alias plot 'plotcom.exe'
  alias xyplot 'xyplot_ascii.exe'

"a" will change from the Tektronix window to the text window in a graphics
terminal.
"ax" will change from the Tektronix window to the text window in xterm, and
erase the screen.
"axn" will change from the Tektronix window to the text window in xterm,
without erasing the screen.
"plot" will operate the plot command on the standard plot files (see below)
"xyplot" will produce an XY plot of columnar data from one or more ASCII files.

These definitions can be placed in a login file if desired.

Finally, edit display-plotting_availability.dat to match the display and
plotting devices availabile on your system.

     The plot device xgterm is a color xterm-like graphics terminal emulator
which runs on Unix.  Copies compiled for Linux with Intel processors for
kernels 2.2 and 2.4, and Mac OS 10.4, Tiger, can be downloaded from the web
page for this package.  The version of xgterm for Mac OS from iraf.net will
not work correctly.  While a plot can be sent to it, the Tek window never
receives focus, so no cursor readback is possible.  The version on the package
web page was prepared by Chip Coldwell, and will work correctly.


                    Running testfits.exe

     Program testfits.exe demonstrates usage of the routines in the FITS
package.  Examine the code in each example to see how the FITS files are
opened, read, and saved.  Examples 8 and 9 demonstrate the most versatile
ways to save results after an operation.  After launching the testfits 
program you will be presented with the following menu:

Enter the number of the FITS file test to perform:
     1 = Reads all or part of a row (default)
     2 = Plots a cut through a file
     3 = Reads an xy area
     4 = Displays an image on SAOimage (Enhanced version)
     5 = Writes all or part of a row for a new or existing file
     6 = Writes an xy area for a new or existing file
     7 = Performs simple rotations on a fileA
     8 = Performs simple arithmetic on a file
     9 = Performs a simple crop on a file
    10 = Copies one or more maps (image extensions) from one file to another
    11 = Copies a set of maps from one file to a set of planes in another file
    12 = Prints the header
    13 = Writes a COMMENT or HISTORY keycard to the header of an existing file
    14 = Updates or creates a keycard with a string value, e.g., AUTHOR,
         CTYPEn, BUNIT, DATE, DATE-OBS, etc.
    15 = Updates or creates the BSCALE and BZERO keycards for an existing file
    16 = Replaces a keycard with blanks

     Test "1" requires an existing FITS file and will print on the terminal 
window the pixel values of the selected columns in the chosen row.  Test 1
demonstrates the use of the routines openfits, rdfitsrow and rddpfitsxy (in 
module rwfitsrow).  Because this is the default test, just press the Return to 
use it.  For example, when the prompt

  Enter the filename:  (<CR> for default)
  FILE=

appears, enter "tst0003.fits" (without the double quotes).  Do not take the 
default when entering the filename, because no pevious filename has been
used at this point.  The program responds with:

  There is one map in the file
  Reading from the file
  271 rows of  137 pixels in I4  format for map number    1
  There is one plane in this map
  Enter the row number:  (default = 1)
  IROW=

You can take the default here or enter a row number.  Taking the default, the
program responds with:

  Enter the start column and end column:
  COLUMNS=

Enter, for example, "1 10", and the result is:

  COLUMN    VALUE
       1    1.000000    
       2    2.000000    
       3    3.000000    
       4    4.000000    
       5    5.000000    
       6    6.000000    
       7    7.000000    
       8    8.000000    
       9    9.000000    
      10    10.00000   

                               *******

     Test "2" will plot on one or more of the supported plot or display
devices a cut through an existing FITS file.  The test makes use of the
high level routine linepl which allows the user to plot one or more rows
or columns in one or more maps, or a single plot at a chosen angle.  For
the case of a plot at an arbitrary angle, the location of the center of the
cut may be input manually or interactively with SAOimage.  The version of
SAOimage which supports such input is v. 1.2E obtainable from 
  http://www.chara.gsu.edu/~gudehus/enhanced_saoimage.html
At the prompt for ITEST, enter "2".  The program then displays:

  Enter a command:
       R = Plots one or more rows (default)
       C = Plots one or more columns
       A = Plots at any angle (manual input of position)
      AS = Plots at any angle (SAOimage cursor input;  SAOimage already loaded
       S = Plots at any angle (SAOimage cursor input;  need to load SAOimage
  
  COMMAND=

Enter "R", or press the <CR>.  At the next prompt,

  Enter the filename:  (<CR> for default)
  FILE=

enter "nicmosn4hk12010_mos.fits".  The program displays:

  There are   5 maps in the file       
  Reading from the file
   263 rows of  270 pixels in R4  format for map number    1
  There is one plane in this map
  Enter the map numbers:  (default = all)
  MAPS=

Enter "1 2" (without the double quotes) in order to plot from maps 1 and 2.
Note that when prompted for a sequence of integers in testfits.exe, one can
enter the numbers individually as indicated above, or, if the numbers are
sequentially increasing one at a time, use the shortcut:  "n:m" where "n"
is the first integer and "m" is the last integer.  For example, if n=2 and
m=5, then "2:5" will be interpreted by the program as the integers "2 3 4 5".
This shortcut can useful when dealing with FITS files containing dozens or
hundreds of maps.  Mixed expressions can also be used.  For example 
"1:3 7:9 11 19" is the same as "1 2 3 7 8 9 11 19".

The program then asks:

  The minimum number of planes for any map in the set is    1
  Enter the plane number:  (default =1)
  PLANE=

Take the default of plane number 1.  The program reports:
The program reports:

  Reading from the file
  Map number    1 contains  263 rows of  270 pixels in R4  format
  Map number    2 contains  263 rows of  270 pixels in R4  format
  Enter the row numbers:
  ROWS=

Enter "151" for the row number.  The program then asks for the range in
columns.

  Enter the start-column and the end-column:  (default = entire range)
  COLUMNS=

Enter a range such as "50 300", or take the default.  The program then asks:

  Do you want to plot only the average of all the rows?  (default = F)
  PLOT_AVERAGE=

Take the default of "no".  Now the program displays the following list:

  Enter the plot devices:
       S   = SAOimage (Enhanced version)
      -S   = SAOimage, no erasure of screen
       G   = Graphics terminal (VT100/Retrographics and Visual 550)
       G4  = Graphics terminal emulator (Versaterm)
       X   = Xterm (default)
       XG  = Xgterm
       F   = File
  
  DEVICES=

The list that is displayed will depend on which devices are not commented
out in the file display-plotting_availability.dat which should be in the
same directory as testfits.exe.  After making a choice, say X, you will see
a plot displayed.  However because the levels in map 2 are about 400 times
smaller than those in map 1, the curve for map 1 dominates.  To more easily
view both curves, press the "L" key (do not press the return key) and the
plotting program will respond with:

  Logs requested
  Do you want to take log(x)?  (default = Y)
  TAKE_LOG_X=

Enter "N" or "n" and the program will prompt with:

  Do you want to take log(y)?  (default = Y)
  TAKE_LOG_Y=

Enter "Y" or "y" or take the default and the graph will be replotted as
log of the ordinate values, making it much easier to see both curves.
     When plotting rows, the labels for the X and Y axes are taken from the
keywords CTYPE1 and BUNIT, respectively.  When plotting columns, the X and
Y axis labels are taken from CTYPE2 and BUNIT, respectively.   If these
keywords are not present in the FITS header, then the labels will be blank.
When plotting at an arbitrary angle, the X label will always be "Pixel".
     Read the sections "Working with the Plot Programs", "The Plot Command",
and "Plotting from an ASCII File" below for more information on plotting.

                               *******

     Test "3" requires an existing FITS file and will print on the terminal
window the pixel values of a selected area.  Test 3 demonstrates the use
of the routines rdfitsxy and rddpfitsxy (in module rwfitsxy).  At
the prompt for ITEST, enter "3".  The program then displays:

  Enter the filename:  (<CR> for default)
  FILE=

Enter "tst0006.fits", and the program prints:

  There is one map in the file
  Reading from the file
   173 rows of   77 pixels in R8  format for map number    1
  There is one plane in this map
  Enter the start row and end row:
  ROWS=

Enter "1 2" and the program next prompts with:

  Enter the start column and end column:
  COLUMNS=

Enter "1 5" and the program prints:

 ROW =    1
 COLUMN =    1    VALUE =     32.00000000000000    
 COLUMN =    2    VALUE =     31.89352263981418    
 COLUMN =    3    VALUE =     31.57479914852124    
 COLUMN =    4    VALUE =     31.04595057837006    
 COLUMN =    5    VALUE =     30.31049632934112    
 ROW =    2
 COLUMN =    1    VALUE =     32.00000000000000    
 COLUMN =    2    VALUE =     31.89352263981418    
 COLUMN =    3    VALUE =     31.57479914852125    
 COLUMN =    4    VALUE =     31.04595057837007    
 COLUMN =    5    VALUE =     30.31049632934113    

                               *******

     Test "4" requires an existing FITS file and a working installation
of Enhanced SAOimage, obtainable from 
  http://www.chara.gsu.edu/~gudehus/enhanced_saoimage.html
This test demonstrates the use of the high level routine fits_to_sao.
Be sure that your X Window display is configured for 8 bits, and then
bring up SAOimage.  Enter "4" at the prompt for ITEST, and enter 
"ngc1316o.fits" at the prompt for the file name.  The program
responds with:

  There is one map in the file
  Reading from the file
   512 rows of  512 pixels in I2  format
  There is 1 plane in this map
  A value of BZERO =    0.5162198486330000E+03 will be used
  A value of BSCALE =    0.1592400892020000E-01 will be used
  Select a frame buffer size:
                  1 =  512 X 512 (default)
                  2 =  800 X 800
                  3 = 1024 X 1024
                  4 = 1600 X 1600
                  5 = 2048 X 2048
                  6 = 4096 X 4096
                  7 = 4096 X 1024
                  8 = 1024 X 4096
                  9 = 1144 X  880
                 10 = 1144 X  764
                 11 =  128 X  128
                 12 =  256 X  256
                 13 =   90 X   90
   
  FRAME_BUFFER=

Because the FITS file is 512X512 pixels, the default frame buffer can be used
to display it.  After pressing the <CR>, the program asks:

  Enter the minimum and maximum for the display (default = values in file)
  MINIMUM_MAXIMUM=

Taking the default gives:

  -5.57808
   1037.89

for the minimum and maximum values, and the image then appears in the SAOimage
window.  After that, the following selection appears:

  Enter a command:  (default = K)
     J = Loads a high contrast spectrum lookup table
     K = Loads a spectrum lookup table including white
     Q = Quits
     W = Loads a black and white triangle look-up table
     X = Loads a black and white sawtooth look-up table
 
  COMMAND=

After making a choice, the same menu appears again, allowing further 
experimentation with the lookup table before quiting.
     The X and Y coordinates of the cursor appear in the SAOimage window
along with a pixel intensity value.  Because the intensity value shown
is read from the lookup table, its accuracy is limited to about 1 part
in 197 over the chosen intensity range. 

                               *******

     Test "5" allows one to write all or part of a row to a new or
existing FITS file, and demonstrates the usage of routines wrfitsrow and 
wrdpfitsrow  in module rwfitsrow.  Because the same unit number is used
for opening the file and writing to it, i.e. the input file is the same
as the ouput file, no header information is lost.  Before running this test,
use the Unix operating system to make a copy of one of the sample files, e.g.,

  cp tst0004.fits scratch.fits

Enter "5" at the prompt for ITEST.  The program responds with

  Does the map storage exist?  (default = Y)
  IOFL=

Answer "Y" to this question.  Enter "scratch.fits" at the prompt for
the file name.  The program responds with:

  There is one map in the file
  Reading from the file
   256 rows of  256 pixels in I4  format for map number    1
  There is one plane in this map
  Enter the row number:  (default = 1)
  IROW=

Take the default.  The next prompt is:

  Enter the start column and end column:
  COLUMNS=

Enter "1 10", and for the prompt

  Enter the value:
  VALUE=

enter "100".  In this case, we simply wrote over the first 10 columns of row
number 1 in an existing map.  The values that were written can be verified
by running test number 1, 2, 3, or 4.  Next we will write to a new map.
     Enter "5" for ITEST, and enter "N" to the question about whether the map
storage exists.  Enter "scratch.fits" for the file name, and the program
responds with:

 Writing to an existing file
 There is one map in the file
 Enter the map number:  (default = one after the last map)
 MAP=

Take the default, and the program responds with:

  Creating   1 new map
  Reading from the last map of the file
   256 rows of  256 pixels in I4  format
  with 1 plane per map
  Enter the number of rows for the new map:  (default = number of last map)
  NUMBER_OF_ROWS=

Take the default, and the program responds with:
         256
  Enter the number of columns for the new map:  (default = number of last map)
  NUMBER_OF_COLUMNS=

Take the default, and the program responds with:
         256
  Enter the data format to use:  (default = format of last map
       I1 = Unsigned 8-bit integer
       I2 = 16-bit twos-complement binary integer
       I4 = 32-bit twos-complement binary integer
       R4 = IEEE single precision floating point
       R8 = IEEE double precision floating point
       C8 = Complex - real and imaginary are R4
      C16 = Complex - real and imaginary are R8
  
  DATA_FORMAT=

Take the default, and the program responds with:
  I4
  Enter the number of planes for the new maps:  (default = 1)
  NUMBER_OF_PLANES=

Take the default, and the program responds with:
           1
  Enter the row number:  (default = 1)
  IROW=

Take the default, and the program responds with:
           1

 Enter the start column and end column:
 COLUMNS=

Enter "1 10", and for the prompt

  Enter the value:
  VALUE=

enter "200".  Note that if we had not taken the default in response to
the prompt "Enter the map number:  (default = one after the last map)",
but had entered a number greater than 2, several new maps would have
been created.  Each new map would have the same number of rows, columns,
data format, and planes as specified by the user's response to the prompts.
Only the last map, i.e., the map whose number was entered, would have had
its row values written to.

                               *******

     Test "6" allows one to write values to an XY area for a new or
existing FITS file, and demonstrates the usage of routines wrfitsxy and
wrdpfitsxy  in module rwfitsxy.  Because the same unit number is used
for opening the file and writing to it, i.e. the input file is the same
as the ouput file, no header information is lost.  Before running this
test, use the Unix operating system to make a copy of one of the sample
files, e.g.,

  cp tst0005.fits scratch2.fits

Enter "6" at the prompt for ITEST.  The program responds with

  Does the map storage exist?  (default = Y)
  IOFL=

Answer "N" to this question.  Enter "scratch2.fits" at the prompt for
the file name.  The program responds with:

  Writing to an existing file
  There is one map in the file
  Enter the map number:  (default = one after the last map)
  MAP=

Enter "3", and the program responds with:

  Creating   2 new maps
  Reading from the last map of the file
   109 rows of  102 pixels in R4  format
  with 1 plane per map
  Enter the number of rows for the new maps:  (default = number of last map)
  NUMBER_OF_ROWS=

We are creating 2 new maps, numbers 2 and 3, where both will be the same size
and have the same data format.  The data for both will initially be all
zeroes.  We will write only to map number 3 however.  Enter "100" for the
number of rows, and the program will respond with:

  Enter the number of columns for the new maps:  (default = number of last map)
  NUMBER_OF_COLUMNS=

Enter "100", and the program responds with:

  Enter the data format to use:  (default = format of last map
       I1 = Unsigned 8-bit integer
       I2 = 16-bit twos-complement binary integer
       I4 = 32-bit twos-complement binary integer
       R4 = IEEE single precision floating point
       R8 = IEEE double precision floating point
       C8 = Complex - real and imaginary are R4
      C16 = Complex - real and imaginary are R8
  
  DATA_FORMAT=

Enter "C8", and the program responds with:

  The map(s) will contain two planes for the real and imaginary parts
  Enter the desired plane number:  (default = 1)
  PLANE=

Because complex data was chosen, the number of planes is required to be 2
according to the FITS standard.  We are asked to specify a plane because we
are only writing to one plane.  Enter "1" (the real plane) or take the default,
and the program responds with:

  Enter the start column and end column:
  COLUMNS=

Enter "25 75", and the program responds with:

  Enter the start row and end row:
  ROWS= 

Enter "25 75", and the program responds with:

  Enter the value:
  VALUE=

Enter "100".  The values that were written can be verified by running test
number test number 1, 2, 3, or 4.

                               *******

     Test "7" permits one to rotate a FITS file by + or - 90 degrees,
or 180 degrees.  The size of the output map is automatically chosen
from the size of the input map.  This test demonstrates the usage of 
routines get_input_fits_maps, get_output_fits_maps, as well as
rdfitsrow, rddpfitsrow, wrfitsrow, and wrdpfitsrow in module rwfitsrow. 
In this example, several maps are rotated in sequence, all the planes
in each map are rotated by the same amount, and the output file can be
an existing file (other than the input file) or a new file.  Another
restriction is that the headers of the output file will have a length
of one block (2880 bytes) and contain only minimal information, i.e.,
the headers of the input maps are not retained.  First use the Unix
operating system to make a copy of a sample file, e.g.,

  cp ngc1316o.fits scratch3.fits

Enter "7" at the prompt for ITEST.  The program responds with

  Enter a command:
       1 = Rotates by 90 degrees clockwise (default)
       2 = Rotates by 180 degrees clockwise
       3 = Rotates by 90 degrees counterclockwise

  COMMAND=

Enter "1", and enter "ngc1316o.fits" to the prompt for the name of the
input file.  The program prints:

  There is one map in the file
  Reading from the file
   512 rows of  512 pixels in I2  format for map number    1
  There is one plane in this map
  Open the output file
  Enter the filename:
  FILE_OUT=

Enter "scratch3.fits", and the program responds with:

  Writing to an existing file
  There is one map in the file
  Creating   1 new map
  
     Rotating 90 Degrees Clockwise
  Input Map No.       Output Map No.
           1                    2

You can view the results on SAOimage, or the publically available viewer "fv".

                               *******

     Test "8" performs simple arithmetic on a file by adding a chosen
constant (or bias) to all the pixel values in a single plane of a single
map, and than multiplying by a chosen factor.  This example demonstrates
usage of the routines open_temp_fits and save_save_as, as well as 
rdfitsrow, rddpfitsrow, wrfitsrow, and wrdpfitsrow in module rwfitsrow.
The routines open_temp_fits and save_save_as permit the widest range of
possibilities for saving the output.  One can save to the original map
and plane, save to the end of the same file as a new map, save to the
end of a different existing file, and save to a new file.  In each case the
information in the original map header is retained.  First use the Unix
operating system to make a copy of a sample file, e.g. 

  cp tst0002.fits scratch4.fits

Enter "8" at the prompt for ITEST.  The program responds with:

  Enter the filename:  (<CR> for default)
  FILE=

Enter "scratch4.fits".  The program responds with:

  There is one map in the file
  Reading from the file
    31 rows of   73 pixels in I2  format for map number    1
  There are    5 planes in this map
  Enter the plane number:  (default = 1)
  PLANE=

Take the default, and the program responds with:

 Enter a bias value:  (default = 0.0)
 BIAS=

Enter "-72".  The program responds with:

 Enter a factor:  (default = 1.0)
 FACTOR=

Enter "-10" and we are presented with several choices for saving.

 Enter a choice for saving your results:
      S  = Save:  saves to the same map (default)
      SA = Save As:   saves to a new, or to the end of an existing file
  
 CHOICE= 

Take your pick here.  To verify that the changes took place, try ITEST 1
or 2.  Previously, the values ran from 0 to 72 starting at column 1;  now
they run from 720 to 0 starting at column 1.

                               *******

     Test "9" performs a simple crop on a file.  This test again demonstrates
usage of the routines open_temp_fits and save_save_as.  Here, however, we 
operate in a loop on a series of maps from the input file.  All the maps will
be cropped to the same size and at the same starting coordinates.  All planes
in the maps are cropped as well.  One can save to the original maps and planes,
save to the end of the same file as a sequence of new maps, save to the
end of a different existing file, and save to a new file.  In each case the
information in the original map headers is retained.  
     First use the Unix operating system to make a copy of 
nicmosn4hk12010_mos.fits, i.e.,

  cp nicmosn4hk12010_mos.fits scratch5.fits

Enter "9" at the prompt for ITEST.  The program responds with:

  Open the input file
  Enter the filename:  (<CR> for default)
  FILE_IN=

Enter "scratch5.fits".  The program responds with:

  There are   5 maps in the file       
  Reading from the file
   263 rows of  270 pixels in R4  format for map number    1
  There is one plane in this map
  Enter the input map numbers:  (default = all)
  MAPS_IN=

Enter "1 2 3" or "1:3" and the program responds with:

  Define the cropped area
  Enter the column and row of the lower left corner:
  LOWER_LEFT=

Enter "60 60", and the program responds with:

  Enter the column and row of the upper right corner:
  UPPER_RIGHT=

Enter "210 210", and the program responds with:

  Enter a choice for saving your results:
       S  = Save:  saves to the same map (default)
       SA = Save As:   saves to a new, or to the end of an existing file
  CHOICE=

You may take your choice here.  If you take the default, the first three maps
are overwritten with new dimensions of 151 by 151 pixels, and the headers
are retained except the keywords NAXIS1 and NAXIS2 will have been updated.
Maps 4 and 5 remain the same.

                               *******

     Test "10" allows one to copy selected maps from an input file to an output
file.  The test demonstrates the usage of the routine copy_fits_records.
Enter "10" at the prompt for ITEST, and enter "nicmosn4hk12010_mos.fits" for
the name of the rquested input file.  The program replies with:

  There are   5 maps in the file       
  Reading from the file
   263 rows of  270 pixels in R4  format for map number    1
  There is one plane in this map
  Enter the input map numbers:  (default = all)
  MAPS_IN=

Enter "1 2" for the input map numbers.  The program responds with:

  Open the output file
  Enter the filename:
  FILE_OUT=

Enter "scratch6.fits" and the program prints:

  Creating new file
  Writing map    1
  Writing map    2

                               *******

     Test "11" copies a selected set of maps from one file to a set of planes 
in a map in another file.  This test demonstrates the high level routine
fits_maps_to_planes.  Enter "9" at the prompt for ITEST, and enter 
"nicmosn4hk12010_mos.fits" for the name of the rquested input file.  The
program replies with:

  There are   5 maps in the file       
  Reading from the file
   263 rows of  270 pixels in R4  format for map number    1
  There is one plane in this map
  Enter the input map numbers:  (default = all)
  MAPS_IN=
  The data formats of the input maps are not all the same
  Map Number     BITPIX
     1            -32
     2            -32
     3             16
     4             16
     5            -32
  Enter the desired output bitpix:
  BITPIX_OUT=

Because all planes in a map must have the same data format, we must select a
format that doesn't sacrifice precision.  Enter "-32".  The program then
asks for an output file:

  Open the output file
  Enter the filename:  (<CR> for default)
  FILE_OUT=

Enter "scratch7.fits", and the program continues with:

   Creating new file

A file containing a map with several planes can be viewed as a movie with the
viewer "fv".

                               *******

     Test "12" prints the header of a FITS file.  It also counts the number of
blank and nonblank keycards.  This test makes use of the routine mhfitscrd.
In order to illustrate this test with a header that is not excessively long,
we will first create a file with 2 maps.  Use the Unix operating system to 
copy one of the sample files.

  cp tst0002.fits scratch8.fits

Then use test number 5 to create an additional map in scratch8.fits  Answer
"N" to the question of whether the map storage exists, enter "scratch8.fits"
for the filename, enter "2" or take the default for the map number, and take
the defaults for the number of rows, number of columns, data format, number of 
planes, and row number.  Enter, for example, "1 10" for the start and end
column, and "100" for the value.
     Now, enter "12" at the prompt for ITEST, and enter "scratch8.fits" for 
the filename.  The program prints:

  There are   2 maps in the file       
  Enter the map number:  (default = 1)
  MAP=

Enter "2" for the map number and both the principle header and extension 
header are printed.

  Reading from the file
    31 rows of   73 pixels in I2  format for map number    2
  There is one plane in this map
  *** Primary Header ***
  SIMPLE  =                    T / Standard FITS file                             
  BITPIX  =                   16 / No. of bits per pixel                          
  NAXIS   =                    0 /                                                
  EXTEND  =                    T / There are FITS extensions                      
                                                                                 
                                                                                 
                                                                                 
                                                                                 
  OBJECT  = 'Ramp 16-bit'        / Name of image                                  
  ORIGIN  = 'ESO     '           / File was prepared at ESO-Garching              
  DATE    = '20/08/92'           / Creation data of this file                     
                                                                                 
  COMMENT  This test file was created by P.Grosbol, ESO (pgrosbol@eso.org)        
                                                                                 
  COMMENT  Simple 16-bit ramp pattern for testing of FITS readers                 
                                                                                 
  That's all                                                                      
  There are   17 keycards, including the END keycard, in the primary header
  Of these,   10 are nonblank
  *** Map Header ***
  XTENSION= ''IMAGE   '        ' /                                                
  BITPIX  =                   16 /                                                
  NAXIS   =                    3 /                                                
  NAXIS1  =                   73 /                                                
  NAXIS2  =                   31 /                                                
  NAXIS3  =                    1 /                                                
  PCOUNT  =                    0 /                                                
  GCOUNT  =                    1 /                                                
  That's all                                 
  There are    9 keycards, including the END keycard, in the map header
  Of these,    9 are nonblank

The END keyword is not printed in this program;  rather, the message
"That's all" is given instead.

                               *******

     Test "13" writes a COMMENT or HISTORY keycard to the header of an 
existing file and demonstrates the usage of routine wrfitsmhst.  Use the Unix
operating system to copy one of the sample files.

  cp tst0003.fits scratch9.fits

Enter "11" at the prompt for ITEST, and enter "scratch9.fits" for the filename.
The program prints:

  There is one map in the file
  Reading from the file
   271 rows of  137 pixels in I4  format for map number    1
  There is one plane in this map
  Enter a keyword choice:
       C = COMMENT (default)
       H = HISTORY
  
  KEYWORD_CHOICE=

Enter "C", and the program responds with:

  Do you want to create/duplicate (T = default) or replace (F) a keycard?
  DUPLICATE=

Answering "T" will simply add another comment at the end of the header but
before the END keyword.  However we will answer "F".  The program then
prints:

  Enter the text (up to 72 characters):
  STRING=

Enter "Modified 32-bit ramp pattern for testing of FITS readers" (without
the double quotes).  The program then prints: 

  The keyword COMMENT occurs    2 times.
  Which occurence do you wish to overwrite?
  OCCURENCE=

Enter "2", and the old comment is replaced.  You can use test 10 to print
the new header.  You can also use the vi editor to view the header, however 
do not use this editor to make any changes in the header.

                               *******

     Test "14" creates or updates a keycard with a string value, e.g., AUTHOR,
CTYPEn, BUNIT, DATE, DATE-OBS, etc.  Use the Unix operating system to make a 
copy of one of the sample files,

  cp tst0005.fits scratch10.fits

Enter "12" at the prompt for ITEST, and enter "scratch10.fits" for the filename.
The program prints:

  There is one map in the file
  Reading from the file
   109 rows of  102 pixels in R4  format for map number    1
  There is one plane in this map
  Enter the desired keyword:
  KEYWORD=

Enter "BUNIT" and the program responds with:

  Do you want to create (T = default) or update (F) a keycard?
  DUPLICATE=

Enter "T" and the program asks:

  Enter a value (up to 20 character):
  STRING_VALUE=

Enter "Displacement", and the program responds with:

  Enter a comment (up to 47 characters):
  STRING_COMMENT=

Enter "In millimeters".  In general, if a keyword is duplicated, the
keyword is added right before the END keyword.  If the keword is replaced,
the old one is replaced with the new values.  The BUNIT keyword is used for
labeling the Y axis when plotting rows or columns with ITEST=2.

                               *******

     Test "15" creates or updates the BSCALE and BZERO keycards for an
existing file.  Enter "15" at the prompt for ITEST, and enter "scratch10.fits"
for the filename.  The program prints:

  There is one map in the file
  Reading from the file
   109 rows of  102 pixels in R4  format for map number    1
  There is one plane in this map
  Enter a value for BSCALE (default = 1.0)
  BSCALE=

Enter "10.0".  The program responds with:

  Enter a value for BZERO (default = 0.0)
  BZERO=

Enter "1352".  Now when this file is inspected with test 1 or 3, or plotted
with test 2, the values will range from 0 to 2704, rather than from -135.2 
to +135.2.

                               *******

     Test "16" replaces a keycard with blanks.  It makes use of the subroutine
wrfitsmhst.  Use the Unix operating system to copy the following sample file:

  cp tst0003.fits scratch11.fits

If this file is submitted to the NASA FITS File Verifier program, the following
warning will be produced:

  *** Warning: Keyword #7, BLOCKED is deprecated.

We will now eliminate the BLOCKED keyword from our scratch file.  Enter "16"  
at the prompt for ITEST, and enter "scratch11.fits" for the filename.  The
program prints:

  There is one map in the file
  Reading from the file
   271 rows of  137 pixels in I4  format for map number    1
  There is one plane in this map
  Enter the desired keyword:
  KEYWORD=

Enter "BLOCKED".  The result can be checked with Test 12 or by submitting the
file to the NASA FITS File Verifier program.  If a FITS file containing one
map has the BLOCKED keyword present, when the file is extended to more than
one map, the FITS library routines will automatically eliminate the BLOCKED 
keyword from the principle header.  In some cases, more than one instance
of the keyword of interest exists.  The program will then ask which occurance
to change to blanks.

 
		Working with the Plot Programs

     Plotting is built into testfits.exe.  A plot can be sent to one or
more plot devices and plot file simultaneously.  The plot devices that appear
in the list presented to the user are determined by settings in the file
display-plotting_availability.dat.  Simply uncomment or comment those
devices you wish to be or not be shown.  When the plot first appears on the
selected device(s), help can be obtained by typing (not entering) the
letter h or H.  The following will then appear (note that ^ denotes that
the control key is to be pressed as well):

A = Turns on the crosshairs and by pressing the <CR> at chosen X limits,
    the mean Y value will be calculated for each plot.
a = Allows the user to enter annotation at the location of the crosshairs
    with the color most recently selected.
    ^I (^L on Mac OS X) toggles to the Greek alphabet and special symbols,
    and back to English
    ^H (^B on Mac Os X) gives a backspace
    ^K toggles to subscript, superscript, and back to normal
^A = Prompts user for the height of the annotation.
B = Defines a box with the crosshairs placed at the lower left and upper right.
    Will replot with this scaling.
b = Allows the user to be prompted for the background color on Enhanced
    SAOimage.
C = Turns on the crosshairs and by pressing the <CR>, prints the values at
    that location and puts the values in a common block;  typing - deletes the
    last pair of values from the common block; and typing Q turns off the
    crosshairs.
c = Allows the user to be prompted for the color, e.g., on Enhanced SAOimage.
F = Allows the user to alter the scaling factor on the current plot device(s).
f = Allows the user to change the fill style for each plot.
H = Gives help.
h = Gives help.
I = Allows the user to be prompted for several of the plotting parameters
    before a replot is done.  This command is typically used when preparing
    a plot for publication.
    The following operations are available:
    1) Inverting the X axis and/or Y axis
    2) Labeling the X and Y axes in the following ways:  Linear automatic,
       Linear manual, Antilog automatic, Antilog manual (antilog refers to
       the fact that the labeling is the antilog of the plotted values which
       are logs)
       a) In the Linear manual mode one can specify for the X and Y axes, the
       lowest labeled physical value, the physical value/interval, and the
       number of intervals (coded as nn.llrr where nn is the integer part, .ll 
       represents the left (or bottom) fractional part, and .rr represents the
       right (or top) fractional part of an interval).
       b) In the Antilog manual mode one can specify for the X and Y axes, the
       lowest displayed tick mark (coded as log.antilog where log is the
       integer part of the plotted value (which is a log), and antilog
       represents the first displayed tick mark of that decade (which
       is an antilog)).  The antilog of the physical value at the first tick
       mark may or may not be printed byu the program.   One can also specify
       the number of displayed decades (coded as n.antilog where n is the
       integer part of the number of decades, and antilog represents the
       rightmost displayed tick mark of an additional decade.  For example, if
       one enters -1.5 for the lowest value and 3.2 for the number of decades,
       then the first tick mark will be at X=0.5 (log = -0.301 = -1 + 0.699)
       and the last tick mark will be at X=200 (log = 2.301).  Note that 
       fractional parts of .0 and .1 behave the same way.
       
       Note:  If the original plot was linear, then the log of the data should
       be taken first (with the L command) for the antilog labeling to make 
       sense.
    3) Specifying symbol heights
    4) Specifying labels for the X and Y axes
    5) Specifying a title
    6) Specifying one or more print devices
L = Allows the user to take log(X) and log(Y).
l = Allows the user to take ln(X) and ln(Y).
M = Allows the user to modify the X and Y values by adding increments and
    adjusting by scaling factors.
m = Allows the user to modify the X and Y values by adding increments and
    adjusting by scaling factors for a selected plot.
O = Redoes the original plot with any new axes, colors, and symbols.
o = Redoes the original plot without any new axes or symbols.
P = Allows the user to take powers.
p = Allows the user to specify the color of each plot.
Q = Returns.
q = Returns.
R = Turns on the crosshairs and by pressing the <CR> at chosen X limits,
    replotting with automatic scaling will be done.
S = Allows the user to specify the style of vector.
s = Allows the user to specify the symbol for a set of points.
V = Draws a vector of the color and vector style most recently selected.
v = Allows the user to be prompted for the starting and ending physical
    values of a vector.
X = Allows plotting an additional X axis in different linear units.
x = Allows plotting an additional X axis in different antilog units.
Y = Allows plotting an additional Y axis in different linear units.
y = Allows plotting an additional Y axis in different antilog units.

     On SAOimage and xgterm, user prompts appear on the text terminal 
whereas on all other devices the prompts will appear on the Tek window.
Note that a plot can be sent to more than one device at a time.
Xgterm, a color xterm, behaves mostly like xterm.  One difference
between the two is that xterm allows one to use the left mouse button to
interact with the plot whereas xgterm requires a <CR> press.  SAOimage
also requires a <CR> press for plot interaction.  SAOimage on Mac OS
also requires that it be given focus by clicking in the frame before
any interaction is attempted.  Following that, the cross cursor should
be positioned within the SAOimage desktop area before and commands are
given.  The version of SAOimage available from most sources will not work
with plotting;  the version that is required is "Enhanced SAOimage, v. 1.24",
available at the MIIPS website.
     The plot device xgterm is a color xterm-like graphics terminal 
emulator which runs on Unix.  Copies for various operating systems can be 
found on the website.
     Xgterm needs to have its colors defined in the user's .Xdefaults file.
The following entries will ensure that the correct colors are displayed:

Xgterm*gterm*color0:      black
Xgterm*gterm*color1:      ivory1
Xgterm*gterm*color2:      red
Xgterm*gterm*color3:      green
Xgterm*gterm*color4:      blue
Xgterm*gterm*color5:      cyan
Xgterm*gterm*color6:      yellow
Xgterm*gterm*color7:      magenta
Xgterm*gterm*color8:      gold1
Xgterm*gterm*color9:      DarkSlateGray3
Xgterm*gterm*height:      601
Xgterm*gterm*width:       801

     If a plot file is being created it is possible to add annotation
that will be written to the file.  For example, if one selects

  DEVICES=X F

the plot will appear on an xterm and be written to a file.  Pressing
"a" while the plot is displayed on an xterm will then bring up a cursor.
Position the cursor on the plot and then click the left mouse button 
(or press the <CR> for xgterm and SAOimage).  You are then prompted to 
enter some annotation.  You can enter either English text, Greek letters,
special symbols, or some combination of them.  Typing ^I (^L on Mac OS X)
at this time, toggles to the Greek alphabet and special symbols, and back
to English.  In the Greek mode, the numbers 0 to 9 produce the symbols 0
to 9.  One could for example use special symbol 1 (a circle) to denote the 
position of the primary in a plot of a relative orbit.  Note however,
that the cursor center currently corresponds to the lower left corner 
of the initial character.


                        The Plot Command

     After a plot file has been created, the plot can at any time be 
directed to any of the available plot devices by using the plotcom.exe 
program.  Since the plot file's default name is plot.plt, be sure to 
change this to some other name to avoid having it be overwritten by another
plot file.  To plot a plot file, first be sure that you have set up the 
alias 'plot' as described above.  Enter:
  
  plot device=P xoff=X yoff=Y scale=S rotate=R number=N input_plot_file

where 
1)  Each optional keyword, and in the case of "device", its value, can be
    shortened to an unambiguous abbreviation
2)  If no device is specified, the default is xterm
3)  If no plot_file is specified, the default is plot.plt
4)  An optional / delimiter can be used between keywords (but not before the
    first one)
5)  The keywords have the following meaning:
      device is the plot device, with values, P, equal to
         TEKTRONIX  = Graphics terminal (VT100/Retrographics and Visual 550)
         GRAPHON    = Graphon graphics terminal
         CODONICS   = Codonocs graphics terminal
         MICROTERM  = Microterm graphics terminal
         VERSATERM  = Versaterm graphics terminal emulator for Macintosh
         XTERM      = Xterm graphics terminal emulator for OpenVMS and Unix
         XGTERM     = Xgterm grpahics terminal emulator for Unix
         SAOIMAGE   = Enhanced SAOimage
         _SAOIMAGE  = Enhanced SAOimage with not erasure of the previous image
         POSTSCRIPT = Postscript output file (default name is plot.ps)
         EPS        = Encapsulated postscript output file (default name
                      is plot.eps)
         (each device can be shortened to an unambiguous abbreviation,
         e.g. pos or POS for POSTSCRIPT)
      xoff is the horizontal offset, X, of the plot in inches
      yoff is the vertical offset, Y, of the plot in inches
      scale is the magnification, S, of the plot in terms of a factor.
      rotate is the counterclockwise rotation, R, of the plot in degrees
      number is the number, N, of the complete plot within the plot file.
         Because the plot file is not closed until testfits quits,
         all plots are written to the same file, and the "number" keyword
         must be used to select the plot.
6)  The keywords and their values can be upper- or lowercase
7)  When both rotation and offsets are given, the operation can be thought of
    as either 1) rotation about the lower left corner of the plot
    followed by translation in the rotated coordinate system, or 2) translation
    followed by rotation about the old location of the corner.  Thus a plot on
    xterm can be viewed rotated 90 counterclockwise with a command such as:
      plot yof=-6 rot=90 sca=0.75 myplot.plt
8)  Postscript files created by the plot command are by default matched to
    a printed sheet viewed in landscape orientation.  Thus when such a file
    is viewed with ghostview or another postscript viewer, they will appear
    to be rotated by 90 degrees counterclockwise.  To create a postscript
    file without the prerotation, use a command such as:
      plot dev=pos xof=-8.0 rot=-90 myplot.plt
9)  Encapsulated postscript files are by default not prerotated and will
    appear in the correct orientation in ghostview.  In addition, encapsulated
    postscript files are by default created with a bounding box size just
    slightly larger than the default XY plot size (X axis = 6 inches, Y axis
    = 5 inches).  If your plot size is larger or smaller than the default size
    just use an editor such as vi to change the dimensions in the *.eps file.
    The BoundingBox line is 5th from the top.  The encapsulated postscript
    files will not ordinarily produce output on a printer because because they
    do not contain the 'showpage' command.  If you wish to see a printed
    version of your eps file, just add 'showpage' after the last 'stroke'
    command on the third line from the end.
10) The keyword, number, selects the number of the plot within a multi-plot
    file.  If the number keyword is not given, by default the first plot is
    displayed on devices such as graphic terminals, xterm, xgterm, and
    SAOimage.  If a postscript file is created and no number keyword is given,
    all plots are written to the file.  For an eps file, only the first file
    is written.  If the value given for the number keywords is -1, then all
    plots are displayed overlapped on all devices, postscript files, and eps
    files.


               Plotting from an ASCII File

     One or more ASCII files of data can be plotted with the program
xyplot_ascii.exe, a general purpose interface for the xyplot.for.  Three
cases can be handled.  In the first case, the data for the abscissa and
ordinate are contained in one file having an arbitrary number of header lines,
an arbitrary number of columns, and an arbitrary number of rows of data.  All
columns must have the same number of rows however.  Multiple plots are possible
by selecting more than one column for the abscissa and ordinate.  The number
of columns chosen for the abscissa and ordinate must match.  In the second
case, the data for the abscissa are contained in a first file and the data for
the ordinate are contained in a second file.  The number of rows in both files,
other than header rows, must match.  Multiple plots are again possible.  In
the third case, the abscissa and ordinate data for the first plot are contained
in the first of several files, and the abscissa and ordinate data for
additional plots are contained in additional files up to a maximum of fifteen
plots.  This is the most general case because the numbers of rows do not have
to match between files.  In all three cases the data can be in the form of
decimal or integer values.
     A setup file needs to be opened which sets up the line dashing, pen
width, line style, symbols, and colors.  By editing this setup file, many
different graphs can be produced.  In the setup file, the name of the
control parameter is followed on successive lines by the values desired
for each plot.  The control parameters may be in any order.  The number of
values can be less than, equal to, or greater than the number of plots
desired.  The program will simply use the values up to the last one
available, and then roll the values over.
    The file xyplot_setup1.dat, shown below, is an example of this format:

LINE VECTOR STYLE
0
0
0
0
0
0
0
1
2
3
4
5
PEN WIDTH
20
LINE TYPE
-1
0
997
997
-1
997
997
SYMBOL
0
1
100
100
327681
100
100
5
6
7
8
9
10
INVERT X
NO
INVERT Y
NO
COLOR
16776960        Yellow
16711935        Magenta
65280           Green
65280           Green
16711680        Red
8388564         Aquamarine
8388564         Aquamarine
255             Blue
16766720        Gold1
65535           Cyan
7982541         DarkSlateGray3
16777200        Ivory1
10824234        Brown
16716947        Deep pink
5597999         Dark olive greem
15631086        Violet
16766720        Gold
16770229        Moccasin
X LABEL
X Axis
Y LABEL
Y Axis
TITLE
Anonymous

1) Each keyword is followed, on successive lines, by the values for a single
plot within the complete plot.  If there are more plots than values, rollover
will occur.  If there are fewer plots than values, the extra ones will not be
used.
2) The keywords may be in any order
3) Comments are allowed to the right of a value, however it is very important
that there be no tabs in the line.
4) The LINE TYPE (as explained in line.for) controls the plot lines and the
   type of plot, where:
   a) The magnitude of the value controls the frequency of plotted symbols,
      e.g. zero gives no symbols, and 4 gives a symbol every 4th data point
   b) Positive values give a straight line connecting every data point
   c) Negative values give no connecting straight lines
   d) If the value is 997 error bars are drawn (two plots are required)
   e) If the value is 998 a histogram is drawn with the bars stacked
      vertically if multiple plots are made
   f) If the valud is 999 a histogram is drawn with the bars placed next
      to each other is multiple plots are made
5) The SYMBOL controls the type of symbol where
   a) values from 0 to 13 in the first byte give the built-in symbols
   b) a character may be plotted if the ASCII code is placed in the second byte
   c) if a histogram is to be drawn, the value in the first byte give the
      filling style
   d) if error bars are to be drawn, the value in the first byte give the
      style of the bar, i.e., 0 give a short tick, 1 gives nothing, 2 gives
      an arrowhead.  If 100 is added to the first byte, the X or Y locations
      contain the central location and the deviation to the low and high
      directions, respectively, for the adjacent array locations.  Because
      errorbars require two plots, the values should be repeated.
   e) the value in the third byte give the symbol height in hundredths of
      an inch.  If the value is not present a default of 0.14 inch is used.

     In the above example setup file, the values under LINE TYPE and SYMBOL
indicate that the first plot will consist of points drawn with symbol number 0
with no connecting lines, and the second plot will have connecting lines
between the points with no symbols drawn.  The third plot will be error bars
drawn with the usual short ticks at the ends.  Because error bars require two
adjacent plot array locations, the values for each keword are repeated.  The
fourth plot will consists of points drawn with symbol number 1, but because
the symbol is to be drawn with a smaller size of 5/100 inches, 5 is added to
the 3rd byte, giving a final value of 1 + 5*256**2 = 327681.  A future version
of xyplot_ascii will attempt to make this operation more user friendly.
The next plot is again error bars, requiring repeated values.

     Five sample ASCII files are included in this package to demonstrate how
xyplot_ascii.exe works.  Launch the program, and you will be presented with
the following menu:

  Enter a choice for the input data:
       1 = Abscissa and ordinate data for one or more plots in one file
           (default)
       2 = Abscissa data in one file and ordinate data in another file for
           one or more plots
       3 = Abscissa and ordinate data for first plot in first file,
           additional data for additional plots in successive files, up
           to a maximum of ten files
  CHOICE=

Enter 1, and the program responds with:

  Open the file containing the abscissa and ordinate data for one or
  more plots.
  Enter the file name:
  FILE=

Enter ascii1.dat, and the program asks:

  How many lines are in the header?  (default = 1)
  LINES_HEADER_1=

Enter 1 or take the default, and the header line will be displayed, along
with the counts of the number of columns of data and the number of lines of
data.  The program then asks:

  Enter the column(s) to be plotted as abscissa values:
  COLUMNS_ABSCISSA=

Here we are going to plot the data in column 2 against time in column 1, plot
the curve in column 6 against time, and plot error bars for the data.  Because
all abscissa values originate from column 1, and because there are 4 plots
(data, curve, and error bars requiring 2 plots) we enter 1 1 1 1.  The program
then asks:

  Enter the column(s) to be plotted as ordinate values:
  COLUMNS_ORDINATE=

We enter 2 6 2 3 (column 2 for the data, column 6 for the curve, column 2 for
the central location of the error bar, and column 3 for the amplitdue of the
error bar).  Now the program asks for the name of the setup file:

  Open the setup file:  (default = xyplot_setup.dat)
  SETUP_FILE=

Enter xyplot_setup1.dat (do not take the default) and the program then asks

  Enter the plot devices:
       S   = SAOimage (Enhanced version)
      -S   = SAOimage, no erasure of screen
       G   = Graphics terminal (VT100/Retrographics and Visual 550)
       G4  = Graphics terminal emulator (Versaterm)
       X   = Xterm (default)
       XG  = Xgterm
       F   = File

Enter the appropriate device name, and you will see the plot.

     If you enter 1 1 1 1 1 1 1 for the abscissa columns, and 2 6 2 3 4 4 5
for the ordinate columns, you will see an additional set of data points
plotted with a different symbol, a different symbol size, a different error
bar length, and different colors (if you are using a color display).

                             *************
     Launch xyplot_ascii.exe again and this time enter 2 for the choice of
input data.  In this case, the abscissa data come from one file and the
ordinate data from a second file.  The program responds with:

  Open the file containing the abscissa data for one or more plots.
  Enter the file name:
  FILE=

Enter ascii2.dat, and the program asks:

  How many lines are in the header?  (default = 1)
  LINES_HEADER_1=

Enter 1 or take the default, and the header line will be displayed, along
with the counts of the number of columns of data and the number of lines of
data.  The program then asks:

  Enter the column(s) to be plotted as abscissa values:
  COLUMNS_ABSCISSA=

Enter 1 1 1 1.  The program then asks:

  Open the file for the ordinate
  Enter the file name:
  FILE=

Enter ascii1.dat, and the program asks:

  How many lines are in the header?  (default = 1)
  LINES_HEADER_2=

Enter 1 or take the default, and the header line will be displayed, along
with the counts of the number of columns of data and the number of lines of
data.  The program then asks:

  Enter the column(s) to be plotted as ordinate values:
  COLUMNS_ORDINATE=

Enter 2 6 2 3, as before, and the program asks:

  Open the setup file:  (default = xyplot_setup.dat)
  SETUP_FILE=

Enter xyplot_setup1.dat, as before, and the program then asks

  Enter the plot devices:
       S   = SAOimage (Enhanced version)
      -S   = SAOimage, no erasure of screen
       G   = Graphics terminal (VT100/Retrographics and Visual 550)
       G4  = Graphics terminal emulator (Versaterm)
       X   = Xterm (default)
       XG  = Xgterm
       F   = File

Enter the appropriate device name, and you will see a plot which differs from
the first one in that the abscissa values are larger by a factor of 100.

                             *************
     Launch xyplot_ascii.exe again and this time enter 3 for the choice of
input data.  In this case, the abscissa and ordinate data for the first plot
are contained in the first of several files, and the abscissa and ordinate
data for additional plots are contained in additional files up to a maximum
of fifteen plots.  The program responds with:

  Open the file containing the abscissa and ordinate data for the first plot.
  Enter the file name:
  FILE=

Enter ascii3.dat, and the program asks:

  How many lines are in the header?  (default = 1)
  LINES_HEADER=

Enter 13, and the program will report the number of columns of data and the
number of lines of data, and then ask:

  Enter the column(s) to be plotted as abscissa values:
  COLUMNS_ABSCISSA=

Enter 1 1 1, (the columns for the x data points and their error bars).  Then
the program asks:

  Enter the column(s) to be plotted as ordinate values:
  COLUMNS_ORDINATE=

Enter 2 2 3, (the columns for the y data points and their error bars), and
the program responds with:

  Enter the name of the input file for an additional plot;
  enter 0 to continue:
  FILE=

Enter ascii4.dat, and the program asks:

 How many lines are in the header?  (default = 1)
 LINES_HEADER=

Enter 13, and the program will report the number of columns of data and the
number of lines of data, and then ask:

  Enter the column(s) to be plotted as abscissa values:
  COLUMNS_ABSCISSA=

Enter 1, (the column for the x data of a single curve).  Then the program
asks:

  Enter the column(s) to be plotted as ordinate values:
  COLUMNS_ORDINATE=

Enter 2, (the column for the y data of that curve).  The program next asks:

   Enter the name of the input file for an additional plot;
  enter 0 to continue:
  FILE=

Enter ascii5.dat, and the program asks:

 How many lines are in the header?  (default = 1)
 LINES_HEADER=

Enter 13, and the program will report the number of columns of data and the
number of lines of data, and then ask:

  Enter the column(s) to be plotted as abscissa values:
  COLUMNS_ABSCISSA=

Enter 1 1 1, (the columns for the x data points and their error bars for
another set of data).  Then the program
asks:

  Enter the column(s) to be plotted as ordinate values:
  COLUMNS_ORDINATE=

Enter 2 2 3, (the columns for the y data points and their error bars).  The
program next asks:

  Enter the name of the input file for an additional plot;
  enter 0 to continue:
  FILE=

Enter 0, because we are done entering the ascii files of data.  Now the
will ask:

  Open the setup file:  (default = xyplot_setup.dat)
  SETUP_FILE=

Enter xyplot_setup2.dat (don't take the default).  Then you are asked:

  Enter the plot devices:
        S   = SAOimage (Enhanced version)
       -S   = SAOimage, no erasure of screen
        G   = Graphics terminal (VT100/Retrographics and Visual 550)
        G4  = Graphics terminal emulator (Versaterm)
        X   = Xterm (default)
        XG  = Xgterm
        F   = File

  DEVICES=

Enter your current graphics device and a plot with two sets of data with error
bars, and a curve with a dashed line will be displayed.  You can then use the
built-in interacive commands of xyplot to rescale, arithmetically tranform
the data, add annotation, and send the plot to the same or a different device,
or a file.


     Any questions should be directed to Donald Gudehus at
gudehus@chara.gsu.edu.
