Introduction

Data References refer to items of data held within Records, and are used within Expressions that occur most commonly in:

• Queries to specify Columns, Row filters, and Titles
• Diagram Text Schemes to define the content of Diagram Boxes
• Diagram > Options > Boxes > Conditions to define box style
• Reports to define Data items in certain Report Sections
• Customise or Print Records Window Columns or Named List Columns
• Captions and Custom Fields in Property Boxes
• Narrative Report Fact Sentence Templates since ƒh V6
• Override Templates for Fact displays since ƒh V6

For a full list see (ƒh7) Expressions and Contexts of Use or (ƒh6) Expressions and Contexts of Use.

Expressions are composed from two ƒh features:

• Data References that often appear enclosed within percentage signs, e.g.%INDI.BIRT%
• Functions that begin with an = sign (except when used within another Function), e.g. =RecordId()

Data References

Data References identify Data items within Records. For example, the following Expression is a Data Reference that specifies a particular Individual Birth Event:

%INDI.BIRT%

For full details see the help pages linked at the top of this article including several new features added in ƒh6 and ƒh7.

The structure of Data References in all versions of ƒh up to version 6 is derived from the The Gedcom Standard, Release 5.5 dated 2nd January 1996.

The Basics

You should rarely need to construct a Data Reference yourself, because ƒh offers a Data Reference Assistant (DRA) associated with every type of Expression. For example, in a Query Window, on the Columns tab, there is a Fields DRA panel on the left, and on the Rows tab, the Expression box has an ellipsis […] DRA button to the right.

Basically each Data Reference is composed of Tags that identify Data. These are separated by either a dot.or a greater than >sign, and the whole reference is usually enclosed within percent %signs.

For example, to identify for any given INDIvidual, the NAME of their father, you could use the following Data Reference:

%INDI.FAMC>HUSB>NAME%

This looks intimidating, but is not as complex as it appears, and the parts have the following meaning:

INDI	Start with an INDIvidual Record
FAMC	Within this Record, follow the > link to the FAMily they belong to as a Child
HUSB	The father is identified by the HUSBand field in this Family Record and another > link leads to another Individual Record
NAME	Within that linked Individual Record we find the NAME field of the father

The available Tags are always offered and explained by the relevant Data Reference Assistant, and Record links are listed with a trailing double greater than >> symbol.

The Tags are mostly the same as used in GEDCOM but there are a few exceptions. For example, in GEDCOM the NOTE tag is used with the format @N321@ to link to a Note Record, or with any other text for a Local Note. Whereas, Data References use the tags NOTE> and NOTE2 respectively to make the distinction clear. Data References also use a special Tag format for custom Events (EVENT-<event_name>) and Attributes (_ATTR-<attr_name>).

Indices

There can be more than one instance of many of the Data fields. An Individual can have more than one Name, more than one Child, or more than one Census entry. Each instance is identified by an index in square brackets [1]. If no index is supplied, then the first instance is assumed by default.

So for example:

%INDI.NAME[2]%	identifies the 2nd Name
%INDI.CENS[4]%	identifies the 4th Census Event
%INDI.CENS[last]%	is an advanced index to identify the last Census Event
%INDI.CENS[year=1881]%	is an advanced index to identify the 1881 Census Event

For more options, see the help pages linked at the top of this article.

These Indices are one of the rare cases where a Data Reference must be manually edited, because they cannot be selected using a Data Reference Assistant.

Relative Data References

An ordinary Data Reference starts with a tag that identifies a record, but in some contexts the Data Reference can be relative to a subsidiary tag such as a Fact in a Fact Query or a Sentence Template in later versions of ƒh.

~.PLAC	identifies the Place field of a Fact
~.DATE	identifies the Date field of a Fact

In some cases the initial tilde ~ can be followed by > instead of a dot.

Relative data references also apply to parameters of some Functions and throughout ƒh Plugins.

Shortcuts

Some data items are difficult or impossible to access using an ordinary Data Reference. To solve this problem ƒh  supports five dummy Tags called Shortcuts that begin with a tilde ~ symbol.

~FATH	identifies the father of an Individual
~MOTH	identifies the mother of an Individual
~CHIL	identifies a child of an Individual
~SPOU	identifies a spouse of an Individual or a Family Record
~CURSPOU	identifies the spouse of an Individual for any particular Diagram Box

So for example:

%INDI.~CHIL[2]%	identifies the 2nd child of an Individual by any marriage
%INDI.~SPOU[1]>BIRT.DATE%	identifies the date of birth of the 1st spouse of an Individual

The available Shortcuts are always offered and explained by the relevant Data Reference Assistant, and are listed with an upward pointing arrow prefix.

Qualifiers

A Data Reference in some cases can specify how the data is displayed by using a Qualifier. These are appended to the last Tag separated by a colon : symbol.

The available Qualifiers are always offered and explained by the relevant Data Reference Assistant.

So for example:

%INDI.NAME:SURNAME%	displays just the Surname of an Individual
%INDI.BIRT.DATE:YEAR%	displays just the Year of Birth of an Individual
%INDI.DEAT.PLAC:SHORT%	displays just the first item up to the first comma in the Death Place field

Contextual Data References

Contextual Data References were added in ƒh V6 and only have meaning in their specific context of use, mostly within Diagrams where the currently displayed Family couple needs to be identified.

%CUR_SPOU% and %CUR_SPOU>%	Current Spouse
%CUR_FAMS% and %CUR_FAMS>%	Current Family As Spouse
%CUR_FAMC% and %CUR_FAMC>%	Current Family as Child
%CUR_SP_FAMS% and %CUR_SP_FAMS>%	Current Spouse’s Family as Spouse
%CUR_SP_FAMC% and %CUR_SP_FAMC>%	Current Spouse’s Family as Child
%CUR_BASE%	Base Person
%CUR_TREE_ROOT%	Tree Root
%CUR_TREE_ROOT_FAM%	Tree Root Family
%CUR_DGM_ROOT%	Diagram Root
%CUR_DGM_ROOT_FAM%	Diagram Root Family
%CUR_DGM_ROOT_COUPLE_FAM%	Diagram Root Couple’s Family

Elsewhere:

%CUR_OTHER_IND%	Other Individual in ‘How Related’ report
%CUR_FILE_ROOT%	File Root nearly everywhere
%CUR_FILE_OWNER%	File Owner nearly everywhere
%CUR_FILE_HEADER%	File Header nearly everywhere

Narrative Sentence Templates:

%CUR_PRIN%	First or current principal for the fact
%CUR_PRIN2%	Second or other principal for the Family fact
%CUR~WITN% and %CUR~WITN>%	Current witness

Contextual data references behave like ordinary data references, in that you can expand them to refer to any detail of the record in question. For example, %CUR_SPOU>SEX% refers to the sex of the Individual’s current spouse, and %CUR_FILE_ROOT.SEX% refers to the sex of the current file root.

Sentence Template Data References

Sentence Template Data References were added in ƒh V6 and only have meaning in specific template contexts.

For more detail, see towards the end of (ƒh7) Sentence Template Codes or (ƒh6) Template Codes.

Typically the data reference is enclosed in curly brackets and its context is the current fact, e.g. {%FACT.PHON%} refers to the fact phone number.

To refer to witness details from a witness sentence template requires the use of the %CUR~WITN% contextual data reference shown above.

{%CUR~WITN>NAME:GIVEN%}	Returns the Witness record forename
{%CUR~WITN.NOTE2%}	Returns the Witness role local Note

Embedded Link Data References (V7)

Version 7 introduced the ability to have embedded links to other records within Note fields.

To access these, the reference is e.g. for a link to an individual within the Text from Source for a Source:

%SOUR.TEXT._LINK_I[1]>% for the first linked individual

%SOUR.TEXT._LINK_I[2]>% for the second linked individual

Note1: a linked object should have the same index no matter how many times they are linked in the Note.

Note2: Replace _I with _S for links to Sources, _R for Repositories etc.

[/glossary-ignore]