Understanding Functions

Functions (all)

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.
Bool A Type-Specifier Function.
Calc Calculates a numeric value.
CalcDate Calculates a date from a given date and a given number of years, months and or days (which can have negative values).
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 CombineText_AB, ExistsText, NotExistsText and ForceText.

CombineText_AB This function is typically used in diagram text schemes. It allows you to combine two items of text by adding a prefix and/or suffix, and optionally a separator for the two items, and alternative text to use if both items of text are blank.

See also CombineText, ExistsText, NotExistsText and ForceText.

ContainsText 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 Type-Specifier Function.
DateAt 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

DateIf Takes a boolean expression (True or False) and 2 dates. If the boolean expression evaluates as True, the first date is returned; otherwise the second date is returned.
Day Returns the day part of a given date (e.g. for 22nd May, 1982 it would return 22). See also Month and Year.
DayNumber If you started counting days on January 1st AD 1 (counting that day as day 1), this function will return the day number for any given date. For example, the day number for 1st January, 2008, is 733,044.
DayOfWeek Returns the day of the week ("Sunday", "Monday", etc) for any given date.
Diff Returns the difference between two numbers as a positive (a.k.a. absolute) value.
DistanceBetween Returns the distance between two Place records (if both have been geocoded).
DnaBloodRelation Returns TRUE if two given people are blood relations of one another.
DnaHalfBlood Returns TRUE if two given people are half blood relations of one another (e.g. are siblings who share only one parent or cousins who share only one ancestor).
DnaOverlapXChrom Returns TRUE if, on the basis of their relationship to one another, two people have a likelihood of sharing some part of their X chromosome(s).
DnaRelatedness Returns a value between 0 and 1 which indicates how closely related two people are.
DnaShareMtDNA Returns TRUE if two people share mitochondrial DNA.
DnaShareYChrom Returns TRUE if two people share a Y chromosome.
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.
Exists Returns true if a given data item exists.
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.
FactAbbrev Returns the abbreviated form for the label of a given fact.
FactLabel Returns the label for a given fact.
FactName Returns the official name of a given fact.
FactOwner Returns the owner (an Individual record) of a given fact. Family facts can have 2 owners - the husband and wife.
FactSentence Returns a narrative sentence describing the fact (usually mentioning date and place, if known).
FactSet Returns the name of the fact set that a given fact belongs to.
FactText Returns formatted text describing the fact (event or attribute).
FactValue Returns the value for a given fact. Only attributes have values. This funtion always returns NULL for events.
FamilyAsChildCount Returns the number of families in which a given Individual is listed as a child.
FamilyAsSpouseCount Returns the number of families in which a given Individual is listed as a spouse or parent.
Field Returns a given field within any given record. See also the GetField function below.
FieldText Returns the value of a given field (see also the GetFieldText function below).
FileRoot Returns a reference to the file root if there is one.
FindText Returns the position of a specified search string within another string. Returns 0 if the search string is not found.
Float Type-Specifier Function.
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.

GetContextItem Allows a reference to a data item in a particular context (such as the current witness, in a witness sentence template). Normally a contextual data reference would be used in such cases, but if that is not possible, this function may be used instead.
GetContextInfo Returns information which is relevant to a specific context of use.
GetDataWarning Gives a warning of any known possible problem with a given data item. Can be used with any data item, but in fact currently only warns of possible problems with dates.
GetDisplayText Provides a standard way of displaying information about any data item.
GetFact Returns a fact of a specified type (and optionally instance or year) for a given person - if there is one. The person may be a principal or a witness with respect to the fact in question.
GetField Returns a given field within any given record. Is similar to the Field function above, but slower to execute and more flexible.
GetFieldText Returns the value of a given field. Is similar to the FieldText function above, but slower to execute and more flexible.
GetKeyword Returns a keyword for a given Media record, specified by index number.
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.
GetLinkedItem If passed a data item that stores a link to another record, this function will return the record that it links to.
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.
GetParentItem Returns the immediate 'parent' data item of a given data item.
GetRecord Returns the record that a given field belongs to.
GetRole Behaves exactly like the GetFact function, except that instead of returning the fact, this function returns the person's role with respect to the fact if they are listed as a witness for the fact in question, with a defined role.
HasFlag Returns TRUE if a given record has a given flag.

See also IsInList.

HasKeyword Returns True, if and only if, a given Media record has a given keyword.
HasNoteInList Returns TRUE if a given record is in a given Named List and has a note attached to it in that Named List.
Individual Type-Specifier Function.
IsAncestorOf Returns TRUE if a given record is an ancestor of another given record.
IsAttribute Returns TRUE if a data item represents an Attribute.
IsDescendantOf Returns TRUE if a given record is an descendant of another given record.
IsEmbedded For Media Objects only. Returns TRUE if the object is embedded in the current file.
IsEmpty Returns TRUE if a data item doesn't exist or has no value
IsEvent Returns TRUE if a data item represents an Event.
IsFact Returns TRUE if a data item represents an Fact.
IsFamilyFact Returns TRUE if a data item is a Family Fact.
IsIndividualFact Returns TRUE if a data item is an Individual Fact.
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.
IsSameItem Returns true if two references to a data item are references to the same data item.
IsSet Returns TRUE if a data item exists and has a value
IsSpouseOf Returns TRUE if a given record is a spouse of another given record.
IsTrue Evaluates a potentially complex expression and determines if it is true or not.
Item Type-Specifier Function.
ItemIf Takes a boolean expression (True or False) and 2 data items. If the boolean expression evaluates as True, the first data item is returned; otherwise the second data item is returned.
KeywordCount Returns the count of keywords held by a given Media record.
LastUpdated Returns the date that a given record was last updated. Used in all of the Last Updated… queries.
LeftText Returns a text string with a specified number of characters, extracted from the leftmost end of a given text string. See also RightText and MidText.
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 Media Objects.
MediaCount Returns a count of the pictures and other media associated with a given record.
MediaType Returns text which identifies the type of a Media Object.
MidText Returns a text string with a specified number of characters, extracted from a given starting position within a given text string. See also LeftText and RightText.
Month Returns the month part of a given date as a number between 1 and 12 (e.g. for 22nd May, 1982 it would return 5). See also Day and Year.
Name Returns the name of a given record.
NextSib Returns a given Individual's next sibling, in the sibling order of the family.
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.

NullDate Returns True if a given date is Null.
Number Type-Specifier Function.
NumberIf Takes a boolean expression (True or False) and 2 numbers. If the boolean expression evaluates as True, the first number is returned; otherwise the second number is returned.
Parentage Returns a description of a given person in relation to their parents, if known (e.g. "son of John Smith and Jane Doe").
PrevSib Returns a given Individual's previous sibling, in the sibling order of the family.
Record Allows you to specify a given record by record type, and record id.
RecordId Returns the record id of a given record.
RecordName Returns the name of a given record.
RecordType Returns the record type of a given record, as a single character string.
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'.
RightText Returns a text string with a specified number of characters, extracted from the rightmost end of a given text string. See also LeftText and MidText.
Section This function is for use with text fields that are separated into multiple sections, using any series of one or more characters as separator characters to define the 'boundaries' of each section. It allows a specific section to be retrieved.
Sex

Used for outputting gender-specific text.

SourceLinks

Returns the number of links from a given individual to a given source.

Used in the query Individuals Linked to Source.

Text Used for assembling complex text strings. Also a Type-Specifier Function.
TextIf Takes a boolean expression (True or False) and 2 text strings. If the boolean expression evaluates as True, the first text expression is returned; otherwise the second text expression is returned.
TextLen Returns the length of a given text string.
TextPart Although designed primarily to help with the presentation of place information in reports and elsewhere, this function can however be used with any text fields. It returns one or more parts of any comma-separated text.
TextToNumber Converts a string expression to a number.
TimelineFactAge Returns a textual representation of a person's age at the time of a given timeline fact.
TimelineFactOrder Returns a number giving the position, in order, of a given timeline fact for a given person.
TimelineFactText Returns a description of a given timeline fact, from the perspective of a given person.
Timespan Calculates the number of years, months or days between any two dates.
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.

ToLower Converts a string expression to lower case.
ToUpper Converts a string expression to upper case.
Witness Returns a witness for a given fact, identified by role.
Year Returns the year part of a given date (e.g. for 22nd May, 1982 it would return 1982). See also Month and Year.