dbz

DBZ(1)                      General Commands Manual                     DBZ(1)



NAME
       dbz - operate on dbz databases of text

SYNOPSIS
       dbz [ -{axmc} ] [ -t c ] [ -l length ] [ -{qiue} ] [ -f old ] [ -p
       parms ] database file ...

DESCRIPTION
       Dbz is a shell-level interface to the dbz(3z) database routines for
       indexed access to a text file.

       The database file must be a text file, one line per database record,
       with the key the first field on the line.  The -t option sets the
       field-separator character; the default is tab.  Setting the separator
       character to NUL (with -t '') makes the whole line the key.  Lines must
       not exceed 1023 bytes in length including the newline; this limit can
       be increased with the -l option.  The limitations and restrictions of
       dbz(3z) must also be observed; in particular, it remains the user's
       responsibility to ensure that no attempt is made to store two entries
       (whether identical or not) with the same key.

       In the absence of options, dbz creates a dbz(3z) index for the
       database; the index comprises files database.pag and database.dir in
       the same directory.  Any previous index is silently overwritten.  The
       -a, -x, -m, and -c options specify other operations.

       With -a, dbz appends lines from the file(s) (standard input if none) to
       the database, updating both the text file and the indexes.

       With -x, dbz reads keys from the file(s) (standard input if none) and
       prints (on standard output) the corresponding lines, if any, from the
       database.  The input is in the form of database lines, although only
       the keys are significant.  The -q option makes -x print the input lines
       whose keys are found instead of the database lines; this is somewhat
       faster.

       With -m, operation is the same as for -x except that the keys which are
       not present in the database are printed.

       With -c, dbz checks the database for internal consistency.  The -q
       option causes this check to be done more quickly but less thoroughly
       (each key is looked up in the index, but no check is made to be sure
       that the index entry points to the right place).

       The -i option suppresses the use of dbz(3z)'s incore facility.  This
       makes accesses slower, but keeps the files current during updating and
       reduces startup/shutdown overhead.

       Normally, dbz checks whether a key is already in the database before
       adding it.  The -u option suppresses this check, speeding things up at
       the expense of safety.

       A new index is normally created with default size, case mapping, and
       tagging.  The default size is right for 90-100,000 records.  The
       default case mapping is right for RFC822 message-ids.  See dbz(3z) for
       what tagging is about.  (Note, these defaults can be changed when
       dbz(3z) is installed.)

       If the -f option is given, size, case mapping, and tagging are instead
       initialized based on the database old.  This is mostly useful when
       creating a new generation of an existing database.  (See the
       description of dbzagain in dbz(3z) for details.)

       If the -p option is given, the parms string specifies the size, case
       mapping, and tagging.  If parms is a single decimal number, that is
       taken as the expected number of records in the index, with case mapping
       and tagging defaulted.  Alternatively, parms can be three fields—a
       decimal number, a case-mapping code character, and a hexadecimal tag
       mask—separated by white space.  The decimal number is, again, the
       expected number of records; 0 means ``use the default''.  See dbz(3z)
       for possible choices of case-mapping code, but in particular, 0 means
       ``no case mapping''.  See dbz(3z) for details on tag masks; 0 means
       ``use the default''.

       If the -e option is given, the decimal number in -p is taken to be the
       exact table size, not the expected number of records, and invocation of
       dbzsize (see dbz(3z)) to predict a good size for that number of records
       is suppressed.

       The .pag file is normally about 6 bytes per record (based on the
       estimate given to -p or the previous history of the -f database).  The
       .dir file is tiny.

SEE ALSO
       dbz(3z)

HISTORY
       Written at U of Toronto by Henry Spencer, for the C News project.  See
       dbz(3z) for the history of the underlying database routines.

BUGS
       There are a number of undocumented options with obscure effects, meant
       for debugging and regression testing of dbz(3z).

       Permissions for the index files probably ought to be taken from those
       of the base file.

       The line-length limit is a blemish, alleviated only slightly by -l.



                                  11 Feb 1992                           DBZ(1)