Update_SPICE
Updates the SPICE database table with a kernel file.
The first eight characters of the kernel file are examined to identify the type of SPICE kernel data it contains. The kernel identifier is the characters following the slash ('/') delimiter with any trailing space characters removed. If an expected kernel type is specified then the identifier from the file must match the specified identifier or the file will be rejected. If the file does not contain a kernel identifier then a kernel type must be specified or the file can not be used.
In addition, "CK" and "SPK" kernel types are associated with a command that is used to obtain the kernel time range coverage. These values are used to set the COVERAGE_RANGE_START_TIME_XXX and COVERAGE_RANGE_END_TIME_XXX field values in the SPICE table record. If no command has been associated with the kernel identifier, whether obtained from the file or specified on the command line, then the file can not be used.
The "SCLK" and "LSK" kernel types are recognized as not containing time range coverages. The COVERAGE_RANGE_START_TIME_XXX and COVERAGE_RANGE_END_TIME_XXX fields for these records in the SPICE table will be empty.
The kernel type identifier is set as the value of the KERNEL_TYPE field of the SPICE table record.
Set the status of the SPICE table record to indicate whether the kernel file contains Predicted, Reconstructed or Smithed data; only these <status> values are recognized. If the kernel status is not specified an attempt will be made to determine the status of the kernel file from its filename. If this does not produce a status the KERNEL_STATUS field of the SPICE table record will not be set.
The configuration file contains the database access information. The configuration file must provide the necessary information needed to identify and connect with the database server where the SPICE table will be found. If the pathname is a simple filename and it is not found in the current working directory it will be looked for in the user's home directory. Default: HiSPICE.conf.
The configuration file may contain connection information for more than one database. The information for each database is organized by Server name. A Server name corresponds to a parameter group in the configuration file, with the same name, that contains access information for a database server. Default: The first name in the Server list specified in the configuration.
The database catalog on the server contains that contains the SPICE table to be updated. Default: HiRISE.
Normally when the SPICE table is found to contain a record for the same type of kernel being updated and with a matching coverage range, or filename, the update is not done. When -replace is specified the record with matching coverage will be replaced with a record containing the information for the kernel file. Also, if the new kernel file has the same name as an existing file in the destination directory, and the files have different contents, the -replace option will cause the existing file to be removed and all database records with the same pathname (in the destination directory) to be deleted before the new file is moved into the destination directory and the SPICE table is updated. If the -replace option is not specified an existing file in the destination directory with the same name as the new file, but different contents, will need to be moved (or removed) - and a message to this effect will be reported - to allow the new file to be moved into the destination directory. By default replace mode is not enabled.
The kernel file will be moved to the subdirectory named for the kernel type in the destination directory. However, this is only done if the kernel file qualifies for a SPICE table update. The default destination directory is $HiRISE_ROOT/Data/NAIF, where $HiRISE_ROOT is the value of the "HiRISE_ROOT" environment variable or "/HiRISE" if the environment variable is not present, unless the configuration file contains a SPICE/Destination parameter.
If the kernel file is not moved to the destination directory, and is not located in the destination directory, remove it. Note that a single file may appear to be located at differenct pathnames. And though filesystem absolute (fully qualified) pathnames are used to help avoid incorrectly indentifying
By default a kernel file that does not result in a SPICE table update is left in place. If -no_op is specified -remove is ignored.
To report the time range coverage of a kernel file a leap seconds kernel (LSK) file and a spacecraft clock kernel (SCLK) file are required. The default LSK kernel file is named LSK.kernel in the destination directory unless the configuration file contains a SPICE/LSK_Kernel parameter.
To report the time range coverage of a kernel file a leap seconds kernel (LSK) file and a spacecraft clock kernel (SCLK) file are required. The default SCLK kernel file is named SCLK.kernel in the destination directory unless the configuration file contains a SPICE/SCLK_Kernel parameter.
Suppress the creation or update of a symbolic link for LSK and SCLK kernel file types when either of these types of kernel files are updated.
The link names are LSK.kernel and SCLK.kernel, respectively and the links are placed in the destination directory. Since the LSK and SCLK kernels are required for various operations on kernel files, using the links to these kernel files ensures that the most recently updated files will be referenced.
N.B.: If -no_op is specified -no_link is implicit.
Suppress the creation of the ISIS kernel database file.
After the SPICE table has been updated and the kernel file has been moved to its kernel type subdirectory of the destination directory an ISIS kernel database file is created in the directory. This file lists all kernel files in the directory that match a specific pattern. The file is named kernel.nnnn.list, where nnnn is a zero-padded number that is incremented for each new database file created in the directory. By default the ISIS kernel database file is created whenever the SPICE table is updated.
N.B.: If -no_op is specified -No_ISIS_kernel_database is implicit.
The Predicted, Reconstructed or Smithed status of a CK or SPK kernel file is determined by matching its filename against one or more patterns, unless the kernel status is specified on the command line. Smithed patterns are applied first, then Reconstructed patterns and finally Predict patterns; the first one that matches determines the kernel status. When multiple selection patterns are provided they are applied in the order specified. An empty pattern matches no files.
In addition, the ISIS kernel database file uses the same file selection pattern to determine the status of a file in the kernel directory.
The <selection_pattern(s)> use shell filename globbing meta-characters:
Multiple patterns are separated by a semi-colon (';') delimiter character. An empty pattern ("") suppresses the automatic detection of the corresponding kernel type status.
The configuration parameter names and default values are:
When not specified on the command line, the default values will be used if the corresponding configuration parameter is not found.
Do not apply any update operations, just list what would be done. By default this mode is not enabled.
Verbose operation reports procedure details. The -very_verbose option adds listings of the kernel report utilities programs that are used. The -very_very_verbose option adds listings of the time conversion utilities that are used. By default a brief summary reporting (verbose) will be listed. Quiet operation minimizes messages.
Print this manual page.
The contents of a SPICE kernel file are used to update the SPICE database table. The PATHNAME field of the table record will contain the fully qualified (but without link file aliasing removed) pathname to the kernel file specified. The ACQUISITION_TIME field of the table will contain the date and time of the timestamp for the file associated with the record, which may be when the kernel file was downloaded from the JPL NAIF distribution site to the local filesystem or the timestamp of the file from the distribution site that was applied to the file after being download to the local filesystem.
The SPICE table is checked for PATHNAME field entries that contain the same filename - the final segment of the complete pathname - as the specified kernel file. The presence of matching filenames is reported. Each pathname with a matching filename is then compared - using canonical pathnames that eliminate link aliasing - with the destination pathname. If a pathname equivalence is found the record with the redundant PATHNAME will be deleted from the table. However, if the pathname exists and the contents of the file are identical to the new kernel file, the record is not deleted and no table update is done. If more than one table record PATHNAME refers to an existing file that has identical contents to the new kernel file, then only the last such record will be retained.
The kernel file is expected to contain an identification sequence in its first eight characters - following a '/' delimiter and excluding any trailing space characters - that specifies the type of kernel data it contains. The KERNEL_TYPE field of the table record will contain the kernel type identification. If the kernel type identification can not be obtained from the kernel file it must be specified on the command line. An identification specified on the command line will override any identification found in the kernel file.
For kernel types "CK" and "SPK" a SPICE Toolkit utility program will be used to obtain the time range coverage of the data in the kernel file. If no time range coverage can be determined no update will be done. If the file contains multiple time range segments the coverage of the file will be from the minimum segment start time to the maximum segment end time. The time range coverage values will be used to set the COVERAGE_RANGE_START_TIME_XXX and COVERAGE_RANGE_END_TIME_XXX fields of the table record, where XXX is:
Coordinated Universal Time (UTC) is represented as a familiar calendar time in "YYYY-MMM-DD HH:MM:SS" format. The database entry is only accurate to one second.
Ephemeris Time is the time in seconds since the J2000 epoch - 2000-JAN-01 12:00:00 - in the TDB (Barycentric Dynamical Time (TDB) reference system (see the NAIF "Time Routines in CSPICE" document; http://naif.jpl.nasa.gov/pub/naif/toolkit_docs/C/req/time.html). This value is accurate to .00001 second.
Spacecraft clock time is measured in seconds and fractional second clock ticks since the spacecraft epoch - 1980-JAN-01 00:00:00 - in "SSSSSSSSSS:FFFFF" format where SSSSSSSSSS is the seconds count and FFFFF is the fractional second clock ticks with each tick being 1/65536 of a second.
The chronos NAIF SPICE Toolkit software utility is used to accurately convert between these different time representations.
The presence of SPICE table records for the same kernel type as the new kernel file that also have a time range coverage that overlaps the kernel file time range will be reported. If such a record has the same coverage as the new kernel file the table update is not done unless the -replace option is specified. If more than one record has the same coverage, and the -replace option is sepcified, only the last record will be replaced with all other redundant records being deleted.
The CK and SPK kernel types are also expected to have a status used to set the KERNEL_STATUS field of the SPICE table record. The status of a kernel may be either predicted, reconstructed or smithed. A predicted kernel contains data that is extrapolated from measured values; a reconstructed kernel replaces the extrapolated values with possibly different measured values. A smithed kernel contains data in which the measured values may have been adjusted to account for measurement inaccuracies (such as spacecraft jitter during a periodically sampled measurement). Thus each status provides increasingly accurate data, respectively.
The kernel types "LSK" and "SCLK" do not have time range coverages nor status; the SPICE table records for these kernel types will have NULL COVERAGE_XXX and KERNEL_STATUS fields. If a table record for the same kernel type has a PATHNAME identical with the kernel file pathname, or the PATHNAME has the same filename as the kernel filename and both files have the same data content (as determined by an MD5 digest) the table update is not done unless the -replace argument is specified.
When the kernel file is found to be an acceptable new entry for the SPICE database table it is moved from its current location to the appropriate destination kernel type subdirectory (unless it is already in the destination directory). However, special conditions apply when a file with the same name exists in the destination directory: A kernel file that has identical contents to the existing file never replaces the existing file and no update is done; otherwise the name conflict is reported and the update is not done unless the -replace option has been specified.
Note that a kernel file with identical contents to an existing file of the same name in the destination directory may be found to have different coverage from that recorded in the database table for the existing file. This can result from changes to files - the SCLK and/or LSK kernels - that are used to calculate the coverage of a kernel file. In this case the kernel file is redundant and no update is done. In the same way a kernel file with no matching coverage in the database and no existing file in the destination directory with the same name may actually be identical to an existing file with a different name, but since this is not known a record will be entered into the database for a redundant file (while this is probably not harmful, careful file naming discipline should be observed to avoid this case).
Soft links are maintained in the destination directory to an LSK or SCLK kernel file that is updated. The name of the LSK kernel file link is LSK.kernel; the name of the SCLK kernel file link is SCLK.kernel. These types of kernels are required for time conversion operations and are referenced in the ISIS database file in the directories containing CK and SPK kernel files. So using the link pathnames ensures that the most current kernel files will be referenced.
The COMMENT field of the SPICE table record is filled with the name, software revision and date of this procedure.
The SPICE table is updated after the kernel file is moved to the destination directory and the kernel file link is set or the ISIS database file is generated. N.B.: The table update is allowed to proceed if the link or ISIS database file could not be created, but not if the kernel file could not be moved to the destination directory. If the SPICE table is not updated because an equivalent record already exists the kernel file will be removed (deleted) if the -remove option is specified. However, if the kernel file pathname is the same as the pathname to where the kernel file would be moved to under the destination directory it will never be removed.
The creation of the link or ISIS database file can be suppressed by using the -no_link or -no_ISIS_kernel_database options. The -no_op option will suppress the creation of the link or ISIS database file as well as the update of the SPICE table, but the kernel file characterization and SPICE table checks will still be done; this is a good way to check a kernel file before committing it for update use.
Other than the kernel file to be processed, all command line arguments have default values. However, configuration parameter values may be used instead of the default values. All configuration parameters used by this procedure - except the database access parameters which are in the -Server group - are sought in the SPICE group. The options descriptions provide the name of the parameter for the particular option.
Note: Configuration parameters may be queried by various utilities. Any utility may used as long as a listing of selected parameters can be obtained with a command line that uses the following syntax:
$Config_Query $parameter_pathname $config_source
where $config_source is the source of the configuration file, $parameter_pathname is the parameter pathname (relative or absolute) that names the parameter of interest, and $Config_Query is the fixed portion of the command line. If a "Config_Query" environment variable is present its value will be used for the fixed portion of the command line. By default the $Config_Query is "Configuration -query". The Configuration utility will accept both file pathnames and URLs for the $config_source and has the advantage of supporting @Include parameters when the source is a locally accessible file, but as a Java application it runs slower than PPVL_report. The PPVL_report utility is an appropriate alternative that is a fast compiled binary application but it will only accept file pathnames for the $config_source and does not support @Include parameters.
All selected files were fetched.
A command line syntax usage message will be provided.
A required configuration parameter could not be found or a parameter value is invalid.
A system operation - such as running a helper utility or creating a directory - failed.
There is a problem with the kernel file or its destination directory.
A database query failed.
A conversion of a time value from one representation to another failed.
The update of the SPICE table failed.
The update was not done because an equivalent SPICE table record was found for the kernel file.
The link in the destination directory to an LSK or SCLK kernel file in its subdirectory could not be created. The SPICE table update was successful.
The ISIS database file for the kernel file subdirectory of the destination directory could not be created. The SPICE table update was successful.
Bradford Castalia, UA/HiROC
Copyright (C) 2009-2020 Arizona Board of Regents on behalf of the Lunar and Planetary Laboratory at the University of Arizona.
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
1.32
Hey! The above document had some coding errors, which are explained below:
Expected text after =item, not a bullet