FirstBase: DBMERGE(1)

URL: http://www.firstbasesoftware.com/man/man1/dbmerge.htm
Last modified: 4 April 1996
Copyright © by FirstBase Software.
[ Index of Contents] [ FirstBase RDBMS Overview]

NAME

dbmerge - merge source text with a FirstBase database (mail merge)

SYNOPSIS

dbmerge [-b] [-y] [-B] [-n count] [-w width] [-d database] [-i index] [source] [destination | -]

DESCRIPTION

Dbmerge merges a source document with user selected fields from a FirstBase database. The end result is a separate copy of the input document for each record in the current FirstBase index with actual database data substituted for in indicated places. The set of processed records can be limited using the -i index specifier. The -n flag can be used to process exactly count records.

The -b flag will run the FirstBase tool in batch mode, suitable for shell scripts. This mode produces no output on the terminal, thus can also be used when running the process in the background. The -y flag will run the tool at the terminal without pausing to ask the user if existing files can be destroyed and without displaying a 'picture' of the requested task.

The -B flag will enable the fastest throughput of records from the database. If this flag can be used, the dbmerge generation is speeded up a great deal by internal record buffering. Note that no index can be used with record buffering, and that record locking is disabled.

The -w flag is used to set the width of the document. Lines longer than this width will be truncated with a warning. The default width is the FirstBase environment variable MERGECOLS or the minimum width of a FirstBase controlling terminal, 80.

If command line arguments for the source or destination are not provided, dbmerge will prompt for the source and/or destination file names. The destination file may be specified as - to produce output on the standard output device.

To begin, a document must be prepared using some kind of text editor, or by using dbdmrg(1). This document is the source to dbmerge(1). One good example of dbmerge(1) input is an nroff(1) source document.

The input document may be interspersed with tokens that represent data fields in a FirstBase database. These tokens are formed by pre-pending a dollar sign, $, to a valid FirstBase field_name. For example, if LastName is a valid database field name as defined in the current database dictionary, then $LastName would be the correct token to insert into the document. Again, this prepared document is the input or source to dbmerge(1).

Tokens can also be forced to appear in an expanded or truncated manner. Each token can be followed by a size delimiter. For example, $LastName[25] would print the LastName contents in a slot exactly 25 characters wide, no matter how big the actual data field is. A size of 0 or no size means the field token data will print unconstrained.

Dbmerge(1) first parses the source looking for tokens to be expanded. During this stage, all found tokens are displayed on the screen. Unresolved tokens are marked ...undefined. These undefined tokens are printed out in place exactly as they appear. Thus, '$100.00' would be marked as undefined, and would print '$100.00'. Note: to get a single dollar sign without a warning, use two dollar signs ($$).

After getting the user's permission to continue, the processing stage takes the source document and produces one copy for each record in the FirstBase index to the destination file. Defined tokens are substituted for their respective field data from the database during this stage.

Note: white spaces (tabs, blanks, newlines) are kept intact during the actual document-database merging. Furthermore, it is up to the user to prepare the document properly. For example, if the document is a letter, then probably a new page is needed for each letter produced. For nroff source, this means that a .bp command must be either the first or last nroff command in the document.

The source document can also contain specific sections of text that are processed exactly once: at the beginning or at the end of the entire merge process. For example, this feature could be used to place a header at the top of some merge output.

To use these features, the symbols _BEGIN_ and _END_ are used to delimit sections of text to be processed at the beginning or at the end of the merge process. Both sections are optional, but if used, should appear as in the following example:

_BEGIN_
[ Header information -- printed exactly once ]
_BEGIN_
[ Normal Text ... with embedded $ Field Tokens ]
_END_
[ Footer information -- printed exactly once ]
_END_

FILES

merge.in: default name for merge source file.
merge.out: default name for the merge output file.
dbase: default name for the FirstBase database.
index: default name for the FirstBase index.
*.cdb: FirstBase database.
*.idx: FirstBase index.
*.ddict: FirstBase database dictionary.

DIAGNOSTICS

Dbmerge(1) pauses to ask permission to destroy an existing output (destination) file. A valid FirstBase database dictionary is required for the current database.

This tool uses a FirstBase index to generate the output from the database in a particular order. If this index is detected to be out of date or non-existent, it is regenerated automatically. An index is out of date if either the database or the index dictionary have changed more recently than the index was generated.