Libgedcom interface details

Index

Record identifiers
Element identifiers
Gedcom_val types

struct date_value
struct date

Record identifiers

The following table describes the identifiers to be used in the record callbacks. The last column gives the Gedcom_val type of the xref argument in the header start callback.

Record	Meaning	Possible `xref` types
`REC_HEAD`	The header of the GEDCOM file	`NULL`
`REC_FAM`	A record describing a family	`STRING`
`REC_INDI`	A record describing an individual	`STRING`
`REC_OBJE`	A record describing a multimedia object	`STRING`
`REC_NOTE`	A record describing a note	`STRING`
`REC_REPO`	A record describing a source repository	`STRING`
`REC_SOUR`	A record describing a source	`STRING`
`REC_SUBN`	A record describing the submission	`STRING`
`REC_SUBM`	A record describing the submitter	`STRING`
`REC_USER`	An application-specific record (the `tag` in the start callback contains the actually used tag).	`NULL` `STRING`

Element identifiers

The following table describes the identifiers to be used in the element callbacks. The last column gives the


Gedcom_val

type of the val argument in the element start callback. (TO BE COMPLETED)

Element	Possible tags	Used within	Possible `val` types
`ELT_HEAD_SOUR`	`SOUR`	`REC_HEAD`	`STRING`
`ELT_HEAD_SOUR_VERS`	`VERS`	`ELT_HEAD_SOUR`	`STRING`
`ELT_HEAD_SOUR_NAME`	`NAME`	`ELT_HEAD_SOUR`	`STRING`
`ELT_HEAD_SOUR_CORP`	`CORP`	`ELT_HEAD_SOUR`	`STRING`
`ELT_HEAD_SOUR_DATA`	`DATA`	`ELT_HEAD_SOUR`	`STRING`
`ELT_HEAD_SOUR_DATA_DATE`	`DATE`	`ELT_HEAD_SOUR_DATA`	`DATE`
`ELT_HEAD_SOUR_DATA_COPR`	`COPR`	`ELT_HEAD_SOUR_DATA`	`STRING`
`ELT_HEAD_DEST`	`DEST`	`REC_HEAD`	`STRING`
`ELT_HEAD_DATE`	`DATE`	`REC_HEAD`	`DATE`
`ELT_HEAD_DATE_TIME`	`TIME`	`ELT_HEAD_DATE`	`STRING`
`ELT_HEAD_SUBM`	`SUBM`	`REC_HEAD`	`STRING`
`ELT_HEAD_SUBN`	`SUBN`	`REC_HEAD`	`STRING`
`ELT_HEAD_FILE`	`FILE`	`REC_HEAD`	`STRING`
`ELT_HEAD_COPR`	`COPR`	`REC_HEAD`	`STRING`
`ELT_HEAD_GEDC`	`GEDC`	`REC_HEAD`	`NULL`
`ELT_HEAD_GEDC_VERS`	`VERS`	`ELT_HEAD_GEDC`	`STRING`
`ELT_HEAD_GEDC_FORM`	`FORM`	`ELT_HEAD_GEDC`	`STRING`
`ELT_HEAD_CHAR`	`CHAR`	`REC_HEAD`	`STRING`
`ELT_HEAD_CHAR_VERS`	`VERS`	`ELT_HEAD_CHAR`	`STRING`
`ELT_HEAD_LANG`	`LANG`	`REC_HEAD`	`STRING`
`ELT_HEAD_PLAC`	`PLAC`	`REC_HEAD`	`NULL`
`ELT_HEAD_PLAC_FORM`	`FORM`	`ELT_HEAD_PLAC`	`STRING`
`ELT_HEAD_NOTE`	`NOTE`	`REC_HEAD`	`STRING`
`ELT_FAM_HUSB`	`HUSB`	`REC_FAM`	`STRING`
`ELT_FAM_WIFE`	`WIFE`	`REC_FAM`	`STRING`
`ELT_FAM_CHIL`	`CHIL`	`REC_FAM`	`STRING`
`ELT_FAM_NCHI`	`NCHI`	`REC_FAM`	`STRING`
`ELT_FAM_SUBM`	`SUBM`	`REC_FAM`	`STRING`
`ELT_INDI_RESN`	`RESN`	`REC_INDI`	`STRING`
`ELT_INDI_SEX`	`SEX`	`REC_INDI`	`STRING`
`ELT_INDI_SUBM`	`SUBM`	`REC_INDI`	`STRING`
`ELT_INDI_ALIA`	`ALIA`	`REC_INDI`	`STRING`
`ELT_INDI_ANCI`	`ANCI`		`STRING`
`ELT_INDI_DESI`	`DESI`		`STRING`
`ELT_INDI_RFN`	`RFN`		`STRING`
`ELT_INDI_AFN`	`AFN`		`STRING`
`ELT_OBJE_FORM`	`FORM`		`STRING`
`ELT_OBJE_TITL`	`TITL`		`STRING`
`ELT_OBJE_BLOB`	`BLOB`		`NULL`
`ELT_OBJE_BLOB_CONT`	`CONT`		`STRING`
`ELT_OBJE_OBJE`	`OBJE`		`STRING`
`ELT_REPO_NAME`	`NAME`		`STRING`
`ELT_SOUR_DATA`	`DATA`		`NULL`
`ELT_SOUR_DATA_EVEN`	`EVEN`		`STRING`
`ELT_SOUR_DATA_EVEN_DATE`	`DATE`		`DATE`
`ELT_SOUR_DATA_EVEN_PLAC`	`PLAC`		`STRING`
`ELT_SOUR_DATA_AGNC`	`AGNC`		`STRING`
`ELT_SOUR_AUTH`	`AUTH`		`STRING`
`ELT_SOUR_TITL`	`TITL`		`STRING`
`ELT_SOUR_ABBR`	`ABBR`		`STRING`
`ELT_SOUR_PUBL`	`PUBL`		`STRING`
`ELT_SOUR_TEXT`	`TEXT`		`STRING`
`ELT_SUBN_SUBM`	`SUBM`		`STRING`
`ELT_SUBN_FAMF`	`FAMF`		`STRING`
`ELT_SUBN_TEMP`	`TEMP`		`STRING`
`ELT_SUBN_ANCE`	`ANCE`		`STRING`
`ELT_SUBN_DESC`	`DESC`		`STRING`
`ELT_SUBN_ORDI`	`ORDI`		`STRING`
`ELT_SUBN_RIN`	`RIN`		`STRING`
`ELT_SUBM_NAME`	`NAME`		`STRING`
`ELT_SUBM_LANG`	`LANG`		`STRING`
`ELT_SUBM_RFN`	`RFN`		`STRING`
`ELT_SUBM_RIN`	`RIN`		`STRING`
`ELT_SUB_ADDR`	`ADDR`		`STRING`
`ELT_SUB_ADDR_CONT`	`CONT`		`STRING`
`ELT_SUB_ADDR_ADR1`	`ADR1`		`STRING`
`ELT_SUB_ADDR_ADR2`	`ADR2`		`STRING`
`ELT_SUB_ADDR_CITY`	`CITY`		`STRING`
`ELT_SUB_ADDR_STAE`	`STAE`		`STRING`
`ELT_SUB_ADDR_POST`	`POST`		`STRING`
`ELT_SUB_ADDR_CTRY`	`CTRY`		`STRING`
`ELT_SUB_PHON`	`PHON`		`STRING`
`ELT_SUB_ASSO`	`ASSO`		`STRING`
`ELT_SUB_ASSO_TYPE`	`TYPE`		`STRING`
`ELT_SUB_ASSO_RELA`	`RELA`		`STRING`
`ELT_SUB_CHAN`	`CHAN`		`NULL`
`ELT_SUB_CHAN_DATE`	`DATE`		`DATE`
`ELT_SUB_CHAN_TIME`	`TIME`		`STRING`
`ELT_SUB_FAMC`	`FAMC`		`STRING`
`ELT_SUB_FAMC_PEDI`	`PEDI`		`STRING`
`ELT_SUB_CONT`	`CONT`		`STRING`
`ELT_SUB_CONC`	`CONC`		`STRING`
`ELT_SUB_EVT_TYPE`	`TYPE`		`STRING`
`ELT_SUB_EVT_DATE`	`DATE`		`DATE`
`ELT_SUB_EVT_AGE`	`AGE`		`STRING`
`ELT_SUB_EVT_AGNC`	`AGNC`		`STRING`
`ELT_SUB_EVT_CAUS`	`CAUS`		`STRING`
`ELT_SUB_FAM_EVT`	`ANUL, CENS, DIV, DIVF, ENGA, MARR, MARB, MARC, MARL, MARS`		`NULL STRING`
`ELT_SUB_FAM_EVT_HUSB`	`HUSB`		`NULL`
`ELT_SUB_FAM_EVT_WIFE`	`WIFE`		`NULL`
`ELT_SUB_FAM_EVT_AGE`	`AGE`		`STRING`
`ELT_SUB_FAM_EVT_EVEN`	`EVEN`		`NULL`
`ELT_SUB_IDENT_REFN`	`REFN`		`STRING`
`ELT_SUB_IDENT_REFN_TYPE`	`TYPE`		`STRING`
`ELT_SUB_IDENT_RIN`	`RIN`		`STRING`
`ELT_SUB_INDIV_ATTR`	`CAST, DSCR, EDUC, IDNO, NATI, NCHR, NMR, OCCU, PROP, RELI, SSN, TITL`		`STRING`
`ELT_SUB_INDIV_RESI`	`RESI`		`NULL`
`ELT_SUB_INDIV_BIRT`	`BIRT, CHR`		`NULL STRING`
`ELT_SUB_INDIV_BIRT_FAMC`	`FAMC`		`STRING`
`ELT_SUB_INDIV_GEN`	`DEAT, BURI, CREM, BAPM, BARM, BASM, BLES, CHRA, CONF, FCOM, ORDN, NATU, EMIG, IMMI, CENS, PROB, WILL, GRAD, RETI`		`NULL STRING`
`ELT_SUB_INDIV_ADOP`	`ADOP`		`NULL STRING`
`ELT_SUB_INDIV_ADOP_FAMC`	`FAMC`		`STRING`
`ELT_SUB_INDIV_ADOP_FAMC_ADOP`	`ADOP`		`STRING`
`ELT_SUB_INDIV_EVEN`	`EVEN`		`NULL`
`ELT_SUB_LIO_BAPL`	`BAPL, CONL, ENDL`		`NULL`
`ELT_SUB_LIO_BAPL_STAT`	`STAT`		`STRING`
`ELT_SUB_LIO_BAPL_DATE`	`DATE`		`DATE`
`ELT_SUB_LIO_BAPL_TEMP`	`TEMP`		`STRING`
`ELT_SUB_LIO_BAPL_PLAC`	`PLAC`		`STRING`
`ELT_SUB_LIO_SLGC`	`SLGC`		`NULL`
`ELT_SUB_LIO_SLGC_FAMC`	`FAMC`		`STRING`
`ELT_SUB_LSS_SLGS`	`SLGS`		`NULL`
`ELT_SUB_LSS_SLGS_STAT`	`STAT`		`STRING`
`ELT_SUB_LSS_SLGS_DATE`	`DATE`		`DATE`
`ELT_SUB_LSS_SLGS_TEMP`	`TEMP`		`STRING`
`ELT_SUB_LSS_SLGS_PLAC`	`PLAC`		`STRING`
`ELT_SUB_MULTIM_OBJE`	`OBJE`		`NULL`
`ELT_SUB_MULTIM_OBJE_FORM`	`FORM`		`STRING`
`ELT_SUB_MULTIM_OBJE_TITL`	`TITL`		`STRING`
`ELT_SUB_MULTIM_OBJE_FILE`	`FILE`		`STRING`
`ELT_SUB_NOTE`	`NOTE`		`NULL STRING`
`ELT_SUB_PERS_NAME`	`NAME`		`STRING`
`ELT_SUB_PERS_NAME_NPFX`	`NPFX`		`STRING`
`ELT_SUB_PERS_NAME_GIVN`	`GIVN`		`STRING`
`ELT_SUB_PERS_NAME_NICK`	`NICK`		`STRING`
`ELT_SUB_PERS_NAME_SPFX`	`SPFX`		`STRING`
`ELT_SUB_PERS_NAME_SURN`	`SURN`		`STRING`
`ELT_SUB_PERS_NAME_NSFX`	`NSFX`		`STRING`
`ELT_SUB_PLAC`	`PLAC`		`STRING`
`ELT_SUB_PLAC_FORM`	`FORM`		`STRING`
`ELT_SUB_SOUR`	`SOUR`		`STRING`
`ELT_SUB_SOUR_PAGE`	`PAGE`		`STRING`
`ELT_SUB_SOUR_EVEN`	`EVEN`		`STRING`
`ELT_SUB_SOUR_EVEN_ROLE`	`ROLE`		`STRING`
`ELT_SUB_SOUR_DATA`	`DATA`		`NULL`
`ELT_SUB_SOUR_DATA_DATE`	`DATE`		`DATE`
`ELT_SUB_SOUR_TEXT`	`TEXT`		`STRING`
`ELT_SUB_SOUR_QUAY`	`QUAY`		`STRING`
`ELT_SUB_REPO`	`REPO`		`STRING`
`ELT_SUB_REPO_CALN`	`CALN`		`STRING`
`ELT_SUB_REPO_CALN_MEDI`	`MEDI`		`STRING`
`ELT_SUB_FAMS`	`FAMS`		`STRING`
`ELT_USER`	`any tag starting with an underscore`		`NULL STRING`

Gedcom_val types

Currently, the specific Gedcom_val types are (with val of type Gedcom_val):

	type checker	cast operator
null value	`GEDCOM_IS_NULL(val)`	N/A
string	`GEDCOM_IS_STRING(val)`	`char* str = GEDCOM_STRING(val);`
date	`GEDCOM_IS_DATE(val)`	`struct date_value dv = GEDCOM_DATE(val);`

The type checker returns a true or a false value according to the type of the value, but this is in principle only necessary in the rare circumstances that two types are possible, or where an optional value can be provided. In most cases, the type is fixed for a specific tag.

The null value is used for when the GEDCOM spec doesn't allow a value, or when an optional value is allowed but none is given.

The string value is the most general used value currently, for all those values that don't have a more specific meaning. In essence, the value that is returned by GEDCOM_STRING is always the same as the raw_value passed to the start callback, and is thus in fact redundant.

The date value is used for all elements that return a date. (Description of struct date_value TBD: look in the header file for the moment).

struct date_value

This struct describes a date as given in the GEDCOM file, and has the following definition:

struct date_value { Date_value_type type; struct date date1; struct date date2; char phrase[MAX_PHRASE_LEN + 1]; };

It depends on the first member, the type, which members are actually relevant:

Date_value_type	Meaning	Relevant members
`DV_NO_MODIFIER`	just a simple date	date1
`DV_BEFORE`	a range (BEFORE date1)	date1
`DV_AFTER`	a range (AFTER date1)	date1
`DV_BETWEEN`	a range (BETWEEN date1 AND date2)	date1, date2
`DV_FROM`	a period (FROM date1)	date1
`DV_TO`	a period (TO date1)	date1
`DV_FROM_TO`	a period (FROM date1 TO date2)	date1, date2
`DV_ABOUT`	an approximation (ABOUT date1)	date1
`DV_CALCULATED`	an approximation (CALCULATED date1)	date1
`DV_ESTIMATED`	an approximation (ESTIMATED date1)	date1
`DV_INTERPRETED`	INTERPRETED date1 FROM a given free form date phrase	date1, phrase
`DV_PHRASE`	a free form date phrase	phrase

struct date

The date1 and date2 also have a strict syntax:

struct date { Calendar_type cal; char day_str[MAX_DAY_LEN + 1]; char month_str[MAX_MONTH_LEN + 1]; char year_str[MAX_YEAR_LEN + 1]; int day; int month; int year; Year_type year_type; Date_type type; long int sdn1; long int sdn2; };

The first four fields are the primary fields parsed from the value in the GEDCOM file. The day_str, month_str and


year_str

are the literal parts of the date that denote the day, month and year. The calendar type cal is one of (see calendar overview LINK TBD):

CAL_GREGORIAN : the Gregorian calendar
CAL_JULIAN : the Julian calendar
CAL_HEBREW : the Hebrew (Jewish) calendar
CAL_FRENCH_REV : the calendar used after the French Revolution
CAL_UNKNOWN : an unknown calendar type

The next four fields are deduced from the first four:

the day is just the numeric representation of the day_str (starting from 1)
the month is the month number of month_str in the given calendar type (also starting from 1)
the year is the numeric representation of the year_str

It is possible that the year_str is given as e.g. "1677/78". This is coming from a date in a so called "annunciation style", where the year began on 25 March, so that "20 March 1677/78" is 20 March 1677 in "annunciation style" and 20 March 1678 in "circumcision style" (the current style). See calendar overview (LINK TBD).

In this case, the year will contain the "circumcision style" year (1678 in the example), and year_type will be YEAR_DOUBLE. Normal dates will have a year_type equal to YEAR_SINGLE .

Finally, the last three fields are probably the most interesting values for applications that want to process dates. Basically, the date is converted to a serial day number (aka Julian day), which is the unique day number since November 25, 4714 BC in the Gregorian calendar. The advantage of these day numbers is that they are unique and independent of the calendar system. Furthermore, date differences can just be computed by subtracting the serial day numbers.

However, since dates in GEDCOM are not necessarily exact (e.g. "MAR 1990"), it is not possible to represent all GEDCOM dates with 1 serial day number. Two cases can be distinguished:

Exact dates (e.g. "25 MAR 1990"):

These are represented by a serial day number in sdn1 and a Date_type equal to DATE_EXACT.

Incomplete dates (e.g. "MAR 1990"):

These are represented by 2 serial day numbers (sdn1 and sdn2) and a Date_type equal to DATE_BOUNDED.

For example, the Gregorian date "MAR 1990" is represented by the serial day numbers for "1 MAR 1990" and "31 MAR 1990", and the Gregorian date "1990" is represented by the serial day numbers for "1 JAN 1990" and "31 DEC 1990". Similarly for the other calendar types.

$Id$
$Name$