Functions (all)

GetField

Function Name:
GetField
Description:

Returns a particular field within a given record (or possibly, a subfield within another field such as a Fact field). You pass in a reference to the record (or a field) as one parameter, and a data reference specified using a text expression, in the second parameter.

Can also be used to find fields in other records - e.g. a person's mother-in-law. Is similar to the GetFieldText function, but this function is used to reference fields, and ignores qualifiers (see Understanding Data References for an explanation of the role of qualifiers). The GetFieldText function, because it returns a text value, will honour qualifiers.

This function is also similar to the Field function. GetField is more flexible as you can use operators to construct the text expressions. But Field is faster to execute. Consequently, you are recommended to use Field for preference, but use GetField if you need the added flexibility that it offers. For example, the following function used in a query will retrieve a census event for a given individual and prompt you to specify the year of the census:

=GetField(%INDI%,"%INDI.CENS[year=" . ["Year"] . "]%")

This would not be possible with the Field function as it uses the concatenation operator '.' which only works with text expressions.

Since version 6.0 of Family Historian, you can now use relative data references with this function, and also with the GetFieldText function. Relative data references begin with a single '~' character. To learn more about them see Understanding Data References.

Minimum FH Version:
4.0
No. of Parameters:
2
Return Type:
A reference to a data item (or NULL if none is found).
Parameter 1:
A datanode to use as a starting point. Usually a record.
Parameter 2:
A text expression that contains a data reference. For example:

"%INDI.DEAT.DATE%" or "%~.DEAT.DATE% (see note above about relative data references).

Note the double-quotes around the data reference. These are always needed for text expressions.

Examples:

=GetField(["Person"], "%INDI.DEAT.DATE%")
=GetField(%INDI.~SPOU>%, "%INDI.DEAT.DATE%")
=GetField(%INDI%,"%INDI.CENS[year=" . ["Year"] . "]%")