FirstBase: DBJOIN(1)

URL: http://www.firstbasesoftware.com/man/man1/dbjoin.htm
Last modified: 12 September 1995
Copyright © by FirstBase Software.
[ Index of Contents] [ FirstBase RDBMS Overview]

NAME

dbjoin - join two FirstBase databases

SYNOPSIS

dbjoin [-a] [-b] [-y] -d dbase1 -i index1 [-d2 dbase2] [-i2 index2] [-o join_dbase]

DESCRIPTION

Dbjoin takes two FirstBase databases and joins the databases together by laminating the records of each database into a single record. These new records are written to a different output file, creating a newly structured database.

Note: the use of dynamic links in the database dictionary can also be used to get join type of information at runtime for each tool, instead of using dbjoin to generate new databases. See dbdbas(1). In addition, the dbsql tool can be used to do joins also.

The order in which records are laminated is determined by the indexes associated with each database. Both indexes are required, and both must be sorted. Note that only the first indexed field of a multiple index is relevant to any joining of database.

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 second database and its associated index are prompted for by dbjoin(1) once the first database (dbase1) has been defined and loaded. This second database (dbase2) and its index must be distinct (different) from the first set.

After loading the second database, dbjoin(1) asks for the name of an output file. This name must not be either of the first two, but it can exist. Dbjoin(1) will deposit the laminated (joined) records into a standard FirstBase database using this name as its base. Of course, a dictionary for the new database is also created.

Using the -d2 and -i2 argument line flags, dbjoin(1) can be fed the names of the second database and index from the command line. The -o option allows specification of an output file from the command line also.

As mentioned above, the method used to join databases depends on two separate, sorted FirstBase indexes that refer to two separate FirstBase databases. Normally, dbjoin(1) will output records only for those entries from both indexes that match. These records take the form of the common indexed field, followed by the fields from dbase1 then the fields from dbase2.

Index entries that do not match only create a record if the -a option is specified. In this case, fields from the 'other' database are left empty.

Again, note that only the first indexed field is tested for matching during the joining phase. Multiple field indexes will work, but those fields beyond the first are unused by dbjoin(1).

Dbjoin(1) allows an interesting tool oriented approach to data entry and database management systems. Combinations of databases can be created using this tool. For example, personal and financial information for a group of people could be joined together, edited all at once with dbedit(1), and then split back into separate databases using dbcgen(1).

Note: dbclean(1) is automatically run at the completion of this program to create a map file for the new database.

EXAMPLES

To run a simple interactive dbjoin, use

dbjoin -d j1 -i j1

To run this in yes mode providing the arguments it will need, use

dbjoin -y -d j1 -i j1 -d2 j2 -i2 j2 -o new_dbase

FILES

*.cdb: FirstBase database.
*.map: record map of FirstBase database.
*.idx: FirstBase index.
*.ddict: FirstBase database dictionary file.
*.idict: index header information.
dbase: default database for dbjoin(1) and for prompted database name.
index: default index for dbjoin(1) and for prompted index name.
join: default name for join output file.

DIAGNOSTICS

Dbjoin(1) will ask permission before overwriting an existing output file.

Field names between the two databases must be unique, except for the indexed field from each database. This is because the original field names are used in the resulting database, and any FirstBase database enforces unique naming among its field names.

This tool uses FirstBase indexes to generate the output from the databases in a particular order. If either 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 been changed more recently than the index was generated.