functions
fhCallBuiltInFunction
Description
"Built-in functions" are functions that are defined within the main application, and which can be used as part of Family Historian expressions (e.g. in queries, text schemes, reports, etc) in a wide variety of different ways. The built-in functions are listed in the main application Help in Understanding functions.
There are a many built-in functions and they can be used for a wide
variety of purposes. For example, the Relationship function can be used
to tell you how any two people are related. The ContainsText function is
used to search a data item for a given word or phrase.
You can call any built-in function from within Lua, using fhCallBuiltInFunction. This function takes a variable number of parameters, depending on the built-in function you are calling. It will always return a value, but the type of the value returned will also depend on the built-in function you are calling.
Syntax
fnValue = fhCallBuiltInFunction(strFunctionName, ...)
Parameters
- StrFunction
- Name of Function to call
- 1 or more function parameters
- Parameters matching those for the function called in parameter 1
Return Value
- fnValue
- As specified in the Function called as parameter 1
The Help for each built-in function specifies exactly how many parameters each function has, and what type of values can be passed as parameters to it. The table below shows the possible parameter types, as described in the Help, and the equivalent Lua type that you should use for that parameter type.
| Built-in Function Parameter Type | Equivalent Lua Type |
|---|---|
| A reference to a data item | An Item Pointer. Note: The Help may specify that the reference must be to a specify kind of data item - e.g. to an Individual record. Clearly, the same requirement will apply to the Item Pointer too. |
| Date | A Date-Point object. |
| Number | number |
| Boolean | boolean |
| Text | string |
| An enumerated value (e.g. TEXT or CODE for relationship) | string (i.e. the enumerated value as a text string). |
| A data reference constant - e.g. 'INDI.DEAT.DATE' | string (e.g. "INDI.DEAT.DATE"). |
| A text expression that contains a data reference - e.g. "%INDI.DEAT.DATE%" | string (e.g. "%INDI.DEAT.DATE%"). |
The possible values returned by built-in functions, and their lua equivalents, are given in the table below.
| Built-in Function Return Type | Equivalent Lua Type |
|---|---|
| A reference to a data item | An Item Pointer. |
| Date | A Date-point object |
| Date-Time | A Date-point object. The hour and
minute are returned as 2nd and 3rd return values. Note: Currently the only function that returns a Date-Time value is 'LastUpdated'. |
| Number | number |
| Boolean | boolean |
| Text | string |
Remarks
Suppose you wish to call the Relationship function from within a Lua script, to find out how two people are related. The Relationship function takes 4 parameters. The first two are references to the Individuals concerned. You will pass both of these as item pointers in Lua. The 3rd parameter is an option, which must be either TEXT (if you want an ordinary language description of the relationship) or CODE (if you want a coded description of their relationship). This parameter must be passed as a string - that is, either "TEXT" or "CODE". The 4th and final parameter is a number. You pass 1 if you want the closest relationship between the two people. If you want their second closest relationship you would pass 2 - and so on.
Imagine in your Lua script that ptrInd1 and ptrInd2 are item pointers that point at the Individual records that you want to use. You could find out how the Individuals were related, as a text string, by making the following call:
strHowRelated=fhCallBuiltInFunction("Relationship", ptrInd1, ptrInd2, "TEXT", 1)
This will return a description of the relationship in the variable strHowRelated.
As it happens, the 4th parameter to this function is optional. If not supplied, it defaults to 1. So you could have achieved the same thing in this case by the following call:
strHowRelated =fhCallBuiltInFunction("Relationship", ptrInd1, ptrInd2, "TEXT")