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

 

NAME

dbgroup - group a sorted table

SYNOPSIS

#include "db.h" ;

Dbptr dbgroup(Dbptr db, Tbl *groupfields,
                 char *name, long type)

DESCRIPTION

dbgroup performs an operation similar to the group by clause of SQL. The input db pointer specifies a table which has previously been sorted, typically by the same fields specified by groupfields. The new table takes the specified name; if name is a null pointer or string, a new, unique name is generated.

dbgroup creates a new table; the fields in this new table are the fields in groupfields, plus two additional fields: bundle and bundletype. Bundle is a database pointer which specifies a contiguous range of rows in the input table; bundletype is an integer field which is filled in with the value type specified in the call to dbgroup.

dbgroup goes through the input table sequentially, checking the values of the fields specified by groupfields. Whenever one of these fields changes from one row to the next in the input table, a new row is created in the new, output table. Each row of the output table is filled with a set of values for the fields, and the bundle field specifies the range of (contiguous) rows from the input which correspond to that set of values.

EXAMPLE

Suppose dbgroup were called with a sorted input table with two fields, sta and chan, like:

record# sta chan
0 AAK BHE
1 AAK BHN
2 AAK BHZ
3 CHM BHE
4 CHM BHN
5 CHM BHZ
6 EKS2 BHE
7 EKS2 BHN
Suppose that the list of groupfields was a single field, "sta", and that type were specified as 1. The resulting output table would look like:
record# sta bundletype bundle
record-range
0 AAK 1 0-3
1 CHM 1 3-6
2 EKS2 1 6-8

RETURN VALUES

dbgroup returns a database pointer which specifies the result of the operation. In the event of an error, all components (database, table, field, record) of the returned database pointer are dbINVALID. In this case, the elog(3) register contains more detailed error messages.

LIBRARY

$(DBLIBS)

DIAGNOSTICS

SEE ALSO

dbget_range(3)
dbintro(3)

BUGS AND CAVEATS

The attributes bundle and bundletype must already be specified (correctly) in the schema for the input table. Probably dbgroup should add these attributes if they are not already present.

Note that the output (grouped) table makes direct references by record number to the input table. Changes to the input table after dbgroup has been executed may (silently) invalidate the output table. (Similar warnings apply to views when changes are made to the underlying base tables).

AUTHOR

Daniel Quinlan
Printer icon