

DBZ(1)                     Unix Programmer's 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 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.

     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.)





C News                              5 July 1991                              1



DBZ(1)                     Unix Programmer's Manual                     DBZ(1)


     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.


















C News                              5 July 1991                              2

