Understanding Functions

This topic is for advanced and technically-minded users only.

There is no need for any user to ever learn or know anything about functions. However, for users who wish to know, this help topic provides some information about them.

A 'function' is an expression which returns values based on computations. Typically, functions require data to be supplied to them as 'parameters'. A function in Family Historian is similar to a 'function' as used in spreadsheet applications (such as MS Excel), macro languages used in Office applications (such as Visual Basic for Applications, used in MS Word), or programming languages. An example of a function in Family Historian is the 'Relationship' function. If you pass this function identifiers for 2 individuals, the function will tell you how they are related. See below for more details.

All expressions which are functions begin with an '='. Expressions which contain data references do not start with an '='.

When using functions in the context of queries, you can often put a quoted string in square brackets as a parameter - e.g. ["Individual"]. When the query is run, Family Historian will display a dialog and prompt you to display a value for this item, labelled "Individual" in the dialog. You cannot however do this in diagrams or reports.

Functions can also be passed as parameters to other functions. When this occurs, do not put an ‘=’ sign in front of the function which is being used as a parameter. For example, “=Relationship(FileRoot())” returns the current records relationship to the file root.

Functions and other expressions can be used in Queries, Diagrams and Reports.

Family Historian supports the following functions:

Function	Short Description
AgeAt	Returns an Individual's age at the time of a given event. Used in the query Age At Marriage.
AhnentafelNumber	Returns an ahnentafel number for an ancestor. This function is used in the Ancestors query.
ChildCount	For Individual records, this function returns the count of the Individual’s children (by all spouses). For Family records, this function returns the count of children in the family. For all other records, the function returns zero.
CombineText	This function is typically used in diagram text schemes. It allows you to combine text by adding a prefix and/or suffix to the text returned by a given data reference; or to optionally supply alternative text to use if no text is returned. See also ExistsText, NotExistsText and ForceText.
CombineText	Returns TRUE if a given record has a text field which matches the specified text. It can also optionally check shared notes (Note records) linked to the record, and (in the case of Individual records), associated spouse family records.
Date	This function is typically used as a parameter to another function. It allows you to pass a date to a function, specifying either a year, a year and month, or a year, month and day. See also Today.
EstimatedAgeAt	Uses available information to estimate a person’s age at a given date.
EstimatedBirthDate	Uses available information to estimate a person’s date of birth.
EstimatedDeathDate	Uses available information to estimate a person’s date of death.
ExistsText	This function is typically used in diagram text schemes. It allows you to specify a data reference, and text to be output if, and only, if data is found for the specified data reference.
FileRoot	Returns a reference to the file root if there is one.
ForceText	This function is typically used in diagram text schemes. It simply outputs the text specified. It is useful because an ordinary label is only output if the data reference following it matches some data. If you want the label to be output regardless, use ForceText. See also CombineText, ExistsText and NotExistsText.
GetLabelledText	Only for use with long text fields that can include multiple paragraphs (notes, address fields, etc). Returns all text within a given paragraph, following a specified label.
GetParagraph	Only for use with long text fields that can include multiple paragraphs (notes, address fields, etc). Returns a numbered paragraph from the text field.
HasFlag	Returns TRUE if a given record has a given flag. See also IsInList.
HasNoteInList	Returns TRUE if a given record is in a given Named List and has a note attached to it in that Named List.
IsAncestorOf	Returns TRUE if a given record is an ancestor of another given record.
IsDescendantOf	Returns TRUE if a given record is an descendant of another given record.
IsEmbedded	For Multimedia Objects only. Returns TRUE if the object is embedded in the current file.
IsInList	Returns TRUE if a given record is in a given Named List or not.
IsRelativeOf	Returns TRUE if a given record is a relative of another given record.
IsSpouseOf	Returns TRUE if a given record is a spouse of another given record.
LastUpdated	Returns the date that a given record was last updated. Used in all of the Last Updated… queries.
LifeDates	Returns birth and death dates in a convenient format. If birth and/or death dates are not available, it will return baptism, christening and/or burial dates instead, if these are known. This function is used in many text schemes, in reports and in the Age At Death query.
LifeDates2	This function behaves exactly like LifeDates, except that it will return a hyphen for individuals who have none of the relevant dates. This is convenient if you want to display a person who has no dates like this: "John Smith ( - )".
LinksFrom	Returns the number of links from 1 record to another.
LinksTo	Returns the number of links to a given record. Used in the query Links to Multimedia Objects.
MediaCount	Returns a count of the pictures and other multimedia associated with a given record.
MediaType	Returns text which identifies the type of a Multimedia Object.
Name	Returns the name of a given record.
NotExistsText	This function is typically used in diagram text schemes. It allows you to specify a data reference, and text to be output if, and only, if data is not found for the specified data reference See also ExistsText, CombineText and ForceText.
RecordId	Returns the record id of a given record.
RecordName	Returns the name of a given record.
RelationCode	Similar to "Relationship", but it returns aspects of the relationship between 2 people, represented numerically (e.g. the number of generations that separate them).
RelationPool	Returns an (arbitrarily assigned) identifier for a pool of relatives, that a given individual belongs to. A 'pool' of relatives is a group of people who are directly or indirectly related to one another. By sorting on the pool number, it is easy to locate 'orphans', and/or small groups of individuals, not related to other individuals in the file. This function is used in the Search For Orphans query.
Relationship	Returns information about how 2 people are related. Can be used to return a description such as 'Uncle' or 'Grandmother'.
SourceLinks	Returns the number of links from a given individual to a given source. Used in the query Individuals Linked to Source.
Today	This function is typically used as a parameter to another function. It allows you to pass today’s date to a function. See also Date.

Many function expressions can be created by simply putting an ‘=’ in front of the function name, and 2 round brackets on the end of it. For example, ‘=ChildCount()’, ‘= RecordId()’, ‘=LastUpdated()’ are all valid expressions. These functions all take one parameter. However, if no parameter is supplied, Family Historian will assume that the current record should be used. The meaning of the 'current record' is context dependent. In a query, it will be the record for the current row in the result set. In a report, it may be the current entry record; or, if used within a section, that relates to a particular record, it may the record associated with that section.

Click on the function name in the list to see a fuller description of each function. Some are more complex than others, and may take several parameters. If you wish to use any of these functions, you are advised to look for an example of a standard query that uses them, and try to copy what it does.