                       FIXED FIELD TO
                           GEDCOM
                     CONVERSION UTILITY
                          June 1993

DESIGN OBJECTIVES

Many have requested the ability to convert data from a data base file into
acceptable GEDCOM data structures so that the data could loaded into one of
the GEDCOM compatible genealogy programs.

This utility was developed so that the user could use a grammar pattern file
to describe the fixed field (field delimited) input file, as well as defining
the appropriate GEDCOM structure in which the specified fixed fields are to be
mapped.

NOTE:
As of now this program will not provide the linkage.  Producing lineage-linked
GEDCOM has not yet been attempted because the conventions are so variable on
how the linkage is maintained in a database system.  If pointers are
maintained between family roles and individuals and vice versa by the database
system, then it would be quite easy to adopt this program in a way as to
produce the lineage-linked form. 

OVERVIEW

The Fixed Field to GEDCOM Conversion Utility uses the GEDCOM processor and a
GEDCOM grammar pattern file to convert the field delimited file into a GEDCOM
output.  The fields in the field delimited input file are usually variable
length, separated by a field delimiter, but they can fixed length as specified
by the GEDCOM grammar pattern file.

The GEDCOM Processor reads in the input fixed file and parses the record into
fields as specified by the define record structure from the GEDCOM grammar
file.  The GEDCOM portion of the grammar file is traversed to determine the
mapping from the fixed field input file to the desired GEDCOM output
structure.  Function call directives are placed within the GEDCOM grammar file
to initiate this mapping.  The GEDCOM processor will call these functions to
retrieve the fixed field values and then places them in the GEDCOM output
structures.  The output structure is written when all of the nodes in the
GEDCOM pattern file have been visited and populated with the fields from the
input file.

The following are the required GEDCOM grammar directives which can be invoked
from the GEDCOM pattern grammar file and a brief description of what they do:
Directive:  define_record
   Defines the record in terms of what the field delimited or fixed field
   input file looks like in terms of subordinate define_field directives,
   defines the input file name, and defines the field and record
   delimiters.
   Parameters:
        The record identifier, a single letter from A - Z.
        The input file name including any optional path.
        The field delimiter character where applicable.
        The record delimiter character where applicable.
        The tag name of the node within the GEDCOM pattern file in which
        the output GEDCOM begins its write.
        The level number with which to begin numbering the output level of
        this node. (see sample grammar)



Directive:  define_field
   Defines the fields in terms of the field length, fill character, left or
   right justification, and the field default value.
   Parameters:
        field number.
        field length.
        Left or right justification.
        fill character.
        field default value.

Directive:  field_to_ged
   This directive is context senstive and retrieves the field value from
   the specified fixed field input and stores the value in the
   corresponding GEDCOM context.  The xref parameter indicates that this
   field value is a GEDCOM cross reference identifier rather than a line
   value.
   Parameters:
        record identifier.
        field number.
        xref indicator.
        concatnation of fields.
        separation character between concatenated fields.
        name formatting to put slashes "/" around surname parts.
        date formatting to convert numeric month to alpha month.

USAGE:
This utility is to create a GEDCOM structure for each single fixed or field
delimited record.

NOTE:
   Lineage linked records are not currently created.  A version which will
   produce lineage-linked GEDCOM is being considered.  It will probably
   require two input files, one being a file of individuals each with a
   unique cross-reference identifier, and the second file being an index
   file of family records grouped by family number.  The index file would
   contain a family_number, a role tag (FATH, MOTH, CHIL), and a pointer to
   their individual record.

A detailed description of the directives used in this utility are attached:
                        ERROR CODES
                    FIXED FIELD To GEDCOM
                     Conversion Utility

Memory Errors:

   Error #        Error definition
   1         Memory error, unusual error, may be bad grammar file or bad
             GEDCOM data file.

   2         Memory error, not enough memory to create space pool.

   3         Memory error, ran out of space in pool, couldn't get any
             more.


Input/Output Errors:

   Error #        Error definition
   100-199   Any errors in this range are due to input/output errors
             reading or writing a file.



GEDCOM Format Errors:

   Error #        Error definition
   201       Invalid character found prior to the level number.
   202       The cross reference value exceeded maximum length.
   203       Characters in the tag are limited to ascii characters from
             32 to 127/
   204       Tag length exceeded maximum length.
   205       Found an opening @ in the cross reference but found a space
             before finding the closing @.
   206       Invalid character was found prior to the level number.

GRAMMAR Format Errors:
define_record _______________________________________________________________

Directive
define_record(Parameter List);

Description
The define_record function is called through grammar function directives as
initiated by the GEDCOM processor.  This function Assumes that a global record
structure was defined. The structure points to a linked list of field
structures assigned to this record type.  The global structure allocates 26 of
these record structures.

Parameter List
The parameter list includes the following keywords set to their default value:
      TYPE=a;           record identifier.
      FILE=stdout;      output file name.
      FDLIM=",";        field delimiter.
      RDLIM=CRLF        record delimiter, CR is used for carriage return, CRLF
                        is used for line feed.
      NODE=INDI         Name of the node in the '0 OUTPUT' GEDCOM tree where
                        writing is to begin (see field_to_ged directive).
      LEVEL=0           The level number with which to begin leveling the
                        output starting at the output NODE.

See Also
define_field, field_to_ged

Example
The placement of the define_record directive within a grammar pattern file is
subordinate to a level 0 DEFINITION GEDCOM line.  The DEFINITION line should
be the first record in the grammar file.

0 DEFINITION
1 define_record TYPE=a; FILE=c:\subdir\filename.ext; FDLIM=","; RDLIM=CRLF; 
  NODE=INDI; LEVEL=0
2 define_field  Field=1; (rest of parameter list)
1 define_record TYPE=b; File=a:filename.ext; FDLIM=",";RDLIM=CRLF
2 define_field Field= 1; (rest of parameter list)

CONSTRAINTS
*  The 0 DEFINITION record must be the first record in the grammar pattern
   file.
*  The parameters must be separated by a semicolon sign(;).
*  The keyword is placed on the left and is separated from the value by an
   equal sign (=).
*  Keywords can be upper or lowercase, and should be present however program
   will default to programmed assumptions.
*  Field delimiter values other than CR or CRLF should be a single character.
*  All parameter values must account for leading and trailing spaces by
   enclosing the total field value inside double quotes, for example
   DEFAULT=" | ".
*  Field delimiters are applied only when the field is variable length, as
   indicated LENGTH=0.
*  There should be a separate record definition to match any record type
   specified by a HDNG parameter. define_field ________________________________________________________________

Directive
define_field(Parameter List);

Description
The define_field directive defines the characteristics of a field within the
output record structure.  These characteristics are length of the field, the
justification of the field, the fill character to be used in fixed length
fields, and the default value assigned when the field is not present in the
input GEDCOM record.

Parameter List
The parameter list includes the following keywords set to their default value:

   FIELD=1;             Field number being defined.
   LENGTH=0;            Field length. LENGTH=0 indicates variable length.
   JUSTIFY=L;           Justify the field either Left or Right within the
                        specified field length.
   FILL=" ";            Fill character used to fill the fixed length field
                        before justification of the field value.
   DEFAULT="";          Specifies the value of the field if no data is found
                        in the GEDCOM input file for this field. A special
                        designator "\n" (back slash n) which causes a CRLF
                        (carriage return + line feed) to be automatically
                        established will applying the editing parameters to
                        the default value.

See Also
define_record, init_record_type, put_record, put_field, put_xref

Example
This shows the placement of the define_field directive within the grammar
pattern file.  Note the fields that belong to a record are specified by
define_field directives which are at a subordinate level to the appropriate
define_record directive. 

0 DEFINITION
1 define_record TYPE=a; RDLIM=CRLF; LINES=58; HDNG=b
2 define_field  FIELD=1; LENGTH=5; FILL=" "; JUSTIFY=R; DEFAULT="_____"
2 define_field  FIELD=33; LENGTH=3; FILL=" "; JUSTIFY=R; DEFAULT=" | "
2 define_field  FIELD=2; LENGTH=35; FILL=" "; JUSTIFY=L
1 define_record TYPE=b
2 define_field  FIELD=9; LENGTH=35; JUSTIFY=R; FILL=" "; DEFAULT="HEADING\n"
2 define_field  FIELD=1; LENGTH=7; FILL="_"; DEFAULT="COL. 1 "
2 define_field  FIELD=2; LENGTH=20; FILL=" "; JUSTIFY=R; DEFAULT="COLUMN 2\n"
 
CONSTRAINTS
*  The 0 DEFINITION record must be present.
*  Must be subordinate to a define_record directive and is used to define
   each field in that output record format.
*  The parameters must be separated by a semicolon sign(;).
*  The keyword is placed on the left and is separated from the value by an
   equal sign (=).field_to_ged ________________________________________________________________

Summary
#include <gedcom.h>
#include <gedslct.h>
int field_to_ged(Parameter List);

Description

The field_to_ged directive assigns the specified input field to a GEDCOM field
value.  This field is not actually saved into the output GEDCOM structure
until all fields of the input record has been processed, then the GEDCOM
structure is written and another fixed or delimited field record is read.

Parameter List

The parameter list includes the following keywords set to their default value:

   TYPE=a;        Record identifier.
   FIELD=1;       Assigned field number.
   XREF=1;        Indicates that the assigned field is a cross-reference
                  identifier and not a line value.
   CONC="4,6,8"   Concatenates the value in field 6 to the end of the value in
                  field 4, then it concatenates the value in field 8 to the
                  end of the previous results of 6 to 4. (see SEP=)
   SEP=" "        Causes a space to be inserted between each of the
                  concatenated parts, it also provides the delimeter in
                  defining name or date editing parts.  The separation
                  character can also be other than a space, "/", "-", "*",
                  etc.  If no SEP parameter is used then the parts are
                  concatenated together as they existed in the fields.
   NAME="R" or "L"
                  This indicates that the resulting name field is to be
                  arranged with slashes around the "/" surname piece.  The "R"
                  indicates that the name should be reversed, that is the
                  surname appears as the first name piece.  The "L" indicates
                  that the surname is the last of the name pieces. See samples
                  in using this in connection with the CONC parameter.

   DATE="xyz"     This allows numeric date fields to be formatted in the dd
                  MON YYYY format.  the x represents the day, the y the month,
                  and the z the year position. The resultant date field is
                  parsed into date parts using the SEP character.  Then the x
                  value indicates which of the three parts is the day.  The y
                  character indicates which of the three parts is the month.
                  The z character indicates which of the three parts is the
                  year.  The entry for this parameter should look like this: ;
                  DATE="213" which indicates that the day is the second part,
                  the month is the first part, and the year is the third part
                  of the parsed date.  This date routine is meant only for
                  numeric months which is then converted to a 3 char alpha
                  month and the resulting date would look like, for example,
                  13 AUG 1993. 

See Also

define_record, define_field
Example:
The grammar pattern file below shows a typical placement of the field_to_ged
directives.  The value from the input fields will be assigned to the line
value of the corresponding GEDCOM structure when this directive is encountered
by the GEDCOM processor.

0 DEFINITION
1  define_record TYPE=a; FILE=c:\subdir\filename.ext; FDLIM=","; RDLIM=CRLF;
   NODE=INDI; LEVEL=0
2 define_field FIELD=1; LENGTH=0  /* unique no. assigned as the xref-id */
2 define_field FIELD=2; LENGTH=0  /* Allen, Jed R. */
2 define_field FIELD=3; LENGTH=0  /* 1993 */
2 define_field FIELD=4; LENGTH=0  /* Cove, Cache, Utah */
2 define_field FIELD=5; LENGTH=0  /* not used in GEDCOM output */
2 define_field FIELD=6; LENGTH=0  /* 8 month */
2 define_field FIELD=7; LENGTH=0  /* 13 day */
0 HEAD
(copies header structure )
0 SUBM
(copies submitter structure)
0 OUTPUT
1 INDI
2 - field_to_ged TYPE=a; xref=1
2 NAME
3 - field_to_ged TYPE=a; FIELD=2; NAME="R"; SEP=","
2 BIRT
3 DATE
4 - field_to_ged TYPE=a; CONC="7,6,3"; SEP=","; DATE="1,2,3"
3 PLAC
4 - field_to_ged TYPE=a; FIELD=4

CONSTRAINTS
*  Lineage-linked GEDCOM is not produced. The individuals father and mother
   data can be stored under the respective FATH MOTH tags subordinate to the
   INDIvidual.
*  DATE edit is used only for numeric months and no more than three date
   parts are handled.

SAMPLE:
The following is sample data in the fixed form as defined using the
define_record structure above and the resulting gedcom output using the GEDCOM
structure shown under the 0 OUTPUT GEDCOM structure.  Note the NODE and the
LEVEL parameters on the define_record structure above indicates the begining
NODE under the OUTPUT structure and what LEVEL to assign to that NODE.

FIXED DATA:
1|Allen, Jed R.|1937|Cove, Cache, Utah||2|10
2|Hyer, Nancy|1940|Lewiston, Cache, UTAH||20|3

GEDCOM OUTPUT:
0 HEAD
  (copies structure)
0 @1@ INDI
1 NAME Jed R. /ALLEN/
1 BIRT
2 DATE 2 OCT 1937
2 PLAC Cove, Cache, Utah
0 @2@ INDI
1 NAME Nancy /HYER/
1 BIRT
2 DATE 20 MAR 1940
2 PLAC Lewiston, Cache, Utah