The task is run by typing the name of the task followed by a list of
observation set root names to retrieve the reference files for. A list
of observation set names can also be placed in a file, one per line,
and the name of the list file preceded by an @ sign can be passed as
an argument to the task. Here are two examples:
The default output produced by getref, the summary output, contains recommended values for the calibration reference files, calibration switches, and other important keywords whose values have changed. The summary output has seven columns:
The information used to produce the summary output is retrieved from the DADS database. Values with embedded blanks are quoted and zero length strings are represented by consecutive quote marks in the output.
The task also has four optional parameters, reffile, text,
retry, and fits. The optional parameters are specified by
giving their name followed by an equals sign and the argument
value. The boolean parameters (text, retry, and fits) can
also be specified by its name followed by a plus or minus sign. The
command lines
and
@ containing observation set rootnames.
yes (the default for command line mode), the task will
return its results as text file. If set to no (the default for cgi
script mode), the task will return its output as an html file.
yes, the task sleeps if it finds the database row it is
querying is locked and tries the query again until the row is
unlocked.(Up to 8 times.) If set to no, the task takes an error
exit if a database row is locked. This switch is chiefly intended for
non-interactive use of getref, where taking an error exit because the
database is locked is inadvisable. The default value of this parameter
is no.
yes, reference file names in the getref output file will
all be fits files. If set to no, reference file names will be geis
file names for the old instruments and fits file names for the new
instruments. This parameter is intended for use of getref in the otfc
pipeline, where the files to be modified are all fits files. The
default value of this parameter is no.
getref_no.html, getref_all.html, and getref_one.html.
These files contain the html code that produces the search page,
summary results page, and detail results page respectively. These
three files are located in the cdbs data directory, so they can only
be modified by the program's maintainer. The reason that the html
template files were created is so the the program's maintainer can
change the appearance and text of the html pages getref produces
without modifying the pages themselves.
The text in the html templates is copied into getref's output except
where variables appear in the template. These variables are replaced
by text generated by getref. Variables in the template file start with
the character string <!-- $ and end with the character string
-->. In between the starting and ending string is the variable
name. The variable thus looks like an html comment to an html browser,
so the template can be checked for style and content without running
getref.
This task supports six variables. Variable names are case sensitive. The variables are:
</a>.
toplink, the template
must supply the text displayed in the anchor and the trailing </a>.
task. It reads any arguments on
the command line and then calls form_input to read and parse any
input that may come from a cgi form. It calls which_qry to
determine which type of query the user may wish to perform. It selects
the name of an html template file and calls the appropriate function
(getref_all or getref_one) depending on the type of query. The
query results are returned as a loadfile table. If the value of the
input variable text is no, the table and template are passed
as arguments to output_html, If the value of text is yes,
the table is passed to output_asc. The the table is freed and the
task exits.
The function form_input can read cgi input sent by either the GET
or POST method. It reads the environment variable REQUEST_METHOD
to determine the input method. If the variable is not found or any
value other than GET or POST, the function does not try to read cgi
input. If the value is GET or POST, it reads the input in the
appropriate manner and calls parse_cgi to decode the
input. Parse_cgi divides the input into individual parameters at
ampersands, decodes the individual parameters by translating escape
sequences, and stores the translated parameters by calling
put_option. Put_option is a function which stores name-value
pairs in a global associative array. This array can be later accessed
by calling get_option. After the cgi input is parsed and stored,
form_input calls def_option to set default values for any
options that may not have been present in the input.
The function getref_all performs the summary query, which returns
the best reference files for a specified observation. It takes the
list of rootnames and calls expand_assoc to expamd any names that
may be associations into the files contained in that association. Then
it calls check_lock to see if the observation set record in the
database it is going to access is locked for update. If it is locked,
it either takes an error exit or waits until the record is unlocked,
depending on the value of retry. Then getref_all calls
set_calibrate to see if the observation set is in the dataset
exceptions table. If it is, it adds the CALIBRAT keyword to the
loadfile table with a value of NO to indicate the observation set
should not be recalibrated. Then getref_all calls best_files
to get the names of the recommended calibration reference files and
best_switches to get the names of the recommended calibration
switches. Finally, it calls key_changes to get other keywords that
should be updated in the image header.
The function best_files calls which_files to determine the
name of the image containing the reference file switches. This is done
by querying a database table in DADS which contains a list of file
name extensions for each instrument and building the name from the
rootname and extension. Then best_files calls file_keywords
to get a list of the header keywords containing reference file names
from the DADS database, along with the names of the fields in the DADS
database containing the recommended and original reference file
names. After collecting this information, then best_files querties
the database for the recommended and original reference file names,
and uses this information to add rows to the loadfile table.
The function best_switches works similarly to best_files,
except that it calls switch_keywords to retrieve the keyword names
and database filed names of the recommended and original calibration
switches. Since both best_files and best_switches pull their
information from the DADS database, the output of getref can be
modified by changing the database and without recompiling the program.
The function getref_one performs the detail query. There are two
sql queries performed. The first query is performed by qry_obsmode
and retrieves the names of the observation mode fields in the cdbs and
dads databases. The second sql query is performed by one of three
functions. Qry_hasroot is called if the reference file has
observation mode fields and the observation set name is
known. Qry_noroot is called if the observation set name is not
known. And qry_nomode is called if the reference file has no
observation mode fields. All three functions are similar, differing
only in the form of the query sent to the database.
The function output_asc produces text output from the loadfile
table created by the query. It first determines the column widths by
finding the maximum length of the column name and any of the values in
the column. It then prints a title line preceded by a comment
character containing the table column names and then prints the
contents of each row in the table using the calculated column widths.
The function output_html produces html output from the loadfile
table. It has two inputs: the name of the template file and the
loadfile table descriptor. It calls in a while loop function
html_template which prints the contents of the template until it
finds a variable name embedded in the template. Html_template then
returns the name of the embedded variable. Output_html takes the
name of the variable and matches it against a list of valid variable
names and executes code in a switch statement which replaces the
variable in the output. If the variable is output, the contents of
the loadfile table is formatted as an html table and printed. For the
other variables, mkanchor is called to produce an anchor from
arguments the task was called with.
The file global.h contains the global variables that control much
of the operation of getref. These variables They describe the
significant names of the database tables and fields used by getref. If
new instruments or reference files are added to the calibration
pipeline, this file must be updated to track the changes. The
variables in this file are structured as arrays of pointers to
character strings. The dimensions of the arrays are defined by macros
in getref.h. Each array must be terminated by a zero length string
so that the function using the array knows where it ends.
datafile.h. The filenames use the DATAFILE macro, defined in
system.h to specify the directory name containing the template
files. The url used to invoke the search screen is defined by the
GETREFURL macro defined in datafile.h. The getref.cgi shell
script in the util directory, used to run getref from a cgi
script script, contains system dependent environment variables and
must be edited and copied to the cgi-bin directory on the system.
This task uses four environment variables to control its access to the
database. CDBS_SERVER sets the database server the task
accesses. CDBS_DB sets the name of the cdbs database that is used
by the task. DADS_DB sets the name of the dads database that is
used by the task. And CDBS_USER sets the user name used to access
the database. If these environment variables are not set, they default
to ZEPPO, cdbs_ops, dads_ops, and a public cdbs account.
In addition to these environment variables that control cdbs access,
the stdb library that this task is linked with requires the two
environment variables SYBASE and ACAREA be set. These
variables define the location of the Sybase and stdb executables and
libraries.
u20l0u01t, enter the command:
To retrieve detail information for a specific reference file for the
hrs observation set z0ek0i01t, enter the command