FirstBase: DDICT(5)

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

NAME

ddict - FirstBase database dictionary file

SYNOPSIS

Layout of FirstBase database dictionary files

DESCRIPTION

A database dictionary file is a text file used to define FirstBase databases. This file describes each field by name, type and length, and also stores defaults, ranges, help file names, and other information.

Formally, this file, called a ddict file, is edited using the dbdbas(1) tool. All FirstBase tools use this file at run time to determine the layout of the database being used or created.

This manual page describes the layout of database dictionary files so that creation of theses files can be accomplished using a text editor or program of some kind.

Warning: dbdbas(1) allows only limited changes to a ddict file after a database has been created. In general, this rule should be followed by those who want to edit ddict files by hand.

However, if you know what you are doing, using a text editor on a ddict file can save lots of time during the design phase of application development, and can also be used on a working system without disturbing the data. As a rule, use dbcheck(8) with the -clp flags after the modifications to ensure a match between the data dictionary and data records.

DATABASE DICTIONARY

A database dictionary consists of a series of text lines representing field descriptors. Each field descriptor contains at least three field attributes: field_name, field_type, and field_size. All of the field descriptors together, the whole file, describe a single record.

Each field descriptor is on a line by itself, with each attribute separated by white space. The optional attributes are represented as switch settings and are defined on a field by field basis. The following represents an entire field attribute in BNF notation, with detailed descriptions below. (Though shown on two lines, each entry must be a single line).

   Field_Name Field_Type Field_Size [-d default] [-c[ab] comment] [-l]
      [-h helpfile] [-A] [-a[u] autoindex] [-r range] [-m macro]

Field_Name

The Field_Name attribute is the sequence of characters that are used to label this field. The limit is ten (10) characters. Blanks and underscores can be used.

Field_Type

The Field_Type describes the data type that the field will be allowed to contain. This attribute is actually a single character depicting the formal FirstBase data type. The following is a list of all field types:

a - alphanumeric
b - binary
c - choice
d - date
$ - dollar
f - float
F - formula
l - link
n - numeric
N - positive numeric
A - strictly alpha
U - uppercase
X - extended choice (see xchoice(5))
C - silent choice

Field_Size

The Field_Size attribute contains the maximum number of characters allowed for the field. These fields are not blank-padded to this maximum, it merely provides an upper limit. Two special notes: date fields should have a size of six (6), link fields have a size of zero (0).

Default

The default attribute of a field descriptor is used to denote the characters that will be placed in the field when no other characters are placed there and a <RETURN> is hit. This attribute consists of two parts, the -d flag, and the actual default string.

Note that if no default is defined, the field becomes a FORCED ENTRY field, and users will not be able to add a new record without this field having information in it. Also, to use a "blank" as the default, use the underscore, as in "-d _".

One special use of the default attribute is for link fields. The link address, as discussed in dbdbas(1), is stored in this attribute.

Another special use of the default attribute concerns the precision of formula and float data types. The precision, or the number of decimal places, is specified by appending a :N to the default string, where N is the desired precision. The default precision is two.

Comment

The comment attribute represents text that is used only in the FirstBase tool dbedit(1) and does not affect any other tools, not even dbvedit(1). This attribute consists of two parts, the comment flag and the comment text.

The comment flag is a -c, optionally followed by an a (after) or a b (before). The comment flag is followed by the actual comment text.

Lock

The -l flag controls the lock attribute. If used, the field will accept a value during record creation, but once the record exists, no modifications to this field can be done using the database editor. This is a good flag to use for items of information that should NOT be altered, like patient or student identification numbers.

Helpfile/Choicefile

This attribute points to a file that is paged to the screen when a HELP keystroke is issued while editing this field from within either of the database editors. The syntax is -h helpfile.

Note that full path names are not needed. When invoked from a distance, FirstBase tools will properly prepend the working directory to the helpfile if needed.

Alternately, the helpfile is used as a choicefile for data fields of type c (choice), C (silent choice), and X (Extended Choice). Choice files are outlined in choice(5) and xchoice(5).

An additional feature allows standard choice types (c and C) to have choice files that dynamically grow during the editing session. This feature is enabled using the -A flag.

Autoindex

The autoindex attribute points to a FirstBase index that will be automatically updated during database additions and modifications. This feature is available from either of the database editors, or addrec(3). The general syntax is -a autoindex.

An autoindex is a standard FirstBase index, but a very simple one. These indexes must be single field indexes, and must select ALL entries. The needed index dictionaries will be created automatically when a database editor is invoked. However, they can be created using dbdind(1) as well as long as the above rules are followed.

A unique values flag can be combined with the autoindex flag, and is denoted as -au. This flag will make the database editor enforce unique values for all values entered into the associated field.

Range

The range attribute allows the definition of enumerated data types. This attribute is marked with a -r flag, followed by the range string.

Along the standard UNIX method, range strings are made up of single elements separated by commas. Each element is either a single value, or an element of the form M-N which covers all numbers or characters in the range M through N. For example, -r 7,9,31 and -r a-j,o,p,w-z are both valid range specifiers.

Macro

The macro attribute is used to specify a file that is used by the database editor dbvedit(1) in place of normal field editing. This macro file contains macro code, as described in macro(5).

HINTS

When building a new database dictionary, it might be a good idea to define excess fields that can quickly be used later. This will alleviate the use of dbcgen(1) or dbemit(1)/dbload(1) to expand the database schema.

Also, data types can be changed by hand if the user is sure of the data within the fields. For example, an A could be converted to an a, but the reverse might not hold true. There is no real difference in how the fields are stored, so conversion is generally alright. New records will be handled correctly, as well as modifications to old records.

Changing the size of a field by hand is also acceptable. In fact, increasing the size of a field will always work. However, decreasing the size must be done carefully. If you know that all the data in a certain field is less than 50 characters wide, yet its defined maximum is 75, changing it to 50 will not hurt anything. Again, dbcheck(8) with the -clp flags is a good sanity check after making direct changes to a ddict file.

FILES