getref

NAME

getref -- Get best reference files to use with an observation

USAGE

getref rootname [rootname ..]

DESCRIPTION

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:

getref u20l0u01t z0ek0i01t getref @rootname.lis

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

getref u20l0u01t reffile=f8213081u.r0h text=yes

and

getref u20l0u01t reffile=f8213081u.r0h text+ are equivalent. The optional parameters can occur anywhere on the command line relative to the list of root names.

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.

PARAMETERS

DATA FILES

Getref uses three html template files to produce its html output. These files are not used when getref produces ascii output. The names of these three template files are hardwired into the task: 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:

ALGORITHM

The main function in getref is 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

INSTALLATION DEPENDENCIES

The names of the three html template files are defined in 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.

EXAMPLES

To retrieve all the reference files for the observation set u20l0u01t, enter the command:

getref u20l0u01t

To retrieve detail information for a specific reference file for the hrs observation set z0ek0i01t, enter the command

getref z0ek0i01t reffile=c7u0854mz.r5h


Back to index of cdbs tasks.