Understanding Functions

Prompts

Prompts within Queries

If you use a function expression in a query, you can include prompts in it. A prompt is a special kind of marker within an expression which are only allowed when the expression is used in the context of a query.  When Family Historian runs the query it will check to see whether the query contains any prompts. If prompts are found, Family Historian will display a dialog box which invites (prompts) the user to enter values which will be substituted into the query at the prompts. For example, you might have a query that will find everyone who was born before a certain year. Rather than specifying the actual year within the query, you might consider it more useful if every time the query is run, you get to specify which year you want to check at that time. This is what prompts are for. They allow you to specify values when the query is run.

Every prompt must have a label (e.g. "Year:") and a data type (e.g. number). Prompts have square brackets round the prompt expression, and within these you specify the label in double quotes. So, for example, in the following expression

=IsTrue(Year(%INDI.BIRT.DATE%) > Number(["Year"]))

the prompt is

["Year"]

The data type is not usually explicitly mentioned. It is determined by the context. If the value of a prompt is to be passed as a parameter to a function, Family Historian knows what type of parameter the function will take and can deduce the data type of the prompt. However, if the value of the prompt is to be directly combined with other expressions using operators, the context does not always determine unamiguously what data type the prompt should be. Consequently we recommend that you always use put the prompt on its own inside a Type-Specifier Function call, as is done in the example above. Strictly-speaking, the Number function, in that example, is not necessary. That particular expression could have been written as

=IsTrue(Year(%INDI.BIRT.DATE%) > ["Year"])

and that would work. But by putting the prompt within the Number function call, any possible uncertainty about the data type is removed. The Number function takes a number as its first and only parameter, so the data type in the example above can only be number.

The following expression does not work, for example:

=IsTrue(["Year"] > Year(%INDI.BIRT.DATE%))

This is because Family Historian cannot determine the data type of the prompt. But by putting the prompt inside a call to the Number function as in this case:

=IsTrue(Number(["Year"]) > Year(%INDI.BIRT.DATE%))

the ambiguity is removed and the expression is now OK. See Type-Specifier Functions for more on this topic.

It sometimes happens that you want the same prompt value to be used in multiple contexts within a particular query. To achieve this, insert a prompt in each context but make sure that they all have the same label and the same data type. Family Historian will treat all prompts which have the same label and the same data type as prompts for one shared value.

Hints

Sometimes a context may require a data item, but for your purposes you may wish to restrict the choice to a particular data item type.  In that case you can supply a hint.  A hint is a keyword that is used to specify more precisely what data item type is required. Hints are ignored if the specified data item type is not allowed in the given context.To use a hint, insert the key word after the opening square bracket of the prompt, followed by a colon.  The keyword "Place" is used in the example prompt below.

=DistanceBetween(,[Place: "Birth-Place"],MILES)

The following hint keywords are supported: