.help xtetape FEB95 ftools.xte
.ih
NAME
xtetape -- Read FITS files from NASA/GSFC/ADF supplied XTE data distribution 
tapes.
.ih    
USAGE
xtetape load_tape load_dir check_size make_dirs load_all load_index 
load_pca load_hexte load_eds load_acs load_ace load_fds load_gsace
load_ipsdu load_spsdu load_pse load_ifog load_prod load_orbit load_clock
load_cal
.ih
DESCRIPTION
xtetape examines the contents of XTE FITS 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 xtetape 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 Entire tape contents
.le

.ls XFF index files
.le

.ls Proportional Counter Array (PCA) instrument files
.le

.ls HEXTE instrument files
.le

.ls Electronic Data System (EDS) housekeeping files
.le
 
.ls Attitude Control System (ACS) files
.le

.ls Attitude Control Electronics (ACE) and star tracker files
.le

.ls Flight Data System (FDS) files
.le

.ls Gimbals and Solar Array Control Electronics (GSACE) files
.le

.ls Instrument Power Switching and Distribution Unit (IPSDU) files
.le

.ls Spacecraft Power Switching and Distribution Unit (SPSDU) files
.le

.ls Power System Electronics (PSE) files
.le

.ls Interferometric Fiber Optics Gyroscope (IFOG) files
.le

.ls Orbit emphemeris files
.le

.ls Time delta corrections (Clock) files
.le

.ls Calibration files
.le

.ls Standard science product files
.le

In addition to loading files by class, xtetape allows users to place the
tape contents into its original GOF (XFF) subdirectory structure. 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 xtetape creates a top level 'FD' directory under the specified load
directory (load_dir). Under the 'FD' directory subdirectores are created
for each announcement of opportunity (AO) phase, proposal ID and XTE 
observation ID (obsID) for which data is present on the tape. Under each of 
the AO/proposal_ID/obsID subdirectires a complete set of subdirectories for
the above listed data classes are created.

The user may construct these directories ahead of time and xtetape 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, xtetape 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 XTE 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 xtetape will report back the number of kilobytes and VMS
blocks 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 xtetape with the check_size option
turned off to load the files.

.ih
PARAMETERS

The following are the xtetape "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] [no default]
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_index [boolean] [default = yes]
Set to "yes" to load the XFF index files from tape.
.le

.ls load_pca [boolean] [default = yes]
Set to "yes" to load all PCA data files from tape
.le

.ls load_hexte [boolean] [default = yes]
Set to "yes" to load all HEXTE data files from tape.
.le

.ls load_eds [boolean] [default = yes]
Set to "yes" to load all EDS housekeeping files from tape.
.le

.ls load_acs [boolean] [default = yes]
Set to "yes" to load all ACS files from tape.
.le

.ls load_ace [boolean] [default = yes]
Set to "yes" to load all ACE files from tape.
.le

.ls load_fds [boolean] [default = yes]
Set to "yes" to load all FDS files from tape.
.le

.ls load_gsace  [boolean] [default = yes]
Set to "yes" to load all GSACE files from tape.
.le

.ls load_ipsdu [boolean] [default = yes]
Set to "yes" to load all IPSDU files from tape.
.le

.ls load_spsdu [boolean] [default = yes]
Set to "yes" to load all SPSDU files from tape.
.le

.ls load_pse [boolean] [default = yes]
Set to "yes" to load all PSE files from tape.
.le

.ls load_ifog [boolean] [default = yes]
Set to "yes" to load all IFOG files from tape.
.le

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

.ls load_orbit [boolean] [default = yes]
Set to "yes" to load all orbit emphemeris files from tape.
.le

.ls load_clock [boolean] [default = yes]
Set to "yes" to load all spacecraft clock files from tape.
.le

.ls load_cal [boolean] [default = yes]
Set to "yes" to load the instrument calibration files from tape.
.le

In addition to the mandatory parameters, there are two "hidden" parameters
that the user may choose set on the command line, but will not be prompted
for:

.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 xtetape Utility. Just by
typing its name xtetape 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 xtetape
.le

This next example reports back to the user the amount of disk space 
needed to load all the files from the tape:

.ls xtetape load_all=yes check_size=yes
.le

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

In all the examples above xtetape 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 the Solaris 2.3 operating
system. 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 xtetape task. Otherwise, a
tape read error might result.

.ih 
SEE ALSO
.endhelp

