@
sign can be passed as
an argument to the task. Here are two examples:
The default output produced by getref, the summary output, contains one row for each type of reference file used by the instrument associated with the observation set root name. The summary output has four columns:
The information used to produce the summary output is retrieved from the DADS database. If the field in the DADS database is blank, it will be represented in the output by two consecutive quote marks. If the string "N/A" is found in the database in the OLDNAME field, it will be also be replaced by two quotes in the output.
The task also has two optional parameters, reffile
and text
. The
optional parameters are specified by giving their name followed by an
equals sign and the argument value. The parameter text
can also be
specified by its name followed by a plus or minus sign, since it is a
boolean parameter. The command lines
and
If the reffile
parameter is present on the command line, the task
will produce a detail report for the specified reference file instead
of the usual summary report. The detail report contains the
significant fields from the file and row level database tables
containing the reference file.
The text
parameter is a boolean parameter taking the values
yes
or no
. If the value of the parameter is yes
, the task will
produce a plain ascii table as output. If the value is no
, the
task will produce an html table as output. The default value of
text
is yes
, so if the parameter is not present on the command
line, the output will be an ascii table. The parameter text
is
primarily useful for running the task from the cgi interface and its
only real use when running the task from the command line is helping
to debug the program when called through the cgi interface.
@
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.
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 five 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 retrieves one
observation set name at a time from the function read_root
and
performs a query with that observation set name. It determines the
instrument from the observation set name by calling
get_icode_obs
. It then gets the database field and table names
from constant arrays stored in global.h
. Getref_all
calls
bind_qryvars
to allocated memory for the fields to be retrieved
and binds them to the query. Then getref_all
calls build_qry
to
fill in a query skeleton with the names of the fields to be retrieved
and the tables to retrieve them from. It then executes the query and
retrieves the results. If the field contains a filename and the output
is html, the filename is wrapped in an anchor by the function
mkanchor
. The fields returned from query are written to the output
table, the bound variables are freed, and getref_all
loops to get
the name of the next observation set.
The read_root
function read a single observation name from either
a file or a comma separated list of observation set names. Before
calling read_root
the calling function calls start_root
. If
the first character of the string passed to start_root
is an at
sign (@
), the function assumes the string contains a file name,
opens the file and saves a pointer to the file in the
structure. Otherwise, a character pointer to the string is saved in
the structure. Read_root
either reads from the file or reads from
the string, advancing the character pointer. The string read is stored
in a static string, whose address is returned to the calling
function. When the end of file or end of string is reached,
read_root
returns a NULL pointer to signal this condition.
The function bind_qryvars
takes an array of character strings as
input. The last string must be a zero length string to mark the end of
the array. The strings are the names of fields in some database
table. The function allocates memory to hold the query result and
binds the memory to the field name.
The function build_qry
takes a query template as an argument and
uses the remaining arguments to fill in slots in the template. Slots
in the template are marked by the caret (^
) character. The
template can contain repeating groups, delimited by left and right
braces. If a caret appears within a set of braces, the text within
the braces is repeated for however many strings there are in the array
and the caret is replaced with each element in the array. The template
also may contain optional text, delimited by square brackets, which is
copied to the query for each repetition except the first. Optional
text is usually used for delimiters (such as commas) between the
repeating text. The function is implemented as a loop which reads each
character in the format containing a switch statement which acts on
special characters in the format. The varargs macros are used to
access function arguments used to replace the carets. When repeating
text is encountered, the state of the function is pushed on a stack
and when the end of the repeating text is reached, the function checks
to see if more elements remain in the array, and if so, the state of
the function is restored to what it was at the start of the repeating
text. If a blank is encountered, the function checks to see if the
internal buffer it is filling is full and if so, it sends the buffer to
the database library.
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 qry_obsmode
calls get_icode_ref
to determine the
instrument from the reference file name. It then calls build_qry
to send a query to the cdbs database to retrieve the names of the
observation mode fields from table cdbs_mode
. When the fields are
retrieved, the function searches for the names of the corresponding
observation mode fields in the dads database by doing a linear search
of the global arrays cdbsmode
and dadsmode
in
global.h
. The array elements are copied to the output arrays and
the arrays are terminated with a zero length string.
The function qry_hasroot
calls get_icode_ref
to determine the
instrument from the reference file name. It then binds the query
output fields, which are retrieved from arrays in global.h
, by
calling bind_qryvars
. The query is constructed by calling
build_qry
and the results are retrieved and stored in a loadfile
table. If the output type is html, the value of the comparison file
name is converted to an anchor by calling mkanchor
. Functions
qry_noroot
and qry_nomode
have the structure as
qry_hasroot
. Only the details of the query are changed.
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 as
well as the corresponding names of the header keyword fields. 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