Subj: GBES schedco Users guide
From: Toney Minter
Date: 96 December 12, updated 97 Jun 25

This document describes GBES offline utility program "schedco" for 
conversion of the global space radio telescope (SRT) schedule file
into a local command file for running the tracking station.

schedco
==============

The schedco program reads through the SRT file, and optionally the orbit 
predictions file in order to produce the local command file. The output
command file  is put into a file which by default is located in the directory 
/s3/ftp/ovlbi/in.  The name of this file is determined by schedco and is
reported to the user after schedco has finished running.


Like all GBES offline programs, schedco also produces a short
help message if executed without arguments.  Ie:

% /s3/ovlbi/bin/schedco

schedco is an offline program which reads a global schedule file and the latest 
orbit file in order to produce a command file and schedule for the GBES.
schedco: optional arguments are in [brackets]; usage
schedco [<times>] [-badtape <bad tape>] [-state <station state>]
[-tapeS2  <1> <1> <T/F>] [-tapeVLBA  <1,2,3> <1-28> <mode> <T/F>] 
[-tapeVSOP  <1,2> <1-28> <T/F>] 
[-orbit <geometry file>] [-out <outputFile>] <SRT file>
  where  <SRT file>      is the SRT file to be interpreted
         <geometry file> is the orbit file used for tracking
         <bad tapes>     not yet in use, do not enter a value
         <station state> not yet in use, do not enter a value
         <outputFile>    is the output file name

  -tape{S2,VLBA,VSOP} indicates that the tape parameters will be specified
    by the user with the following four arguements:
         <1,2,3>   specifies the current tape drives available
                   1,2 => how many tape drives available to
                          the designated tape drive
                   3   => record on two tapes at once (vlba only)
         <1-28>    specifies the tape track to begin recording on
         <mode>    specifies the VLBA recording mode (001,002)
         <T/F>     specifies whether a new tape is to be mounted
All three arguements must be entered if -tape?? is specified
           
where <times> can be one or more of:
      -b[egin] <mjd> [<time>] first date and time to examine
      -e[nd]   <mjd> [<time>] last  date and time to examine
      -s[ingle] <mjd>         process a single day of files
      -t                      todays files (UTC date)
      -y                      yesterdays files (UTC date)
<times> must have the date (ie 96Oct31), but hours are optional
ie: -b 96Jun23                start at begining of day (0 hours)
ie: -e 96Jun23 13h30m15s      specify fixed end time
           
NOTE: If no orbit file is provided, the times of key holes can not be
      calculated, and the command file must be edited to include a orbit
      prediction file name.  The output file name is determined automatically 
      if -out is not specified.  If -out is specified then the tape histories 
      WILL NOT be updated.

Options
=======
-badtape <bad tape>		Allow the user to specify if a tape drive is
				not to be used.  NOT YET IMPLIMENTED.
-state <station state>          Allow the user to specify the state of the 
				tracking station. NOT YET IMPLIMENTED.
-tapeS2  <1> <1> <T/F>		Allows the user to specify the state
				of the S2 tape that is loaded at the
				begin time used by schedco. The first value
				is the number of the S2 tape drive - currently
				their is only one drive available.  The 
				second input is the tape pass number - S2 only
				has one pass.  The <T/F> value specifies
				if a new set of tapes is to be mounted.
-tapeVLBA  <1,2,3 > <1-28> <mode> <T/F>]	Allows the user to specify the
						status of the VLBA tape(s) at
						schedco's begin time.  The 
						first value is the current tape
						drive unit number. (Note that
						3 means recording on both units
						at the same time.)  The second
						input is the tape pass number -
						there are 28 passes in our 
						recording to VLBA tapes.
						The third entry is the mode
						of tape recording.  Mode 1
						is 16 tracks.  Mode 2 is 32
						tracks.  The <T/F> value 
						specifies if a new set of tapes
						is to be mounted.
-tapeVSOP  <1,2> <1-28> <T/F>	Allows the user to specify the VSOP tape status
				at the begin time that schedco used.  NOT YET
				AVAILABLE FOR USE.
-orbit <geometry file>		This is not a required value but it is strongly
				urged that it be specified.  It specifies what
				orbit file to use.  See below for an 
				explenation of why it should be specified.
-out <outputFile>		This option allows the user to the define the 
				output file name.  This option is usually used 
				for debugging.
<SRT file>			This input is the space radio telescope 
				schedule file that schedco will use to generate
				the local command file.

Standard Use
============
The usual way in which schedco  will be used is to specify the begin
time, the geometry (orbit predictions) file and the SRT file.  Note
that if the geometry file is in the directory /s3/ovlbi/in then the
directory structure can be omitted from the geometry file name.  
Similarly if the SRT file is in /s3/ftp/ovlbi/in then the directory 
structure can be omitted from this file name. For example, if the SRT
file is  /s3/ftp/ovlbi/in/961010.srs, the geometry file is 
/s3/ovlbi/in/961010.bsp.orb and we would like to create a command file
that begins on October 11 then the command line should be

% /s3/ovbli/bin/schedco -begin 1996OCT11 -orbit 961010.bsp.orb 961010.srs

OUTPUT
======
By default schedco determines the output command file name.  The name is
given by YYMMMDD.cmd where YYMMMDD is the year, month (abbrevated first three
letters in all capitals) and day of the first
valid command in the output command file.  By default the command file
is located in the directory /s3/ovlbi/in.

If schedco has run succesfully then the command file name will be presented
as the next to last line of the output. I.E. the last two lines will be

Opened output file: (filename)
DONE

where (filename) will be the name of the command file that has been created.

The Geometry File
=================

Schedco does not depend on having valid data from the geoemtry file in 
order to run.  However, the command file that is created does depend 
on having valid data from the geometry file.  Schedco was designed to
run so that the geometry file was an optional input.  If the geometry
file is not specified in the inputs to schedco then the resulting command
file will need to be edited in order to define the geometry (or orbit) file.
Also, if the geometry file is not given to schedco then there will be
no estimation of when the tracking station will enter and leave the keyhole.
The demodulator attenuation settings will also remain unspecified.

If a valid geometry file is given as input to schedco, we may encounter
the situation in which the geometry file expires before the SRT file ends.
In this case a message command is put in the command file to tell the
operators that the geometry (orbit) file has expired.  Schedco will 
continue to run after the geometry file has ended as if there was no
geometry file specified.  When this situation is encountered the following
message is displayed by schedco 

Orbit file error: Failed to Read Orbit File Entry
Will continue processing data without orbit file

PLATFORMS
=========
Currently schedco will only run under solaris.