1funview(n) SAORD Documentation funview(n)
2
6 Funview: Database View Support for Tables
7
9 This document contains a summary of the options for utilizing database-
10 inspired Views of tables.
11
13 Database Views
14 In database parlance, a View defines a "virtual table", i.e., a
16 description of row and/or column selection filters (but with no perma‐
17 nent storage space allocated). When used in place of a table, a View
18 selects the specified rows and/or columns from one or more real tables.
19 Views enable you to see complicated data tables in a more convenient
20 format. They also can be used as a security mechanism, by restricting
21 user access to specific columns and/or rows. [See:
22 http://www.cs.unibo.it/~ciaccia/COURSES/RESOURCES/SQLTuto‐
24 rial/sqlch5.htm
25 for a good discussion of SQL Views.]
27 Funtools supports an expanded notion of Views for all tabular data
29 (FITS tables, raw binary tables, and ASCII column files). Funtools
30 Views allow you to pre-set values for the filter specification, the
31 columns to activate, and display format (though the latter is for
32 fundisp only). Setting the filter and column activation values pro‐
33 vides functionality equivalent to that of a classical database View,
34 while the ability to set the format is similar to classical report
35 writing capabilities.
36 Funtools View Attributes
38 A Funtools View is a text file containing one or more of the following
40 columns:
41 column description
43 ------ -----------------------------
44 view name of view
45 file data file name or template
46 filter filter specification
47 columns columns to activate
48 format fundisp format specification
49 All of the attribute columns are optional, including the view name
51 itself. This means that a View can be named or unnamed. Unnamed Views
52 can refer to a specific file or a template of files (obviously if nei‐
53 ther the view or the file column is specified, the input View specifi‐
54 cation will never be used). You can specify any combination of filter,
55 column, and format parameters. (It also is possible to apply file-spe‐
56 cific View to other files; see the discussion on View Lists below).
57 Each column has a size limit of 1024 characters.
58 For example, consider the following View file:
60 view file format columns filter
62 ---- ---------------------- ------ ------------ -------
63 x3 ${HOME}/data/snr.ev I=%4d x y pi pha cir 512 512 .1
64 x2 ${HOME}/data/snr.ev x y pi pha cir 512 512 .1
65 x1 ${HOME}/data/snr.ev cir 512 512 .1
66 x1a ${HOME}/data/snr.ev x y pi pha
67 x0 ${HOME}/data/snr.ev
68 xf I=%4d
69 xc x y pi pha
70 xr cir 512 512 .1
71 *.ev x y pi pha
72 *.fit x y dx dy cir 400 400 3
73 *.fits I=%3d x y dx dy cir 400 400 3
74 This database example is in rdb format, i.e. using tab delimiters and
76 permitting null values. Any valid ASCII table format is acceptable, but
77 if you use a format that does not permit null values, it will be neces‐
78 sary to quote the null strings.
79 The first five entries (x3, x2, x1, x1a, x0) are named entries defining
81 default values specifically for the snr.ev data file. Typically, you
82 would use these Views by specifying View name, and the corresponding
83 file, filter, column, and format values would be used. Note that the x0
84 View is essentially an alias for the pathname of this file.
85 The next three entries define defaults that can be applied to any file.
87 You typically would use these View names in conjunction with a specific
88 file name (see View Lists below) so that the associated parameter(s)
89 were applied to that file.
90 The last three entry in the database define unnamed Views that pertains
92 to all files ending with the specified templates. In these cases, any
93 View that specifies a file name matching the file template would be
94 processed with the associated parameter attributes.
95 Invoking a Funtools View (in Place of an Input File)
97 To use a Funtools View, you simply pre-pend the "v:" prefix to a View
99 name or a file name where an input file name usually is specified. For
100 example:
101 fundisp v:x3
103 specifies that the View named x3 (with its file name and associated
105 parameters) is processed as the input file to fundisp. Using the exam‐
106 ple database, above, this is equivalent to:
107 fundisp -f "I=%4d" ${HOME}/data/snr.ev'[cir 512 512 .1]' "x y pi pha"
109 That is, the format is used with fundisp's -f (format) switch, while
111 the filename and extension are composed of the x3 View's filename and
112 region filter.
113 Similarly, executing a command such as:
115 fundisp v:foo.fit
117 will match the unnamed View associated with the template "*.fit". This
119 is equivalent to executing:
120 fundisp foo.fit'[cir 400 400 3]' "x y dx dy"
122 Of course, if you omit the "v:" prefix, then no View processing takes
124 place:
125 fundisp foo.fit # process foo.fit without any View parameters
127 fundisp x3 # error (assuming there is no file named x3)
128 Basic View Matching Rules
130 When a "v:" prefix is recognized, Funtools searches for a View database
132 file in the following order:
133 location description
135 ------------ ------------------------------------
136 FUN_VIEWFILE environment variable (any file name)
137 ./.funtools.vu hidden file, default name
138 $HOME/.funtools.vu hidden file, default name
139 The first View database file located is used to construct a new file‐
141 name, as well as an activation column specification and a format speci‐
142 fication. The following rules are used:
143 1. An attempt is made to match the input name (i.e., the part of the
145 input View after the "v:" prefix) against the view column value (if
146 present) of each row in the database. If a match is found, the values
147 of all non-blank columns are saved for later use. Also note that the
148 first match terminates the search: i.e., the order of the database rows
149 matters.
150 2. If no view match is made, an attempt is made to match the input name
152 against the file column value (if present). Matching is performed on
153 the full pathname of both the input name and the database file name,
154 and on the non-directory (root) part of these files. This means that
155 the root specification:
156 fundisp v:snr.ev
158 will match a row in the database that has a full pathname in the file,
160 allowing you to use a file-matched View without having to specify the
161 full pathname. In this example, the "v:snr.ev" View specification will
162 match the first row (v:x3) in the database:
163 x3 ${HOME}/data/snr.ev I=%4d x y pi pha cir 512 512 .1
165 even though the row contains a fully qualified pathname as the file
167 value. Once again, values of all non-blank columns are saved, and the
168 first match terminates the search.
169 3. If neither a view or a view match has been found, then a simple tem‐
171 plate match is attempted against the view values. Template matching
172 supports a simplified version of file globbing (not a regular expres‐
173 sion), with support for a single "*" (all characters), "?" (single
174 character), or "[...]" (range) specification.
175 4. If no template match was found on the view column, then a simple
177 template match is attempted against the file columns.
178 5. If no match is found, then the filename (minus the "v:" prefix) is
180 returned.
181 More on View Matching Rules: Single vs. Multiple Matches
183 The matching rules described above stop after the first match, regard‐
185 less of whether that match provides values for all three parameters
186 (filter, columns, and format). In cases where a view or file match does
187 not provide all three values, it is possible that a template match
188 might do so. With regard to the example View database above, the x1
189 View provides only a filter, while omitting both the format and columns
190 values. But note that the final rows in the database could provide the
191 values via a template match on the filename. This sort of multiple
192 matching is especially valuable in order to provide "global" values to
193 several Views.
194 Obviously, multiple matching might not be wanted in every case. There‐
196 fore, we support both multiple matching and single matching according
197 to the value of the FUN_VIEWMATCH environment variable. If the
198 FUN_VIEWMATCH environment variable exists and if its value begins with
199 "s", then a single match is used and missing parameters are not filled
200 in with subsequent template matches on the file name. That is, matching
201 rules above are followed exactly as explained above. If the value of
202 this environment variable begins with "m" (or does not exist), then
203 multiple matches are used to try to fill in missing parameters. In
204 this case, template matching always takes place and missing values are
205 taken from these template matches.
206 Thus, in the example above, the View specification:
208 fundisp v:x1
210 will take the file name and filter value from the x1 View:
212 x1 ${HOME}/data/snr.ev cir 512 512 .1
214 The column value then will be taken from the "*.ev" file template match
216 against the x1 file name:
217 *.ev x y pi pha
219 Note once again that order is important: missing values are taken in
221 the order in which the template matches are processed.
222 View Lists: Applying a View to Any File
224 It is possible to apply a named View, or even several Views, to any
226 data file by appending a viewlist immediately after the standard "v:"
227 prefix. A viewlist takes the form:
228 :v1,v2,...vn:
230 where v1, v2, etc. are named Views. The two ":" colon characters sur‐
232 rounding the list are required. Thus, the syntax for applying a
233 viewlist to a file is:
234 v::view1,view2,...viewn:filename
236 Note that the name after the last ":" is assumed to be a file; it is
238 not permissible (or sensible) to use a View name.
239 For example, the View specification:
241 fundisp v::x2:foo
243 applies the x2 View to the file foo (even if there is a View named foo)
245 and (in using our example database) is equivalent to:
246 ./fundisp foo'[cir 512 512 .1] "x y pi pha"
248 The same command can be effected using a list of Views:
250 fundisp v::x1,x1a:foo
252 What happens if a viewlist is used and the file also matches a tem‐
254 plate? Consider, for example, this View specification:
255 fundisp v::x2:foo.fit
257 Here, the x2 View will supply filter and column values, while the tem‐
259 plate *.fit can also supply (different) filter and column values. In
260 this case, the explicitly specified Views of the viewlist trump the
261 matched view values.
262 On the other hand, if a file template match can supply a View value
264 that is not supplied by the viewlist, then that value will be taken
265 from the file template match. For example:
266 fundisp v::x2:foo.fits
268 does not explicitly supply a format value, but the file match on *.fits
270 can and does. You can avoid supplying missing values using file tem‐
271 plate matching by replacing the first ":" with a "-" in a viewlist
272 specification:
273 fundisp v:-x2:foo.fits
275 The use of ":+" to explicitly allow file template matching is also sup‐
277 ported, but is the same as the default case. Note that the nuances of
278 viewlist support are subject to change as our experience and under‐
279 standing grow.
280 Overriding Values Associated with a View
282 To override values associated with a View, simply supply the override
284 values in the correct place on the command line. Thus, given the exam‐
285 ple database described above, the command:
286 fundisp v:x3
288 specifies that the View named x3, along with its file name and associ‐
290 ated parameters, be processed as the input file to fundisp in this way:
291 fundisp -f "I=%4d" ${HOME}/data/snr.ev'[cir 512 512 .1]' "x y pi pha"
293 To override one or more of these values, simply specify a new value for
295 the format, filter, or columns. For example, if your input View file
296 contains a filter, then the View will use that filter as an override of
297 the View filter:
298 fundisp v:x3'[cir 400 400 3]'
300 will use the columns and format of the x3 View but not the x3 filter.
302 Further examples are:
303 fundisp v:x3 "x y dx dy" # activate a different set of columns
305 fundisp -f "I=%3d" v:x3 # use a different format statement
306 Note that extension names, extension index values, and other non-filter
308 specifications do not override the View filter. Thus:
309 fundisp v:foo.fit[3]
311 will still use the filter associated with the .fit template (see
313 above), since the "3" is an extension index, not a filter.
314 Environment Variables
316 The following environment variables are used by Funtools Views:
318 · FUN_VIEWNAME
320 The FUN_VIEWNAME environment variable specifies the name and loca‐
322 tion of the View database file. If not present, the files ./.fun‐
323 tools.vu and $HOME/.funtools.vu are searched for, in that order.
324 · FUN_VIEWMATCH
326 The FUN_VIEWMATCH environment variable specifies whether a single
328 match or multiple match algorithm is used to locate parameter val‐
329 ues. If the value of this environment variable begins with "s",
330 then a single match is used and missing parameters are not filled
331 in with subsequent template matches on the file name. If the value
332 begins with "m", then multiple matches are used to try to fill in
333 missing parameters. The default is to use multiple matches.
334 Restrictions and Problems
336 Support for overriding a filter (while not overriding extension names,
338 extension indexes, etc.) requires that we can sense the presence of a
339 filter in a bracket specification. It is unclear yet whether our algo‐
340 rithm is perfect.
341 Go to Funtools Help Index
343 Last updated: August 3, 2007
345version 1.4.0 August 15, 2007 funview(n)