8. Creating Databases

Using the FileFlex Database Designer
Executing the DBCreate Function
Describing the Database

The easiest way to create a new database is to use the click and drag interface of the FileFlex Database Designer. Just launch the FileFlex Database Designer (from Director 5, you'll just select it under the tools Xtra menu).

You can also program database creation. To make it possible for your project to create new database files, you must:

Build a field to contain the database description as described below.
Execute the DBCreate function and pass it the appropriate information.

We'll discuss these tasks in reverse order because that's the easiest way to understand them.

Runtime Note: When you purchase the FileFlex runtime, the DBCreate and DBCreateIndex functions are disabled. If you purchase a license to distribute FileFlex with your application, you may not include the DBCreate function in your product. (Our lawyers made us say what follows) Failure to adhere to this requirement voids your license and may result in civil and/or criminal liability for copyright infringement or other violations of law.

Using the FileFlex Database Designer

New in 2.0: FileFlex now includes an interactive tool for creating database files, creating index files, and viewing existing database files. This tool is called the FileFlex Database Designer. You can invoke the FileFlex Database Designer in two ways. If you're using Director 5, just select it from under the tools Xtra menu in Director. If you're not using Director 5, the FileFlex Database Designer is available as a double-clickable application. In either case, once launched, the interface is the same.

The Database Designer interface has three tabs: Create, Index, and Browse. To create a new database, click the Create tab. Likewise, to create an index, click the Index tab and to browse a database, click the Browse tab.

Creating a new database is a matter of simply dragging fields from the field buckets located along the bottom of the Create page into the gray field on the left side of the screen. FileFlex supports five basic data types, each is represented by a bucket.

When you click and drag in the text bucket, a panel will show up by your cursor. Drag that panel into the gray area and release. A dialog box will be displayed that will let you enter the field name, switch between field types, and (if appropriate) select the width of the field.

Keep this up until you've added all the fields you want. If you don't like a given field, just click, hold the mouse, and drag the field panel to the trash. When you're done, just click Make It and a database file will be created.

To browse an already created (and populated) database, select the Browse tab. Open a database file by clicking the button marked Open a Database. Click the left and right arrows to move between records and the up and down arrows to scroll the list of fields.

Executing the DBCreate Function

The DBCreate function requires four parameters. In order, they are:

the name of the database you wish to create (with optional path name and no file suffix)
the number of fields in the database
the name of the container in which the description of the fields can be found
a Boolean ("true" or "false") that tells FileFlex what to do if it finds a database file of the same name as it attempts to create the new one

All of these parameters are self-explanatory except the last. If the fourth argument passed to the DBCreate function is "true," and FileFlex finds an existing file, it will not overwrite it. Instead, it will abort the database creation process and return an error. If the fourth argument is "false," it will overwrite any existing database file of the same name. (Note that FileFlex appends a suffix, ".DBF," to the name you provide, so it won't overwrite a text or other file of the same name, only a file whose name matches the name you provide as a first argument, with the ".DBF" appended.)

After the database is created, it is automatically opened by FileFlex and is ready to receive data. If you don't want to work with the file immediately, be sure to close it.

If you include any memo ("M") fields, FileFlex will automatically generate a matching file with an extension of ".DBT" to hold the memo field information.

Describing the Database

The container in which you store the description of the database file to be created should be a field, a variable, or any other easily accessible container. The container should contain one line for each field to be created. Each line should contain, in order, these items, separated by commas:

name of the field
type of field
length of field, for string and numeric fields
number of decimal places for numeric fields

Remember the xBASE field naming rules when naming fields in your database file: keep the names under ten characters, do not include anything but letters, numbers, and the underscore character. If you are unfamiliar with these rules, consult a good book on xBASE programming. The field type will be one of these characters: C (for a character, or string, field), N (for a numeric field), M (for a memo field), L (for a logical, or Boolean, field), or D (for a date field).

Character and numeric require lengths to be supplied. Only numeric fields require the fourth element. For memo, Boolean, and date fields, no length information is required. Supplying it may produce unexpected results in the database file.

Here is an example of a database file description that might appear in a container:

  NAME,C,24
  STREET,C,24
  AGE,N,2,0
  MARRIED,L
  DOB,D
  COMMENTS,M

Executing DBCreate with this description would produce a database file with six fields: two 24-character string fields; a two-digit, no-decimals age field; a logical field called MARRIED; a date field holding the date of birth and called DOB; and a memo field named COMMENTS.

Example

If we wanted to create a database file called FRIENDS.DBF in the current default path using the fields in the previous section which we had stored in a card field called dbFields, this is how we would write the function call:

   put dbCreate ("FRIENDS",6,cd fld dbFields,false) into dbResult

  [Previous Chapter]    [Table of Contents]    [Next Chapter]