                            Database File Converter
                                  by Dan Wilga
            Copyright 1992, Gribnif Software. All rights reserved.

This program is included as part of the CardFile 4 package, and is not
public domain.

Introduction
------------

This program will convert most common file types to other file types. It
can also be used to remove particular fields from a database or blank them
out.


Installing It
-------------

The Database Converter can be run as either a program or as a desk
accessory.

PRG:  The files DB_CONV.PRG and DB_CONV.RSC should be in the same folder.
      All .DCL and .DCD files must be in the same folder, though this does
      not have to be the same folder as where the program is stored.

ACC:  Copy DB_CONV.PRG to the root directory of the disk you normally boot
      from. Rename it to DB_CONV.ACC. Also, copy DB_CONV.RSC to the root
      of the boot disk.


Terminology
-----------

For the beginner, perhaps it would be best to describe the terms used by
this program.

A database file is composed of "records". A record corresponds to one card
in CardFile, or one address book entry in Desk Cart. When a database file
is stored on disk, each record is often delimited by a unique series of
characters, the "record separator".

Within each record are the fields which contain the data items. Examples
are "First Name" and "Home Phone Number". Each field can be both preceded
with and followed by a unique series of characters (the "prefix" and
"suffix"). Yet another sequence, the "field separator" can appear in
between each field in the database.

A database file often also begins with a unique header, which is just a
series of bytes that contain information specific to the program which
uses the database file.

Here is a segment of a sample CardFile 4 DAT file. "CR LF" is an
abbreviation for the two characters "carriage return" and "linefeed":

Header:   CardFile V4.00 Data File
          <CR LF>
          Sorted by field 05
          <CR LF>
Record 1: "15/06/1992 12:31:48","GRIBNIF","Rick","","Flashman","President",
          "Gribnif Software","P.O. Box 779","Northampton","MA","01061",
          "(413) 247-5620","(413) 247-5622","(413) 247-5622","GRIBNIF","","","",
          "","","","","","","",
End:      <CR LF>
Record 2: "17/06/1992 12:10:42","WORK","John","E","Stevenson",
          "Marketing Manager","Amazing Marketing, Inc.",
          "241 Queen Drive, Suite #7","Townville","Mass","01060",
          "(413) 555-2354","(413) 555-9234","(413) 555-1234",
          "(413) 555-1355","Last contacted on 5/15/92, should call",
          "back in two weeks to see if the ","rates have been worked out.",
          "","Check about the contract he was supposed",
          "to finish, and its current status.","","","",""
End:      <CR LF>

Note that if you were to load a CardFile 4 DAT file into a text editor, it
would not look exactly like this. The lines here have been wrapped around
for clarity.

In this case, the following values are used:

  Field Prefix:       "
  Field Suffix:       "
  Field Separator:    ,
  Record Separator:   <CR LF>


The Main Dialog
---------------

When the Database Converter first opens, you are presented with a dialog
which contains several areas. The long column on the left is where the
source database file is described. The column on the right describes the
destination database file.

Each database description can have a unique name asociated with it. You
should edit this so that it will serve as a reminder as to what file type
the description defines.

Underneath the description name is the grey area where the fields of the
database are listed. If you have not loaded any files or have not set the
number of fields (see below) there will be no fields displayed. To see
what the field list looks like, you should click on the "Load" button,
which is underneath the "Format..." button, and load-in one of the Database
Converter Description (.DCD) files that came with this program.

The "Number of Fields" can be changed by clicking on the button with this
name. After you have entered a new number, press Return to revert to the
normal editing mode.

Once there are some fields, you will notice that each field has a description
(like "Name", "Home Phone", etc.) and a length assigned to it. The length
is very important, as it defines how many characters are read by the
converter as part of each field. If a field's name begins with an asterisk
("*") then its contents are "skipped". This means that "length" bytes are
read, and no checks are done for a field prefix, suffix, or separator. It
is assumed, in this case, that the prefix of the next field immediately
follows the skipped bytes, like so:

  "Previous Field",xxxxxxxxxxxxxxxxxxxxxxxxxx"Next field","Last Field"
                   <--- 25 bytes skipped --->

In the Destination column, you will notice that the first column says
"Source Field #". This column specifies which source field contains the
data to use when each field in the destination is written.

You will now be able to use the up/down scroll boxes (if there are enough
fields for this to be necessary), and you will also have access to the
manipulation functions, Copy, Insert, and Delete.

Which mode is in use is affected by the row of radio buttons underneath
the field list. In Copy mode, clicking on the grey area to the right or
left of a field allows you to drag a field description to another
location. Dragging a field from the Source column to the Destination
column creates a "link" which tells the converter which field to use when
writing the destination file.

Insert mode will move all of the field descriptions down by one line from
the location where you click with the mouse, and insert a blank field. Note
that this deletes the last field description from the list!  Be careful
when using this function, because if you affect the Source fields list,
the list of "Source Field #'s" in the Destination column is not updated.

Delete mode does just the opposite:  it deletes the field you select and
moves all of the following fields up by one. Here, again, the list of
"Source Field #'s" is not updated.


The Format Dialog
-----------------

For both the source and destination database descriptions, there is
another option which allows you to define the more general configuration
of the database file. This is accessed by selecting either of the
"Format..." buttons in the main dialog.

This dialog displays the header for the database file and also the
separators, prefix, and suffix. Any of these fields can be edited, in
either decimal or ASCII notation by clicking with the mouse. When in
editing mode, pressing Return will return you to the default mode.

In ASCII mode, any of the Control key combinations on the keyboard can be
used to generate characters. Note that a carriage return (CR, ASCII 13)
appears as the two letters C and R, whereas a linefeed (LF, ASCII 10)
character appears as a bell. Carriage return can be generated by pressing
Control-M and linefeed can be generated with Control-Return or Control-J.

CAUTION! Care should be taken when editing the ASCII representation of a
field. If an entry contains ASCII character 0 (a NUL), it is displayed as
a "digital zero" in the ASCII representation. This allows you to enter a
NUL character when editing ASCII (by pressing control-P) and also allows
you to "see" the NUL character (which is normally not printable). This has
the unfortunate side-effect that if you actually enter "016" into one of
the decimal fields and then edit it as ASCII, the DECIMAL VALUE WILL
CHANGE to 000! In summary, be careful when editing as ASCII any string that
includes a decimal "016".

In the Header section is a button called "From File", which lets you take
the header information from the beginning of an actual database file. This
function simply reads the first 54 characters. You will have to edit the
header data so that only the header portion remains in the display. If any
of the actual fields of the database file are included as part of the
header definition, conversion will not work correctly.

The Padding Character option affects fields which are filled with a
particular character to their maximum length. The most common padding
characters are a space (ASCII 32) and a NUL (ASCII 0). Left justification
means that the padding characters appear after the actual data; right
justification places them before the data. For example, here are two 25
character fields which are space-padded:

        "Left Justified           " 
        "          Right Justified"

Another option, "Chop", is intended primarily for databases which have
fixed record lengths, but for which the data can end before the length of
the field. Partner ST files do this; the data elements each end with an
ASCII NUL character, and what follows the NUL needs to be thrown out:

        | Data | NUL | garbage bytes | Data2 | NUL | garbage2...

In this case, the Chop option should be selected, and the Padding Char
should be set to "000". A field separator of "000" is also used, to ensure
that a field which contains exactly the right number of characters (and no
garbage) is processed correctly.

The Extension entry in this dialog is simply the filename extension to be
used by the item selector when prompting for the names of files to convert.
For example, this is ".DAT" for CardFile 4.

When creating a new database definition, deciding what characters to enter
as suffix, prefix, separators, and padding can be a bit tricky. It is not
necessary to enter anything into all of these fields in all circumstances.

Perhaps the best thing to do is to look at the sample DCD files (use the
"Load" option under either "Format" button in the main dialog) included
with this program; these represent the basic types of database file. The
format for Partner ST is a binary format with C-style (NUL-terminated)
strings of fixed length. The format for DeskCart is very simple; each
space-padded field is simply entered on its own line. Tracker ST format is
just like DeskCart, but does not have the padding. CardFile's format is
described in the beginning section of this manual.


Other Main Options
------------------

Back in the main dialog, there are a few more options to describe:

"Load Link" and "Save Link" allow you to create and load another type of
description, the Database Converter Link (.DCL) file. This file contains a
list of the Source Field Numbers (contained in the Destination fields
list). It also knows the names of the associated .DCD files for the source
and destination field descriptions and loads them automatically whenever
you load a .DCL file. You should always make sure that a .DCL file is
saved in the same disk directory as the .DCD files that it references,
otherwise the .DCL file will not load properly.

If the "Log Errors" option is selected, then any errors which occur during
the actual conversion process are written to a file called DB_CONV.LOG,
in the same directory where DB_CONV.PRG resides. This file is always
appended to, so you can convert several files and maintain a list of all
the errors encountered.

The other button (at last!) is "Convert", which actually begins the
conversion process. After the names of the source and destination files
have been provided, a window will appear. This displays the status of the
conversion and any errors which occur.


Helpful Hints
-------------

When the source file to be converted is a CardFile 4 file:
  o You may get a warning alert which says that the header is not correct.
    This happens because the number of the field on which the CardFile
    cards are sorted is stored in the file header and it can vary from file
    to file. This warning can be ignored.
When the destination file is a CardFile 4 file:
  o Unless the source is also a CardFile 4 file, you will not be able to
    specify the modification date for the cards (field #1).


Dan Wilga
Gribnif Software
