Functions are an advanced feature of Family Historian, 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 since fh V4
- Reports to define Data items in certain Report Sections
- Customise or Print Records Window Columns or Named List Columns
- Captions in Property Boxes
- Narrative Report Fact Sentence Templates since fh V6
- Override Templates for Fact displays since fh V6
For a full list see the Family Historian Help > Using Family Historian > Advanced Topics > Expressions and Contexts of Use.
Expressions are composed from two technical features:
A Function is a predefined computation that returns a value, often based on data supplied as Parameters. They are similar to 'functions' used in spreadsheets (such as MS Excel), macro languages (such as Visual Basic for Applications), or other programming languages. For example:
=ChildCount() supplies the Child Count, and =RecordId() supplies the Record ID for the current Record. See another example in Query Functions.
Any Parameters are enclosed in parentheses ( ) and separated with commas , as shown below:
=CalcDate(%INDI.BIRT.DATE%, 10, 3) returns a Date that is the Date of Birth plus 10 years and 3 months.
For full details see the Family Historian Help > Using Family Historian > Advanced Topics > Understanding Functions and then the subsidiary topics Functions (by category), Functions (all), Data Types, Operators, etc.
Family Historian offers nothing equivalent to the Data Reference Assistant for constructing Functions, so they must be composed manually, and if Family Historian says that an Expression is invalid, then you must deduce where the error lies.
An alternative is the Utility ~ PSPad Family Historian Functions editor that helps you compose the Function syntax correctly before pasting it into an Expression.
Therefore, to start with it would be best to focus on the simpler Functions that have no Parameters until some experience has been gained.
Some Functions are more complex than others, and may take several Parameters. To use these, it would help to find an example in an existing Expression, and try to copy how it is used.
One common misunderstanding is whether to include or exclude the leading = sign on the Function name.
If the Function is NOT within the parentheses of another Function then the = sign is required.
If the Function is within the parentheses then the = must be omitted.
So for example:
=Year(%INDI.BIRT.DATE%) returns the Year of Birth of an Individual.
=CalcDate(Year(%INDI.BIRT.DATE%), 10) returns a Date that is the Year of Birth plus 10 years.
In the second example the Year() Function must NOT have the = sign prefix.
It is also essential that the parentheses ( ) are in matched nested pairs. In other words every opening parenthesis ( must have a matching closing parenthesis ).
This becomes quite difficult to check for complex nested Functions with multiple Parameters, that are larger than the Expression box display.
To overcome this it is a good idea to compose the complex Expression in a simple text editor such as Notepad, and build up the components bit by bit. At each step, copy and paste the Expression into Family Historian to check its syntax is valid, before adding the next component.
Several functions calcuate an Age or Date from recorded information. These include =AgeAt(), =EstimatedAgeAt(), =EstimatedBirthDate() & =EstimatedDeathDate().
=AgeAt() only uses the first Birth event Date and the supplied Date parameter. If either is a Range or Period with two Dates then only the earlier Date is used. If either Date is undefined then the function returns an empty string.
=EstimatedAgeAt(), =EstimatedBirthDate() & =EstimatedDeathDate() are far more sophisticated and use much more database information together with Tools > Preferences > Estimates to produce a value. They give precedence to Birth and Death events, but may also use Baptism, Christening, Burial, or Cremation events, or other facts for the individual and their relatives.
Despite that, there are scenarios for which =EstimatedBirthDate() gives erroneous dates that may also affect =EstimatedAgeAt():
- If a fact has a Date and an Age then that may be used to establish the estimated Birth Date.
- If a Death event has a Before Date Range then that Date is set as the Earliest Birth Date.
In such scenarios, the Earliest Birth Date may be later than the Latest Birth Date, and both may be later than the Date of a life fact such as a Baptism or Census event.