diff options
Diffstat (limited to 'funtools/doc/view.html')
| -rw-r--r-- | funtools/doc/view.html | 376 |
1 files changed, 376 insertions, 0 deletions
diff --git a/funtools/doc/view.html b/funtools/doc/view.html new file mode 100644 index 0000000..6f1faa8 --- /dev/null +++ b/funtools/doc/view.html @@ -0,0 +1,376 @@ +<!-- =defdoc funview funview n --> +<HTML> +<HEAD> +<TITLE>Database View Support for Tables</TITLE> +</HEAD> +<BODY> + +<!-- =section funview NAME --> +<H2><A NAME="funview">Funview: Database View Support for Tables</A></H2> + +<!-- =section funview SYNOPSIS --> +<H2>Summary</H2> +<P> +This document contains a summary of the options for utilizing +database-inspired Views of tables. + +<!-- =section funview DESCRIPTION --> +<H2>Description</H2> + +<H2>Database Views</H2> +<P> +In database parlance, a <B>View</B> defines a "virtual table", i.e., +a description of row and/or column selection filters (but with no +permanent storage space allocated). When used in place of a table, a +View selects the specified rows and/or columns from one or more real +tables. Views enable you to see complicated data tables in a more +convenient format. They also can be used as a security mechanism, by +restricting user access to specific columns and/or rows. [See: +<pre> +http://www.cs.unibo.it/~ciaccia/COURSES/RESOURCES/SQLTutorial/sqlch5.htm +</pre> +for a good discussion of SQL Views.] + +<P> +Funtools supports an expanded notion of Views for all tabular data +(FITS tables, raw binary tables, and ASCII column files). Funtools +Views allow you to pre-set values for the filter specification, the +columns to activate, and display format (though the latter is for +fundisp only). Setting the filter and column activation values +provides functionality equivalent to that of a classical database +View, while the ability to set the format is similar to classical +report writing capabilities. + +<H2>Funtools View Attributes</H2> +<P> +A Funtools View is a text file containing one or more of the following +columns: +<PRE> + column description + ------ ----------------------------- + view name of view + file data file name or template + filter filter specification + columns columns to activate + format fundisp format specification +</PRE> +All of the attribute columns are optional, including +the <B>view</B> name itself. This means that a View can be named or +unnamed. Unnamed Views can refer to a specific file or a template of +files (obviously if neither the view or the file column is specified, +the input View specification will never be used). You can specify any +combination of filter, column, and format parameters. (It also is +possible to apply file-specific View to other files; see the discussion +on <B>View Lists</B> below). Each column has a size limit of 1024 characters. + +<P> +For example, consider the following View file: +<PRE> + view file format columns filter + ---- ---------------------- ------ ------------ ------- + x3 ${HOME}/data/snr.ev I=%4d x y pi pha cir 512 512 .1 + x2 ${HOME}/data/snr.ev x y pi pha cir 512 512 .1 + x1 ${HOME}/data/snr.ev cir 512 512 .1 + x1a ${HOME}/data/snr.ev x y pi pha + x0 ${HOME}/data/snr.ev + xf I=%4d + xc x y pi pha + xr cir 512 512 .1 + *.ev x y pi pha + *.fit x y dx dy cir 400 400 3 + *.fits I=%3d x y dx dy cir 400 400 3 +</PRE> +This database example is in rdb format, i.e. using tab delimiters and +permitting null values. Any valid ASCII table format is acceptable, +but if you use a format that does not permit null values, it will be +necessary to quote the null strings. + +<P> +The first five entries (x3, x2, x1, x1a, x0) are named entries defining +default values specifically for the snr.ev data file. Typically, you +would use these Views by specifying View name, and the corresponding +file, filter, column, and format values would be used. Note that the x0 +View is essentially an alias for the pathname of this file. + +<P> +The next three entries define defaults that can be applied to any +file. You typically would use these View names in conjunction with +a specific file name (see <B>View Lists</B> below) so that the associated +parameter(s) were applied to that file. + +<P> +The last three entry in the database define unnamed Views that +pertains to all files ending with the specified templates. In these +cases, any View that specifies a file name matching the file template +would be processed with the associated parameter attributes. + +<H2>Invoking a Funtools View (in Place of an Input File)</H2> +<P> +To use a Funtools View, you simply pre-pend the "v:" prefix to a View name or +a file name where an input file name usually is specified. For example: +<PRE> + fundisp v:x3 +</PRE> +specifies that the View named x3 (with its file name and associated +parameters) is processed as the input file to fundisp. Using the +example database, above, this is equivalent to: +<PRE> + fundisp -f "I=%4d" ${HOME}/data/snr.ev'[cir 512 512 .1]' "x y pi pha" +</PRE> +That is, the format is used with fundisp's -f (format) switch, while the +filename and extension are composed of the x3 View's filename and +region filter. + +<P> +Similarly, executing a command such as: +<PRE> + fundisp v:foo.fit +</PRE> +will match the unnamed View associated with the template "*.fit". +This is equivalent to executing: +<PRE> + fundisp foo.fit'[cir 400 400 3]' "x y dx dy" +</PRE> +Of course, if you omit the "v:" prefix, then no View processing takes place: +<PRE> + fundisp foo.fit # process foo.fit without any View parameters + fundisp x3 # error (assuming there is no file named x3) +</PRE> + +<H2>Basic View Matching Rules</H2> + +<P> +When a "v:" prefix is recognized, Funtools searches for a View database +file in the following order: +<PRE> + location description + ------------ ------------------------------------ + FUN_VIEWFILE environment variable (any file name) + ./.funtools.vu hidden file, default name + $HOME/.funtools.vu hidden file, default name +</PRE> +The first View database file located is used to construct a new +filename, as well as an activation column specification and a format +specification. The following rules are used: + +<P> +1. An attempt is made to match the input name (i.e., the part of the +input View after the "v:" prefix) against the <B>view</B> column value +(if present) of each row in the database. If a match is found, the +values of all non-blank columns are saved for later use. Also note +that the first match terminates the search: i.e., <B>the order of the +database rows matters</B>. + +<P> +2. If no <B>view</B> match is made, an attempt is made to match the input +name against the <B>file</B> column value (if present). Matching is +performed on the full pathname of both the input name and the +database file name, and on the non-directory (root) part of these +files. This means that the root specification: +<PRE> + fundisp v:snr.ev +</PRE> +will match a row in the database that has a full pathname in the file, +allowing you to use a <B>file</B>-matched View without having to +specify the full pathname. In this example, the "v:snr.ev" View +specification will match the first row (v:x3) in the database: +<PRE> + x3 ${HOME}/data/snr.ev I=%4d x y pi pha cir 512 512 .1 +</PRE> +even though the row contains a fully qualified pathname as the file +value. Once again, values of all non-blank columns are saved, and the +first match terminates the search. + +<P> +3. If neither a <B>view</B> or a <B>view</B> match has been found, +then a simple template match is attempted against the <B>view</B> +values. Template matching supports a simplified version of file +globbing (not a regular expression), with support for a single "*" +(all characters), "?" (single character), or "[...]" (range) specification. + +<P> +4. If no template match was found on the <B>view</B> column, then a +simple template match is attempted against the <B>file</B> columns. + +<P> +5. If no match is found, then the filename (minus the "v:" prefix) is +returned. + +<H2>More on View Matching Rules: Single vs. Multiple Matches </H2> + +The matching rules described above stop after the first match, +regardless of whether that match provides values for all three +parameters (filter, columns, and format). In cases where a <B>view</B> +or <B>file</B> match does not provide all three values, it is possible +that a template match might do so. With regard to the example View +database above, the x1 View provides only a filter, while omitting +both the format and columns values. But note that the final rows in +the database could provide the values via a template match on the +filename. This sort of multiple matching is especially valuable in +order to provide "global" values to several Views. + +<P> +Obviously, multiple matching might not be wanted in every +case. Therefore, we support both multiple matching and single matching +according to the value of the FUN_VIEWMATCH environment variable. If +the FUN_VIEWMATCH environment variable exists and if its value begins +with "s", then a single match is used and missing parameters are not +filled in with subsequent template matches on the file name. That is, +matching rules above are followed exactly as explained above. If the +value of this environment variable begins with "m" (or does not exist), +then multiple matches are used to try to fill in missing parameters. +In this case, template matching always takes place and missing values are +taken from these template matches. + +<P> +Thus, in the example above, the View specification: +<PRE> + fundisp v:x1 +</PRE> +will take the file name and filter value from the x1 View: +<PRE> + x1 ${HOME}/data/snr.ev cir 512 512 .1 +</PRE> +The column value then will be taken from the "*.ev" file template match +against the x1 file name: +<PRE> + *.ev x y pi pha +</PRE> +Note once again that order is important: missing values are taken in the +order in which the template matches are processed. + +<H2>View Lists: Applying a View to Any File</H2> + +<P> +It is possible to apply a named View, or even several Views, to any +data file by appending a <B>viewlist</B> immediately after the standard "v:" +prefix. A viewlist takes the form: +<PRE> + :v1,v2,...vn: +</PRE> +where v1, v2, etc. are named Views. The two ":" colon characters surrounding +the list are required. Thus, the syntax for applying a viewlist to a file is: +<PRE> + v::view1,view2,...viewn:filename +</PRE> +Note that the name after the last ":" is assumed to be a file; it is +not permissible (or sensible) to use a View name. + +<P> +For example, the View specification: +<PRE> + fundisp v::x2:foo +</PRE> +applies the x2 View to the file foo (even if there is a View named foo) +and (in using our example database) is equivalent to: +<PRE> + ./fundisp foo'[cir 512 512 .1] "x y pi pha" +</PRE> +The same command can be effected using a list of Views: +<PRE> + fundisp v::x1,x1a:foo +</PRE> + +<P> +What happens if a viewlist is used and the file also matches a +template? Consider, for example, this View specification: +<PRE> + fundisp v::x2:foo.fit +</PRE> +Here, the x2 View will supply filter and column values, while the +template *.fit can also supply (different) filter and column +values. In this case, the explicitly specified Views of the viewlist +trump the matched view values. + +<P> +On the other hand, if a file template match can supply a View value +that is not supplied by the viewlist, then that value will be taken +from the file template match. For example: +<PRE> + fundisp v::x2:foo.fits +</PRE> +does not explicitly supply a format value, but the file match on *.fits +can and does. You can avoid supplying missing values using file template +matching by replacing the first ":" with a "-" in a viewlist +specification: +<PRE> + fundisp v:-x2:foo.fits +</PRE> +The use of ":+" to explicitly allow file template matching is also +supported, but is the same as the default case. Note that the nuances +of viewlist support are subject to change as our experience and +understanding grow. + +<H2>Overriding Values Associated with a View</H2> + +<P> +To override values associated with a View, simply supply the override +values in the correct place on the command line. Thus, given +the example database described above, the command: +<PRE> + fundisp v:x3 +</PRE> +specifies that the View named x3, along with its file name and +associated parameters, be processed as the input file to fundisp in +this way: +<PRE> + fundisp -f "I=%4d" ${HOME}/data/snr.ev'[cir 512 512 .1]' "x y pi pha" +</PRE> +To override one or more of these values, simply specify a new value +for the format, filter, or columns. For example, if your input View file +contains a filter, then the View will use that filter as an override +of the View filter: +<PRE> + fundisp v:x3'[cir 400 400 3]' +</PRE> +will use the columns and format of the x3 View but not the x3 filter. Further +examples are: +<PRE> + fundisp v:x3 "x y dx dy" # activate a different set of columns + fundisp -f "I=%3d" v:x3 # use a different format statement +</PRE> + +<P> +Note that extension names, extension index values, and other +non-filter specifications <B>do not</B> override the View +filter. Thus: +<PRE> + fundisp v:foo.fit[3] +</PRE> +will still use the filter associated with the .fit template (see above), since +the "3" is an extension index, not a filter. + +<H2>Environment Variables</H2> + +The following environment variables are used by Funtools Views: +<DL> +<DT><B>FUN_VIEWNAME</B> +<DD> The <B>FUN_VIEWNAME</B> environment variable specifies the +name and location of the View database file. If not present, the +files ./.funtools.vu and $HOME/.funtools.vu are searched for, in +that order. + +<DT><B>FUN_VIEWMATCH</B> +<DD> The <B>FUN_VIEWMATCH</B> environment variable specifies whether a +single match or multiple match algorithm is used to locate parameter +values. If the value of this environment variable begins with "s", +then a single match is used and missing parameters are not filled in +with subsequent template matches on the file name. If the value begins +with "m", then multiple matches are used to try to fill in missing +parameters. The default is to use multiple matches. +</DL> + +<H2>Restrictions and Problems</H2> + +Support for overriding a filter (while not overriding extension names, +extension indexes, etc.) requires that we can sense the presence of a +filter in a bracket specification. It is unclear yet whether our +algorithm is perfect. + +<P> +<A HREF="./help.html">Go to Funtools Help Index</A> + +<H5>Last updated: August 3, 2007</H5> + +</BODY> +</HTML> |