Wildcard patterns can be used to expand the list of filenames, but care should be taken that the pattern expands to the image header file name and not the data file name. If a file being renamed contains the name of another reference file and that file is not already in the list, its name will be added to the list.
The task changes the filename root to a unique name based on one of
three naming conventions. The instrument, as read from the cdbs
catalog, determines the naming convention. Reference files whose
instrument is synphot add a counted suffix to a fixed root. For
example, if the file hst_ota_004.tab exists, the next file of that
type renamed will be named hst_ota_005.tab. Only the synphot
throughput tables and some of the non-opus reference files are in the
synphot instrument class and use this naming convention. Reference
files for the new instruments (stis and nicmos) create a unique name
from the current time, plus a suffix indicating the reference file
type. For example, a Nicmos background file may be renamed to
gae11178n_bac.fits. Reference files for the other instruments
create a unique name from the time without any suffix. For example, an
fos table might be renamed to gae1119oy.cy2.
The algorithm for creating a new filename from the time creates a
new filename root with the format YMDHHMMSSI where
- Y denotes the year (where 1981 = 1)
- M denotes the month of the year (where January = 1)
- D denotes the day
- HH denotes the hour (00 - 23)
- MM denotes the minutes
- S denotes the seconds divided by 2
- I denotes the instrument code
The algorithm used to generate the name has a time granularity of two seconds. If asked to rename two separate files, the task will wait until two seconds have elapsed to rename the second, to prevent name clashes. Files which originally have the same root name receive the same new name when renamed.
Reference files that contain their own names or the names of other reference files inside the file have those names changed within the file. The files mentioned in the reference file must be accessible to the program or the reference file will not be renamed.
The task checks the online cdbs directory that the file will eventually be stored in to make sure that it does not duplicate an existing reference file name. Hence the task must be run on a machine from which the cdbs directories are accessible.
Uniqname also uses the file directory.dat to translate between
STSDAS logical names and the host operating system names. All
directories are relative to the top level directory, defined by the
macro CDBSDIR in system.h. This allows the directories to be placed
under a different root on each system without changing this file.
task, loops over the files in the
argument list, calling uniqname, to rename each file. It also sets up
three data structures: a lookup table containing the information from the
CDBS catalog file, a list of files to process, and an associative
array that lists the old and new root file names. The lookup table is
used to identify the reference file type of each file processed. The
list of files is created so that new files can be added to the files
passed on the command line if any of the renamed files contains the
name of another file. The associative array is created so that the
task can make sure that two files with the same root receive the same
new file name.
The uniqname function checks to see if the file can be renamed,
generates the new file name, changes keywords in the file to agree
with the new name, and then renames the file. The checking is done by
function renamable. It looks to see if all files mentioned in the file
to be renamed are present on the system and can be written to. If not,
the function prints a warning message. The function does this checking
so that the task does not leave files in a half changed state, with
some files renamed and others not. The name generation is done by
function getuniqname. It determines which renaming convention to
use from the instrument name and either calls thruname,
oldinstname, or newinstname to rename them. Thruname calls
getsynroot to generate the new synphot root name, while the other
two functions call makeid to create the root name from the time.
Makeid generates the file name from the current time according to
the pattern explained previously. Getsynroot looks in the header
of the table to be renamed for the keyword used to generate the new
name. The keyword use depends on the reference file type. Setnames
changes the keyword within the file containing the file name to the
new name. If the file contains a mention of another file, this mention
is also renamed and the file is added to the list of files to be
renamed.
DEPENDENCIES)
This task uses the macro DATADIR in system.h to define the
directory containg the catalog and directory files. It also uses the
macro CDBSDIR in the same include file to define the top level
directory of the CDBS reference files.