                     User guide to Apriori, Skeleton, Ut1pm
 
 
                                Brent Archinal
                                Leonid Petrov
 
 
                                2000.09.07
 
 
                                Abstract
 
   This document is a user manual for programs apriori, skeleton, ut1pm
which are a part of MARK-4 VLBI Analaysis Software CALC/SOLVE.
 
 
Questions and comments about this guide should be sent to:
 
Leonid Petrov ( pet@leo.gsfc.nasa.gov )
 
 
                                Table of contents:
 
 
1 ................ Overview
 
 
2 ................ Apriori
 
 
3 ................ Skeleton
 
 
4 ................ Ut1pm:
 
 
5 ................ History
 
 
________________________________________________________________________________
 
        1 Overview
        ==========
 
Apriori:    A Priori and Ephemeris Utility
Skeleton:   Skeleton Database Maintenance Utility
            (and format for VLBI apriori file, blokq.dat)
Ut1pm:      UT1 and Polar Motion Data File Maintenance Utility
 
   Documentation follows for each of the three programs and the
library listed above.  It consists of at least brief documentation
on the use and operation of the programs, including listings of the
runstring options (in standard Unix notation), and descriptions of
those options.  In some cases example runstrings, installation
instructions, file descriptions, and other information is provided.
 
 
        2 Apriori
        =========
 
   The HP-UX program apriori replaces portions of the A900 program KBMSG,
as well as the A900 program EPHEM, in addition to adding a few more features.
The interface is completely different as is the runstring but the function
remains the same: optionally update a list of databases by removing calc
supplied information, updating station and source a prioris, and providing
appropriate ephemeris and Earth rotation information. Alternative data sources
can be specified if the user does not wish to use the system default skeleton
database, or Earth rotation ("ut1pm.dat") file. The runstring parameters are
as follows:
 
           (database keyname)
            -e
            -s <(skeleton database keyname)>
            -u <(ut1pm file pathname)>
            -n (user's name - 10 characters)
            -f (name of file containing list of databases)
            -c
            -q
            -h
 
  "database keyname", if given, must be a valid keyname for a single
existing database that is to be updated.  Since such keynames
usually contain a "$", the name should be enclosed in single quotes
or else the "$" should be preceded by a "\" (in order to keep most
HP-UX shells from considering the "$" to be a parameter flag).
 
   The e, s, and u options set the action to be taken.  The e option
enables ephemeris updating, the s option enables updating from the
skeleton database, and the u option enables Earth rotation
updating.  If any of these options are present, they will turn ON
the appropriate updating activity.  If none are present, ALL are
turned on (this default is set in ../includes/param.i).  If you
must specify one of them (e.g. "-s" in order to specify an
alternative skeleton database) and you want all the options, you
MUST specify all the options.  Alternative data sources can be
specified as indicated.  Note that these options MUST be given
separately.
 
   If the n option is not given, the user will be prompted for a name.
If the f option is not given and no database keyname is given, the
user will be prompted for a database keyname.
 
   The c option will enable the uncalcing feature, effectively
removing all calc-supplied lcodes from the databases in the current
run so that calc may be rerun on these databases.
 
   The q option runs apriori in a quiet batch mode, with no output to
the screen.
 
  The h option displays a help screen and terminates the program.
 
 
Example runstrings:
 
  1. Have the program prompt interactively for a user name and a
database to be updated with ephemeris, skeleton, and Earth rotation
information:
 
     apriori
 
2. Read database keynames from a file "dblist" in the current
directory and update the ephemeris and Earth rotation information:
 
     apriori -e -u -n GreggCooke -f dblist
 
3. Uncalc, and update all possible information in the database
"$88FEB10XA":
 
     apriori '$88FEB10XA' -n B.Archinal -c
 
 
        3 Skeleton
        ==========
 
   This is the Unix implementation of the A900 program SKELETON,
with a couple of added features:  the ability to create alternative
skeleton databases, and the ability to pull a priori values from
an existing database (as per A900 KBMSG).  The option to use data
from another database cannot be used on the system default
skeleton; only the blokq.dat file can be used as its data source.
The targeted skeleton database is either updated or created as
needed.  Also, the amount of output the program produces can be
controlled.  Finally, it should be noted that the mathematical
constants are no longer read from the blokq.dat file but instead
are set in the "mathbd" subroutine.  Documentation of the constants
used is provided in that subroutine and also in memos of B.
Archinal (to the mk4-analysis e-mail exploder) of January 5 and
February 7, 1994.  Documentation of the blokq.dat format
description follows this section.
 
     The runstring parameters are as follows:
 
           -s <(skeleton database keyname)>
           -b <(blokq file pathname)>
           -a (alternative database keyname) <(version of
database)>
           -v <012>
           -h
 
     Skeleton database name MUST begin with "$$".
     Database name should be in quotes.
     The -s option MUST accompany the -a option.
 
 
   If the s or b options are omitted, the system defaults will be used, only
if the user permits the system to do so -- by typing "go". The alternative
database must be an experiment database; ALL the station and source a priori
values in such a database are used. The verbosity level is 0 for silent
(no output), 1 for standard (default), and 2 for the nosy (lots of interesting
stuff...).  The h option displays a help screen and terminates the program.
 
   Deleting a database from the $$SKELETON key:
 
   Normally, a skeleton database once created should never be deleted.
This is because any databases processed at a later date may contain
information derived from the skeleton database which in turn should
always be maintained for documentation purposes.  For this reason,
in the "catlg" program the particular key "$$SKELETON" is protected
from deletion or having any database versions deleted from it.
 
   On occasion however, it may be desirable to delete at least the
most recently created database on the $$SKELETON key.  This may
happen for example if a mistake is made in the blokq.dat file, or
when a very bad source position is being updated in an iterative
fashion, or if the skeleton program itself should fail
unexpectedly.  If one carefully assures that no other databases are
created (or left) that use information from this version, it can
be deleted with the assistance of the catalog utility routine
"catlx" as follows.
 
   First, the physical location of the database file should be
determined using the catlg LI function - so that it can manually
be deleted later.  Then catlx should be run in order to provide the
actual catalog record number of the latest $$SKELETON database.
Input to this program includes the identifying two letters of the
database catalog (e.g. "i4" at USNO), and its location (e.g.
"/data/catalog").  After this point one can also just press return
in order to get a list of commands available - but great care
should be exercised in issuing commands so as to not accidentally
corrupt the catalog in any way.  To complete the deletion process,
the user "runs down" the key, with the "RK" command, and by giving
the keyname "$$SKELETON" (properly justified between the "*"), and
the F and L options.  A list of numbers will then be given which
are the catalog record numbers of the various $$SKELETON databases,
listed in increasing version number order.  Make a note of the last
number, and then issue the "DE" command with this number (right
justified between the "*") in order to remove the last version from
the catalog.  Finally, the database file itself should be manually
deleted.
 
 
        4 Ut1pm:
        ========
 
   The ut1pm program is a utility program used to maintain the direct access
"ut1pm.dat" file used by the apriori and dbedit programs. That file contains
a single Earth rotation parameter (ERP) series, at a given interval, over
a number of years, that is used primarily so that ERP information can be
obtained and inserted into a VLBI experiment database.  It also has other
options which allow for easy output of desired portions of the series and
creation of so-called "flyby" or "mod" ERP files for use by the solve system
of programs.
 
   This program has evolved from programs of the same name, first written
at GSFC for an HP1000/F computer, and rewritten at USNO for the HP1000/A900
computer. This version of the program provides all the options available on
the A900 version (except for plotting), but it is not generally interactive.
It is completely controlled by the runstring (except during ut1pm file
creation). Xgraph plotting scripts have been set up which make this version
fully functionally equivalent to the A900 one.
 
   FOR FURTHER INFORMATION ON THE THEORY AND OPERATION OF THE
PROGRAM, FILE FORMATS, AND ON THE STANDARD IERS BULLETIN A ERP
SERIES, PLEASE SEE THE A900 DOCUMENTATION "erp.hlp" AND
"ut1pm.hlp"!
 
     The runstring parameters are as follows:
 
           <(ut1pm file name)>
           -f     (ut1pm file name)
           -u     (update file names)
           -a900  (input HPUX ut1pm file name) (output A900 ut1pm
file name)
           -unix  (input A900 ut1pm file name) (output HPUX ut1pm
file name)
           -C
           -S
           -U
           -F     (flyby file name)
           -TS     XWOB | YWOB | XY | UT1 | UT1R | TAI
           -t      UT1 | UT1R | UT1S
           -span   (first date) | FIRST | NOW  (last date) | LAST | NOW
           -acc    FV | RS | EX
           -#     (update number)
           -hi    (update history entry)
 
   If the default or specified ut1pm file does not exist, the user
will be prompted for information with which to create it if they
desire - this is the only mode in which this program operates
interactively.
 
   The update (-u), conversion (-a900 or -unix), and print/output
options (-C, -S, -U, -F, -TS) are all mutually exclusive.  If these
major options are mixed, only the first one encountered gets used.
The -f option can be used with all of them.  Note that the
conversion options (-a900 or -unix) require both the input and
output ut1pm file names.
 
   The -u option will accept any number of update filenames (up to the
limit of the runstring buffer, currently set in ../includes/param.i
with PARMSZ at 1024 characters), except that the total number of
update records plus the number of records being replaced must not
exceed the value set in ut1com.i with MXUPDT, currently 6000.  If
this limit should be exceeded, one can either change the MXUPDT
value (and all programs which use ut1com.i), do successive updates
with only portions of the total update file(s), or recreate the
ut1pm file from scratch using less than MXUPDT new records at a
time.  The -hi option can be used prior to any occurrence of the
-u option in order to indicate an up to 14 character history entry
for that update.
 
   If the -f option is present with a conversion option, the converted
file will be output into that filename, instead of being returned
to the original file.
 
   The print options are specified by an uppercase letter, sometimes
followed with a special parameter.  The -C ("correlator") option
outputs data for use in correlator "#S" files (including 2 digit
year, day of year, TAI-UTC, XWOB, YWOB).  The -S option outputs
data in a "standard" readable format (including MJD, date, XWOB,
XWOB s. d., YWOB, YWOB s. d., UT1-TAI, UT1-TAI s. d.).  The -U
option outputs data in the same format as input to the program
under the -u option ((including MJD, accuracy designation, XWOB,
XWOB s. d., YWOB, YWOB s. d., UT1-UTC, UT1-UTC s. d.).  The -F
("flyby") option specifies Solve flyby (or mod) file format.  This
format is as specified in the Solve cutil routine "gerot".  The
output is directed to a file "flyby.erp" in the current directory
unless a filename is specified after the -F option.  This file is
written as an ("editable") sequential file, but is used as a direct
access file in the Solve system.   The -TS ("time series") option
outputs data as a "time series", i.e. including the MJD and the
specified values and standard deviations (for XWOB, YWOB, UT1-UTC,
UT1R-UTC, UT1S-UTC, UT1- TAI).  The option -TS XY can also be
specified to get XWOB and YWOB values along with their respective
standard deviations only.  The -TS output can be easily piped to
files or program for plotting or other uses.  If no -TS option is
specified, UT1-UTC data is output by default.
 
   The remaining options -- -t, -span, -acc, and -# -- modify the next
print option, i.e, modifier options are applied to the next print
option encountered in the runstring.  The -t option specifies the
type of UT1-UTC data (if any) to be output, i.e. either "UT1",
"UT1R", or "UT1S".  [Please note that currently - 92OCT28 - the
Solve program cannot yet handle UT1S data in the flyby files.]
This option will override conflicting specifications of the -TS
option.  The -span option specifies a spanning interval over which
the print option operates - start and end dates should be given in
the form "YYMMDD" (or using the words "FIRST", "EARLIEST", "BEGIN",
"START", "LATEST", "END", "LAST", "FINISH", "TODAY", "NOW", "TIME",
or  "DATE").  If one date is given it is assumed to be the start
date, and "LAST" is used as the default end date.  If no dates are
given, this option does nothing.  The -acc option specifies the
accuracy designations to be included in the output.  This is a
cumulative option, so specifying -acc FV -acc RS will print out
final values and rapid service values.  The -# option selects an
update version number for which the print option will operate.
 
   Following are some sample runstrings.  Note that the Unix script command
or piping can be used in order to direct printed output to a file. An
example script which generates the ut1pm file from scratch is included in
the default erp data directory as /data/erp/gen_ut1pm.cmd.  A further example
script which uses Xgraph to plot the erp values is included as
/data/erp/chk_ut1pm.cmd (this latter script requires the workstation hostname
as its only runstring parameter).
 
1. To convert an A900 ut1pm file into a HPUX ut1pm file:
 
     ut1pm -unix A900_ut1pm.dat ut1pm.dat
 
2. To convert a HPUX ut1pm file into an A900 ut1pm file:
 
     ut1pm -a900 ut1pm.dat A900_ut1pm.dat
 
3. To update the ut1pm file:
 
     ut1pm -u ut1up.dat (one update file)
 
     ut1pm -u n9106_0.dat n9106_1.dat ... n9106_12.dat
(multiple update files - can be used to create ut1pm file from
scratch)
 
     ut1pm -u ut1up.dat -f my_ut1pm.dat
(one update file and create special ut1pm file)
 
4. To print the whole ut1pm file:
 
     ut1pm -S
 
5. To print the whole ut1pm file in update file format:
 
     ut1pm -U
 
6. To create a Solve ERP flyby file:
 
     ut1pm -F ERP_flyby.dat
 
 
7. To create a Solve ERP flyby file called "flyby.erp" in the
current directory, using UT1R-UTC values.
 
     ut1pm -t UT1R -F
 
 
8. To print rapid service, polar motion data from update #103 from
January 18, 1990 to April 4, 1990:
 
     ut1pm -span 900118 900404 -acc RS -# 103 -TS XY
 
 
9. To output a time series of UT1-UTC data:
 
     ut1pm -TS
(The type of data desired can also be specified with -TS (e.g.-TS
UT1S), if no type is specified, the default (ut1) is used.  If the
-t and -TS are both included in the run string, the -t option
overrides the -TS; special cases are  "XY", XWOB and YWOB, where
the -t option is ignored).
 
 
10. Generate an update file (ut1up.tmp) containing all the
information currently in the ut1pm file:
 
     ut1pm -U > up1up.tmp
 
        5 History
        =========
 
04/15/90 GGC Written
06/20/90 BAA Converted to WP 4.1 format.  ut1pm section updated,
             some cleanup done in other sections.  Name changed
             from "README" to "apriori.hlp"
12/17/90 BAA ut1pm documentation updated to reflect operation of
             final version.  skeleton program and apriori library
             documentation also updated.
03/08/91 BAA apriori documentation updated to better explain
             runstring.  Explanation of how to delete skeleton
             database added to skeleton program documentation.
             Various other corrections and cosmetic changes made.
04/30/91 BAA Name of put_ephemhdr routine changed, and new_ut1pm
             and getutpm_updt routine documentation added.  Also
             a few other cosmetic changes.
92.04.10 BA  Notes that defaults are in ../includes/param.i
             added.  Converted to WP 5.0 format (and available as
             apriori.wp5).
92.10.28 BA & KW  Modifications in Skeleton and Ut1pm program
(92.12.17)   operation documented.  Ut1pm options description and
             examples also improved.
93.01.05 BA  Warning added concerning Uncalc option of apriori.
94.02.15 MW  Added blokq.dat format description documentation.
94.02.16 BA  General cleanup.
 
Melvin White     94.04.08  Version 2.0.  Dropped all statements
Brent Archinal             referring to slew rates and limit
                           stops.  Default tectonic plate names
                           and lcodes TECTPLNM and TECTMODL
                           added.  Version number for ephem
                           line added in database history.
                           Handled changed error returns from
                           get_ut1pm.f.  luin, luout, luerr
                           used instead of 5, 6, 7.
 
David Gordon     94.07.15  Call obcladd and obclput to put in
                           14 new default observation dependent
                           calibrations and the bitmap of
                           whether they are ON or OFF (Lcodes
                           OBCLLIST and OBCLFLGS).
 
Brent Archinal   95.02.13  "Temporary" indication of above
                           modifications removed.  Installed
                           at USNO.  Version 2.2.
 
Brent Archinal   95.05.25  Observation time set properly if
                           seconds are 60 or above (or hours
                           are 24 or above).
 
Brent Archinal   95.11.07  Using xjd2int1 (rather than xjd2int)
                           in order to avoid roundoff of time.
 
Brent Archinal   95.12.11  Further correction to avoid 1 minute
                           decrease of time if seconds ~ zero.
 
Axel Nothnagel   97.07.29  "ever" initialized properly to allow
                           HP-UX 10.20 use.
 
Brent Archinal   98.03.13  Handling integer*4 number of
                           observations.  Added implicit none.
                           Version 3.0.
 
"     "        1999.05.20  Version 3.1 (changes to get_skull.f).
 
"     "        1999.12.08  Version 4.0.  Handling UTC TAG4 and
                           INTRVAL4.
 
"     "        2000.03.08  Improved error return message from
                           find_intrvl and made fixes to above
                           changes.
 
Leonid Petrov  2000.07.17  Upgraded for using common interface with dbedit.
 
Leonid Petrov  2000.09.07  Forced add_ut1pm to remove all old
                           lcodes with EOP whcih the database
                           might had before adding new lcodes.
                           As a result the output database will
                           have only one type of apriories:
                           FINAL, PRELIMINARY or EXTRAPOLATED.
 
----------------------------------------------------------------
