Before attempting to begin using the SDP Toolkit version 5.2.1 some preliminary work ought to be done to ensure as smooth a transition from your previous Toolkit version as possible. This document discusses the changes that you should make before upgrading to TK5.2.1 from TK5.2 (if you are upgrading from an earlier version of the Toolkit it is critical that you first refer to the document UPGRADING TO TOOLKIT 5.2). The following is an outline of this document:


NOTE: In this document:
$PGSHOME is the Toolkit top level directory location (i.e. /tools/cots/TOOLKIT).
$BRAND is the Toolkit name for the O/S you are running (one of: dec, hp, ibm, sgi, sgi32, sgi64, sun5) .


UPGRADING THE PROCESS CONTROL FILE (PCF)

The first thing that you should do is make a local copy of $PGSHOME/runtime/$BRAND/PCF.relB0 and edit this file to suit your individual needs.

NOTE: system administrators should make any necessary global changes to this file or a copy of this file and leave it in $PGSHOME/runtime/$BRAND so that all users can get a copy of the PCF for their personal use.

Do not attempt to use TK5.2.1 with a PCF that was being used with an older version of the Toolkit.

NOTE: for a list of major changes made to the PCF for TK5.2.1 see: Appendix A--Changes to the PCF.

When you have finished upgrading to the new PCF you should run this new PCF through the Toolkit PCF checking utility, pccheck.sh. This utility can be found in the Toolkit bin directory ($PGSHOME/bin/$BRAND). It should be run like this:

pccheck.sh -i PCF.relB0

Check the comments (in the PCF) of any entries that show up with errors and take appropriate action.

Tips On Updating Your PCF

  • Default directories

    If you have changed any of the default directories (indicated in each relevant section of the PCF with '!' character as the first character on the line), make sure you replace the entry(ies) in your new PCF, otherwise you will get the Toolkit defaults which may not even work for you.

  • Toolkit Defaults

    If you have changed the default values of any Toolkit runtime parameters (or added values where there weren't any), make sure you update your new PCF to reflect these changes.

    If you have changed the location of any files that came with the Toolkit (e.g. earthfigure.dat) to a non-standard location, make sure that you update your new PCF to reflect these changes.


  • AA data directory

    If you have installed the AA data on your system and you are using this data (you are using the PGS_AA_... tools), make sure you replace all occurrences of AA_DATA_INSTALL_DIR in your new PCF with the actual directory location of the AA data.

    NOTE: it is not necessary to re-install this data, there has been no change in this data since the last Toolkit delivery.


L0 FILE FORMAT CHANGE

The format of the EDOS PDS/EDS Construction Record has changed as has the naming convention for the physical files comprising a PDS/EDS. The PDS/EDS file naming convention now specifies that all files in the PDS/EDS will have the extention ".PDS" or ".EDS" (respectively). For example files that previously had the names:

P1690000AAAAAAAAAAAAAA96001010000000
P1690000AAAAAAAAAAAAAA96001010000001

now have the names:

P1690000AAAAAAAAAAAAAA96001010000000.PDS
P1690000AAAAAAAAAAAAAA96001010000001.PDS

Item 25-2 of the EDOS Construction Record contains the name of PDS or EDS file. Since the name has been increased by four characters the size of item 25-2 has been increased by four bytes. This change means that the Toolkit WILL NOT properly parse any EDOS data set with a Construction Record conforming to a format prior to that specified in the August 9, 1996 EDOS ICD (calls to the Toolkit function PGS_IO_L0_Open() will fail).

The Toolkit L0 file simulation utility, L0sim, has been updated to conform to the PDS/EDS definiton specified in the August 9, 1996 EDOS ICD.

The version of L0sim distributed with prior versions of the Toolkit DID NOT conform to the August 9, 1996 EDOS ICD. Any data sets generated with prior versions of L0sim should be reconstructed, they CANNOT BE READ with the IO L0 tools using TK5.2.1 (the actual culprit is the Construction Record, so technically speaking the data sets could be used if they are renamed according to the above mentioned naming convention and the Construction Record is regenerated or updated).


SPECIAL NOTES ON TIME FILES

If you are running simulations using future times you must make adjustments to your time files (utcpole.dat, leapsec.dat).

Using the files as delivered with TK5.2.1 the latest dates that can be successfully processed by tools that require these files are:

leapsec.dat: 1998-03-02
utcpole.dat: 1998-10-26 (updates already available)

NOTE: some tools require both files, therefore the limiting factor is likely to be leapsec.dat.

NOTE: the tool groups affected by these files are CBP, CSC, EPH, IO_L0, and TD. If you attempt to use these tools with times in future of the times supported by the time files, the tools will return an error.

Changing the time files

Given below are instructions on how you can change your new time files (i.e. those delivered with TK5.2.1) to allow for processing of times beyond those that are currently supported.

WARNING !

These changes are only to allow simulations to run without getting errors from the Toolkit time tools. Once you make these changes to the time file(s) your results may no longer be temporally accurate or scientifically valid.

Note: Any time file altered to support simulations using future times should not then be updated using the Toolkit time file update utilities (update_utcpole.sh and update_leapsec.sh).

    • Changing leapsec.dat

Do not change the leapsec.dat file that was delivered with the Toolkit. Make a local copy and alter that. Even if you would like to create a new file for a large group of people, make a copy somewhere that everyone can read it.

Edit your local copy and change the date of the first line in the header from:

Checked(unchanged): 1997-04-29T23:06:10Z using USNO ...

to:

Checked(unchanged): 2010-04-29T23:06:10Z using USNO ...

NOTE: The exact date is not significant, but it should be greater than any times for which you plan to do simulations.

Then replace the line in your PCF:

10301|leapsec.dat|~/database/common/TD||||1

with:

10301|leapsec.simulation|/usr/local/data||||1

(where, in this case, a copy of the file leapsec.dat was made and named leapsec.simulation, then edited--as above--and placed in the directory /usr/local/data)

    • Changing utcpole.dat

The Toolkit now contains a utility to alter the time span of the utcpole.dat utility. In the directory $PGSHOME/database/common/CSC is an executable C-shell script file called sim.csh. Executing this file will create a file in the same directory called utcpole.bogus (you may need write permission in the $PGSHOME/database/common/CSC directory).

This simple script adds three thousand days each entry in the original file (the script is a series of sed statements, and can be easily altered to produce a larger time shift). Using the script is the prefered method of changing this file (again, for simulation purposes ONLY!) since the file, although ASCII, is read as a binary file by the Toolkit and any spurious characters introduced into the file will cause the Toolkit to fail to parse it properly. To view a discussion on changing the file by hand, please follow this link.

After creating the simulation file, replace the line in your PCF:

10401|utcpole.dat|~/database/common/CSC||||1

with:

10401|utcpole.bogus|~/database/common/CSC||||1


APPENDIX A--MAJOR CHANGES TO THE PCF FOR TK5.2.1

  • Changed the logical ID for the udunits.dat file (used by the CUC units conversion tool PGS_CSC_Conv()) from 11001 to 10302 (11001 is outside the range of logical IDs reserved for Toolkit usage so this number was changed to avoid potential conflicts with user defined logical IDs).

  • All support files for the GCT and AA tools that were previously delivered in the Toolkit runtime directory have been moved to $PGSHOME/database/common/GCT and $PGSHOME/database/common/AA respectively. The entries for these files in the PCF have been updated accordingly.

    NOTE: the AA files in question here were the files previously delivered in $PGSHOME/runtime with the rest of the Toolkit, these are NOT the file in the larger set of AA data files which are available in a seperate tar file.

    NOTE: for the SCF the Toolkit will put links from the old locations of these files to the new locations (i.e. an old PCF type entry will work).
  • Updated the value of the toolkit version string (logical ID 10220), the value of this string should be: SCF B.0 TK5.2.1

    NOTE: it is STRONGLY recommended that a new PCF be constructed from the PCF delivered with TK5.2.1 in $PGSHOME/runtime/$BRAND. Old PCFs should NOT be edited for use with a new Toolkit version.
  • No labels