NAME
dbprocess - construct a view as series of standard operations: joins, subsets, groups
SYNOPSIS
#include "db.h"
Dbptr dbprocess(Dbptr db, Tbl *list, Dbptr (*unknown)())
DESCRIPTION
dbprocess provides a flexible, simplified
method for forming views from input specifications.
These specs are a list of statements,
which are performed in order, to create a view.
Each statement uses the result from the previous
statement.
The statements which may be used to form views are:
-
"dbopen table"
-
"dbjoin [-o] table [ key key ..]"
-
"dbgroup key [ key ..]"
-
"dbleftjoin [-o] table [ key key ..]"
-
"dbnojoin table [ key key ..]"
-
"dbselect expr [expr ...]"
-
"dbseparate table"
-
"dbsever table"
-
"dbsort [-ru] [key .. ]"
-
"dbsubset expression"
-
"dbtheta table [ expression ..]"
-
"dbungroup"
-
"dbunjoin new-database"
-
"verbose"
dbprocess is useful for creating programs which do more
complex manipulations. For example, dbverify uses
a version of dbprocess.
dbprocess and dbselect(3) are especially useful
in conjunction with parameter files, which provide a
convenient method for creating the lists which dbprocess
and dbselect require.
When a statement is not recognized, dbprocess
calls the unknown procedure with two arguments:
the input database pointer, and the offending line.
The procedure must return a database pointer,
which should be dbinvalid in the case of an error.
dbopen table
dbprocess can use the table specified in its
db argument,
or explicitly open a table.
dbjoin [-o] table [ key key ..]
join with the specified
table, using the optionally specified
keys.
The syntax is very similar to command line dbjoin, but the keys
do not need to be introduced with colon, since only one table is joined at a
time; all the arguments after the table name are keys.
dbleftjoin [-o] table [ key key ..]
join with the specified
table, using the optionally specified
keys.
However, the named table is first in the join, rather than last.
dbnojoin table [ key key ..]
the resulting view has only records which do not join with the specified
table.
dbgroup key [ key ..]
group a (sorted) table, so that records with the same values for the specified
keys occur in a group.
dbungroup
removes one level of grouping. This may be useful if the grouping
were necessary to do a subset.
dbtheta table [ expression ..]
join every record in the input with every record in the specified table,
provided the expression evaluates to true.
dbsubset expression
subset the input according to expression.
dbsort [-ru] [key .. ]
sort the input according to the specified keys. The -r option specifies
reverse sort, the -u option specifies unique.
dbseparate table
Eliminate all other tables except table from join.
dbsever table
Eliminate the specified table from the join.
dbselect expr [expr ...]
has no effect on the view, but as a side
effect, prints out the values of each expr (to stderr) for each row of the view.
It may be useful for debugging purposes.
dbunjoin new-database
Saves the current view into a new database using
dbunjoin(3).
verbose
has no effect on the view, but causes the command and the resultant number
of records to be printed after each command.
EXAMPLE
This example can be found in
$ANTELOPE/example/c/db.
%cat dbprocess.c
#include <stdio.h>
#include <math.h>
#include "coords.h"
#include "db.h"
#include "stock.h"
int
main(int argc, char **argv)
{
Dbptr db ;
char *database ;
Pf *pf ;
Tbl *input, *list ;
elog_init(argc,argv) ;
if (pfread(Program_Name, &pf) != 0)
die(0, "Can't read parameter file\n");
if ( argc != 2 )
die ( 0, "Usage: %s database\n", Program_Name ) ;
database = argv[1] ;
if ( dbopen(database, "r", &db ) < 0)
die (0, "Couldn't open database %s\n", database ) ;
input = pfget_tbl (pf, "input" ) ;
db = dbprocess ( db, input, 0 ) ;
if ( db.table >= 0 ) {
list = pfget_tbl ( pf, "fields" ) ;
dbselect (db, list, stdout ) ;
} else {
complain ( 0, "dbprocess fails" ) ;
}
return 0;
}
% cat dbprocess.pf
input &Tbl{
verbose
dbopen wfdisc
dbsubset chan== "BHZ" && time > "5/1/83"
dbsort sta
dbjoin site sta time::endtime\#ondate::offdate
dbjoin sitechan
}
fields &Tbl{
sta
chan
strtime(time)
staname
lat
lon
hang
vang
}
% dbprocess demo
% ./dbprocess $db
dbprocess: ## dbopen wfdisc => 18 records
dbprocess: ## dbsubset chan== "BHZ" && time > "5/1/83" => 6 records
dbprocess: ## dbsort sta => 6 records
dbprocess: ## dbjoin site sta time::endtime#ondate::offdate => 6 records
dbprocess: ## dbjoin sitechan => 6 records
AAK BHZ 5/17/1992 21:55:10.250 Ala-Archa, Kyrgyzstan 42.6333 74.4944 0.0 0.0
CHM BHZ 5/17/1992 21:55:15.200 Chumysh, Kyrgyzstan 42.9986 74.7513 0.0 0.0
EKS2 BHZ 5/17/1992 21:55:04.700 Erkin-Sai, Kyrgyzstan 42.6615 73.7772 0.0 0.0
KBK BHZ 5/17/1992 21:55:14.400 Karagaibulak, Kyrgyzstan 42.6564 74.9478 0.0 0.0
TKM BHZ 5/17/1992 21:55:19.050 Tokmak, Kyrgyzstan 42.8601 75.3184 0.0 0.0
USP BHZ 5/17/1992 21:55:15.700 Uspenovka, Kyrgyzstan 43.2669 74.4997 0.0 0.0
RETURN VALUES
dbprocess returns a database pointer to the resulting view.
For detected (syntax) errors,
dbinvalid() is returned.
If at any point during construction,
the intermediate view has zero records,
processing ceases and a view with no records is returned.
LIBRARY
$(DBLIBS)
SEE ALSO
dbselect(3)
dbintro(3)
tbl(3)
pf(3)
BUGS AND CAVEATS
The parsing is extremely simple, and doesn't accommodate
different quoting conventions.
AUTHOR
Daniel Quinlan