This topic is for advanced and technically-minded users only.
The most important thing to know about Data References is that you never have to construct them yourself! Family Historian will always do it for you, whenever you need them. And you will only need them if you want to do advanced customizations of diagrams or reports, or write custom queries. A 'Data Reference' is a way of identifying a particular item of data (i.e. a field) within a given type of record. For example a NAME tag in INDIvidual records is identified as INDI.NAME. By extension, a data reference can also be used to identify tags in linked records too. For example, if you want to know, for a given INDIvidual what their father's name is, you could use the following expression:
INDI.FAMC>HUSB>NAME
This looks intimidating, but is actually not as complex as it looks. The parts have the following meaning:
| INDI | We're starting with a given INDIvidual |
| FAMC> | Within the Individual's record, we want the (first) link to the FAMily they belonged to as a Child. |
| HUSB> | We're interested in the HUSBand tag in this family record (i.e. the father). This tag represents another link - this time from the family record to another individual record. |
| NAME | Within that linked Individual record, we want the person's NAME. |
What if the husband had more than one name, and you wanted the second name? In that case, you would insert '[2]' after the NAME tag, to indicate that it is the 2nd NAME that is wanted. i.e.:
INDI.FAMC>HUSB>NAME[2]
In Family Historian, a person can have any number of families as a child too (e.g. you could record the birth family, multiple foster families, an adoption family, etc). What if you were interested in the person's third family as a child? In that case, you would insert a '[3]' after the FAMC tag (but before the '>' link indicator). That is, you would write the data reference as:
INDI.FAMC[3]>HUSB>NAME[2]
Not all tags can have an 'index' in this way. If you had put the [3] after 'HUSB', this would not have been accepted, because a family record cannot have more than one male parent.
Of course, if you used this expression for a given individual, who did not have 3 families as a child, or if the 3rd family had no male parent, or if there was one, but that person only had one name (or none), then this expression would return no data. The query result set cell, or diagram box (portion of) that you used it for, would simply be blank.
Its worth understanding how to edit data reference to use indices, because Family Historian will not do this for you automatically. Data references generated by Family Historian are always for the first instance of a tag only. If you want the 2nd or 3rd value of a tag, you have to edit the data reference yourself.
There are some items of data which are difficult or impossible to access using a standard data reference. Suppose, for example, you want a data reference that will show, for any given person, what their spouse’s data of birth was? You might think you could use this data reference:
INDI.FAMS>HUSB.BIRT.DATE
That would work fine if the person you started with was a woman. But if it was a man, it would simply return that person’s own date of birth and not their spouse’s. What you need for this kind of situation is a shortcut. Family Historian supports 4 shortcuts. They are shortcuts to a person’s father, mother, spouse, and child, and they are displayed respectively as:
INDI.~FATH
INDI.~MOTH
INDI.~SPOU
INDI.~CHIL
You can continue a data reference containing a shortcut as if it were any other data reference to an Individual. So, for example,
INDI.~SPOU>BIRT.DATE
will, for any individual, give you the date of birth of their first spouse.
Shortcuts can have indices like any ordinary tag. So,
INDI.~SPOU[2]>BIRT.DATE
will return a person’s second spouse’s date of birth.
The Father and Mother shortcuts are actually not essential. There is nothing that you can do with them that you can’t do without them. But both the Spouse and Child shortcuts allow you to do things you couldn’t otherwise do.
It might appear that
INDI.~CHIL[2]
is equivalent to
IND.FAMS>CHIL[2]
However, that is not correct. The former will return a given person’s 2nd child - i.e. by any marriage. The latter will return a person’s 2nd child of their first marriage (or relationship), and will return NULL if there were fewer than 2 children in this relationship.
As well as specifying which item of data you wish to reference, Data References also allow you, at least in some cases, to specify how you wish the data in question to be displayed. They do this using Qualifiers. To see a list of qualifiers associated with any given tag, open the Query Window, make sure that you are viewing an Individual query, and select the Columns tag. Find ‘Individual’ (first item in the list) and then ‘Name’. When you expand ‘Name’ you will see a list of words in capitals, all with a colon at the front of their name. These are qualifiers. The qualifier “:SURNAME” first, for example, will extract just the surname from a person’s name. So, for example, to see a person’s spouse’s surname, you could use
INDI.~SPOU>NAME:SURNAME
You don’t have to remember qualifier names. Whenever you wish to create a data reference, you simply expand the item you wish to qualify and you will see a list of all available qualifiers. When you select each qualifier, a description field below the list explains what that qualifier is for.
Name fields have 16 qualifiers. Dates have between 15 and 17 qualifiers (see Date Formats). Places have 4. Other fields mainly have no qualifier.
As we saw earlier, you can use indices within a data reference if you want to access an item which isn’t the first instance of its kind. For example,
INDI.~SPOU[2]>NAME:SURNAME
will give you a person’s 2nd spouse’s surname. But what if you want to see the surname of the person’s last spouse? In that case, you should use [last] as the index. e.g.:
INDI.~SPOU[last]>NAME:SURNAME
If you want to see the 2nd last spouse’s surname, you need this version:
INDI.~SPOU[last-1]>NAME:SURNAME
This will return nothing (null) if a person only has one spouse.
To see the 3rd last spouse’s surname use
INDI.~SPOU[last-2]>NAME:SURNAME
This will return nothing for a given person, if that person has fewer than three spouses.
Sometimes you may want the 3rd index if there is one, but the 2nd if there are only 2, or the first if there is only one. You can achieve this using the ‘<’ character in front of the index. So, for example,
INDI.NAME[<2]
will return a person’s 2nd name if they have more than one, and the first if they only have one. It is not quite the same as
INDI.NAME[last]
because the former would never return any index value greater than 2. The latter will always return the last item, however many instances there may be.
There is also another special index which is primarily intended for use with Census events, although you can use it to reference any item of data that has an associated date.
INDI.CENS[year=1881]
will return the census event that is dated 1881. Similarly, this
INDI.CENS[year=1891]
will return the Census event dated 1891.
Finally, there is also the looping index. This is only used in text templates (see Understanding Text Templates) in text schemes and provides a mechanism whereby an item in a text scheme can be repeated for all instances. A looping index has a ‘+’ after the index number, and means ‘repeat for all instances, starting with this one’. For example, an item with this text template:
%IND.OCCU[1+]
would show all occupations, starting with the first.
Looping indices only work within text templates in text schemes.
| The CHM file was converted to HTML by chm2web software. |