User guide to Apriori, Skeleton, Ut1pm
Brent Archinal
Leonid Petrov

Abstract:

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 <0񼆊> -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. ----------------------------------------------------------------


Questions and comments about this guide should be sent to:

Leonid Petrov ( pet@leo.gsfc.nasa.gov )

Last update: 2000.09.07