• Antelope Release 5.10 Linux CentOS release 7.6.1810 (Core) 3.10.0 2020-05-12

 

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:

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
Printer icon