.help ascatape OCT94 ftools.asca
.ih
NAME
ascatape -- Read FITS files from NASA/GSFC/ADF supplied ASCA data distribution 
tapes.
.ih    
USAGE
ascatape load_tape load_dir check_size make_dirs load_all load_min, 
load_raw load_merged load_clean load_aux load_prod load_optional
.ih
DESCRIPTION
ascatape examines the contents of ASCA data distribution tapes
and then reads those files selected by the user. The tape format
must conform to the NASA/GSFC Astrophysics Data Facility (ADF)
standard. This standard mandates that the first tape file contain a 
FITS file with a single ASCII table extension describing the contents of 
the rest of the tape. If the tape was not made by the ADF, or does not
conform to this standard, then ascatape cannot read the tape.

Users may choose to unload the entire contents of the tape (which
usually takes up a lot of disk space) or certain classes of files.
The following file classes are supported:

.ls Minimum science data set
absolute minimum file set necessary to perform ASCA data analysis. This 
includes all the raw science files (ft*.fits), Mkfilter files (*.mkf) and
associated Xselect catalog files (*frf.cat).
.le

.ls Raw event data files
all files and file catalogs containing raw, unprocessed events along with
their catalogs (ft*.fits, *raw.cat and *frf.cat).
.le

.ls Unscreened event data files
event files that have not been filtered of unwanted events
along with the associated catalog files (*.unf and *unf.cat).
.le

.ls Screened event data files
event files that have been screened of unwanted
events along with the associated catalog files (*.evt and *evt.cat).
.le

.ls Necessary auxiliary data files
auxiliary files needed for data analysis and/or further data processing
(*.ghf, *.orbit and *.mkf).
.le
 
.ls Necessary science product data set
products derived from the event files (*.img, *.detimg, *.pxl and *.gif).
.le

.ls Optional data files 
files not necessary for data analysis. This includes the housekeeping, FITS 
wrapped, calibration, attitude and processing related data files (*HK.*,
*.wrap, fa*, etc...).
.le

In addition to unloading files by class, ascatape allows users to place
the unloaded files in a set of ASCA GOF recommended subdirectories. Using
this subdirectory structure makes for a more organized and understandable
loading of the tape contents. If this option is chosen (make_dirs=yes)
then ascatape creates the subdirectories 'raw', 'unscreened', 'screened',
'aux', 'telem', 'product' and 'work' under the specified load directory. All 
files concerning the raw events will be placed in the 'raw' subdirectory, all 
files concerning the unscreened events wil be placed in the 'unscreened'
directory, all files concerning the screened events will be placed in the 
'screened' directory, all files deemed as auxiliary will be placed in the 
'aux' directory, all original telemetry data files will be placed in the 
'tleme' directory and all processing product related data files will be 
placed in the 'product directory (forgive the run-on sentence). The 'work'
directory is the intended (although not required) area where the user will 
perform his/her analysis. 

The user may construct these directories ahead of time and ascatape will make 
use of the existing directories instead of trying to create them. Thus, by 
creating the directories beforehand, symbolic links may be used to spread the 
loaded data over several file systems (Unix only).

As a final option, ascatape allows users to find out how much disk space
will be necessary to unload a given configuration of files before the
files are unloaded. Since a full ASCA data tape can contain
many hundreds of megabytes of files, this option (check_size=yes) is often 
useful for users who have limited disk space. When the check_size option
is invoked ascatape will report back the number of kilobytes 
necessary to unload the selected file sets instead of actually
unloading the selected file sets. If the reported disk requirements are
satisfactory then the user may rerun ascatape with the check_size option
turned off to load the files.

.ih
PARAMETERS

The following are the ascatape "mandatory" parameters that require answers 
each time the utility is run. If you do not specify them on the command line 
then you will be prompted for them. In case you are unsure of what files are
necessary to load from tape, choosing the default values will load all the 
files necessary for data analysis.

.ls tape_drive [string]
Name of the tape drive to read from. Note that on Unix systems
the "no rewind" tape device driver must be specified.
.le

.ls load_dir  [string] [no default]
Absolute directory path of the area used to load the tape files.
.le

.ls check_size [boolean] [default = no]
Set to "yes" to check the disk space requirements of the selected file sets
before unloading from tape
.le

.ls make_dirs [boolean] [default = yes]
Set to "yes" to create and use the recommended default subdirectory 
structure under the specified load_dir
.le

.ls load_all  [boolean] [default = no]
Set to "yes" to load all files from the tape (uses a lot of space). 
.le

.ls load_min [boolean] [default = no]
Set to "yes" to load the minimum science data set (all ft*.fits and *.mkf 
files) from tape.
.le

.ls load_raw [boolean] [default = yes]
Set to "yes" to load all raw (frfread produced) event files and associated
catalog files.
.le

.ls load_unscreened [boolean] [default = no]
Set to "yes" to load all unscreened event files and associated catalog files.
.le

.ls load_screened [boolean] [default = no]
Set to "yes" to load all screened event files and associated catalog files.
.le

.ls load_aux [boolean] [default = yes]
Set to "yes" to load all necessary auxiliary data files from tape.
.le

.ls load_prod [boolean] [default = yes]
Set to "yes" to load all necessary processing product data files from tape.
.le

.ls load_optional [boolean] [default = no]
Set to "yes" to be shown a further list of possible (optional) data products
that may be loaded from tape
.le

In addition to the above parameters, many other "hidden" parameters exist
within the ascatape utility that allow the user to load specific data 
file sets. To make use of these parameters you must enter them as
command line arguments.

.ls load_sci  [boolean] [default = no]
Set to "yes" to load the minimum science data files (all ft*.fits) from tape.
.le

.ls load_filters [boolean] [default = no]
Set to "yes" to load Mkfilter files.
.le

.ls load_hc [boolean] [default = no]
Set to "yes" to load all housekeeping files.
.le

.ls load_wrapped [boolean] [default = no]
Set to "yes" to load all FITS wrapped scientific product text files.
.le

.ls load_calib [boolean] [default = no]
Set to "yes" to load all calibration files.
.le

.ls load_att [boolean] [default = no]
Set to "yes" to load all attitude files.
.le

.ls load_proc_rel [boolean] [default = no]
Set to "yes" to load all optional processing related log and list files.
.le

.ls load_tel [boolean] [default = no]
Set to "yes" to load all telemetry files.
.le

.ls load_imkf [boolean] [default = no]
Set to "yes" to load the enhanced Mkfilter file(s).
.le

.ls load_sis0 [boolean] [default = no]
Set to "yes" to load all SIS0 instrument data files.
.le
  
.ls load_sis1 [boolean] [default = no]
Set to "yes" to load all SIS1 data files.
.le

.ls load_gis2 [boolean] [default = no]
Set to "yes" to load all GIS2 instrument data files.
.le
  
.ls load_gis3 [boolean] [default = no]
Set to "yes" to load all GIS3 data files.
.le

.ls verbose [boolean] [default = no]
Set to "yes" to get runtime status information.
.le

.ls unwrap [boolean] [default = yes]
Set to "yes" to unwrap FITS wrapped data files as they are unloaded.
.le
.ih
EXAMPLES
.fi

This first example shows the simplest use of the ascatape Utility. Just by
typing its name ascatape will prompt the user for all necessary information.
And, by accepting all the default parameter values, the user will load
from tape all files necessary for data analysis:

.ls ascatape
.le

The following example loads the absolute minimum set of files
from the tape necessary to analyze ASCA data:

.ls ascatape load_min=yes
.le

This next example reports back to the user the amount of disk space 
needed to load the SIS0, GIS3 and MKfilter files:

.ls ascatape load_sis0=yes load_gis3=yes load_filter=yes check_size=yes
.le

If the returned space requirements were satisfactory then the same command
minus the "check_size=yes" would actually load the requested file sets.

This final example shows how to load the science product files, not use 
the default subdirectories and have ascatape report what it is doing

.ls ascatape load_sci=yes verbose=yes make_dirs=no
.le

In all the examples above ascatape would prompt the user for the tape drive
name, load directory name and all other mandatory parameter values; thus, 
it is not necessary to specify these values on the command line.

.ih
BUGS
This routine has been tested under Ultrix, SUN OS, and Solaris operating
systems. While it should work under other OS, there is no guarantee.

The weakest link in any computer system are the tape drives. Therefore,
if your tape does not read correctly please make sure that the drive
it is being read upon is in proper working order. Try cleaning
the drive in the appropriate manner or re-reading the tape on a similar 
drive before giving up.

8mm tape drive systems usually require 30 seconds or more to load tapes.
Therefore, when using 8mm drives please wait an appropriate amount of time
between loading the tape and executing the ascatape task. Otherwise, a
tape read error might result.

Ascatape divides the tape files into classes by parsing the file
name. If the ASCA file naming convention changes, then ascatape
will not work properly.

.ih 
SEE ALSO
.endhelp




