                                 GEDCOM TO
                                FIXED FIELD
                            CONVERSION UTILITY
                               October 1993

DESIGN OBJECTIVES

Many have requested the ability to convert the GEDCOM data structures into a
fixed-format record structure so that the data could loaded into general
purpose data base programs.

This utility was developed so that the user could use a grammar pattern file
to indicate what GEDCOM fields they would like to extract and to specify the
output field that the extracted field should be placed in.

OVERVIEW

The GEDCOM To Fixed Field Conversion Utility uses the GEDCOM processor and a
GEDCOM grammar pattern file to convert GEDCOM into a flat file output.  The
fields in the output file can either be fixed length or delimited variable
length.

The GEDCOM Processor traverses the GEDCOM input file in parallel fashion with
matching structures in the GEDCOM grammar file.  Function call directives are
placed within the GEDCOM grammar file.  The GEDCOM processor will call these
functions as the GEDCOM input structures are matched to the GEDCOM grammar
pattern structures.  These directives are prefixed with either a '+' tag or a
'-' tag.  The '-' tag tells the GEDCOM processor to execute the directive
before processing any of the subordinate GEDCOM levels.  The '+' tag tells the
GEDCOM processor to execute the directives after all of the subordinate levels
have been processed.

The GEDCOM grammar pattern file is populated with all of the tags that are to
be extracted from the GEDCOM data file, showing the proper context as they
would appear in the input GEDCOM data.  A special procedure for handling
multiple occurrences of the same tag must be considered, such as the NOTE
structure. (See put_multi_field and reset_multi_fld_grp directives.

New GEDCOM Processor directives were written to:
          Define up to 26 different output record formats. 
          Define characteristics of each of the fields contained within each
           record.
          Initialize each field in the output record with default values.
          Select GEDCOM input data and assign them to a field within an
           output record format as the tag structures from the input GEDCOM
           file match the GEDCOM grammar pattern file.
          Separate selected fields into sub-fields and assign each sub-field
           to its own ordered field number.
          Separate selected fields into sub-fields and reverse their order.
          Write a record to the specified output 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 file is the record to be written to
      and the field and record delimiters.
      Parameters:
           The output record identifier, a single letter from A - Z.
           The output file name and optional path.
           The field delimiter character where applicable.
           The record delimiter character where applicable.

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:  init_record
      This directive sets the field values to the field defaults.
      Parameters:
           record identifier to initialize.

Directive: order_field
      This directive is always used following either a put_field or put_xref
      directive.  When invoked the directive will either separate a specified
      field into sub-fields and assign each sub-field to a defined field
      number or it will separate the specified field into sub-fields and
      reverse the order that each appear in the specified field.
      Parameters:
           record identifier.
           field number to be separated in to sub-fields.
           order parameter which specifies the sub-field assignments.
           order parameter which reverses the sub-field order.
           delimiter character on which the specified field is parsed.
           date to numeric switch to convert 3 alpha to 2 numeric month.

Directive:  put_field
      This directive is context sensitive and stores the value of the matching
      input context in the output field within the specified record type.
      Parameters:
           record identifier.
           field number.
           concatenate field to end of specified field.
           store field in to temporary field.
           fetch field from temporary field and assign to field.
           temporary record identifier for storing temporary fields.

Directive:  put_multi_field
      This directive is context sensitive and stores the values of all
      matching input contexts into the fixed output fields, as specified by
      the field sub-parameter, as they are encountered in the input GEDCOM
      data structure by the gedcom processor.
      Parameters:
           record identifier.
           field number.

Directive: put_xref
      This directive is similar in function to the put_field directive but
      differs in that the parameter allows for the cross reference value, the
      GEDCOM tag, and the GEDCOM context value each to be assigned to a
      specified field within the specified record.  If the field number for
      any of these items is set to 0, then that field is not extracted.
      Parameters:
           record identifier.
           cross reference field assignment parameter.
           GEDCOM tag field assignment parameter.
           pointer (value) field assignment parameter.

Directive:  reset_multi_fld_grp
      This directive is used to reset the multiple tag group pointer back to
      zero.  This must be used at a higher level such as after all of the
      children of the multiple tag's parent.  For example, if you are
      accounting for the NOTE structure subordinate to the BIRTh tag then you
      would use this directive at the next subordinate level to BIRT.
      Parameters:
           multiple tag group identifier (from 1 to 5).
      
USAGE:
Typically this utility is to create a single record containing each of the
selected fields; however, you can produce some creative listing grammars by
properly placing the init_record_type and put_record directives within the
grammar context.

Using the put_xref directive you can assign the cross reference value, the
tag, and the pointer or value, from a GEDCOM line to the desired fields in the
output record. 

As an example, this utility can be used to create load files for a relational
database.  Extracting the GEDCOM pointers and cross-references along with the
desired data from the Individual records allows these files to be loaded into
a database which will preserve the family linkage.

See the documentation for put_xref directive for examples of how the put_xref
was used in producing two related files which was loaded into a database
application.

A detailed description of the directives used in this utility are attached:ERROR CODES
                           GEDCOM TO FIXED FIELD
                            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.

      303        Found a directive syntax in the grammar that is not
                 recognized by the program.
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 key words 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.
optional parameters for page control, used only when creating GEDCOM to
printed lists:
      LINES=0;         number of lines on a page.
      HDNG=a;          column headings are provided by the default values of
                       a different defined record structure.
See Also
define_field, init_record_type, put_record, put_field, put_xref

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
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 key word is placed on the left and is separated from the value by an
   equal sign (=).
  Key words 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 key words 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 key word is placed on the left and is separated from the value by an
   equal sign (=).init_record ________________________________________________________________

Summary

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

Description

The init_record directive is to initialize the specified output record format
by setting each of its fields to the specified default values. 

Parameter List

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

   TYPE=a;       record identifier.

See Also

define_record, define_field, put_record, put_field, put_xref

Example

This shows a typical place with in the grammar pattern file that the
init_record directive can be placed.  The fields for the specified record
format will be initialized when this directive is encountered by the GEDCOM
processor.

0 DEFINITION
1 define_record TYPE=a; FILE=c:\subdir\filename.ext; FDLIM=","; RDLIM=CRLF
2 define_field  FIELD=1; LENGTH=8; FILL=" "; JUSTIFY=R; DEFAULT="_____"
0 HEAD
1 - init_record TYPE=a
1 + put_record TYPE=a
1 DATE
2 - put_field FIELD=1

CONSTRAINTS

  The parameters must be separated by a semicolon sign(;).
  The key word is placed on the left and is separated from the value by an
   equal sign (=).
  Key words can be upper or lowercase, and should be present however program
   will default to programmed assumptions.
order_field ________________________________________________________________
Summary

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

Description

The order_field directive separates the specified field into sub-fields based
on a character specified by the parse parameter.  Each sub-field of the input
GEDCOM field is assigned to the specified field within a specific output
record.  The sub-field value is not actually copied into the output record
until a put_record directive is encountered.

Parameter List

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

   TYPE=a;             record identifier.
   FIELD=1;            assigned field number.
   ORDER=REVERSE;      reverses the sub-fields of the assigned field number
or
   ORDER=4,5,6         assigns 1st sub-field to field number 4, second to 5,
                       third to field 6, etc. assumes no more than 9 sub-
                       fields in any one field. Default is to REVERSE.
   PARSE=","           specifies the character which delimits the sub-fields.
   DATE=NUMERIC        this parameter is a switch that converts the first
                       sub-field within the specified field that matches the
                       3 byte alpha month to a 2 byte numeric month.    

See Also

define_record, define_field, init_record, put_field, put_record, put_xref

Example

The grammar pattern file below shows a typical placement of the order_field
directives.  The field from the FIELD parameter will be separated into sub-
fields based on the delimiting character specified by the PARSE parameter.  If
the ORDER parameter specifies REVERSE then this field will be separated into
sub-fields, their order exactly reversed, and then restored in to the
specified field.  If the ORDER parameter specifies field assignment numbers,
such as ORDER=4,5,6; then the sub-fields in left to right order will be
assigned to fields 4, 5, and 6 respectively.  One of the sub-fields can be
reassigned to the original field number to avoid redundant data.

In the example below, the name field was separated into sub-fields based on
the slash character, the surname was assigned to field 3 and the remaining
name was restored in field 1.  The birth place field was reversed in its order
based on the ',' delimiter.  This allows the highest locality jurisdiction to
appear first.  The REVERSE key replaces the original field with the reversed
sub-fields.

The order_field directive retrieves the original field from the data already
assigned to the specified field number, not from the current GEDCOM input
stream, that is why it follows the put_field directive.

The DATE parameter used in the example below will cause the directive to look
at each of the sub-fields in the assigned field and to change the first sub-
field that matches one of the 3 character month abbreviations to the
corresponding 2 byte numeric equivalent.  If the ORDER=REVERSE is used and the
DATE parameter is present then the field value in field 3 (in this example)
will be first changed to a numeric month and then reversed and the result will
remain in field 3.  If you define new fields to receive these sub-fields such
as ORDER=7,6,5 will cause the first sub-field to be placed into field 7, the
second into field 6 and the third into field 5.  In this example this also
reverses the date sub-field sequence, but it places each date piece into a
different field than specified for the original date field 3.  Since the date
parameter is present, the month value in field 6 is changed to a 2 digit
numeric month, which is convenient for ordering purposes.

0 DEFINITION
1 define_record TYPE=a; FILE=c:\subdir\filename.ext; FDLIM=","; RDLIM=CRLF
2 define_field FIELD=1; Length=18; fill=" " 
2 define_field FIELD=2; LENGTH=10; FILL=" "; JUSTIFY=L; DEFAULT="_____"
2 define_field FIELD=3; LENGTH=8; FILL=" "; JUSTIFY=R; DEFAULT="_____"
2 define_field FIELD=4; LENGTH=20; FILL=" "; JUSTIFY=L; DEFAULT=""
2 define_field FIELD=5; LENGTH=4: FILL="0"; JUSTIFY=R; DEFAULT="0000"
2 define_field FIELD=6; LENGTH=2: FILL="0"; JUSTIFY=R; DEFAULT="00"
2 define_field FIELD=7; LENGTH=2: FILL="0"; JUSTIFY=R; DEFAULT="00"
0 INDI
1 - init_record TYPE=a
1 + put_record TYPE=a
1 NAME
2 - put_field TYPE=a; FIELD=1
2 - order_field TYPE=a; FIELD=1; order=1,3; PARSE="/"
1 BIRT
2 DATE
3 + put_field TYPE=a; FIELD=3
3 + order_field TYPE=a; FIELD=3; order=7,6,5; parse=" "; DATE=numeric
2 PLAC
3 - put_field TYPE=a; FIELD=4
3 - order_field TYPE=a; FIELD=4; order=REVERSE; PARSE=","


CONSTRAINTS
  A put_record directive must be encountered to output any fields selected
   using the order_field directive.
  The order_field directive applies to a field already assigned to a field
   number, thus it usually follows either a put_field or put_xref directive.
  The parameters must be separated by a semicolon sign(;).
  The key-word is placed on the left and is separated from the value by an
   equal sign (=), and sub-fields range in number of 1-9.
  Key-words can be upper or lowercase, and should be present however program
   will default to programmed assumptions.
put_field ________________________________________________________________

Summary

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

Description

The put_field directive assigns the input GEDCOM field value to the specified
field within a specific output record.  This field is not actually copied into
the output record until a put_record directive is encountered.  This directive
also makes it possible to store data from one record type and retrieve it for
use in another record type.  For example, storing the batch number from a
header record and writing it as one of the fields for each individual record.

Parameter List

The parameter list includes the following key-words set to a typical value:

   TYPE=a;       record identifier.
   FIELD=1;      assigned field number.
   CONC=" ";     indicates that the data from the GEDCOM input is to be
                 concatenated to the end of the data that already resides in
                 the specified field.  The data in between the quotes is used
                 as the delimiter between the existing data and the new data
                 being concatenated.
   STORE=yes;    used when writing to a temporary storage for later recall. 
                 **Caution: using this parameter causes space to be allocated
                 from a space pool which does not get freed up until the end-
                 of-file is reached on the input.  If temporary storage is
                 needed for only the life of the record (level 0) then define
                 a separate fixed record but do not use the STORE parameter
                 in storing the field with put_field.
   TTYPE=b;      the record identifier used to define temporary storage.
   FETCH=1;      used to retrieve field n from temporary storage to use as
                 the value to be placed in FIELD n of record TYPE n.

See Also

define_record, define_field, init_record, put_record, put_xref

Example

The grammar pattern file below shows a typical placement of the put_field
directives.  The value from the matching GEDCOM input structure will be
assigned to the specified field within the specified record format  when this
directive is encountered by the GEDCOM processor.

0 DEFINITION
1 define_record TYPE=a; FILE=c:\subdir\filename.ext; FDLIM=","; RDLIM=CRLF
2 define_field FIELD=1; Length=18; fill=" " 
2 define_field FIELD=2; LENGTH=8; FILL=" "; JUSTIFY=R; DEFAULT="_____"
2 define_field FIELD=3; length=11; JUSTIFY=R
2 define_field FIELD=4; length=0
1 define_record TYPE=b
2 define_field FIELD=1; length=0
0 HEAD
1 - init_record TYPE=b
1 DATE
2 - put_field type=b; field=1; store=yes
0 INDI
1 - init_record TYPE=a
1 - put_field type=a; field=3; ttype=b; fetch=1
1 + put_record TYPE=a
1 NAME
2 - put_field TYPE=a; FIELD=1
1 BIRT
2 DATE
3 - put_field TYPE=a; FIELD=2
1 NOTE
2 - put_field type=A; field=4; conc="! "
2 CONT
3 - put_field type=A; field=4; conc="! "

CONSTRAINTS
  A put_record directive must be encountered to output any fields selected
   using the put_field directive.
  The parameters must be separated by a semicolon sign(;).
  The key word is placed on the left and is separated from the value by an
   equal sign (=).
  Key words can be upper or lowercase, and should be present however program
   will default to programmed assumptions.
put_multi_field_______________________________________________________________
_
Summary

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

Description

The put_multi_field directive is required when the same tag occurs multiple
times at the same level.  This occurs often with the note structure. The
GEDCOM processor processes the input GEDCOM tree structure from top to bottom,
processing all of it children before moving to the next lower sibling.  When
it finds a value in the GEDCOM data tree, it matches the GEDCOM grammar tree
for matching paths.  When the processor finds a matching path it calls the
directive contained in the matching grammar path.  This is why the put_field
directive would store only the value from the last occurrence of the tag. 
Therefore multiple tags are handled by a global field pointer which is
incremented each time a multiple field path is encountered.  Since more than
one set of multiple occurring tags can happen within a structure, one must
keep each of these contexts separate by assigning a group number between 1 and
5.  Each of these group pointers are managed by resetting the next field
pointer back to one using a properly placed directive called
reset_multi_fld_grp. (See directive specifications for reset_multi_fld_grp).

The number of occurrences processed by this directive is controlled by two
things. The first is the use of the reset_multi_fld_grp directive which as
explained above resets the field pointer count back to the first field in the
set specified by the field parameter.  The second is that each of the fields
specified in the fields parameter are filled in order as each occurrence of
the multiple tag value is encountered.  (Warning) When the fields are all
filled, then any further occurrence of that field is ignored.  If the
reset_multi_fld_grp directive is not used to reset the field pointer, then
only the multiple occurring fields will be processed from the record in which
they first appear. 


Parameter List

The parameter list includes the following key words set to typical values:

   TYPE=a;             record identifier.
   FIELD=1,2,3,4;      a set of assigned field number(s).
   GROUP=1;            identifies the group used to manage the multiple
                       occurring tags (must be from 1 to 5).

See Also

reset_multi_fld_grp

Example

The grammar pattern file below shows a typical placement of the
put_multi_field directives and shows how at least two different groups of
multiple occurring fields are managed.  The fields from the FIELD parameter
will filled in order of encountering the data with in the GEDCOM data tree.  

In the example below, the NOTE structure that occurs subordinate to the BIRT
tag is arbitrarily assigned to group 2 and the NOTE structure that is
subordinate to the INDI tag is assigned to group 1.  The reset_multi_fld_grp
is placed subordinate to the BIRT tag using the (+) tag to indicate that the
field pointer for group 2 should be reset after processing all of BIRT's
children.  Then both group 1 and 2 field pointers are reset after all of
INDI's children are processed.

0 DEFINITION
1 define_record TYPE=a; FILE=c:\subdir\filename.ext; FDLIM="|"; RDLIM=CRLF
2 define_field FIELD=1; Length=0 
2 define_field FIELD=2; LENGTH=0
2 define_field FIELD=3; LENGTH=0
2 define_field FIELD=4; LENGTH=0
2 define_field FIELD=5; LENGTH=0
2 define_field FIELD=6; LENGTH=0
2 define_field FIELD=7; LENGTH=0
2 define_field FIELD=8; LENGTH=0
2 define_field FIELD=9; LENGTH=0
0 INDI
1 - init_record TYPE=a
1 + put_record TYPE=a
1 + reset_multi_fld_grp group=1
1 + reset_multi_fld_grp group=2
1 NAME
2 - put_field TYPE=a; FIELD=1
1 BIRT
2 + reset_multi_fld_grp group=2
2 DATE
3 + put_field TYPE=a; FIELD=2
2 PLAC
3 - put_field TYPE=a; FIELD=3
2 NOTE
3 - put_multi_field Type=a; group=2; field=6,7,8,9
3 CONT
4 - put_multi_field Type=a; group=2; field=6,7,8,9
1 NOTE
2 - put_multi_field Type=a; group=1; field=4,5,6
2 CONT
3 - put_multi_field Type=a; group=1; field=4,5,6

CONSTRAINTS
  A put_record directive must be encountered to output any fields selected
   using the order_field directive.
  The order_field directive applies to a field already assigned to a field
   number, thus it usually follows either a put_field or put_xref directive.
  The parameters must be separated by a semicolon sign(;).
  The key word is placed on the left and is separated from the value by an
   equal sign (=), and sub-fields range in number of 1-9.
  Key words can be upper or lowercase, and should be present however program
   will default to programmed assumptions.
put_record ________________________________________________________________

Summary

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

Description

The put_record function is called through a grammar function directive as
initiated by the GEDCOM processor.

This function writes out each field in the order that they were defined within
the define record structure, not by field number order.

Parameter List

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

   TYPE=a;       record identifier.

See Also

define_record, define_field, init_record, put_field, put_xref

Example

This shows the placement in the grammar pattern file of a put_record
directive.  It is place in this example with a tag value of '+' which tells
the processor to write the specified record after it gets done processing all
of the INDIvidual's subordinate levels.  All of the fields for the specified
record format will be written in the order that they were defined in the
DEFINITION structure of the grammar file.

0 DEFINITION
1 define_record TYPE=a; FILE=c:\subdir\filename.ext; FDLIM=","; RDLIM=CRLF
2 define_field  FIELD=1; LENGTH=28; FILL=" "
0 INDI
1 - init_record TYPE=a
1 + put_record TYPE=a
1 NAME
2 - put_field FIELD=1

CONSTRAINTS

  The put_record directive releases the memory required to store the
   selected field values.  Therefore; if the put_record directive is not
   placed in the grammar pattern file so that the processor will encounter
   it, the program will eventually run out of memory.
  The parameters must be separated by a semicolon sign(;).
  The key word is placed on the left and is separated from the value by an
   equal sign (=).
  Key words can be upper or lowercase, and should be present however program
   will default to programmed assumptions.
put_xref ________________________________________________________________

Summary

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

Description

The put_xref function is called through grammar function directives as
initiated by the GEDCOM processor.  This function is like the put_field
function in that it assigns the GEDCOM value to the specified field within the
specified record format.  However, this function is used so that in addition
to the GEDCOM value being assigned to a field within the record format, so can
the cross reference ID and the GEDCOM Tag.

Parameter List

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

   TYPE=a;       record identifier.
   XREF=0;       assigns the cross reference ID to a field number.
   TAG=0;        assigns the GEDCOM Tag to a field number.
   PTR=0;        assigns the value or pointer to a field number.
   (Any parameter assigned to field 0 is not assigned. This is so that any or
   all of these GEDCOM line parts may be saved.)

See Also

define_record, define_field, init_record, put_record, put_field

Example

The grammar pattern file below shows the placement of the put_xref directives. 
This placement shows how the pointer to family records can be used to
construct two different load files, one the individuals, and two the family
records showing the roles (Tags) each person played in that family, and the
pointers to the individual records.  These two outputs can then be loaded into
a relational database which through its relationships, display the members of
each of the families. 
0 DEFINITION 
1 define_record type=a; file=a:indi.flt; rdlim=crlf; fdlim=*
2 define_field field=1; length=8; fill=" ";justify=L; default="no indi xref"
2 define_field field=2; length=8; fill=" ";justify=L; default="no fams"
2 define_field field=3; length=8; fill=" ";justify=L; default="no famc"
2 define_field field=4; length=35; fill=" ";justify=L; default="no name"
2 define_field field=5; length=11; fill=" ";justify=R; default="no date"
2 define_field field=6; length=30; fill=" ";justify=L; default="no place"
1 define_record type=b; file=fam.flt; rdlim=crlf; fdlim=*
2 define_field field=1; length=8; fill=" ";justify=L; default="no fam xref"
2 define_field field=2; length=8; fill=" ";justify=L; default="no tag"
2 define_field field=3; length=8; fill=" ";justify=L; default="no pointer"
0 INDI
1 - init_record type=a
1 + put_record type=a
1 NAME
2 + put_xref type=a; xref=1; tag=0; ptr=4
1 BIRT
2 DATE
3 + put_field type=a; field=5
2 PLAC
3 + put_field type=a; field=6
1 FAMC
2 + put_xref type=a; xref=0; tag=0; ptr=3
1 FAMS
2 + put_xref type=a; xref=0; tag=0; ptr=2
0 FAM
1 - init_record type=b
1 HUSB
2 + put_xref type=b; xref=1; tag=2; ptr=3
2 + put_record type=b
1 WIFE
2 + put_xref type=b; xref=1; tag=2; ptr=3
2 + put_record type=b
1 CHIL
2 + put_xref type=b; xref=1; tag=2; ptr=3
2 + put_record type=b

CONSTRAINTS

  The put_xref directive only assigns the value from the GEDCOM structure,
   it is not saved until a put_record directive is encountered.
  Any parameters that is set to 0 will not assign that value. 
  The parameters must be separated by a semicolon sign(;).
  The key word is placed on the left and is separated from the value by an
   equal sign (=).
  Key words can be upper or lowercase, and should be present however program
   will default to programmed assumptions.
reset_multi_fld_grp___________________________________________________________

Summary

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

Description
This directive resets the current field pointer for the specified group. (See
put_multi_field).

The directive must be strategically placed so that the current field pointer
is reset to the beginning before processing a particular set of multiple tag
values.

Parameter List

The parameter list includes the following key words set to their typical
values:

   GROUP=1;      resets the field pointer for multiple tag groups back to the
                 beginning field.

See Also

put_multi_field

Example

See example used in put_multi_field.