<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML ><HEAD ><TITLE > THE LIFELINES PROGRAMMING SUBSYSTEM AND REPORT GENERATOR </TITLE ><META NAME="GENERATOR" CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+ "></HEAD ><BODY CLASS="book" BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#840084" ALINK="#0000FF" ><DIV CLASS="BOOK" ><A NAME="docbook" ></A ><DIV CLASS="TITLEPAGE" ><H1 CLASS="title" ><A NAME="AEN2" ></A >THE <TT CLASS="application" >LIFELINES</TT > PROGRAMMING SUBSYSTEM AND REPORT GENERATOR</H1 ><H2 CLASS="subtitle" ><TT CLASS="application" >LifeLines</TT > Version 3.0.61</H2 ><H3 CLASS="author" ><A NAME="AEN6" ></A >Thomas T. Wetmore , IV</H3 ><HR></DIV ><DIV CLASS="TOC" ><DL ><DT ><B >Table of Contents</B ></DT ><DT ><A HREF="#AEN12" >Report Programming Manual</A ></DT ><DD ><DL ><DT ><A HREF="#AEN14" >Introduction</A ></DT ><DT ><A HREF="#AEN28" >Tutorial Ahnentafel report</A ></DT ><DT ><A HREF="#AEN141" >Template for creating new reports</A ></DT ><DT ><A HREF="#AEN145" >Invoking Reports</A ></DT ></DL ></DD ><DT ><A HREF="#AEN155" ><TT CLASS="application" >LIFELINES</TT > PROGRAMMING REFERENCE</A ></DT ><DD ><DL ><DT ><A HREF="#AEN164" >Procedures and Functions</A ></DT ><DT ><A HREF="#AEN218" >Comments</A ></DT ><DT ><A HREF="#AEN229" >Statements</A ></DT ><DT ><A HREF="#AEN336" >Expressions</A ></DT ><DT ><A HREF="#AEN352" >Include Feature</A ></DT ><DT ><A HREF="#AEN368" >Built-in Functions</A ></DT ><DT ><A HREF="#AEN377" >Value Types</A ></DT ><DT ><A HREF="#AEN474" >Iterators</A ></DT ><DT ><A HREF="#AEN505" >Arithmetic and Logic Functions</A ></DT ><DT ><A HREF="#AEN760" >Trigonometric and Spherical Calculations</A ></DT ><DT ><A HREF="#AEN867" >Person Functions</A ></DT ><DT ><A HREF="#AEN1353" >Family Functions</A ></DT ><DT ><A HREF="#AEN1567" >Other types of records</A ></DT ><DT ><A HREF="#AEN1601" >List Functions</A ></DT ><DT ><A HREF="#AEN1829" >Table Functions</A ></DT ><DT ><A HREF="#AEN1893" >GEDCOM Node Functions</A ></DT ><DT ><A HREF="#AEN2033" >Event and Date Functions</A ></DT ><DT ><A HREF="#AEN2498" >Date Arithmetic</A ></DT ><DT ><A HREF="#AEN2527" >Value Extraction Functions</A ></DT ><DT ><A HREF="#AEN2625" >User Interaction Functions</A ></DT ><DT ><A HREF="#AEN2765" >String Functions</A ></DT ><DT ><A HREF="#AEN3074" >Output Mode Functions</A ></DT ><DT ><A HREF="#AEN3265" >Person Set Functions and GEDCOM Extraction</A ></DT ><DT ><A HREF="#AEN3540" >Record Update Functions</A ></DT ><DT ><A HREF="#AEN3610" >Record Linking Functions</A ></DT ><DT ><A HREF="#AEN3637" >Miscellaneous Functions</A ></DT ><DT ><A HREF="#AEN3813" >Deprecated Functions</A ></DT ></DL ></DD ></DL ></DIV ><DIV CLASS="chapter" ><HR><H1 ><A NAME="AEN12" ></A > Report Programming Manual </H1 ><DIV CLASS="sect1" ><H2 CLASS="sect1" ><A NAME="AEN14" ></A >Introduction</H2 ><P > The <TT CLASS="application" >LifeLines</TT > programming subsystem lets you produce reports in any style or layout. You may generate files in <TT CLASS="application" >troff</TT >, <TT CLASS="application" >Postscript</TT >, <TT CLASS="application" >TeX</TT >, <SPAN CLASS="acronym" >SGML</SPAN > or any other <SPAN CLASS="acronym" >ASCII</SPAN >-based format, for further text processing and printing. You access the report generator by choosing the r command from the main menu. You may also use the programming subsystem to create query and other processing programs that write their results directly upon the screen. For example, there is a <TT CLASS="application" >LifeLines</TT > program that computes the relationship between any two persons in a database. </P ><P > Each <TT CLASS="application" >LifeLines</TT > program is written in the <TT CLASS="application" >LifeLines</TT > programming language, and the programs are stored in normal files. When you direct <TT CLASS="application" >LifeLines</TT > to run a program, it asks you for the name of the program file, asks you where you want the program's output written, and then runs the program. </P ></DIV ><DIV CLASS="sect1" ><HR><H2 CLASS="sect1" ><A NAME="AEN28" ></A >Tutorial Ahnentafel report</H2 ><P > For example, say you want <TT CLASS="application" >LifeLines</TT > to generate an ahnentafel (ancestor) report for Tom Wetmore. Such a report would show Tom Wetmore, his parents, grandparents, great-grandparents, and so on. It would like like the following: <DIV CLASS="example" ><A NAME="AEN32" ></A ><P ><B >Example 1. Example of ahnentafel report </B ></P ><P CLASS="literallayout" ><br> 1. Thomas Trask WETMORE IV<br> b. 18 December 1949, New London, Connecticut<br> 2. Thomas Trask WETMORE III<br> b. 15 October 1925, New London, Connecticut<br> 3. Joan Marie HANCOCK<br> b. 6 June 1928, New London, Connecticut<br> 4. Thomas Trask WETMORE Jr<br> b. 5 May 1896, New London, Connecticut<br> d. 8 November 1970, New London, Connecticut<br> 5. Vivian Genevieve BROWN<br> b. 5 April 1896, Mondovi, Wisconsin<br> 6. Richard James HANCOCK<br> b. 18 August 1904, New London, Connecticut<br> d. 24 December 1976, Waterford, Connecticut<br> 7. Muriel Armstrong SMITH<br> b. 28 October 1905, New Haven, Connecticut<br> 8. Thomas Trask WETMORE Sr<br> b. 13 March 1866, St. Mary's Bay, Nova Scotia<br> d. 17 February 1947, New London, Connecticut<br> 9. Margaret Ellen KANEEN<br> b. 27 October 1859, Liverpool, England<br> d. 10 May 1900, New London, Connecticut<br> ... lots more</P ></DIV > </P ><P > Here is a <TT CLASS="application" >LifeLines</TT > program that generates this report: <DIV CLASS="example" ><A NAME="AEN37" ></A ><P ><B >Example 2. Example of ahnentafel report script </B ></P ><TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="programlisting" > /* * @progname ahnentafel_tutorial.ll * @version 1.0 * @author Wetmore * @category sample * @output text * @description * * Generate an ahnentafel chart for the selected person (tutorial sample). */ proc main () { getindi(indi) list(ilist) list(alist) enqueue(ilist, indi) /* list of people needing to be displayed */ enqueue(alist, 1) /* ancestor numbers for people on ilist */ /* Our basic loop is we take the next person who needs to be displayed, display them, and then record their parents as needing to be displayed. */ while (indi, dequeue(ilist)) { /* display person we just pulled off list */ set(ahnen, dequeue(alist)) d(ahnen) ". " name(indi) nl() if (e, birth(indi)) { " b. " long(e) nl() } if (e, death(indi)) { " d. " long(e) nl() } /* add person's parents to list to display */ if (par, father(indi)) { enqueue(ilist, par) enqueue(alist, mul(2,ahnen)) } if (par,mother(indi)) { enqueue(ilist, par) enqueue(alist, add(1,mul(2,ahnen))) } } } </PRE ></TD ></TR ></TABLE ></DIV > </P ><P > Say this program is in the file <TT CLASS="filename" >ahnentafel_tutorial</TT >. When you choose the <B CLASS="keycap" >r</B > option from the main menu, <TT CLASS="application" >LifeLines</TT > asks: <TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="screen" > What is the name of the report program? enter string: </PRE ></TD ></TR ></TABLE > </P ><P > You enter <TT CLASS="userinput" ><B ><TT CLASS="literal" >ahnentafel_tutorial</TT ></B ></TT >. Since the program generates a report, <TT CLASS="application" >LifeLines</TT > asks where to write that report: <TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="screen" > What is the name of the output file? enter file name: </PRE ></TD ></TR ></TABLE > </P ><P > You enter a file name, say <TT CLASS="userinput" ><B ><TT CLASS="filename" >my.ahnen</TT ></B ></TT >. <TT CLASS="application" >LifeLines</TT > reads the program ahnen, executes the program, and writes the report output to <TT CLASS="filename" >my.ahnen</TT >. <TT CLASS="application" >LifeLines</TT > reports any syntax or run-time errors found while trying to run the program. </P ><P > A <TT CLASS="application" >LifeLines</TT > program is made up of <SPAN CLASS="type" >procedures</SPAN > and <SPAN CLASS="type" >functions</SPAN >; every program must contain at least one <SPAN CLASS="type" >procedure</SPAN > named <TT CLASS="literal" >main</TT >. The <TT CLASS="literal" >main</TT > <SPAN CLASS="type" >procedure</SPAN > runs first; it may call other <SPAN CLASS="type" >procedures</SPAN >, <SPAN CLASS="type" >functions</SPAN > and <SPAN CLASS="type" >built-in functions</SPAN >. In the ahnentafel example there is only one <SPAN CLASS="type" >procedure</SPAN >. </P ><P > In the example program, there are some comments at the top, to tell the reader a bit about the program. The comments run from <TT CLASS="literal" >/*</TT > to <TT CLASS="literal" >*/</TT >, and are not necessary (but are suggested). </P ><P > A <SPAN CLASS="type" >procedure</SPAN > body is a sequence of <SPAN CLASS="type" >statements</SPAN >. In the example program, the first five <SPAN CLASS="type" >statements</SPAN > are: <TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="programlisting" > getindi(indi) list(ilist) list(alist) enqueue(ilist, indi) enqueue(alist, 1) </PRE ></TD ></TR ></TABLE > </P ><P > The first <SPAN CLASS="type" >statement</SPAN > calls the <TT CLASS="function" >getindi</TT > (get individual) <SPAN CLASS="type" >built-in function</SPAN >, which causes <TT CLASS="application" >LifeLines</TT > to ask you to identify a person using the zip browse style of identification: <TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="screen" > Identify person for interpreted report enter name: </PRE ></TD ></TR ></TABLE > </P ><P > After you identify a person, he or she is assigned to the variable <TT CLASS="varname" >indi</TT >. The next two <SPAN CLASS="type" >statements</SPAN > declare two <SPAN CLASS="type" >list variables</SPAN >, <TT CLASS="varname" >ilist</TT > and <TT CLASS="varname" >alist</TT >. <SPAN CLASS="type" >Lists</SPAN > hold sequences of things; there are operations for placing things on lists, taking things off, and iterating through the list elements. In the example, <TT CLASS="varname" >ilist</TT > holds a list of ancestors, in ahnentafel order, who have not yet been reported on, and <TT CLASS="varname" >alist</TT > holds their respective ahnentafel numbers. </P ><P > The next two statements call the <TT CLASS="function" >enqueue</TT > function, adding the first members to both lists. The person identified by the <TT CLASS="function" >getindi</TT > function is made the first member of <TT CLASS="varname" >ilist</TT >, and the number one, this person's ahnentafel number, is made the first member of <TT CLASS="varname" >alist</TT >. </P ><P > The rest of the program is: <TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="programlisting" > while (indi, dequeue(ilist)) { set(ahnen, dequeue(alist)) d(ahnen) ". " name(indi) nl() if (e, birth(indi)) { " b. " long(e) nl() } if (e, death(indi)) { " d. " long(e) nl() } if (par, father(indi)) { enqueue(ilist, par) enqueue(alist, mul(2,ahnen)) } if (par, mother(indi)) { enqueue(ilist, par) enqueue(alist, add(1,mul(2,ahnen))) } } </PRE ></TD ></TR ></TABLE > </P ><P > This is a loop that iteratively removes persons and their ahnentafel numbers from the two lists, and then prints their names and birth and death information. If the persons have parents in the database, their parents and their parents' ahnentafel numbers are then put at the ends of the lists. The loop iterates until the list is empty. </P ><P > The loop is a <SPAN CLASS="type" >while</SPAN > loop statement. The line: <TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="programlisting" > while (indi, dequeue(ilist)) { </PRE ></TD ></TR ></TABLE > removes (via <TT CLASS="function" >dequeue</TT >) a person from <TT CLASS="varname" >ilist</TT >, and assigns the person to variable <TT CLASS="varname" >indi</TT >. As long as there are persons on <TT CLASS="varname" >ilist</TT >, another iteration of the loop follows. </P ><P > The statement:<TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="programlisting" > set(ahnen, dequeue(alist))</PRE ></TD ></TR ></TABLE >is an <SPAN CLASS="type" >assignment</SPAN > statement. The second argument is evaluated; its value is assigned to the first argument, which must be a variable. Here the next number in <TT CLASS="varname" >alist</TT > is removed and assigned to variable <TT CLASS="varname" >ahnen</TT >. This is the ahnentafel number of the person just removed from <TT CLASS="varname" >ilist</TT >. </P ><P > The line:<TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="programlisting" > d(ahnen) ". " name(indi) nl()</PRE ></TD ></TR ></TABLE >contains four <SPAN CLASS="type" >expression</SPAN > statements; when expressions are used as statements, their values, if any, are treated as strings and written directly to the report output file. The <TT CLASS="function" >d</TT > function converts its integer argument to a numeric string. The ". " is a literal (constant) string value. The <TT CLASS="function" >name</TT > function returns the default form of a person's name. The <TT CLASS="function" >nl</TT > function returns a string containing the newline character. </P ><P > The next two lines: <TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="programlisting" > if (e, birth(indi)) { " b. " long(e) nl() } if (e, death(indi)) { " d. " long(e) nl() } </PRE ></TD ></TR ></TABLE > write out basic birth and death information about a person. These lines are <SPAN CLASS="type" >if</SPAN > statements. The second argument in the conditional is evaluated and assigned to the first argument, which must be a variable. The first <SPAN CLASS="type" >if</SPAN > statement calls the birth function, returning the first birth event in a person's record. If the event exists it is assigned to variable <TT CLASS="varname" >e</TT >, and the <SPAN CLASS="type" >body</SPAN > (the items between the curly brackets) of the <SPAN CLASS="type" >if</SPAN > statement is executed. The <SPAN CLASS="type" >body</SPAN > consists of three <SPAN CLASS="type" >expression</SPAN > statements: a literal, and calls to the <TT CLASS="function" >long</TT > and <TT CLASS="function" >nl</TT > functions. <TT CLASS="function" >Long</TT > takes an <TT CLASS="parameter" ><I >event</I ></TT > and returns the values of the first <TT CLASS="structfield" ><I >DATE</I ></TT > and <TT CLASS="structfield" ><I >PLAC</I ></TT > lines in the <SPAN CLASS="type" >event</SPAN >. </P ><P > Finally in the program is:<TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="programlisting" > if (par, father(indi)) { enqueue(ilist,par) enqueue(alist,mul(2,ahnen)) } if (par,mother(indi)) { enqueue(ilist,par) enqueue(alist,add(1,mul(2,ahnen))) }</PRE ></TD ></TR ></TABLE > </P ><P > These lines add the father and mother of the current person, if either or both are in the database, to <TT CLASS="varname" >ilist</TT >. They also compute and add the parents' ahnentafel numbers to <TT CLASS="varname" >alist</TT >. A father's ahnentafel number is twice that of his child. A mother's ahnentafel number is twice that of her child plus one. These values are computed with the <TT CLASS="function" >mul</TT > and <TT CLASS="function" >add</TT > functions. </P ></DIV ><DIV CLASS="sect1" ><HR><H2 CLASS="sect1" ><A NAME="AEN141" ></A >Template for creating new reports</H2 ><P > The following is a good template to use when creating a new report from scratch. </P ><TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="programlisting" > /* * @progname reportname * @version Version Number. * @author report author and possible email address * @category ???? * @output Format of Report Output * @description The following paragraph is used to populate index.html. * * This report .... (Note, the text in the 1st paragraph following the @keyword * lines is used as a description in the automatically generated index.html * file. The text following the @description is not used for this purpose.) * The description lines can be written with or without the *'s on the left * they will be removed when generating index.html. * * Additional descriptive text */ proc main() { } </PRE ></TD ></TR ></TABLE ></DIV ><DIV CLASS="sect1" ><HR><H2 CLASS="sect1" ><A NAME="AEN145" ></A >Invoking Reports</H2 ><P > As mentioned earlier, reports may be invoked interactively from the main menu via the <B CLASS="keycap" >r</B > option from the main menu. </P ><P > Alternatively, llines may be called with the -x option to have it immediately run a report. For example, to have lifelines run the example ahnentafel report above, on a database named wetmore, this command <B CLASS="command" >llines -x ahnentafel_tutorial wetmore</B > would be used. </P ><P > For more efficient operation from scripts, the lifelines distribution includes a smaller program <B CLASS="command" >llexec</B > which includes all functionality of lifelines except the curses GUI. <B CLASS="command" >llexec</B > is made specifically, therefore, for invocations such as <B CLASS="command" >llexec -x ahnentafel_tutorial wetmore</B > </P ></DIV ></DIV ><DIV CLASS="chapter" ><HR><H1 ><A NAME="AEN155" ></A > <TT CLASS="application" >LIFELINES</TT > PROGRAMMING REFERENCE </H1 ><P > <TT CLASS="application" >LifeLines</TT > programs are stored in files you edit with a screen editor. Programs are not edited from within the <TT CLASS="application" >LifeLines</TT > program; edit them as you would any text file. The programs may be stored in any directories; they do not have to be kept in or associated with <TT CLASS="application" >LifeLines</TT > databases. You may set the <TT CLASS="envar" >LLPROGRAMS</TT > shell variable to hold a list of directories that <TT CLASS="application" >LifeLines</TT > will use to automatically search for programs when you request program execution. </P ><DIV CLASS="sect1" ><HR><H2 CLASS="sect1" ><A NAME="AEN164" ></A >Procedures and Functions</H2 ><P > A <TT CLASS="application" >LifeLines</TT > program is made up of one or more <SPAN CLASS="type" >procedures</SPAN > and <SPAN CLASS="type" >functions</SPAN >. A <SPAN CLASS="type" >procedure</SPAN > has format:<TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="synopsis" >proc name(params) { statements }</PRE ></TD ></TR ></TABLE > </P ><P > <SPAN CLASS="symbol" >Name</SPAN > is the name of the <SPAN CLASS="type" >procedure</SPAN >, <SPAN CLASS="symbol" >params</SPAN > is an optional list of <SPAN CLASS="type" >parameters</SPAN > separated by commas, and <SPAN CLASS="symbol" >statements</SPAN > is a list of statements that make up the <SPAN CLASS="type" >procedure</SPAN > body. Report generation begins with the first <SPAN CLASS="type" >statement</SPAN > in the <SPAN CLASS="type" >procedure</SPAN > named <TT CLASS="literal" >main</TT >. <SPAN CLASS="type" >Procedures</SPAN > may call other <SPAN CLASS="type" >procedures</SPAN > and <SPAN CLASS="type" >functions</SPAN >. <SPAN CLASS="type" >Procedures</SPAN > are called with the <SPAN CLASS="type" >call</SPAN > statement described below.When a <SPAN CLASS="type" >procedure</SPAN > is called, the <SPAN CLASS="type" >statements</SPAN > making up its <SPAN CLASS="type" >body</SPAN > are executed. </P ><P > A function has format:<TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="synopsis" >func name(params) { statements }</PRE ></TD ></TR ></TABLE > </P ><P > <SPAN CLASS="symbol" >Name</SPAN >, <SPAN CLASS="symbol" >params</SPAN > and <SPAN CLASS="symbol" >statements</SPAN > are defined as in <SPAN CLASS="type" >procedures</SPAN >. <SPAN CLASS="type" >Functions</SPAN > may call other <SPAN CLASS="type" >procedures</SPAN > and <SPAN CLASS="type" >functions</SPAN >. When a <SPAN CLASS="type" >function</SPAN > is called the <SPAN CLASS="type" >statements</SPAN > that make it up are executed. A <SPAN CLASS="type" >function</SPAN > differs from a <SPAN CLASS="type" >procedure</SPAN > by returning a <SPAN CLASS="type" >value</SPAN > to the <SPAN CLASS="type" >procedure</SPAN > or <SPAN CLASS="type" >function</SPAN > that calls it. Values are returned by the <SPAN CLASS="type" >return</SPAN > statement, described below. <SPAN CLASS="type" >Recursive functions</SPAN > are allowed. A <SPAN CLASS="type" >function</SPAN > is called by invoking it in an <SPAN CLASS="type" >expression</SPAN >. </P ><P > <SPAN CLASS="type" >Function</SPAN > and <SPAN CLASS="type" >procedure</SPAN > parameters are passed by value except for <SPAN CLASS="type" >list</SPAN >, <SPAN CLASS="type" >set</SPAN > and <SPAN CLASS="type" >table</SPAN > types which are passed by reference. Redeclaration of a parameter instantiates a new variable of the stated or implied type. The previous instance continues to exist in the scope of the caller. </P ><P > </P ></DIV ><DIV CLASS="sect1" ><HR><H2 CLASS="sect1" ><A NAME="AEN218" ></A >Comments</H2 ><P > You may comment your <TT CLASS="application" >LifeLines</TT > programs using the following notation:<TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="programlisting" > /*...comment text including any characters except */... */</PRE ></TD ></TR ></TABLE > </P ><P > These comments may be inserted anywhere in the program file. </P ><P > You should put in some report header comments, because they will provide useful text for your report when it is included in the report list seen by the user who uses the lifelines pick report menu function. Report header comments are some specific comments at the top of the report, with keywords preceded by @ signs. The following is an illustration of report header comments, with explanations inside them: </P ><TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="programlisting" > /* * @progname The name of the report without the extension. This shows in the pick report option. * @version Version Number of the report. This is stored here and not in the report name. * @author Name of the author of this report and email address if he/she desires. * @category ???? * @output Modifies Database | text | HTML | GEDCOM | RTF | XML | PostScript | etc. * @description The first paragraph after this is used to generate the description in the index.html. This report .... */ </PRE ></TD ></TR ></TABLE ><P > Comments begin with a <TT CLASS="literal" >/*</TT > and end with a <TT CLASS="literal" >*/</TT >. Comments may appear on lines of their own or on lines that have program constructs. Comments may span many lines. Comments may not be nested. </P ></DIV ><DIV CLASS="sect1" ><HR><H2 CLASS="sect1" ><A NAME="AEN229" ></A >Statements</H2 ><P > There are a number of <SPAN CLASS="type" >statement</SPAN > types. The simplest is an <SPAN CLASS="type" >expression</SPAN > statement, an expression that is not part of any other <SPAN CLASS="type" >statement</SPAN > or <SPAN CLASS="type" >expression</SPAN >. <SPAN CLASS="type" >Expressions</SPAN > are defined more fully below. An <SPAN CLASS="type" >expression</SPAN > statement is evaluated, and if its value is <SPAN CLASS="returnvalue" >non-null</SPAN > (non-zero), it is assumed to be a <SPAN CLASS="type" >string</SPAN >, and written to the program output file. If its value is <SPAN CLASS="returnvalue" >null</SPAN >, nothing is written to the output file. For example, the expression <TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="synopsis" >name(indi)</PRE ></TD ></TR ></TABLE >, where <SPAN CLASS="symbol" >indi</SPAN > is a person, returns the person's name and writes it to the output file. On the other hand, the expression <TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="synopsis" >set(n, nspouses(indi))</PRE ></TD ></TR ></TABLE > assigns the variable <TT CLASS="varname" >n</TT > the number of spouses that person <TT CLASS="varname" >indi</TT > has, but since <TT CLASS="function" >set</TT > returns <SPAN CLASS="returnvalue" >null</SPAN >, nothing is written to the output file. </P ><P > The programming language includes <SPAN CLASS="type" >if</SPAN > statements, <SPAN CLASS="type" >while</SPAN > statements and <SPAN CLASS="type" >procedure call</SPAN > statements, with the following formats: <TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="synopsis" >if ([varb,] expr) { statements } [ elsif ([varb], expr) { statements } ]* [ else { statements } ] </PRE ></TD ></TR ></TABLE > <TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="synopsis" >while ([varb,] expr ) { statements }</PRE ></TD ></TR ></TABLE > <TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="synopsis" >call name(args)</PRE ></TD ></TR ></TABLE > </P ><P > Square brackets indicate optional parts of the statement syntax. An <SPAN CLASS="type" >if</SPAN > statement is executed by first evaluating the conditional expression in the <SPAN CLASS="type" >if</SPAN > clause. If <SPAN CLASS="returnvalue" >non-zero</SPAN >, the statements in the <SPAN CLASS="type" >if</SPAN > clause are evaluated, and the rest of the <SPAN CLASS="type" >if</SPAN > statement, if any, is ignored. If the value is <SPAN CLASS="returnvalue" >zero</SPAN >, and there is an <SPAN CLASS="type" >elsif</SPAN > clause following, the conditional in the <SPAN CLASS="type" >elsif</SPAN > clause is evaluated, and if <SPAN CLASS="returnvalue" >non-zero</SPAN >, the statements in that clause are executed. <SPAN CLASS="type" >Conditionals</SPAN > are evaluated until one of them is <SPAN CLASS="returnvalue" >non-zero</SPAN >, or until there are no more. If no conditional is <SPAN CLASS="returnvalue" >non-zero</SPAN >, and if the <SPAN CLASS="type" >if</SPAN > statement ends with an <SPAN CLASS="type" >else</SPAN > clause, the statements in the <SPAN CLASS="type" >else</SPAN > clause are executed. There are two forms of <SPAN CLASS="type" >conditional</SPAN > expressions. If the <SPAN CLASS="type" >conditional</SPAN > is a single <SPAN CLASS="type" >expression</SPAN >, it is simply evaluated. If the <SPAN CLASS="type" >conditional</SPAN > is a <SPAN CLASS="type" >variable</SPAN > followed by an <SPAN CLASS="type" >expression</SPAN >, the <SPAN CLASS="type" >expression</SPAN > is evaluated and its value is assigned to the variable. </P ><P > Note that <SPAN CLASS="type" >if</SPAN > treats null strings as false, but empty strings as true. This has the benefit that <TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="programlisting" > if (birth(indi)) </PRE ></TD ></TR ></TABLE > will return <SPAN CLASS="returnvalue" >true</SPAN > if there is a BIRT record, even if it is empty, but will return false if there is no BIRT record at all. </P ><P > The <SPAN CLASS="type" >while</SPAN > statement provides a looping mechanism. The <SPAN CLASS="type" >conditional</SPAN > is evaluated, and if <SPAN CLASS="returnvalue" >non-zero</SPAN >, the <SPAN CLASS="type" >body</SPAN > of the loop is executed. After each iteration the <SPAN CLASS="type" >expression</SPAN > is reevaluated; as long as it remains <SPAN CLASS="returnvalue" >non-zero</SPAN >, the loop is repeated. </P ><P > The <SPAN CLASS="type" >call</SPAN > statement provides procedure calls. <SPAN CLASS="symbol" >Name</SPAN > must match one of the <SPAN CLASS="type" >procedures</SPAN > defined in the report program. <SPAN CLASS="symbol" >Args</SPAN > is a list of <SPAN CLASS="type" >argument</SPAN > expressions separated by commas. <SPAN CLASS="type" >Recursion</SPAN > is allowed. When a <SPAN CLASS="type" >call</SPAN > is executed, the values of its <SPAN CLASS="type" >arguments</SPAN > are evaluated and used to initialize the procedure's <SPAN CLASS="type" >parameters</SPAN >. The <SPAN CLASS="type" >procedure</SPAN > is then executed. When the <SPAN CLASS="type" >procedure</SPAN > completes, execution resumes with the first item after the call. </P ><P > The following report language statements are commonly encountered only near the top of a report: <TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="synopsis" >char_encoding(string)</PRE ></TD ></TR ></TABLE > <TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="synopsis" >require(string)</PRE ></TD ></TR ></TABLE > <TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="synopsis" >option(string)</PRE ></TD ></TR ></TABLE > <TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="synopsis" >include(string)</PRE ></TD ></TR ></TABLE > <TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="synopsis" >global(varb)</PRE ></TD ></TR ></TABLE > </P ><P > The <SPAN CLASS="type" >char_encoding</SPAN > statement specifies what character encoding scheme is used by the report, so that the report processor can correctly interpret bytes not in ASCII (e.g., accented letters). An example specifying a character encoding common in Western Europe: <TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="programlisting" > char_encoding("ISO-8859-1") </PRE ></TD ></TR ></TABLE > The <SPAN CLASS="type" >option</SPAN > statement allows the report writer to specify options. The only option currently available is "explicitvars", which causes any use of variables not previously declared or set to be reported as a parsing error. The <SPAN CLASS="type" >require</SPAN > statement allows the report writer to specify that this report needs a version of the report interpreter no older than that specified. The <SPAN CLASS="type" >include</SPAN > statement includes the contents of another file into the current file; its <TT CLASS="parameter" ><I >string</I ></TT > expression is the name of another <TT CLASS="application" >LifeLines</TT > program file. It is described in more detail below. The <SPAN CLASS="type" >global</SPAN > statement must be used outside the scope of any <SPAN CLASS="type" >procedure</SPAN > or <SPAN CLASS="type" >function</SPAN >; it declares a <TT CLASS="parameter" ><I >variable</I ></TT > to have global scope. The <TT CLASS="parameter" ><I >variable</I ></TT > is initialized to 0. </P ><P > The report language also includes the following statements, which mimic some common programming languages: <TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="synopsis" >set(varb, expr)</PRE ></TD ></TR ></TABLE > <TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="synopsis" >continue()</PRE ></TD ></TR ></TABLE > <TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="synopsis" >break()</PRE ></TD ></TR ></TABLE > <TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="synopsis" >return([expr])</PRE ></TD ></TR ></TABLE > </P ><P > The <SPAN CLASS="type" >set</SPAN > statement is the assignment statement; the <TT CLASS="parameter" ><I >expression</I ></TT > is evaluated, and its value is assigned to the <TT CLASS="parameter" ><I >variable</I ></TT >. The <SPAN CLASS="type" >continue</SPAN > statement jumps to the bottom of the current loop, but does not leave the loop. The <SPAN CLASS="type" >break</SPAN > statement breaks out of the most closely nested loop. The <SPAN CLASS="type" >return</SPAN > statement returns from the current <SPAN CLASS="type" >procedure</SPAN > or <SPAN CLASS="type" >function</SPAN >. <SPAN CLASS="type" >Procedures</SPAN > have return statements without expressions; <SPAN CLASS="type" >functions</SPAN > have return statements with expressions. None of these statements return a value, so none has a direct effect on program output. </P ></DIV ><DIV CLASS="sect1" ><HR><H2 CLASS="sect1" ><A NAME="AEN336" ></A >Expressions</H2 ><P > There are four types of expressions: <SPAN CLASS="type" >literals</SPAN >, <SPAN CLASS="type" >numbers</SPAN >, <SPAN CLASS="type" >variables</SPAN > and built-in or user defined function <SPAN CLASS="type" >calls</SPAN >. </P ><P > A <SPAN CLASS="type" >literal</SPAN > is any string enclosed in double quotes; its value is itself. A <SPAN CLASS="type" >number</SPAN > is any integer or floating point constant; its value is itself. A <SPAN CLASS="type" >variable</SPAN > is a named location that can be assigned different values during program execution. The value of a <SPAN CLASS="type" >variable</SPAN > is the last value assigned to it. <SPAN CLASS="type" >Variables</SPAN > do not have fixed type; at different times in a program, the same <SPAN CLASS="type" >variable</SPAN > may be assigned data of completely different types. An identifier followed by comma-separated list of expressions enclosed in parentheses, is either a <SPAN CLASS="type" >call</SPAN > to a built-in function or a <SPAN CLASS="type" >call</SPAN > to a user-defined function. </P ></DIV ><DIV CLASS="sect1" ><HR><H2 CLASS="sect1" ><A NAME="AEN352" ></A >Include Feature</H2 ><P > The <TT CLASS="application" >LifeLines</TT > programming language provides an <SPAN CLASS="type" >include</SPAN > feature. Using this feature one <TT CLASS="application" >LifeLines</TT > program can refer to other <TT CLASS="application" >LifeLines</TT > programs. This feature is provided by the include statement:<TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="synopsis" >include(string)</PRE ></TD ></TR ></TABLE >where <SPAN CLASS="symbol" >string</SPAN > is a quoted string that is the name of another <TT CLASS="application" >LifeLines</TT > program file. When an include statement is encountered, the program that it refers to is read at that point, exactly as if the contents of included file had been in the body of the original file at that point. This allows you to create <TT CLASS="application" >LifeLines</TT > program library files that can be used by many programs. Included files may in turn contain <SPAN CLASS="type" >include</SPAN > statements, and so on to any depth. <TT CLASS="application" >LifeLines</TT > will use the <TT CLASS="envar" >LLPROGRAMS</TT > shell variable, if set, to search for the <SPAN CLASS="type" >include</SPAN > files. Each file included with a include statement is only read once. If multiple include statements are encountered that include the same file, only the first statement has any effect. </P ><P > The only main procedure actually executed is the one in the report the user chose. main procedures in other reports which are included do not get run. This allows a module intended to be included in other programs to have a main procedure for test purposes. If multiple functions or procedures with the same name are included (other than the name main) a runtime error is generated and the program is not run. </P ></DIV ><DIV CLASS="sect1" ><HR><H2 CLASS="sect1" ><A NAME="AEN368" ></A >Built-in Functions</H2 ><P > There is a long list of <SPAN CLASS="type" >built-in functions</SPAN >, and this list will continue to grow for some time. The first subsection below describes the value types used in <TT CLASS="application" >LifeLines</TT > programs; these are the types of <SPAN CLASS="type" >variables</SPAN >, <SPAN CLASS="type" >function parameters</SPAN > and <SPAN CLASS="type" >function return values</SPAN >. In the remaining sections the <SPAN CLASS="type" >built-in functions</SPAN > are separated into logical categories and described. </P ></DIV ><DIV CLASS="sect1" ><HR><H2 CLASS="sect1" ><A NAME="AEN377" ></A >Value Types</H2 ><DIV CLASS="glosslist" ><DL ><DT ><B ><SPAN CLASS="type" >ANY</SPAN ></B ></DT ><DD ><P > union of all types </P ></DD ><DT ><B ><SPAN CLASS="type" >BOOL</SPAN ></B ></DT ><DD ><P > boolean (0 represents false; anything else represents true) </P ></DD ><DT ><B ><SPAN CLASS="type" >EVENT</SPAN ></B ></DT ><DD ><P > event; reference to substructure of nodes in a <SPAN CLASS="acronym" >GEDCOM</SPAN > record (reference) </P ></DD ><DT ><B ><SPAN CLASS="type" >FAM</SPAN ></B ></DT ><DD ><P > family; reference to a <SPAN CLASS="acronym" >GEDCOM</SPAN > FAM record (reference) </P ></DD ><DT ><B ><SPAN CLASS="type" >FLOAT</SPAN ></B ></DT ><DD ><P > floating point number (may be used anywhere an INT may be used) </P ></DD ><DT ><B ><SPAN CLASS="type" >INDI</SPAN ></B ></DT ><DD ><P > person; reference to a <SPAN CLASS="acronym" >GEDCOM</SPAN > INDI record (reference) </P ></DD ><DT ><B ><SPAN CLASS="type" >INT</SPAN ></B ></DT ><DD ><P > integer (on most systems a 32-bit signed value) </P ></DD ><DT ><B ><SPAN CLASS="type" >LIST</SPAN ></B ></DT ><DD ><P > arbitrary length list of any values (reference) </P ></DD ><DT ><B ><SPAN CLASS="type" >NODE</SPAN ></B ></DT ><DD ><P > <SPAN CLASS="acronym" >GEDCOM</SPAN > node; reference to a line in a <SPAN CLASS="acronym" >GEDCOM</SPAN > tree/record (reference) </P ></DD ><DT ><B ><SPAN CLASS="type" >NUMBER</SPAN ></B ></DT ><DD ><P > union of all arithmetic types (INT and FLOAT) </P ></DD ><DT ><B ><SPAN CLASS="type" >SET</SPAN ></B ></DT ><DD ><P > a collection of persons each with a value (see person sets below). </P ></DD ><DT ><B ><SPAN CLASS="type" >STRING</SPAN ></B ></DT ><DD ><P > text string </P ></DD ><DT ><B ><SPAN CLASS="type" >TABLE</SPAN ></B ></DT ><DD ><P > keyed look-up table (reference) </P ></DD ><DT ><B ><SPAN CLASS="type" >VOID</SPAN ></B ></DT ><DD ><P > type with no values </P ></DD ></DL ></DIV ><P > In the summaries of <SPAN CLASS="type" >built-in functions</SPAN > below, each function is shown with its <SPAN CLASS="type" >argument</SPAN > types and its <SPAN CLASS="type" >return</SPAN > type. The types are from the preceding list. Sometimes an <SPAN CLASS="type" >argument</SPAN > to a <SPAN CLASS="type" >built-in function</SPAN > must be a <SPAN CLASS="type" >variable</SPAN >; when this is so its type is given as <TT CLASS="varname" >XXX_V</TT >, where <SPAN CLASS="symbol" >XXX</SPAN > is one of the types above. The <SPAN CLASS="type" >built-ins</SPAN > do not check the types of their <SPAN CLASS="type" >arguments</SPAN >. <SPAN CLASS="type" >Variables</SPAN > can hold values of any type, though at any one time they will hold values of only one type. Note that <SPAN CLASS="type" >EVENT</SPAN > is a subtype of <SPAN CLASS="type" >NODE</SPAN >, and <SPAN CLASS="type" >BOOL</SPAN > is a subtype of <SPAN CLASS="type" >INT</SPAN >. Built-ins with type <SPAN CLASS="type" >VOID</SPAN > actually return <SPAN CLASS="returnvalue" >null</SPAN > (zero) values. </P ><P > Reference types (denoted above in parentheses) obey "pointer semantics", which is to say that assigning one to another variable results in both variables pointing at the same data (no copy is made). Therefore, if you pass a string to a function which changes the string, the caller does not see the change, because a string is not a reference type. On the other hand, if you pass a table to a function which alters the table, the caller does see the change, because a table is a reference type. </P ></DIV ><DIV CLASS="sect1" ><HR><H2 CLASS="sect1" ><A NAME="AEN474" ></A >Iterators</H2 ><P > The report generator provides a number of iterator statements for looping through genealogical and other types of data. For example, the <SPAN CLASS="type" >children</SPAN > statement iterates through the children of a family, the <SPAN CLASS="type" >spouses</SPAN > statement iterates through the spouses of a person, and the <SPAN CLASS="type" >families</SPAN > statement iterates through the families that a person is a spouse or parent in. </P ><P > Usually the first argument to the iterator is an expression that evaluates to an individual or a family. The other arguments of the iterator are variable names that are set with values for each iteration. The last argument is often a variable name used as a counter. It starts with the value of one and is increased by one for each iteration of the loop. After completion of the iteration, these variables have the value null. </P ><P > <TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="synopsis" >children(afam,indi,cnt) { commands }</PRE ></TD ></TR ></TABLE > For example, the first argument to <SPAN CLASS="type" >children</SPAN > is the family that the iterator will operate on. This iterator will execute the block of commands for each child in the specified family. The second argument is set to each child in the family in the order they are listed in the family and the third argument is the loop counter which starts at one and is incremented by one each time the the block of commands is executed. The two variables indi and cnt will have the value null after the iteration has completed. </P ><P > For the purpose of traversing all records in the database, the following iterators may be used: <DIV CLASS="informaltable" ><A NAME="AEN485" ></A ><P ></P ><TABLE BORDER="0" BGCOLOR="#E0E0E0" CELLSPACING="0" CELLPADDING="4" CLASS="CALSTABLE" ><TBODY ><TR ><TD WIDTH="96" ALIGN="LEFT" VALIGN="MIDDLE" >forindi</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" >Iterate over all people</TD ></TR ><TR ><TD WIDTH="96" ALIGN="LEFT" VALIGN="MIDDLE" >forfam</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" >Iterate over all families</TD ></TR ><TR ><TD WIDTH="96" ALIGN="LEFT" VALIGN="MIDDLE" >forsour</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" >Iterate over all sources</TD ></TR ><TR ><TD WIDTH="96" ALIGN="LEFT" VALIGN="MIDDLE" >foreven</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" >Iterate over all events</TD ></TR ><TR ><TD WIDTH="96" ALIGN="LEFT" VALIGN="MIDDLE" >forothr</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" >Iterate over all other recoure types</TD ></TR ></TBODY ></TABLE ><P ></P ></DIV > </P ><P > All the iterators are described in more detail later in the section where their definition occurs. </P ></DIV ><DIV CLASS="sect1" ><HR><H2 CLASS="sect1" ><A NAME="AEN505" ></A >Arithmetic and Logic Functions</H2 ><DIV CLASS="glosslist" ><DL ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN510" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >NUMBER <TT CLASS="function" >add</TT ></CODE >(<TT CLASS="parameter" ><I >NUMBER</I ></TT >, <TT CLASS="parameter" ><I >NUMBER</I ></TT > <TT CLASS="parameter" ><I >...</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > addition - two to 32 arguments </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN522" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >NUMBER <TT CLASS="function" >sub</TT ></CODE >(<TT CLASS="parameter" ><I >NUMBER</I ></TT >, <TT CLASS="parameter" ><I >NUMBER</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > subtraction </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN533" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >NUMBER <TT CLASS="function" >mul</TT ></CODE >(<TT CLASS="parameter" ><I >NUMBER</I ></TT >, <TT CLASS="parameter" ><I >NUMBER</I ></TT > <TT CLASS="parameter" ><I >...</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > multiplication - two to 32 arguments </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN545" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >NUMBER <TT CLASS="function" >div</TT ></CODE >(<TT CLASS="parameter" ><I >NUMBER</I ></TT >, <TT CLASS="parameter" ><I >NUMBER</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > division </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN556" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >INT <TT CLASS="function" >mod</TT ></CODE >(<TT CLASS="parameter" ><I >INT</I ></TT >, <TT CLASS="parameter" ><I >INT</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > modulus (remainder) </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN567" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >NUMBER <TT CLASS="function" >exp</TT ></CODE >(<TT CLASS="parameter" ><I >NUMBER</I ></TT >, <TT CLASS="parameter" ><I >INT</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > exponentiation </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN578" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >NUMBER <TT CLASS="function" >neg</TT ></CODE >(<TT CLASS="parameter" ><I >NUMBER</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > negation </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN588" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >FLOAT <TT CLASS="function" >float</TT ></CODE >(<TT CLASS="parameter" ><I >INT</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > convert int to float </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN598" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >INT <TT CLASS="function" >int</TT ></CODE >(<TT CLASS="parameter" ><I >FLOAT</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > convert float to int </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN608" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >incr</TT ></CODE >(<TT CLASS="parameter" ><I >NUMBER</I ></TT >,<TT CLASS="parameter" ><I >NUMBER</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > increment variable by second argument (or by 1 if no second argument) </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN619" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >decr</TT ></CODE >(<TT CLASS="parameter" ><I >NUMBER</I ></TT >,<TT CLASS="parameter" ><I >NUMBER</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > decrement variable by second argument (or by 1 if no second argument) </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN630" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >BOOL <TT CLASS="function" >and</TT ></CODE >(<TT CLASS="parameter" ><I >BOOL</I ></TT >, <TT CLASS="parameter" ><I >BOOL</I ></TT > <TT CLASS="parameter" ><I >...</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > logical and - two to 32 arguments </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN642" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >BOOL <TT CLASS="function" >or</TT ></CODE >(<TT CLASS="parameter" ><I >BOOL</I ></TT >, <TT CLASS="parameter" ><I >BOOL</I ></TT > <TT CLASS="parameter" ><I >...</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > logical or - two to 32 arguments </P ></DD ><DT ><B > <DIV CLASS="funcsynopsis" ><A NAME="AEN654" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >BOOL <TT CLASS="function" >not</TT ></CODE >(<TT CLASS="parameter" ><I >BOOL</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > logical not </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN664" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >BOOL <TT CLASS="function" >eq</TT ></CODE >(<TT CLASS="parameter" ><I >ANY</I ></TT >, <TT CLASS="parameter" ><I >ANY</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > equality (not strings) </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN675" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >BOOL <TT CLASS="function" >ne</TT ></CODE >(<TT CLASS="parameter" ><I >ANY</I ></TT >, <TT CLASS="parameter" ><I >ANY</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > non-equality </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN686" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >BOOL <TT CLASS="function" >lt</TT ></CODE >(<TT CLASS="parameter" ><I >ANY</I ></TT >, <TT CLASS="parameter" ><I >ANY</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > less than </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN697" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >BOOL <TT CLASS="function" >gt</TT ></CODE >(<TT CLASS="parameter" ><I >ANY</I ></TT >, <TT CLASS="parameter" ><I >ANY</I ></TT > );</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > greater than </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN708" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >BOOL <TT CLASS="function" >le</TT ></CODE >(<TT CLASS="parameter" ><I >ANY</I ></TT >, <TT CLASS="parameter" ><I >ANY</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > less than or equal </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN719" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >BOOL <TT CLASS="function" >ge</TT ></CODE >(<TT CLASS="parameter" ><I >ANY</I ></TT >, <TT CLASS="parameter" ><I >ANY</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > greater than or equal </P ></DD ></DL ></DIV ><P > <TT CLASS="function" >Add</TT >, <TT CLASS="function" >sub</TT >, <TT CLASS="function" >mul</TT > and <TT CLASS="function" >div</TT > do normal arithmetic of integer or floating values. If any operand is float, the result is float. Functions <TT CLASS="function" >add</TT > and <TT CLASS="function" >mul</TT > can have two to 32 arguments; the sum or product of the full set of arguments is computed. Functions <TT CLASS="function" >sub</TT > and <TT CLASS="function" >div</TT > have two arguments each; <TT CLASS="function" >sub</TT > subtracts its second argument from its first, and <TT CLASS="function" >div</TT > divides its first argument by its second. The <TT CLASS="function" >mod</TT > function returns the remainder after dividing the first parameter by the second. If the second argument to <TT CLASS="function" >div</TT > or <TT CLASS="function" >mod</TT > is zero, these functions return 0 and generate a run time error. <TT CLASS="function" >Exp</TT > performs integer exponentiation. <TT CLASS="function" >Neg</TT > negates its argument. The functions <TT CLASS="function" >float</TT > and <TT CLASS="function" >int</TT > can be used to explicitly convert a value to float or int where needed. </P ><P > <TT CLASS="function" >Incr</TT > and <TT CLASS="function" >decr</TT > increment by one and decrement by one, respectively, the value of a variable. The argument to both functions must be a variable. These functions take an optional second argument which is the amount to increment or decrement the variable by. </P ><P > <TT CLASS="function" >And</TT > and <TT CLASS="function" >or</TT > do logical operations. Both functions take two to 32 arguments. All arguments are and'ed or or'ed together, respectively. The arguments are evaluated from left to right, but only up to the point where the final value of the function becomes known. <TT CLASS="function" >Not</TT > does the logical not operation. </P ><P > <TT CLASS="function" >Eq</TT >, <TT CLASS="function" >ne</TT >, <TT CLASS="function" >lt</TT >, <TT CLASS="function" >le</TT >, <TT CLASS="function" >gt</TT > and <TT CLASS="function" >ge</TT > evaluate the six ordering relationships between two integers. </P ></DIV ><DIV CLASS="sect1" ><HR><H2 CLASS="sect1" ><A NAME="AEN760" ></A >Trigonometric and Spherical Calculations</H2 ><DIV CLASS="glosslist" ><DL ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN765" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >FLOAT <TT CLASS="function" >sin</TT ></CODE >(<TT CLASS="parameter" ><I >FLOAT</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > compute sine of argument in degrees </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN775" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >FLOAT <TT CLASS="function" >cos</TT ></CODE >(<TT CLASS="parameter" ><I >FLOAT</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > compute cosine of argument in degrees </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN785" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >FLOAT <TT CLASS="function" >tan</TT ></CODE >(<TT CLASS="parameter" ><I >FLOAT</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > compute tangent of argument in degrees </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN795" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >FLOAT <TT CLASS="function" >arcsin</TT ></CODE >(<TT CLASS="parameter" ><I >FLOAT</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > compute inverse sine of argument </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN805" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >FLOAT <TT CLASS="function" >arccos</TT ></CODE >(<TT CLASS="parameter" ><I >FLOAT</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > compute inverse cosine of argument </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN815" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >FLOAT <TT CLASS="function" >arctan</TT ></CODE >(<TT CLASS="parameter" ><I >FLOAT</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > compute inverse tangent of argument </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN825" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >dms2deg</TT ></CODE >(<TT CLASS="parameter" ><I >INT degree</I ></TT >, <TT CLASS="parameter" ><I >INT minute</I ></TT >, <TT CLASS="parameter" ><I >INT second</I ></TT >, <TT CLASS="parameter" ><I >FLOAT_V decimal</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > convert (degree, minute, second) to decimal degrees </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN838" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >void <TT CLASS="function" >deg2dms</TT ></CODE >(<TT CLASS="parameter" ><I >FLOAT decimal</I ></TT >, <TT CLASS="parameter" ><I >INT_V degree</I ></TT >, <TT CLASS="parameter" ><I >INT_V minute</I ></TT >, <TT CLASS="parameter" ><I >INT_V second</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > convert decimal degrees to (degree, minute, second) </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN851" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >FLOAT <TT CLASS="function" >spdist</TT ></CODE >(<TT CLASS="parameter" ><I >FLOAT lat0</I ></TT >, <TT CLASS="parameter" ><I >FLOAT long0</I ></TT >, <TT CLASS="parameter" ><I >FLOAT lat1</I ></TT >, <TT CLASS="parameter" ><I >FLOAT long1</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > compute distance between two locations </P ></DD ></DL ></DIV ><P > The trigonometric functions specify angles using degrees. The functions <TT CLASS="function" >deg2dms</TT > and <TT CLASS="function" >dms2deg</TT > are provided to convert between (degree,minute,second) notation and decimal degree representations for angles. </P ><P > <TT CLASS="function" >spdist</TT > estimates the distance between two spherical coordinates. The arguments provided are, in order, first latitude, first longitude, second latitude, second longitude. The result is in kilometers. </P ></DIV ><DIV CLASS="sect1" ><HR><H2 CLASS="sect1" ><A NAME="AEN867" ></A >Person Functions</H2 ><DIV CLASS="glosslist" ><DL ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN872" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >STRING <TT CLASS="function" >name</TT ></CODE >(<TT CLASS="parameter" ><I >INDI</I ></TT >, <TT CLASS="parameter" ><I ><TT CLASS="replaceable" ><I >BOOL</I ></TT ></I ></TT >);</CODE ></P ><P ></P ></DIV > </B ></DT ><DD ><P > default name of </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN884" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >STRING <TT CLASS="function" >fullname</TT ></CODE >(<TT CLASS="parameter" ><I >INDI</I ></TT >, <TT CLASS="parameter" ><I >BOOL</I ></TT >, <TT CLASS="parameter" ><I >BOOL</I ></TT >, <TT CLASS="parameter" ><I >INT</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > many name forms of </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN897" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >STRING <TT CLASS="function" >surname</TT ></CODE >(<TT CLASS="parameter" ><I >INDI</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > surname of </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN907" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >STRING <TT CLASS="function" >givens</TT ></CODE >(<TT CLASS="parameter" ><I >INDI</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > given names of </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN917" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >STRING <TT CLASS="function" >trimname</TT ></CODE >(<TT CLASS="parameter" ><I >INDI</I ></TT >, <TT CLASS="parameter" ><I >INT</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > trimmed name of </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN928" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >EVENT <TT CLASS="function" >birth</TT ></CODE >(<TT CLASS="parameter" ><I >INDI</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > first birth event of </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN938" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >EVENT <TT CLASS="function" >death</TT ></CODE >(<TT CLASS="parameter" ><I >INDI</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > first death event of </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN948" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >EVENT <TT CLASS="function" >burial</TT ></CODE >(<TT CLASS="parameter" ><I >INDI</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > first burial event of </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN958" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >INDI <TT CLASS="function" >father</TT ></CODE >(<TT CLASS="parameter" ><I >INDI</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > first father of </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN968" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >INDI <TT CLASS="function" >mother</TT ></CODE >(<TT CLASS="parameter" ><I >INDI</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > first mother of </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN978" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >INDI <TT CLASS="function" >nextsib</TT ></CODE >(<TT CLASS="parameter" ><I >INDI</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > next (younger) sibling of </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN988" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >INDI <TT CLASS="function" >prevsib</TT ></CODE >(<TT CLASS="parameter" ><I >INDI</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > previous (older) sibling of </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN998" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >STRING <TT CLASS="function" >sex</TT ></CODE >(<TT CLASS="parameter" ><I >INDI</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > sex of </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN1008" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >BOOL <TT CLASS="function" >male</TT ></CODE >(<TT CLASS="parameter" ><I >INDI</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > male predicate </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN1018" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >BOOL <TT CLASS="function" >female</TT ></CODE >(<TT CLASS="parameter" ><I >INDI</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > female predicate </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN1028" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >STRING <TT CLASS="function" >pn</TT ></CODE >(<TT CLASS="parameter" ><I >INDI</I ></TT >, <TT CLASS="parameter" ><I >INT</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > pronoun referring to </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN1039" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >INT <TT CLASS="function" >nspouses</TT ></CODE >(<TT CLASS="parameter" ><I >INDI</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > number of spouses of </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN1049" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >INT <TT CLASS="function" >nfamilies</TT ></CODE >(<TT CLASS="parameter" ><I >INDI</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > number of families (as spouse/parent) of </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN1059" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >FAM <TT CLASS="function" >parents</TT ></CODE >(<TT CLASS="parameter" ><I >INDI</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > first parents' family of </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN1069" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >STRING <TT CLASS="function" >title</TT ></CODE >(<TT CLASS="parameter" ><I >INDI</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > first title of </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN1079" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >STRING <TT CLASS="function" >key</TT ></CODE >(<TT CLASS="parameter" ><I >RECORD</I ></TT >, <TT CLASS="parameter" ><I ><TT CLASS="replaceable" ><I >BOOL</I ></TT ></I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > internal key of (works for any record type) </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN1091" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >STRING <TT CLASS="function" >soundex</TT ></CODE >(<TT CLASS="parameter" ><I >INDI</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > SOUNDEX code of </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN1101" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >NODE <TT CLASS="function" >inode</TT ></CODE >(<TT CLASS="parameter" ><I >INDI</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > root GEDCOM node of </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN1111" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >NODE <TT CLASS="function" >root</TT ></CODE >(<TT CLASS="parameter" ><I >INDI</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > root GEDCOM node of </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN1121" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >INDI <TT CLASS="function" >indi</TT ></CODE >(<TT CLASS="parameter" ><I >STRING</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > find person with key value </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN1131" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >INDI <TT CLASS="function" >firstindi</TT ></CODE >(void);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > first person in database in key order </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN1140" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >INDI <TT CLASS="function" >lastindi</TT ></CODE >(void);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > last person in database in key order </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN1149" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >INDI <TT CLASS="function" >nextindi</TT ></CODE >(<TT CLASS="parameter" ><I >INDI</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > next person in database in key order </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN1159" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >INDI <TT CLASS="function" >previndi</TT ></CODE >(<TT CLASS="parameter" ><I >INDI</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > previous person in database in key order </P ></DD ><DT ><B ><TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="synopsis" ><B CLASS="command" >spouses</B > (<TT CLASS="replaceable" ><I >INDI</I ></TT >, <TT CLASS="replaceable" ><I >INDI_V</I ></TT >, <TT CLASS="replaceable" ><I >FAM_V</I ></TT >, <TT CLASS="replaceable" ><I >INT_V</I ></TT >) { <TT CLASS="replaceable" ><I >commands</I ></TT > } </PRE ></TD ></TR ></TABLE > </B ></DT ><DD ><P > loop through all spouses of </P ></DD ><DT ><B ><TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="synopsis" ><B CLASS="command" >families</B > (<TT CLASS="replaceable" ><I >INDI</I ></TT >, <TT CLASS="replaceable" ><I >FAM_V</I ></TT >, <TT CLASS="replaceable" ><I >INDI_V</I ></TT >, <TT CLASS="replaceable" ><I >INT_V</I ></TT >) { <TT CLASS="replaceable" ><I >commands</I ></TT > } </PRE ></TD ></TR ></TABLE ></B ></DT ><DD ><P > loop through all families (as spouse) of </P ></DD ><DT ><B ><TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="synopsis" ><B CLASS="command" >forindi</B > (<TT CLASS="replaceable" ><I >INDI_V</I ></TT >, <TT CLASS="replaceable" ><I >INT_V</I ></TT >) { <TT CLASS="replaceable" ><I >commands</I ></TT > } </PRE ></TD ></TR ></TABLE > </B ></DT ><DD ><P > loop through all persons in database </P ></DD ><DT ><B ><TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="synopsis" ><B CLASS="command" >mothers</B > (<TT CLASS="replaceable" ><I >INDI</I ></TT >, <TT CLASS="replaceable" ><I >INDI_V</I ></TT >, <TT CLASS="replaceable" ><I >FAM_V</I ></TT >, <TT CLASS="replaceable" ><I >INT_V</I ></TT >) { <TT CLASS="replaceable" ><I >commands</I ></TT > } </PRE ></TD ></TR ></TABLE ></B ></DT ><DD ><P > loop through all female parents of a person </P ></DD ><DT ><B ><TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="synopsis" ><B CLASS="command" >fathers</B > (<TT CLASS="replaceable" ><I >INDI</I ></TT >, <TT CLASS="replaceable" ><I >INDI_V</I ></TT >, <TT CLASS="replaceable" ><I >FAM_V</I ></TT >, <TT CLASS="replaceable" ><I >INT_V</I ></TT >) { <TT CLASS="replaceable" ><I >commands</I ></TT > } </PRE ></TD ></TR ></TABLE > </B ></DT ><DD ><P > loop through all male parents of a person </P ></DD ><DT ><B ><TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="synopsis" ><B CLASS="command" >Parents</B > (<TT CLASS="replaceable" ><I >INDI</I ></TT >, <TT CLASS="replaceable" ><I >FAM</I ></TT >, <TT CLASS="replaceable" ><I >INT_V</I ></TT >) { <TT CLASS="replaceable" ><I >commands</I ></TT > } </PRE ></TD ></TR ></TABLE ></B ></DT ><DD ><P > loop through all familes a person is a child of </P ></DD ></DL ></DIV ><P > These functions take a person as a parameter and return information about him or her. </P ><P > <TT CLASS="function" >Name</TT > returns the default name of a person; this is the name found on the first <TT CLASS="structfield" ><I >1 NAME</I ></TT > line in the person's record; the slashes are removed and the surname is made all capitals; <TT CLASS="function" >name</TT > can take an optional second parameter - if it is <SPAN CLASS="returnvalue" >true</SPAN > the function acts as described above; if <SPAN CLASS="returnvalue" >false</SPAN >, the surname is kept exactly as it is in the record. </P ><P > <TT CLASS="function" >Fullname</TT > returns the name of a person in a variety of formats. If the second parameter is <SPAN CLASS="returnvalue" >true</SPAN > the surname is shown in upper case; otherwise the surname is as in the record. If the third parameter is <SPAN CLASS="returnvalue" >true</SPAN > the parts of the name are shown in the order as found in the record; otherwise the surname is given first, followed by a comma, followed by the other name parts. The fourth parameter specifies the maximum length field that can be used to show the name; various conversions occur if it is necessary to shorten the name to fit this length. </P ><P > <TT CLASS="function" >Surname</TT > returns the surname of the person, as found in the first <TT CLASS="structfield" ><I >1 NAME</I ></TT > line; the slashes are removed. <TT CLASS="function" >Givens</TT > returns the given names of the person in the same order and format as found in the first <TT CLASS="structfield" ><I >1 NAME</I ></TT > line of the record. <TT CLASS="function" >Trimname</TT > returns the default name of the person trimmed to the maximum character length given in the second variable. </P ><P > <TT CLASS="function" >Birth</TT >, <TT CLASS="function" >death</TT >, and <TT CLASS="function" >burial</TT > return the first birth, death, and burial event in the person's record, respectively. An event is a level <TT CLASS="structfield" ><I >1 GEDCOM</I ></TT > node. If there is no matching event these functions return <SPAN CLASS="returnvalue" >null</SPAN >. </P ><P > <TT CLASS="function" >Father</TT >, <TT CLASS="function" >mother</TT >, <TT CLASS="function" >nextsib</TT > and <TT CLASS="function" >prevsib</TT > return the father, mother, next younger sibling and next older sibling of the person, respectively. If the person has more than one father (mother) the <TT CLASS="function" >father</TT > (<TT CLASS="function" >mother</TT >) function returns the first one. These functions return <SPAN CLASS="returnvalue" >null</SPAN > if there is no person in the role. </P ><P > <TT CLASS="function" >Sex</TT > returns the person's sex as the string <SPAN CLASS="returnvalue" >M</SPAN > if the person is male, <SPAN CLASS="returnvalue" >F</SPAN > if the person is female, or <SPAN CLASS="returnvalue" >U</SPAN > if the sex of the person is not known. <TT CLASS="function" >Male</TT > and <TT CLASS="function" >female</TT > return <SPAN CLASS="returnvalue" >true</SPAN > if the person is male or female, respectively, or <SPAN CLASS="returnvalue" >false</SPAN > if not. </P ><P > <TT CLASS="function" >Pn</TT > generates pronouns, useful when generating English text; the second parameter selects the type of pronoun: </P ><DIV CLASS="informaltable" ><A NAME="AEN1272" ></A ><P ></P ><TABLE BORDER="0" BGCOLOR="#E0E0E0" CELLSPACING="0" CELLPADDING="4" CLASS="CALSTABLE" ><TBODY ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >0</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" >He/She</TD ></TR ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >1</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" >he/she</TD ></TR ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >2</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" >His/Her</TD ></TR ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >3</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" >his/her</TD ></TR ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >4</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" >him/her</TD ></TR ></TBODY ></TABLE ><P ></P ></DIV ><P > <TT CLASS="function" >Nspouses</TT > returns the number of spouses the person has in the database, and <TT CLASS="function" >nfamilies</TT > returns the number of families the person is a parent/spouse in; these two values are not necessarily the same. <TT CLASS="function" >Parents</TT > returns the first family that the person is a child in. </P ><P > <TT CLASS="function" >Title</TT > returns the value of the first <TT CLASS="structfield" ><I >1 TITL</I ></TT > line in the record. </P ><P > <TT CLASS="function" >Key</TT > returns the key value of a person (or any record); if there is a second parameter and it is non-null, the leading <TT CLASS="literal" >I</TT > (or <TT CLASS="literal" >F</TT > or <TT CLASS="literal" >S</TT > or <TT CLASS="literal" >E</TT > or <TT CLASS="literal" >X</TT >) will be stripped. For example, if <TT CLASS="literal" >key(curindi)</TT > returns <TT CLASS="literal" >I23</TT >, then <TT CLASS="literal" >key(curindi,1)</TT > returns <TT CLASS="literal" >23</TT >. </P ><P > <TT CLASS="function" >Soundex</TT > returns the Soundex code of the person. </P ><P > <TT CLASS="function" >Root</TT > and <TT CLASS="function" >Inode</TT > return the root node of the person's <SPAN CLASS="acronym" >GEDCOM</SPAN > node tree. Note that an <SPAN CLASS="type" >INDI</SPAN > value is not a <SPAN CLASS="type" >NODE</SPAN > value. If you want to process the nodes within a person node tree, you must first use the <TT CLASS="function" >root</TT > or <TT CLASS="function" >inode</TT > function to get the root of the person node tree. <TT CLASS="function" >Root</TT > and <TT CLASS="function" >inode</TT > are synonyms. </P ><P > <TT CLASS="function" >Indi</TT > returns the person whose key is passed as an argument; if no person has the key <TT CLASS="function" >indi</TT > returns <SPAN CLASS="returnvalue" >null</SPAN >. INDI keys are accepted either as Innn or @Innn@. </P ><P > <TT CLASS="function" >Firstindi</TT >, <TT CLASS="function" >nextindi</TT > and <TT CLASS="function" >previndi</TT > allow you to iterate through all persons in the database. <TT CLASS="function" >Firstindi</TT > returns the first person in the database in key order. <TT CLASS="function" >Nextindi</TT > returns the next person after the argument person in key order. <TT CLASS="function" >Previndi</TT > returns the previous person before the argument person in key order. </P ><P > <TT CLASS="function" >Spouses</TT > is an iterator that loops through each spouse a person has. The first argument is a person. The second argument is a person variable that iterates through the first person's spouses. The third argument is a family variable that iterates through the families the person and each spouse are in. The fourth argument is an integer variable that counts the iterations. The spouses iterator skips any family that has no spouse, whereas the families iterator does not. </P ><P > <TT CLASS="function" >Families</TT > is an iterator that loops through the families a person was a spouse/parent in. The first argument is a person. The second argument is a family variable that iterates through the families the first person was a spouse/parent in. The third argument iterates through the spouses from the families; if there is no spouse in a particular family, the variable is set to null for that iteration. The fourth argument is an integer variable that counts the iterations. </P ><P > <TT CLASS="function" >Families</TT > and <TT CLASS="function" >Spouses</TT > behave the same except for one situation. If the person is a spouse in a family that only has one spouse identified, that family does not show up with the <TT CLASS="function" >spouses</TT > iterator, but it does show up with the <TT CLASS="function" >families</TT > iterator. One caution, this situation causes the 3rd argument of the <TT CLASS="function" >families</TT > iterator to be set to null. You must check for this. </P ><P > <TT CLASS="function" >Forindi</TT > is an iterator that loops through every person in the database in ascending key order. Its first parameter is a variable that iterates through the persons; its second parameter is an integer counter variable that counts the persons starting at one. </P ><P > <TT CLASS="function" >mothers</TT > is an iterator that loops through every female parent of the specified individual. Its first parameter is a person; its third parameter is a family variable that iterates through the familes that the person is a child in; its second parameter is a person variable that is the female parent associated with the family in the third parameter; The fourth parameter is a variable that counts the families returned starting at one. </P ><P > <TT CLASS="function" >Parents</TT > is an iterator that loops through every family that a person is a child in. Note: This iterator's name begins with a capital P. There is another function of the same name that begins with a lower case p. Its first parameter is a person; its second parameter is a family variable that iterates through the familes that the person is a child in; and the third parameter is a variable that counts the families returned starting at one. </P ><P > <TT CLASS="function" >Forindi</TT > is an iterator that loops through every person in the database in ascending key order. Its first parameter is a variable that iterates through the persons; its second parameter is an integer counter variable that counts the persons starting at one. </P ><P > <TT CLASS="function" >fathers</TT > and <TT CLASS="function" >mothers</TT > are iterators that loop through each family the specified individual is in returns each father or mother found. If a non-traditional family is processed, there will be separate iterations for each father or mother found. </P ></DIV ><DIV CLASS="sect1" ><HR><H2 CLASS="sect1" ><A NAME="AEN1353" ></A >Family Functions</H2 ><DIV CLASS="glosslist" ><DL ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN1358" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >EVENT <TT CLASS="function" >marriage</TT ></CODE >(<TT CLASS="parameter" ><I >FAM</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > first marriage event of </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN1368" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >INDI <TT CLASS="function" >husband</TT ></CODE >(<TT CLASS="parameter" ><I >FAM</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > first husband/father of </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN1378" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >INDI <TT CLASS="function" >wife</TT ></CODE >(<TT CLASS="parameter" ><I >FAM</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > first wife/mother of </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN1388" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >INT <TT CLASS="function" >nchildren</TT ></CODE >(<TT CLASS="parameter" ><I >FAM</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > number of children in </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN1398" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >INDI <TT CLASS="function" >firstchild</TT ></CODE >(<TT CLASS="parameter" ><I >FAM</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > first child of </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN1408" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >INDI <TT CLASS="function" >lastchild</TT ></CODE >(<TT CLASS="parameter" ><I >FAM</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > last child of </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN1418" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >STRING <TT CLASS="function" >key</TT ></CODE >(<TT CLASS="parameter" ><I >FAM|INDI</I ></TT >, <TT CLASS="parameter" ><I ><TT CLASS="replaceable" ><I >BOOL</I ></TT ></I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > internal key of (works for persons also) </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN1430" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >NODE <TT CLASS="function" >fnode</TT ></CODE >(<TT CLASS="parameter" ><I >FAM</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > root GEDCOM node of </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN1440" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >NODE <TT CLASS="function" >root</TT ></CODE >(<TT CLASS="parameter" ><I >FAM</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > root GEDCOM node of </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN1450" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >FAM <TT CLASS="function" >fam</TT ></CODE >(<TT CLASS="parameter" ><I >STRING</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > find family from key </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN1460" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >FAM <TT CLASS="function" >firstfam</TT ></CODE >(void);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > first family in database in key order </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN1469" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >FAM <TT CLASS="function" >lastfam</TT ></CODE >(void);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > last family in database in key order </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN1478" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >FAM <TT CLASS="function" >nextfam</TT ></CODE >(<TT CLASS="parameter" ><I >FAM</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > next family in database in key order </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN1488" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >FAM <TT CLASS="function" >prevfam</TT ></CODE >(<TT CLASS="parameter" ><I >FAM</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > previous family in database in key order </P ></DD ><DT ><B ><TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="synopsis" ><B CLASS="command" >children</B > (<TT CLASS="replaceable" ><I >FAM</I ></TT >, <TT CLASS="replaceable" ><I >INDI_V</I ></TT >, <TT CLASS="replaceable" ><I >INT_V</I ></TT >) { <TT CLASS="replaceable" ><I >commands</I ></TT > } </PRE ></TD ></TR ></TABLE ></B ></DT ><DD ><P > loop through children of family </P ></DD ><DT ><B ><TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="synopsis" ><B CLASS="command" >spouses</B > (<TT CLASS="replaceable" ><I >FAM</I ></TT >, <TT CLASS="replaceable" ><I >INDI_V</I ></TT >, <TT CLASS="replaceable" ><I >INT_V</I ></TT >) { <TT CLASS="replaceable" ><I >commands</I ></TT > } </PRE ></TD ></TR ></TABLE ></B ></DT ><DD ><P > loop through all husbands and wives of a family </P ></DD ><DT ><B ><TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="synopsis" ><B CLASS="command" >forfam</B > (<TT CLASS="replaceable" ><I >FAM_V</I ></TT >, <TT CLASS="replaceable" ><I >INT_V</I ></TT >) { <TT CLASS="replaceable" ><I >commands</I ></TT > } </PRE ></TD ></TR ></TABLE ></B ></DT ><DD ><P > loop through all families in database </P ></DD ></DL ></DIV ><P > These functions take a family as an argument and return information about it. </P ><P > <TT CLASS="function" >Marriage</TT > returns the first marriage event found in the family record, if any; it returns <SPAN CLASS="returnvalue" >null</SPAN > if there is no marriage event. </P ><P > <TT CLASS="function" >Husband</TT > returns the first husband/father of the family, if any; and <TT CLASS="function" >wife</TT > returns the first wife/mother of the family, if any. Each returns <SPAN CLASS="returnvalue" >null</SPAN > if the requested person is not in the family. </P ><P > <TT CLASS="function" >Nchildren</TT > returns the number of children in the family. </P ><P > <TT CLASS="function" >Firstchild</TT > and <TT CLASS="function" >lastchild</TT > return the first child and last child in a family, respectively. </P ><P > <TT CLASS="function" >Key</TT > was described in the section on person functions. </P ><P > <TT CLASS="function" >Root</TT > and <TT CLASS="function" >fnode</TT > return the root node of a family <SPAN CLASS="acronym" >GEDCOM</SPAN > node tree. Note that a <SPAN CLASS="type" >FAM</SPAN > value is not a <SPAN CLASS="type" >NODE</SPAN > value. If you want to process the nodes within a family node tree, you must first use <TT CLASS="function" >root</TT > or <TT CLASS="function" >fnode</TT > function to get the root of the family node tree. <TT CLASS="function" >Root</TT > and <TT CLASS="function" >fnode</TT > are synonyms. </P ><P > <TT CLASS="function" >Fam</TT > returns the family who's key is passed as an argument; if no family has the key <TT CLASS="function" >fam</TT > returns <SPAN CLASS="returnvalue" >null</SPAN >. Family keys are accepted either as Fnnn or @Fnnn@. </P ><P > <TT CLASS="function" >Firstfam</TT >, <TT CLASS="function" >nextfam</TT > and <TT CLASS="function" >prevfam</TT > allow you to iterate through all families in the database. <TT CLASS="function" >Firstfam</TT > returns the first family in the database in key order. <TT CLASS="function" >Nextfam</TT > returns the next family after the argument family in key order. <TT CLASS="function" >Prevfam</TT > returns the previous family before the argument family in key order. </P ><P > <TT CLASS="function" >Children</TT > is an iterator that loops through the children in a family. Its first parameter is a family expression; its second parameter is a variable that iterates through each child; its third parameter is an integer counter variable that counts the children starting at one. These two variables may be used within the loop body. </P ><P > <TT CLASS="function" >spouses</TT > is an iterator that loops through all the husbands and wives of a family. Its first parameter is a family expression; its second parameter is a variable that iterates through each parent; its third parameter is an integer counter variable that counts the parents starting at one. These two variables may be used within the loop body. </P ><P > <TT CLASS="function" >Forfam</TT > is an iterator that loops through every family in the database in ascending key order. Its first parameter is a variable that iterates through the families; its second parameter is an integer counter variable that counts the families starting at one. </P ></DIV ><DIV CLASS="sect1" ><HR><H2 CLASS="sect1" ><A NAME="AEN1567" ></A >Other types of records</H2 ><DIV CLASS="glosslist" ><DL ><DT ><B ><TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="synopsis" ><B CLASS="command" >forsour</B > (<TT CLASS="replaceable" ><I >NODE_V</I ></TT >, <TT CLASS="replaceable" ><I >INT_V</I ></TT >) { <TT CLASS="replaceable" ><I >commands</I ></TT > } </PRE ></TD ></TR ></TABLE ></B ></DT ><DD ><P > loop through all sources in database </P ></DD ><DT ><B ><TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="synopsis" ><B CLASS="command" >foreven</B > (<TT CLASS="replaceable" ><I >NODE_V</I ></TT >, <TT CLASS="replaceable" ><I >INT_V</I ></TT >) { <TT CLASS="replaceable" ><I >commands</I ></TT > } </PRE ></TD ></TR ></TABLE ></B ></DT ><DD ><P > loop through all EVEN nodes in database </P ></DD ><DT ><B ><TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="synopsis" ><B CLASS="command" >forothr</B > (<TT CLASS="replaceable" ><I >NODE_V</I ></TT >, <TT CLASS="replaceable" ><I >INT_V</I ></TT >) { <TT CLASS="replaceable" ><I >commands</I ></TT > } </PRE ></TD ></TR ></TABLE ></B ></DT ><DD ><P > loop through all other (notes, etc.) nodes in database </P ></DD ></DL ></DIV ><P > <TT CLASS="function" >forsour</TT > is an iterator that loops through all the Source nodes in the database. Its first argument is the SOUR record and its second parameter is an integer counter variable that counts the sources elements starting at one. <TT CLASS="function" >foreven</TT > is an iterator that loops through all the Event nodes in the database. Its first argument is the EVEN record and its second parameter is an integer counter variable that counts the events elements starting at one. <TT CLASS="function" >forothr</TT > is an iterator that loops through all the Other nodes in the database. Its first argument is the record (NOTE, etc.) and its second parameter is an integer counter variable that counts the nodes starting at one. </P ></DIV ><DIV CLASS="sect1" ><HR><H2 CLASS="sect1" ><A NAME="AEN1601" ></A >List Functions</H2 ><DIV CLASS="glosslist" ><DL ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN1606" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >list</TT ></CODE >(<TT CLASS="parameter" ><I >LIST_V</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > declare a list </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN1616" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >clear</TT ></CODE >(<TT CLASS="parameter" ><I >LIST</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > clear a list </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN1626" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >BOOL <TT CLASS="function" >empty</TT ></CODE >(<TT CLASS="parameter" ><I >LIST</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > check if list is empty </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN1636" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >INT <TT CLASS="function" >length</TT ></CODE >(<TT CLASS="parameter" ><I >LIST</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > length of list </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN1646" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >enqueue</TT ></CODE >(<TT CLASS="parameter" ><I >LIST</I ></TT >, <TT CLASS="parameter" ><I >ANY</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > enqueue element on list </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN1657" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >ANY <TT CLASS="function" >dequeue</TT ></CODE >(<TT CLASS="parameter" ><I >LIST</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > dequeue and return element from list </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN1667" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >requeue</TT ></CODE >(<TT CLASS="parameter" ><I >LIST</I ></TT >, <TT CLASS="parameter" ><I >ANY</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > requeue an element on list </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN1678" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >push</TT ></CODE >(<TT CLASS="parameter" ><I >LIST</I ></TT >, <TT CLASS="parameter" ><I >ANY</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > push element on list </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN1689" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >ANY <TT CLASS="function" >pop</TT ></CODE >(<TT CLASS="parameter" ><I >LIST</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > pop and return element from list </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN1699" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >setel</TT ></CODE >(<TT CLASS="parameter" ><I >LIST</I ></TT >, <TT CLASS="parameter" ><I >INT</I ></TT >, <TT CLASS="parameter" ><I >ANY</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > array element assignment </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN1711" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >ANY <TT CLASS="function" >getel</TT ></CODE >(<TT CLASS="parameter" ><I >LIST</I ></TT >, <TT CLASS="parameter" ><I >INT</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > array element selection </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN1722" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >BOOL <TT CLASS="function" >inlist</TT ></CODE >(<TT CLASS="parameter" ><I >LIST</I ></TT >, <TT CLASS="parameter" ><I >ANY</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > is second argument in list. </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN1733" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >sort</TT ></CODE >(<TT CLASS="parameter" ><I >LIST</I ></TT >, <TT CLASS="parameter" ><I >LIST</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > sort list elements </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN1744" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >rsort</TT ></CODE >(<TT CLASS="parameter" ><I >LIST</I ></TT >, <TT CLASS="parameter" ><I >LIST</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > reverse sort list elements </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN1755" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >LIST <TT CLASS="function" >dup</TT ></CODE >(<TT CLASS="parameter" ><I >LIST</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > duplicate a list </P ></DD ><DT ><B ><TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="synopsis" ><B CLASS="command" >forlist</B > (<TT CLASS="replaceable" ><I >LIST</I ></TT >, <TT CLASS="replaceable" ><I >ANY_V</I ></TT >, <TT CLASS="replaceable" ><I >INT_V</I ></TT >) { <TT CLASS="replaceable" ><I >commands</I ></TT > } </PRE ></TD ></TR ></TABLE ></B ></DT ><DD ><P > loop through all elements of list </P ></DD ></DL ></DIV ><P > <TT CLASS="application" >LifeLines</TT > provides general purpose lists that can be accessed as queues, stacks or arrays. A list must be declared with the <TT CLASS="function" >list</TT > function before it can be used. Redeclaring an existing variable with the <TT CLASS="function" >list</TT > clears it and restores it to being an empty list. If the argument to list() is the name of a parameter to the current routine, the reference to the calling routines list is removed and a new list is created. </P ><P > A list can have any number of elements. <TT CLASS="function" >Empty</TT > returns <SPAN CLASS="returnvalue" >true</SPAN > if the list has no elements and <SPAN CLASS="returnvalue" >false</SPAN > otherwise. <TT CLASS="function" >Length</TT > returns the length of the list. The only parameter to both is a list. The following diagram indicates how the various access functions for a list interact: </P ><P > <SPAN CLASS="inlinemediaobject" ><IMG SRC="listops.jpg"></SPAN > </P ><P > <TT CLASS="function" >Enqueue</TT >, <TT CLASS="function" >dequeue</TT > and <TT CLASS="function" >requeue</TT > provide queue access to a list. <TT CLASS="function" >Enqueue</TT > adds an element to the back of a queue, <TT CLASS="function" >dequeue</TT > removes and returns the element from the front of a queue, and <TT CLASS="function" >requeue</TT > adds an element to the front of a queue. The first parameter to all three is a list, and the second parameter to <TT CLASS="function" >enqueue</TT > and <TT CLASS="function" >requeue</TT > is the value to be added to the queue and can be any value. </P ><P > <TT CLASS="function" >Push</TT > and <TT CLASS="function" >pop</TT > provide stack access to a list. <TT CLASS="function" >Push</TT > pushes an element on the stack, and <TT CLASS="function" >pop</TT > removes and returns the most recently pushed element from the stack. The first parameter to both is a list, and the second parameter to <TT CLASS="function" >push</TT > is the value to be pushed on the stack and can be of any type. </P ><P > <TT CLASS="function" >Setel</TT > and <TT CLASS="function" >getel</TT > provide array access to a list. <TT CLASS="function" >Setel</TT > sets a value of an array element, and <TT CLASS="function" >getel</TT > returns the value of an array element. The first parameter to both is a list; the second parameter to both is an integer index into the array; and the third parameter to <TT CLASS="function" >setel</TT > is the value to assign to the array element and can be of any type. Array elements are indexed starting at one. Unassigned elements are assumed to be <SPAN CLASS="returnvalue" >null</SPAN > (<SPAN CLASS="returnvalue" >0</SPAN >). Arrays automatically grow in size to accommodate the largest index value that is used. Passing 0 references the last element at the other end from 1, and -1 the one before it, etc. </P ><P > <TT CLASS="function" >inlist</TT > compares the second argument with each element in the list. If it finds a match <TT CLASS="function" >inlist</TT > returns <SPAN CLASS="returnvalue" >true</SPAN >. </P ><P > <TT CLASS="function" >sort</TT > and <TT CLASS="function" >rsort</TT > sort a list, using the elements of the second array to determine the new order. Both lists are reordered, so essentially both are sorted using the sort order of the second argument. (If only one argument is given, it is sorted on its own elements.) rsort sorts in order reverse of sort. The order that sort produces places the smallest element at position 1, and the largest element at the end of the list, such that <TT CLASS="function" >dequeue</TT > will remove the smallest element. </P ><P > <TT CLASS="function" >dup</TT > creates a copy of a <SPAN CLASS="type" >list</SPAN >. If b is a <SPAN CLASS="type" >list</SPAN >, the function <TT CLASS="function" >set</TT >(a,b) makes the variable a a reference to the <SPAN CLASS="type" >list</SPAN > b. If you want to make a new <SPAN CLASS="type" >list</SPAN >, you must use <TT CLASS="function" >set</TT >(a,<TT CLASS="function" >dup</TT >(b)). </P ><P > <TT CLASS="function" >Forlist</TT > is an iterator that loops through the element in a list. Its first parameter is a <SPAN CLASS="type" >LIST</SPAN > expression; its second parameter is a variable that iterates through the list elements; and its third parameter is an integer counter variable that counts the list elements starting at one. </P ></DIV ><DIV CLASS="sect1" ><HR><H2 CLASS="sect1" ><A NAME="AEN1829" ></A >Table Functions</H2 ><DIV CLASS="glosslist" ><DL ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN1834" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >table</TT ></CODE >(<TT CLASS="parameter" ><I >TABLE_V</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > declare a table </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN1844" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >insert</TT ></CODE >(<TT CLASS="parameter" ><I >TABLE</I ></TT >, <TT CLASS="parameter" ><I >STRING</I ></TT >, <TT CLASS="parameter" ><I >ANY</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > insert entry in table </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN1856" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >ANY <TT CLASS="function" >lookup</TT ></CODE >(<TT CLASS="parameter" ><I >TABLE</I ></TT >, <TT CLASS="parameter" ><I >STRING</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > lookup and return entry from table </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN1867" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >INT <TT CLASS="function" >length</TT ></CODE >(<TT CLASS="parameter" ><I >TABLE</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > size of the table </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN1877" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >BOOL <TT CLASS="function" >empty</TT ></CODE >(<TT CLASS="parameter" ><I >TABLE</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > check if table is empty </P ></DD ></DL ></DIV ><P > These functions provide general purpose, keyed tables. A table must be declared with the <TT CLASS="function" >table</TT > function before it can be used. </P ><P > <TT CLASS="function" >Insert</TT > adds an object and its key to a table. Its first parameter is a table; the second parameter is the object's key; and the third parameter is the object itself. The key must be a string and the object can be any value. If there already is an object in the table with that key, the old object is replaced with the new. </P ><P > <TT CLASS="function" >Lookup</TT > retrieves an object from a table. Its first parameter is a table, and the second parameter is the object's key. The function returns the object with that key from the table; if there is no such object, <SPAN CLASS="returnvalue" >null</SPAN > is returned. <TT CLASS="function" >length</TT > returns the number of elements in the table. </P ></DIV ><DIV CLASS="sect1" ><HR><H2 CLASS="sect1" ><A NAME="AEN1893" ></A >GEDCOM Node Functions</H2 ><DIV CLASS="glosslist" ><DL ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN1898" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >STRING <TT CLASS="function" >xref</TT ></CODE >(<TT CLASS="parameter" ><I >NODE</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > cross reference index of </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN1908" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >STRING <TT CLASS="function" >tag</TT ></CODE >(<TT CLASS="parameter" ><I >NODE</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > tag of </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN1918" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >STRING <TT CLASS="function" >value</TT ></CODE >(<TT CLASS="parameter" ><I >NODE</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > value of </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN1928" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >NODE <TT CLASS="function" >parent</TT ></CODE >(<TT CLASS="parameter" ><I >NODE</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > parent node of </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN1938" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >NODE <TT CLASS="function" >child</TT ></CODE >(<TT CLASS="parameter" ><I >NODE</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > first child of </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN1948" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >NODE <TT CLASS="function" >sibling</TT ></CODE >(<TT CLASS="parameter" ><I >NODE</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > next sibling of </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN1958" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >NODE <TT CLASS="function" >savenode</TT ></CODE >(<TT CLASS="parameter" ><I >NODE</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > copy a node structure </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN1968" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >INT <TT CLASS="function" >level</TT ></CODE >(<TT CLASS="parameter" ><I >NODE</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > level of a node </P ></DD ><DT ><B ><TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="synopsis" ><B CLASS="command" >fornodes</B > (<TT CLASS="replaceable" ><I >NODE</I ></TT >, <TT CLASS="replaceable" ><I >NODE_V</I ></TT >) { <TT CLASS="replaceable" ><I >commands</I ></TT > } </PRE ></TD ></TR ></TABLE ></B ></DT ><DD ><P > loop through child nodes </P ></DD ><DT ><B ><TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="synopsis" ><B CLASS="command" >fornotes</B > (<TT CLASS="replaceable" ><I >NODE</I ></TT >, <TT CLASS="replaceable" ><I >STRING_V</I ></TT >) { <TT CLASS="replaceable" ><I >commands</I ></TT > } </PRE ></TD ></TR ></TABLE ></B ></DT ><DD ><P > loop through notes on a node </P ></DD ><DT ><B ><TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="synopsis" ><B CLASS="command" >traverse</B > (<TT CLASS="replaceable" ><I >NODE</I ></TT >, <TT CLASS="replaceable" ><I >NODE_V</I ></TT >, <TT CLASS="replaceable" ><I >INT_V</I ></TT >) { <TT CLASS="replaceable" ><I >commands</I ></TT > } </PRE ></TD ></TR ></TABLE ></B ></DT ><DD ><P > loop through all descendent nodes </P ></DD ></DL ></DIV ><P > These functions provide access to the components of a <SPAN CLASS="acronym" >GEDCOM</SPAN > node. All take a <SPAN CLASS="acronym" >GEDCOM</SPAN > node as their only parameter, and each returns a different value associated with the node. </P ><P > <TT CLASS="function" >Xref</TT > returns the cross reference index of the node, if any; <TT CLASS="function" >tag</TT > returns the tag of the node; and <TT CLASS="function" >value</TT > returns the value of the node, if any. If there is no cross reference, <TT CLASS="function" >xref</TT > returns <SPAN CLASS="returnvalue" >null</SPAN >; if there is no value, value returns <SPAN CLASS="returnvalue" >null</SPAN >. </P ><P > <TT CLASS="function" >Parent</TT > returns the parent node of the node, if any; <TT CLASS="function" >child</TT > returns the first child node of the node, if any; and <TT CLASS="function" >sibling</TT > returns the next sibling node of the node, if any. Whenever there is no such related node, these functions return <SPAN CLASS="returnvalue" >null</SPAN >. These three functions allow simple navigation through a <SPAN CLASS="acronym" >GEDCOM</SPAN > node tree. </P ><P > <TT CLASS="function" >Savenode</TT > makes a copy of the node, and the substructure of nodes below the node, that is passed to it. Beware: the memory used to make the copy is never returned to the system. </P ><P > The <TT CLASS="function" >level</TT > function returns the level of the node. </P ><P > <TT CLASS="function" >Fornodes</TT > is an iterator that loops through the child nodes of a <SPAN CLASS="acronym" >GEDCOM</SPAN > node. Its first argument is a node expression, and its second parameter is a variable that iterates through each direct child node of the first node. </P ><P > <TT CLASS="function" >Fornotes</TT > is an iterator that loops through the NOTE nodes of a <SPAN CLASS="acronym" >GEDCOM</SPAN > node. Its first argument is a node expression, and its second parameter is a variable that returns the value of the NOTE. The value includes processed sub CONC and CONT records. </P ><P > <TT CLASS="function" >Traverse</TT > is an iterator providing a general method for traversing <SPAN CLASS="acronym" >GEDCOM</SPAN > trees. Its first parameter is a node expression; its second parameter is a variable that iterates over every node under the first node in a top down, left to right manner; and its third parameter is a variable that is set to the level of the current node in the iteration. </P ></DIV ><DIV CLASS="sect1" ><HR><H2 CLASS="sect1" ><A NAME="AEN2033" ></A >Event and Date Functions</H2 ><DIV CLASS="glosslist" ><DL ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN2038" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >STRING <TT CLASS="function" >date</TT ></CODE >(<TT CLASS="parameter" ><I >EVENT</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > date of, value of first <TT CLASS="structfield" ><I >DATE</I ></TT > line </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN2049" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >STRING <TT CLASS="function" >place</TT ></CODE >(<TT CLASS="parameter" ><I >EVENT</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > place of, value of first <TT CLASS="structfield" ><I >PLAC</I ></TT > line </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN2060" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >STRING <TT CLASS="function" >year</TT ></CODE >(<TT CLASS="parameter" ><I >EVENT</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > year or, 1st string of 3-4 digits in 1st <TT CLASS="structfield" ><I >DATE</I ></TT > line </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN2071" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >STRING <TT CLASS="function" >long</TT ></CODE >(<TT CLASS="parameter" ><I >EVENT</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > date and place, values of 1st <TT CLASS="structfield" ><I >DATE</I ></TT > and <TT CLASS="structfield" ><I >PLAC</I ></TT > lines </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN2083" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >STRING <TT CLASS="function" >short</TT ></CODE >(<TT CLASS="parameter" ><I >EVENT</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > date and place of, abbreviated from </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN2093" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >EVENT <TT CLASS="function" >gettoday</TT ></CODE >(void);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > returns the `event' of the current date </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN2102" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >setdate</TT ></CODE >(<TT CLASS="parameter" ><I >VAR</I ></TT ><TT CLASS="parameter" ><I >STRING</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > creates an event with specified date and assigns to specified variable </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN2113" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >dayformat</TT ></CODE >(<TT CLASS="parameter" ><I >INT</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > set day format for stddate calls </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN2123" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >monthformat</TT ></CODE >(<TT CLASS="parameter" ><I >INT</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > set month format for stddate calls </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN2133" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >yearformat</TT ></CODE >(<TT CLASS="parameter" ><I >INT</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > set year format for stddate calls </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN2143" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >eraformat</TT ></CODE >(<TT CLASS="parameter" ><I >INT</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > set era format for stddate calls </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN2153" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >dateformat</TT ></CODE >(<TT CLASS="parameter" ><I >INT</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > set date format for stddate calls </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN2163" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >datepic</TT ></CODE >(<TT CLASS="parameter" ><I >STRING</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > set custom date format for stddate calls </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN2173" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >STRING <TT CLASS="function" >stddate</TT ></CODE >(<TT CLASS="parameter" ><I >EVENT|STRING</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > date of, in current format </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN2183" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >complexformat</TT ></CODE >(<TT CLASS="parameter" ><I >INT</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > set complex date format </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN2193" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >complexpic</TT ></CODE >(<TT CLASS="parameter" ><I >INT</I ></TT >, <TT CLASS="parameter" ><I >STRING</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > set custom complex date picture string </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN2204" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >STRING <TT CLASS="function" >complexdate</TT ></CODE >(<TT CLASS="parameter" ><I >EVENT|STRING</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > date of, in current complex format </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN2214" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >STRING <TT CLASS="function" >dayofweek</TT ></CODE >(<TT CLASS="parameter" ><I >EVENT|STRING</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > day of week, in appropriate language </P ></DD ></DL ></DIV ><P > These functions extract information about the dates and places of events. </P ><P > <TT CLASS="function" >Date</TT > returns the value of the first <TT CLASS="structfield" ><I >DATE</I ></TT > line in an event, a node in a <SPAN CLASS="acronym" >GEDCOM</SPAN > record tree. <TT CLASS="function" >Date</TT > finds the first <TT CLASS="structfield" ><I >DATE</I ></TT > line one level deeper than the event node. <TT CLASS="function" >Place</TT > returns the value of the first <TT CLASS="structfield" ><I >PLAC</I ></TT > line in an event. <TT CLASS="function" >Year</TT > returns the first three or four digit number in the value of the first <TT CLASS="structfield" ><I >DATE</I ></TT > line in an event; this number is assumed to be the year of the event. </P ><P > <TT CLASS="function" >Long</TT > returns the verbatim values of the first <TT CLASS="structfield" ><I >DATE</I ></TT > and <TT CLASS="structfield" ><I >PLAC</I ></TT > lines in an event, concatenated together and separated by a comma. <TT CLASS="function" >Short</TT > abbreviates information from the first <TT CLASS="structfield" ><I >DATE</I ></TT > and <TT CLASS="structfield" ><I >PLAC</I ></TT > lines, concatenates the shortened information together with a comma separator and returns it. An abbreviated date is its year; an abbreviated place is the last component in the value, further abbreviated if the component has an entry in the place abbreviation table. </P ><P > <TT CLASS="function" >Gettoday</TT > creates an event that has today's date in the <TT CLASS="structfield" ><I >DATE</I ></TT > line. <TT CLASS="function" >Setdate</TT > creates an event that has the specified date in the <TT CLASS="structfield" ><I >DATE</I ></TT > line, and assigns the new event to the specified variable. </P ><P > The next seven functions are used to format dates in a variety of ways. <TT CLASS="function" >Dayformat</TT >, <TT CLASS="function" >monthformat</TT >, <TT CLASS="function" >yearformat</TT >, <TT CLASS="function" >eraformat</TT >, and <TT CLASS="function" >dateformat</TT > select style options for formatting the day, month, year, era, and overall date structure; <TT CLASS="function" >stddate</TT > returns dates in the selected style. <TT CLASS="function" >datepic</TT > allows specifying a custom pattern that overrides the date format selected with <TT CLASS="function" >dateformat</TT >. The string supplied specifies the placement of the day, month and year in the string with %d, %m and %y. A null argument disables the overrided format. The argument to <TT CLASS="function" >stddate</TT > is normally an event and the date is extracted from the event and formatted. If the argument is a date string it is converted using the current date formats. </P ><P > The next three functions provide for more complex formatting of dates. Taking into account the abt, est, cal, bef, aft, fr and to qualifiers on GEDCOM dates. <TT CLASS="function" >complexformat</TT > selects the format to use. The format effects only the complex picture, not the format of the date itself. The function <TT CLASS="function" >complexpic</TT > can be used to specify a custom picture string for any or all of the 9 custom format strings. The custom string can be canceled by passing a null for the string. When a custom picture string is provided it overrides both the abbreviated and full word picture strings. <TT CLASS="function" >complexdate</TT > formats the date similarly to <TT CLASS="function" >stddate</TT >, but with the addition of the complex date format string selected. </P ><P > The day format codes passed to <TT CLASS="function" >dayformat</TT > are: </P ><DIV CLASS="informaltable" ><A NAME="AEN2262" ></A ><P ></P ><TABLE BORDER="0" BGCOLOR="#E0E0E0" CELLSPACING="0" CELLPADDING="4" CLASS="CALSTABLE" ><TBODY ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >0</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" >leave space before single digit days</TD ></TR ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >1</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > use leading 0 before single digit days </TD ></TR ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >2</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > no space or leading 0 before single digit days </TD ></TR ></TBODY ></TABLE ><P ></P ></DIV ><P > The month format codes passed to <TT CLASS="function" >monthformat</TT > are: </P ><DIV CLASS="informaltable" ><A NAME="AEN2277" ></A ><P ></P ><TABLE BORDER="0" BGCOLOR="#E0E0E0" CELLSPACING="0" CELLPADDING="4" CLASS="CALSTABLE" ><TBODY ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >0</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > number with space before single digit months </TD ></TR ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >1</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > number with leading zero before single digit months </TD ></TR ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >2</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > number with no space or zero before single digit months </TD ></TR ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >3</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > upper case abbreviation (eg, JAN, FEB) (localized) </TD ></TR ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >4</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > capitalized abbreviation (eg, Jan, Feb) (localized) </TD ></TR ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >5</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > upper case full word (eg, JANUARY, FEBRUARY) (localized) </TD ></TR ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >6</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > capitalized full word (eg, January, February) (localized) </TD ></TR ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >7</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > lower case abbreviation (eg, jan, feb) (localized) </TD ></TR ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >8</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > lower case full word (eg, january, february) (localized) </TD ></TR ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >9</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > upper case abbreviation in English per GEDCOM (eg, JAN, FEB) </TD ></TR ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >10</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > lower case roman letter (eg, i, ii) </TD ></TR ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >11</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > upper case roman letter (eg, I, II) </TD ></TR ></TBODY ></TABLE ><P ></P ></DIV ><P > The year format codes passed to <TT CLASS="function" >yearformat</TT > are: </P ><DIV CLASS="informaltable" ><A NAME="AEN2319" ></A ><P ></P ><TABLE BORDER="0" BGCOLOR="#E0E0E0" CELLSPACING="0" CELLPADDING="4" CLASS="CALSTABLE" ><TBODY ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >0</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > use leading spaces before years with less than four digits </TD ></TR ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >1</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > use leading 0 before years with less than four digits </TD ></TR ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >2</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > no space or leading 0 before years </TD ></TR ></TBODY ></TABLE ><P ></P ></DIV ><P > The era format codes passed to <TT CLASS="function" >eraformat</TT > are: </P ><DIV CLASS="informaltable" ><A NAME="AEN2334" ></A ><P ></P ><TABLE BORDER="0" BGCOLOR="#E0E0E0" CELLSPACING="0" CELLPADDING="4" CLASS="CALSTABLE" ><TBODY ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >0</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > no AD/BC markers </TD ></TR ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >1</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > trailing B.C. if appropriate </TD ></TR ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >2</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > trailing A.D. or B.C. </TD ></TR ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >11</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > trailing BC if appropriate </TD ></TR ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >12</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > trailing AD or BC </TD ></TR ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >21</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > trailing B.C.E. if appropriate </TD ></TR ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >22</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > trailing C.E. or B.C.E. </TD ></TR ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >31</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > trailing BC if appropriate </TD ></TR ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >32</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > trailing CE or BCE </TD ></TR ></TBODY ></TABLE ><P ></P ></DIV ><P > The full date formats passed to <TT CLASS="function" >stddate</TT > are: </P ><DIV CLASS="informaltable" ><A NAME="AEN2367" ></A ><P ></P ><TABLE BORDER="0" BGCOLOR="#E0E0E0" CELLSPACING="0" CELLPADDING="4" CLASS="CALSTABLE" ><TBODY ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >0</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > da mo yr </TD ></TR ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >1</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > mo da, yr </TD ></TR ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >2</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > mo/da/yr </TD ></TR ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >3</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > da/mo/yr </TD ></TR ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >4</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > mo-da-yr </TD ></TR ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >5</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > da-mo-yr </TD ></TR ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >6</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > modayr </TD ></TR ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >7</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > damoyr </TD ></TR ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >8</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > yr mo da </TD ></TR ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >9</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > yr/mo/da </TD ></TR ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >10</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > yr-mo-da </TD ></TR ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >11</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > yrmoda </TD ></TR ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >12</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > yr (year only, omitting all else) </TD ></TR ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >13</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > da/mo yr </TD ></TR ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >14</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > (As in GEDCOM) </TD ></TR ></TBODY ></TABLE ><P ></P ></DIV ><P > The complex date formats selected by the <TT CLASS="function" >complexformat</TT > and used by <TT CLASS="function" >complexdate</TT > are: </P ><DIV CLASS="informaltable" ><A NAME="AEN2419" ></A ><P ></P ><TABLE BORDER="0" BGCOLOR="#E0E0E0" CELLSPACING="0" CELLPADDING="4" CLASS="CALSTABLE" ><TBODY ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" > </TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > Mode </TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > Example </TD ></TR ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >3</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > use abbreviations in uppercase </TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > ABT 1 JAN 2002 </TD ></TR ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >4</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > use abbreviations in titlecase </TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > Abt 1 JAN 2002 </TD ></TR ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >5</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > use uppercased full words </TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > ABOUT 1 JAN 2002 </TD ></TR ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >6</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > use titlecased full words </TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > About 1 JAN 2002 </TD ></TR ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >7</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > use abbreviations in lowercase </TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > abt 1 JAN 2002 </TD ></TR ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >8</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > use lowercase full words </TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > about 1 JAN 2002 </TD ></TR ></TBODY ></TABLE ><P ></P ></DIV ><P > The complex date string pictures that can be overridden with the <TT CLASS="function" >complexpic</TT > are: </P ><DIV CLASS="informaltable" ><A NAME="AEN2453" ></A ><P ></P ><TABLE BORDER="0" BGCOLOR="#E0E0E0" CELLSPACING="0" CELLPADDING="4" CLASS="CALSTABLE" ><TBODY ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" > </TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > Abbreviation </TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > Full word </TD ></TR ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >0</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > abt %1 </TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > about %1 </TD ></TR ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >1</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > est %1 </TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > estimated %1 </TD ></TR ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >2</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > cal %1 </TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > calculated %1 </TD ></TR ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >3</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > bef %1 </TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > before %1 </TD ></TR ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >4</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > aft %1 </TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > after %1 </TD ></TR ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >5</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > bet %1 and %2 </TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > between %1 and %2 </TD ></TR ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >6</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > fr %1 </TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > from %1 </TD ></TR ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >7</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > to %1 </TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > to %1 </TD ></TR ><TR ><TD WIDTH="48" ALIGN="LEFT" VALIGN="MIDDLE" >8</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > fr %1 to %2 </TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" > from %1 to $2 </TD ></TR ></TBODY ></TABLE ><P ></P ></DIV ><P > The function dayofweek is a way to access the (localized) day name, eg, "Thursday", for a given date. </P ></DIV ><DIV CLASS="sect1" ><HR><H2 CLASS="sect1" ><A NAME="AEN2498" ></A >Date Arithmetic</H2 ><DIV CLASS="glosslist" ><DL ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN2503" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >FLOAT <TT CLASS="function" >date2jd</TT ></CODE >(<TT CLASS="parameter" ><I >EVENT|STRING</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > julian date number is number of days since origin (-4712/01/01 12h00 UT) of specified date </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN2513" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >EVENT <TT CLASS="function" >jd2date</TT ></CODE >(<TT CLASS="parameter" ><I >FLOAT</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > Convert julian date number to date (actually to event structure with subordinate date) </P ></DD ></DL ></DIV ><P > These functions allow adding or subtracting days from dates. </P ><P > <TT CLASS="function" >date2jd</TT > converts a date into a number of days, which can then be adjusted by simple arithmetic. Finally, <TT CLASS="function" >jd2date</TT > converts the number of days back into a date. </P ><P > Julian calendar is used before 4 OCT 1582, and Gregorian calendar afterwards. </P ><P > As with other date functions, calendar escapes (eg, "@#DRENCH R#@") are not respected, and the only the first date of the DATE record is used. </P ></DIV ><DIV CLASS="sect1" ><HR><H2 CLASS="sect1" ><A NAME="AEN2527" ></A >Value Extraction Functions</H2 ><DIV CLASS="glosslist" ><DL ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN2532" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >extractdate</TT ></CODE >(<TT CLASS="parameter" ><I >NODE</I ></TT >, <TT CLASS="parameter" ><I >INT_V</I ></TT >, <TT CLASS="parameter" ><I >INT_V</I ></TT >, <TT CLASS="parameter" ><I >INT_V</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > extract a date </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN2545" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >extractnames</TT ></CODE >(<TT CLASS="parameter" ><I >NODE</I ></TT >, <TT CLASS="parameter" ><I >LIST_V</I ></TT >, <TT CLASS="parameter" ><I >INT_V</I ></TT >, <TT CLASS="parameter" ><I >INT_V</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > extract a name </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN2558" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >extractplaces</TT ></CODE >(<TT CLASS="parameter" ><I >NODE</I ></TT >, <TT CLASS="parameter" ><I >LIST_V</I ></TT >, <TT CLASS="parameter" ><I >INT_V</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > extract a place </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN2570" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >extracttokens</TT ></CODE >(<TT CLASS="parameter" ><I >STRING</I ></TT >, <TT CLASS="parameter" ><I >LIST_V</I ></TT >, <TT CLASS="parameter" ><I >INT_V</I ></TT >, <TT CLASS="parameter" ><I >STRING</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > extract tokens </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN2583" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >extractdatestr</TT ></CODE >(<TT CLASS="parameter" ><I >VARB</I ></TT >, <TT CLASS="parameter" ><I >VARB</I ></TT >, <TT CLASS="parameter" ><I >VARB</I ></TT >, <TT CLASS="parameter" ><I >VARB</I ></TT >, <TT CLASS="parameter" ><I >VARB</I ></TT >, <TT CLASS="parameter" ><I >STRING</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > extract date from string </P ></DD ></DL ></DIV ><P > Value extraction functions read the values of certain lines and return those values in extracted form. </P ><P > <TT CLASS="function" >Extractdate</TT > extracts date values from either an event node or <TT CLASS="structfield" ><I >DATE</I ></TT > node. The first parameter must be a node; if its tag is <TT CLASS="structfield" ><I >DATE</I ></TT >, the date is extracted from the value of that node; if its tag is not <TT CLASS="structfield" ><I >DATE</I ></TT >, the date is extracted from the first <TT CLASS="structfield" ><I >DATE</I ></TT > line one level below the argument node. The remaining three arguments are variables. The first is assigned the integer value of the extracted day; the second is assigned the integer value of the extracted month; and the third is assigned the integer value of the extracted year. </P ><P > <TT CLASS="function" >Extractnames</TT > extracts name components from a <TT CLASS="structfield" ><I >NAME</I ></TT > line. Its first argument is either an <TT CLASS="structfield" ><I >INDI</I ></TT > or a <TT CLASS="structfield" ><I >NAME</I ></TT > node. If it is a <TT CLASS="structfield" ><I >NAME</I ></TT > line, the components are extracted from the value of that node; if it is an <TT CLASS="structfield" ><I >INDI</I ></TT > line, the components are extracted from the value of the first <TT CLASS="structfield" ><I >NAME</I ></TT > line in the person record. The second argument is a list that will hold the extracted components. The third argument is an integer variable that is set to the number of extracted components. The fourth argument is a variable that is set to the index (starting at one) of the surname component; the <TT CLASS="literal" >/</TT > characters are removed from around the surname component. If there is no surname this argument variable is set to zero. </P ><P > <TT CLASS="function" >Extractplaces</TT > extracts place components from a <TT CLASS="structfield" ><I >PLAC</I ></TT > node. The first argument is a node; if its tag is <TT CLASS="structfield" ><I >PLAC</I ></TT >, the places are extracted from the value of the node; if its tag is not <TT CLASS="structfield" ><I >PLAC</I ></TT >, places are extracted from the first <TT CLASS="structfield" ><I >PLAC</I ></TT > line one level below the argument node. The second parameter is a list that will hold the extracted components. The third argument is an integer variable that is set to the number of extracted components. Place components are defined by the comma-separated portions of the <TT CLASS="structfield" ><I >PLAC</I ></TT > value; leading and trailing white space is removed from the components, while all internal white space is retained. </P ><P > <TT CLASS="function" >Extracttokens</TT > extracts tokens from a string and places them in a list. The first argument is the string to extract tokens from. The second argument is the list to hold the tokens. The third argument is an integer variable that is set to the number of tokens extracted. The fourth parameter is the string of delimiter characters that <TT CLASS="function" >extracttokens</TT > uses to break the input string into tokens. </P ><P > <TT CLASS="function" >extractdatestr</TT > extracts date values from a . <TT CLASS="structfield" ><I >STRING</I ></TT >. It is intended for internal verification of date extraction code. The remaining five arguments are variables. The second is assigned the integer value of the extracted day; the third is assigned the integer value of the extracted month; and the fourth is assigned the integer value of the extracted year. </P ></DIV ><DIV CLASS="sect1" ><HR><H2 CLASS="sect1" ><A NAME="AEN2625" ></A >User Interaction Functions</H2 ><DIV CLASS="glosslist" ><DL ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN2630" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >getindi</TT ></CODE >(<TT CLASS="parameter" ><I >INDI_V</I ></TT >, <TT CLASS="parameter" ><I ><TT CLASS="replaceable" ><I >STRING</I ></TT ></I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > identify person through user interface </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN2642" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >getindiset</TT ></CODE >(<TT CLASS="parameter" ><I >SET_V</I ></TT >, <TT CLASS="parameter" ><I ><TT CLASS="replaceable" ><I >STRING</I ></TT ></I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > identify set of persons through user interface </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN2654" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >getfam</TT ></CODE >(<TT CLASS="parameter" ><I >FAM_V</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > identify family through user interface </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN2664" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >getint</TT ></CODE >(<TT CLASS="parameter" ><I >INT_V</I ></TT >, <TT CLASS="parameter" ><I ><TT CLASS="replaceable" ><I >STRING</I ></TT ></I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > get integer through user interface </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN2676" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >getstr</TT ></CODE >(<TT CLASS="parameter" ><I >STRING_V</I ></TT >, <TT CLASS="parameter" ><I ><TT CLASS="replaceable" ><I >STRING</I ></TT ></I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > get string through user interface </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN2688" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >INDI <TT CLASS="function" >choosechild</TT ></CODE >(<TT CLASS="parameter" ><I >INDI|FAM</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > select child of person/family through user interface </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN2698" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >FAM <TT CLASS="function" >choosefam</TT ></CODE >(<TT CLASS="parameter" ><I >INDI</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > select family person is in as spouse </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN2708" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >INDI <TT CLASS="function" >chooseindi</TT ></CODE >(<TT CLASS="parameter" ><I >SET</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > select person from set of persons </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN2718" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >INDI <TT CLASS="function" >choosespouse</TT ></CODE >(<TT CLASS="parameter" ><I >INDI</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > select spouse of person </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN2728" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >SET <TT CLASS="function" >choosesubset</TT ></CODE >(<TT CLASS="parameter" ><I >SET</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > select a subset of persons from set of persons </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN2738" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >INT <TT CLASS="function" >menuchoose</TT ></CODE >(<TT CLASS="parameter" ><I >LIST</I ></TT >, <TT CLASS="parameter" ><I ><TT CLASS="replaceable" ><I >STRING</I ></TT ></I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > select from a list of options </P ></DD ></DL ></DIV ><P > These functions interact with the user to get information needed by the program. </P ><P > <TT CLASS="function" >Getindi</TT > asks the user to identify a person. The first argument is a variable that is set to the person. The second is an optional string to use as a prompt. <TT CLASS="function" >Getindiset</TT > asks the user to identify a set of persons. <TT CLASS="function" >Getfam</TT > asks the user identify a family. <TT CLASS="function" >Getint</TT > and <TT CLASS="function" >getstr</TT > ask the user enter an integer and string, respectively. </P ><P > <TT CLASS="function" >Choosechild</TT > asks the user select a child of a family or person; its single argument is a person or family; it return the child. <TT CLASS="function" >Choosefam</TT > has the user select a family that a person is in as a spouse; its argument is a person; it returns the family. <TT CLASS="function" >Chooseindi</TT > has the user select one person from a set of persons; its argument in a set of persons; it returns the chosen person. <TT CLASS="function" >Choosespouse</TT > has the user select a spouse of a person; its argument is a person; it returns the chosen spouse. <TT CLASS="function" >Choosesubset</TT > has the user select a subset of persons from a set of persons; its argument is the chosen subset. </P ><P > <TT CLASS="function" >Menuchoose</TT > allows the user to select from an arbitrary menu. The first argument is a list of strings making up the items in the menu; the second, optional argument is a prompt string for the menu; <TT CLASS="function" >menuchoose</TT > returns the integer index of the item selected by the user; if the user doesn't select an item, <SPAN CLASS="returnvalue" >zero</SPAN > is returned. </P ></DIV ><DIV CLASS="sect1" ><HR><H2 CLASS="sect1" ><A NAME="AEN2765" ></A >String Functions</H2 ><DIV CLASS="glosslist" ><DL ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN2770" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >STRING <TT CLASS="function" >lower</TT ></CODE >(<TT CLASS="parameter" ><I >STRING</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > convert to lower case </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN2780" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >STRING <TT CLASS="function" >upper</TT ></CODE >(<TT CLASS="parameter" ><I >STRING</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > convert to upper case </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN2790" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >STRING <TT CLASS="function" >capitalize</TT ></CODE >(<TT CLASS="parameter" ><I >STRING</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > capitalize first letter </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN2800" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >STRING <TT CLASS="function" >titlecase</TT ></CODE >(<TT CLASS="parameter" ><I >STRING</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > capitalize first letter of each word </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN2810" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >STRING <TT CLASS="function" >trim</TT ></CODE >(<TT CLASS="parameter" ><I >STRING</I ></TT >, <TT CLASS="parameter" ><I >INT</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > trim to length </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN2821" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >STRING <TT CLASS="function" >rjustify</TT ></CODE >(<TT CLASS="parameter" ><I >STRING</I ></TT >, <TT CLASS="parameter" ><I >INT</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > right justify in field </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN2832" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >STRING <TT CLASS="function" >concat</TT ></CODE >(<TT CLASS="parameter" ><I >STRING</I ></TT >, <TT CLASS="parameter" ><I ><TT CLASS="replaceable" ><I >STRING</I ></TT ></I ></TT > <TT CLASS="parameter" ><I ><TT CLASS="replaceable" ><I >...</I ></TT ></I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > catenate two strings </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN2846" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >STRING <TT CLASS="function" >strconcat</TT ></CODE >(<TT CLASS="parameter" ><I >STRING</I ></TT >, <TT CLASS="parameter" ><I ><TT CLASS="replaceable" ><I >STRING</I ></TT ></I ></TT > <TT CLASS="parameter" ><I ><TT CLASS="replaceable" ><I >...</I ></TT ></I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > catenate two strings </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN2860" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >INT <TT CLASS="function" >strlen</TT ></CODE >(<TT CLASS="parameter" ><I >STRING</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > number of characters in string </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN2870" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >STRING <TT CLASS="function" >substring(</TT ></CODE >(<TT CLASS="parameter" ><I >STRING</I ></TT >, <TT CLASS="parameter" ><I >INT</I ></TT >, <TT CLASS="parameter" ><I >INT</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > substring function </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN2882" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >INT <TT CLASS="function" >index</TT ></CODE >(<TT CLASS="parameter" ><I >STRING</I ></TT >, <TT CLASS="parameter" ><I >STRING</I ></TT >, <TT CLASS="parameter" ><I >INT</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > index function </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN2894" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >STRING <TT CLASS="function" >d</TT ></CODE >(<TT CLASS="parameter" ><I >INT</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > number as decimal string </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN2904" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >STRING <TT CLASS="function" >f</TT ></CODE >(<TT CLASS="parameter" ><I >FLOAT</I ></TT >, <TT CLASS="parameter" ><I >INT</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > number as floating point string </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN2915" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >STRING <TT CLASS="function" >card</TT ></CODE >(<TT CLASS="parameter" ><I >INT</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > number in cardinal form (<TT CLASS="literal" >one, two, ...</TT >) </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN2926" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >STRING <TT CLASS="function" >ord</TT ></CODE >(<TT CLASS="parameter" ><I >INT</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > number in ordinal form (<TT CLASS="literal" >first, second, ...</TT >) </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN2937" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >STRING <TT CLASS="function" >alpha</TT ></CODE >(<TT CLASS="parameter" ><I >INT</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > convert number to Latin letter (<TT CLASS="literal" >a, b, ...</TT >) </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN2948" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >STRING <TT CLASS="function" >roman</TT ></CODE >(<TT CLASS="parameter" ><I >INT</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > number in Roman numeral form (<TT CLASS="literal" >i, ii, ...</TT >) </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN2959" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >STRING <TT CLASS="function" >strsoundex</TT ></CODE >(<TT CLASS="parameter" ><I >STRING</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > find SOUNDEX value of arbitrary string </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN2969" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >INT <TT CLASS="function" >strtoint</TT ></CODE >(<TT CLASS="parameter" ><I >STRING</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > convert numeric string to integer </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN2979" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >INT <TT CLASS="function" >atoi</TT ></CODE >(<TT CLASS="parameter" ><I >STRING</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > convert numeric string to integer </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN2989" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >INT <TT CLASS="function" >strcmp</TT ></CODE >(<TT CLASS="parameter" ><I >STRING</I ></TT >, <TT CLASS="parameter" ><I >STRING</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > general string compare </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3000" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >BOOL <TT CLASS="function" >eqstr</TT ></CODE >(<TT CLASS="parameter" ><I >STRING</I ></TT >, <TT CLASS="parameter" ><I >STRING</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > compare strings for equality </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3011" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >BOOL <TT CLASS="function" >nestr</TT ></CODE >(<TT CLASS="parameter" ><I >STRING</I ></TT >, <TT CLASS="parameter" ><I >STRING</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > compare strings for inequality </P ></DD ></DL ></DIV ><P > These functions provide string handling. Prior to version 3.0.6, many of them used an approach to memory management chosen for absolute minimal memory footprint. A function using this approach constructed its output string in its own string buffer, reusing that buffer each time it was called. When a function using this approach returned a string value it returned its buffer. In consequence the strings returned by these functions were to be either used or saved before the function was called again. </P ><P > <TT CLASS="function" >Lower</TT > and <TT CLASS="function" >upper</TT > convert the letters in their arguments to lower or upper case, respectively. <TT CLASS="function" >Capitalize</TT > converts the first character of the argument, if it is a letter, to upper case. <TT CLASS="function" >Lower</TT > and <TT CLASS="function" >upper</TT > historically used the buffer return method; <TT CLASS="function" >capitalize</TT > operates on and returns its argument. <TT CLASS="function" >titlecase</TT > converts the first letter of each word if it is a letter, to upper case and all other characters to lower case. </P ><P > <TT CLASS="function" >Trim</TT > shortens a string to the length specified by the second parameter. If the string is already of that length or shorter the string is not changed. <TT CLASS="function" >Rjustify</TT > right justifies a string into another string of the length specified by the second parameter. If the original string is shorter than the justified string, blanks are inserted to the left of the original string; if the string is longer than the justified string, the original string is truncated on the right. <TT CLASS="function" >Trim</TT > historically used the buffer return method; <TT CLASS="function" >rjustify</TT > creates and returns a new string. </P ><P > <TT CLASS="function" >Concat</TT > and <TT CLASS="function" >strconcat</TT > catenate strings and return the result. They are identical functions. They may take two to 32 string arguments; null arguments are allowed. The arguments are concatenated together into a single, newly allocated string, which is returned. </P ><P > <TT CLASS="function" >Strlen</TT > returns the length of the string argument. </P ><P > <TT CLASS="function" >Substring</TT > returns a substring of the first argument string. The second and third arguments are the indices of the first and last characters in the argument string to use to form the substring. The indexes are relative one. <TT CLASS="function" >Substring</TT > historically used the buffer return method. </P ><P > <TT CLASS="function" >Index</TT > returns the character index of the nth occurrence of a substring within a string. The index is the relative one character offset to the beginning of the substring. The first argument is the string; the second argument is the substring; and the third argument is the occurrence number. </P ><P > <TT CLASS="function" >D</TT >, <TT CLASS="function" >card</TT >, <TT CLASS="function" >ord</TT >, <TT CLASS="function" >alpha</TT > and <TT CLASS="function" >roman</TT > convert integers to strings. <TT CLASS="function" >D</TT > converts an integer to a numeric string; <TT CLASS="function" >card</TT > converts an integer to a cardinal number string (eg, <TT CLASS="literal" >one, two, three</TT >); <TT CLASS="function" >ord</TT > converts an integer to an ordinal number (eg, <TT CLASS="literal" >first, second, third</TT >); <TT CLASS="function" >alpha</TT > converts an integer to a letter (eg, <TT CLASS="literal" >a, b, c</TT >); and <TT CLASS="function" >roman</TT > converts an integer to a Roman numeral (eg, <TT CLASS="literal" >i, ii, iii</TT >). </P ><P > The <TT CLASS="function" >f</TT > function converts a float to a string. The optional second argument specifies the precision of the output. The default precision is 2. </P ><P > <TT CLASS="function" >Strsoundex</TT > converts an arbitrary string to a SOUNDEX value. Non-ASCII text characters are ignored in the string. </P ><P > <TT CLASS="function" >Strtoint</TT > converts a numeric string to an integer. <TT CLASS="function" >Atoi</TT > is identical to <TT CLASS="function" >strtoint</TT >. </P ><P > <TT CLASS="function" >Strcmp</TT > compares two strings and returns an integer that is less than zero, equal to zero, or greater than zero, if, respectively, the first string is lexicographically less than, equal to, or greater than the second string. <TT CLASS="function" >Eqstr</TT > and <TT CLASS="function" >nestr</TT > return whether two strings are equal or not equal, respectively. <TT CLASS="function" >Strcmp</TT >, <TT CLASS="function" >Eqstr</TT >, and <TT CLASS="function" >nestr</TT > all treat null strings as empty strings, which is to say they pretend that a null string is actually "". This means that all null and empty strings compare as equal. </P ></DIV ><DIV CLASS="sect1" ><HR><H2 CLASS="sect1" ><A NAME="AEN3074" ></A >Output Mode Functions</H2 ><DIV CLASS="glosslist" ><DL ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3079" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >linemode</TT ></CODE >(void);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > use line output mode </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3088" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >pagemode</TT ></CODE >(<TT CLASS="parameter" ><I >INT</I ></TT >, <TT CLASS="parameter" ><I >INT</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > use page output mode with given page size </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3099" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >col</TT ></CODE >(<TT CLASS="parameter" ><I >INT</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > position to column in output </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3109" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >INT <TT CLASS="function" >getcol</TT ></CODE >(void);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > get current column in output </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3118" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >row</TT ></CODE >(<TT CLASS="parameter" ><I >INT</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > position to row in output </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3128" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >pos</TT ></CODE >(<TT CLASS="parameter" ><I >INT</I ></TT >, <TT CLASS="parameter" ><I >INT</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > position to (row, col) coordinate in output </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3139" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >pageout</TT ></CODE >(void);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > output page buffer </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3148" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >STRING <TT CLASS="function" >nl</TT ></CODE >(void);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > newline character </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3157" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >STRING <TT CLASS="function" >sp</TT ></CODE >(void);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > space character </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3166" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >STRING <TT CLASS="function" >qt</TT ></CODE >(void);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > double quote character </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3175" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >newfile</TT ></CODE >(<TT CLASS="parameter" ><I >STRING</I ></TT >, <TT CLASS="parameter" ><I >BOOL</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > send program output to this file </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3186" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >STRING <TT CLASS="function" >outfile</TT ></CODE >(void);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > return name of current program output file </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3195" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >copyfile</TT ></CODE >(<TT CLASS="parameter" ><I >STRING</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > copy file contents to program output file </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3205" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >BOOLEAN <TT CLASS="function" >test</TT ></CODE >(<TT CLASS="parameter" ><I >STRING</I ></TT >, <TT CLASS="parameter" ><I >STRING</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > tests for characteristics of a file </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3217" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >print</TT ></CODE >(<TT CLASS="parameter" ><I >STRING</I ></TT >, <TT CLASS="parameter" ><I ><TT CLASS="replaceable" ><I >STRING</I ></TT ></I ></TT > <TT CLASS="parameter" ><I ><TT CLASS="replaceable" ><I >...</I ></TT ></I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > print string to standard output window </P ></DD ></DL ></DIV ><P > Reports can be generated in two modes, line mode and page mode. <TT CLASS="function" >Linemode</TT > selects line mode and <TT CLASS="function" >pagemode</TT > selects page mode; line mode is the default. The first parameter to <TT CLASS="function" >pagemode</TT > is the number of rows per page; the second parameter is the number of columns per page. When in the line mode report output is written directly to the output file as the program runs, line by line. When in page mode output is buffered into pages which are written to the output file when <TT CLASS="function" >pageout</TT > is called. Page mode is useful for generating charts (eg, pedigree charts or box charts) where it is convenient to compute the two-dimensional location of output. </P ><P > <TT CLASS="function" >Col</TT > positions output to the given column. If the current column is greater than the argument, col positions output to the given column on the next line. <TT CLASS="function" >Col</TT > works in both modes. <TT CLASS="function" >Getcol</TT > returns the current column in the output. </P ><P > <TT CLASS="function" >Row</TT > positions output to the first character in the given row; <TT CLASS="function" >row</TT > can only be used in page mode. </P ><P > <TT CLASS="function" >Pos</TT > positions output to a specified row and column coordinate; the first argument specifies the row, and the second specifies the column. <TT CLASS="function" >Pos</TT > can only be used in page mode. </P ><P > <TT CLASS="function" >Nl</TT > write a new line character to the output file; <TT CLASS="function" >sp</TT > writes a space character to the output file; and <TT CLASS="function" >qt</TT > writes a quote character to the output file. Note that <TT CLASS="literal" >\n</TT > and <TT CLASS="literal" >\'</TT > can be used within string values to represent the newline and double quote characters. </P ><P > <TT CLASS="function" >Newfile</TT > specifies the name of the report output file. Its first argument is the file's name; its second argument is an append flag - if its value is non-zero the report appends to this file; if its value is zero the report overwrites the contents of the file. <TT CLASS="function" >Newfile</TT > can be called many times; this allows a single report program to generate many report output files during one execution. Programs are not required to use <TT CLASS="function" >newfile</TT >; if it is not used then <TT CLASS="application" >LifeLines</TT > automatically asks for the name of the report output file. </P ><P > <TT CLASS="function" >Outfile</TT > returns the name of the current report output file. </P ><P > <TT CLASS="function" >Copyfile</TT > copies the contents of a file to the report output file; its argument is a string whose value is the name of a file; if the file name is not absolute nor relative, then the <TT CLASS="envar" >LLPROGRAMS</TT > environment variable, if set, will be used to search for the file; the file is opened and its contents copied to the report output file. </P ><P > <TT CLASS="function" >Test</TT > will check for a specified property of the specified file. The first argument is the property, the second argument is the filename. Supported properties are: r - file is readable w - file is writeable x - file is executable s - file has non-zero size z - file has zero size e - file exists f - check if argument is a file d - check if argument is a directory The return value is TRUE or FALSE, depending on whether the file had the specified property or not. </P ><P > <TT CLASS="function" >Print</TT > prints its argument string to the standard output window; <TT CLASS="function" >print</TT > may have one to 32 arguments. </P ></DIV ><DIV CLASS="sect1" ><HR><H2 CLASS="sect1" ><A NAME="AEN3265" ></A >Person Set Functions and GEDCOM Extraction</H2 ><DIV CLASS="glosslist" ><DL ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3270" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >indiset</TT ></CODE >(<TT CLASS="parameter" ><I >SET_V</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > declare a set variable </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3280" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >addtoset</TT ></CODE >(<TT CLASS="parameter" ><I >SET</I ></TT >, <TT CLASS="parameter" ><I >INDI</I ></TT >, <TT CLASS="parameter" ><I >ANY</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > add a person to a set </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3292" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >deletefromset</TT ></CODE >(<TT CLASS="parameter" ><I >SET</I ></TT >, <TT CLASS="parameter" ><I >INDI</I ></TT >, <TT CLASS="parameter" ><I >BOOL</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > remove a person from a set </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3304" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >INT <TT CLASS="function" >length</TT ></CODE >(<TT CLASS="parameter" ><I >SET</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > size of a set </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3314" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >SET <TT CLASS="function" >union</TT ></CODE >(<TT CLASS="parameter" ><I >SET</I ></TT >, <TT CLASS="parameter" ><I >SET</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > union of two sets </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3325" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >SET <TT CLASS="function" >intersect</TT ></CODE >(<TT CLASS="parameter" ><I >SET</I ></TT >, <TT CLASS="parameter" ><I >SET</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > intersection of two sets </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3336" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >SET <TT CLASS="function" >difference</TT ></CODE >(<TT CLASS="parameter" ><I >SET</I ></TT >, <TT CLASS="parameter" ><I >SET</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > difference of two sets </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3347" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >SET <TT CLASS="function" >parentset</TT ></CODE >(<TT CLASS="parameter" ><I >SET</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > set of all parents </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3357" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >SET <TT CLASS="function" >childset</TT ></CODE >(<TT CLASS="parameter" ><I >SET</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > set of all children </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3367" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >SET <TT CLASS="function" >spouseset</TT ></CODE >(<TT CLASS="parameter" ><I >SET</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > set of all spouses </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3377" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >SET <TT CLASS="function" >siblingset</TT ></CODE >(<TT CLASS="parameter" ><I >SET</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > set of all siblings </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3387" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >SET <TT CLASS="function" >ancestorset</TT ></CODE >(<TT CLASS="parameter" ><I >SET</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > set of all ancestors </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3397" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >SET <TT CLASS="function" >descendentset</TT ></CODE >(<TT CLASS="parameter" ><I >SET</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > set of all descendents </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3407" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >SET <TT CLASS="function" >descendantset</TT ></CODE >(<TT CLASS="parameter" ><I >SET</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > same as descendentset; spelling </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3417" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >SET <TT CLASS="function" >uniqueset</TT ></CODE >(<TT CLASS="parameter" ><I >SET</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > remove duplicates from set </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3427" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >namesort</TT ></CODE >(<TT CLASS="parameter" ><I >SET</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > sort indiset by name </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3437" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >keysort</TT ></CODE >(<TT CLASS="parameter" ><I >SET</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > sort indiset by key values </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3447" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >valuesort</TT ></CODE >(<TT CLASS="parameter" ><I >SET</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > sort indiset by auxiliary values </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3457" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >genindiset</TT ></CODE >(<TT CLASS="parameter" ><I >STRING</I ></TT >, <TT CLASS="parameter" ><I >SET</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > generate indiset from GEDCOM name string </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3468" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >BOOL <TT CLASS="function" >inset</TT ></CODE >(<TT CLASS="parameter" ><I >SET</I ></TT >, <TT CLASS="parameter" ><I >INDI</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > <SPAN CLASS="returnvalue" >true</SPAN > if the Individual is in the set. </P ></DD ><DT ><B ><TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="synopsis" ><B CLASS="command" >forindiset</B >( <TT CLASS="replaceable" ><I >SET</I ></TT >, <TT CLASS="replaceable" ><I >INDI_V</I ></TT >, <TT CLASS="replaceable" ><I >ANY_V</I ></TT >, <TT CLASS="replaceable" ><I >INT_V</I ></TT > ) { <TT CLASS="replaceable" ><I >commands</I ></TT > } </PRE ></TD ></TR ></TABLE ></B ></DT ><DD ><P > loop through all persons in person set </P ></DD ></DL ></DIV ><P > These functions allow you to manipulate person sets. A person set is a potentially large set of persons; each person may have an arbitrary value associated with him/her. A person set must be declared with the <TT CLASS="function" >indiset</TT > function before it can be used. </P ><P > <TT CLASS="function" >Addtoset</TT > adds a person to a set. The first argument is the set; the second argument is the person; and the third argument may be any value. The same person may be added to a set more than once, each time with a different value. <TT CLASS="function" >Deletefromset</TT > removes a person from a set. The first argument is the set; the second argument is the person; if the third parameter is <SPAN CLASS="returnvalue" >true</SPAN > all of the person's entries are removed from the set; if <SPAN CLASS="returnvalue" >false</SPAN > only the first entry is removed. <TT CLASS="function" >Length</TT > returns the number of persons in a person set. </P ><P > <TT CLASS="function" >Union</TT >, <TT CLASS="function" >intersect</TT > and <TT CLASS="function" >difference</TT > return the set union, set intersection and set difference, respectively, of two person sets. Each functions takes two person sets as arguments and returns a third person set. The functions actually modify their argument sets, both reordering them into canonical key order and removing any duplicates (these operations are necessary to easily implement these types of set functions). </P ><P > <TT CLASS="function" >Parentset</TT >, <TT CLASS="function" >childset</TT >, <TT CLASS="function" >spouseset</TT > and <TT CLASS="function" >siblingset</TT > return the set of all parents, set of all children, set of all spouses and set of all siblings, respectively, of the set of persons in their argument. In all cases there is no change to the argument person set. </P ><P > <TT CLASS="function" >Ancestorset</TT > returns the set all ancestors of all persons in the argument set. <TT CLASS="function" >Descendentset</TT > returns the set of all descendents of all persons in the argument set. <TT CLASS="function" >Descendantset</TT > is the same as <TT CLASS="function" >descendentset</TT >; it allows an alternate spelling. </P ><P > <TT CLASS="function" >Uniqueset</TT > sorts a person set by key value and then removes all entries with duplicate keys; the input set is modified and returned. </P ><P > <TT CLASS="function" >Namesort</TT >, <TT CLASS="function" >keysort</TT > and <TT CLASS="function" >valuesort</TT > sort a set of persons by name, by key and by associated value, respectively. </P ><P > Each person in a person set has an associated value. When a person is added to a set with <TT CLASS="function" >addtoset</TT >, the value is explicitly assigned. When new sets are created by other functions, a number of rules are used to associate values with persons as they are added to the new sets. For <TT CLASS="function" >parentset</TT >, <TT CLASS="function" >childset</TT > and <TT CLASS="function" >spouseset</TT > the values are copied from the first input set person that causes the new person to be added to the set. For <TT CLASS="function" >union</TT >, <TT CLASS="function" >intersect</TT > and <TT CLASS="function" >difference</TT >, the values are copied from the values in the first input set, except in the case of <TT CLASS="function" >union</TT >, when persons are taken from the second set alone, in which case the values come from there. For <TT CLASS="function" >ancestorset</TT > and <TT CLASS="function" >descendantset</TT > the value is set to the number of generations the new person is away from the <I CLASS="emphasis" >first</I > person in the input set that the new person is related to. If the new person is related to more than one person in the input set, the value is set for the nearest relationship; that is, the value is as low as possible. <TT CLASS="function" >Valuesort</TT > sorts a person set by the values of these auxiliary values. </P ><P > <TT CLASS="function" >Genindiset</TT > generates the set of persons that matches a string whose value is a name in <SPAN CLASS="acronym" >GEDCOM</SPAN > format. <TT CLASS="function" >Genindiset</TT > uses the same algorithm that matches names entered at the browse prompt or by the user interaction <TT CLASS="function" >getindiset</TT > function. </P ><P > <TT CLASS="function" >Inset</TT > returns <SPAN CLASS="returnvalue" >true</SPAN > if the the specified individual is in the SET. </P ><P > <TT CLASS="function" >Forindiset</TT > is an iterator that loops through each person in an indiset. The first parameter is an indiset. The second parameter is a variable that iterates through each person in the set. The third parameter iterates through the values associated with the persons. The fourth parameter is an integer variable that counts the iterations. </P ></DIV ><DIV CLASS="sect1" ><HR><H2 CLASS="sect1" ><A NAME="AEN3540" ></A >Record Update Functions</H2 ><DIV CLASS="glosslist" ><DL ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3545" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >NODE <TT CLASS="function" >createnode</TT ></CODE >(<TT CLASS="parameter" ><I >STRING</I ></TT >, <TT CLASS="parameter" ><I >STRING</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > create a GEDCOM node </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3556" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >addnode</TT ></CODE >(<TT CLASS="parameter" ><I >NODE</I ></TT >, <TT CLASS="parameter" ><I >NODE</I ></TT >, <TT CLASS="parameter" ><I >NODE</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > add a node to a GEDCOM tree </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3568" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >detachnode</TT ></CODE >(<TT CLASS="parameter" ><I >NODE</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > delete a node from a GEDCOM tree </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3578" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >writeindi</TT ></CODE >(<TT CLASS="parameter" ><I >INDI</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > write a person back to the database </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3588" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >writefam</TT ></CODE >(<TT CLASS="parameter" ><I >FAM</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > write a family back to the database </P ></DD ></DL ></DIV ><P > These functions allow you to modify an internal <SPAN CLASS="acronym" >GEDCOM</SPAN > node tree. </P ><P > <TT CLASS="function" >Createnode</TT > creates a <SPAN CLASS="acronym" >GEDCOM</SPAN > node; the two arguments are tag and value strings, respectively; the value string can be <SPAN CLASS="returnvalue" >null</SPAN >. <TT CLASS="function" >Addnode</TT > adds a node to a node tree. The first argument is the new node; the second is the node in the tree that becomes the parent of the new node; the third is the node in the tree that becomes the previous sibling of the new node; this argument is <SPAN CLASS="returnvalue" >null</SPAN > if the new node is to become the first child of the parent. <TT CLASS="function" >Detachnode</TT > removes a node from a node tree. <TT CLASS="function" >writeindi</TT > writes an individual record back to the database, and <TT CLASS="function" >writefam</TT > writes a family record back to the database, allowing the report to make permanent changes to the database. </P ><P > The node functions only change data in memory; there is no effect on the database until and unless <TT CLASS="function" >writeindi</TT > or <TT CLASS="function" >writefam</TT > are called. </P ></DIV ><DIV CLASS="sect1" ><HR><H2 CLASS="sect1" ><A NAME="AEN3610" ></A >Record Linking Functions</H2 ><DIV CLASS="glosslist" ><DL ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3615" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >BOOL <TT CLASS="function" >reference</TT ></CODE >(<TT CLASS="parameter" ><I >STRING</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > determine if string is a cross reference </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3625" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >NODE <TT CLASS="function" >dereference</TT ></CODE >(<TT CLASS="parameter" ><I >STRING</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > reference cross reference or key to node tree </P ></DD ></DL ></DIV ><P > These functions allow you to recognize values that are cross references and to read the records they refer to. <TT CLASS="function" >Reference</TT > returns <SPAN CLASS="returnvalue" >true</SPAN > if its string argument is a cross reference value, that is, the internal key of one of the records in the database. <TT CLASS="function" >Dereference</TT > returns the node tree of the record referred to by its cross-reference string argument. </P ></DIV ><DIV CLASS="sect1" ><HR><H2 CLASS="sect1" ><A NAME="AEN3637" ></A >Miscellaneous Functions</H2 ><DIV CLASS="glosslist" ><DL ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3642" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >lock</TT ></CODE >(<TT CLASS="parameter" ><I >RECORD|NODE</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > lock a record (or record containing specified node) in memory </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3652" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >unlock</TT ></CODE >(<TT CLASS="parameter" ><I >RECORD|NODE</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > unlock a record (or record containing specified node) from memory </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3662" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >STRING <TT CLASS="function" >database</TT ></CODE >(void);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > return name of current database </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3671" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >STRING <TT CLASS="function" >program</TT ></CODE >(void);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > return name of current program </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3680" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >STRING <TT CLASS="function" >version</TT ></CODE >(void);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > return version of <TT CLASS="application" >LifeLines</TT > program </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3690" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >system</TT ></CODE >(<TT CLASS="parameter" ><I >STRING</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > execute string as a UNIX shell command </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3700" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >INT <TT CLASS="function" >heapused</TT ></CODE >(void);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > amount of heap used for windows </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3709" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >STRING <TT CLASS="function" >getproperty</TT ></CODE >(<TT CLASS="parameter" ><I >STRING</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > extract system or user property. Function available after v3.0.5. </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3719" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >STRING <TT CLASS="function" >setlocale</TT ></CODE >(<TT CLASS="parameter" ><I >STRING</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > set the locale </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3729" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >STRING <TT CLASS="function" >bytecode</TT ></CODE >(<TT CLASS="parameter" ><I >STRING</I ></TT >, <TT CLASS="parameter" ><I >STRING</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > encode a string in a codeset </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3740" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >STRING <TT CLASS="function" >convertcode</TT ></CODE >(<TT CLASS="parameter" ><I >STRING</I ></TT >, <TT CLASS="parameter" ><I >STRING</I ></TT >, <TT CLASS="parameter" ><I >STRING</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > convert string from one codeset to another </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3752" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >debug</TT ></CODE >(<TT CLASS="parameter" ><I >BOOLEAN</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > set interperter debug mode </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3762" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >STRING <TT CLASS="function" >pvalue</TT ></CODE >(<TT CLASS="parameter" ><I >ANY</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > dump information about a pvalue </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3772" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >free</TT ></CODE >(<TT CLASS="parameter" ><I >ANY</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > free space associated with a variable </P ></DD ></DL ></DIV ><P > <TT CLASS="function" >Lock</TT > and <TT CLASS="function" >unlock</TT > are used to lock a person or family into <SPAN CLASS="acronym" >RAM</SPAN > memory, and to unlock a person or family from <SPAN CLASS="acronym" >RAM</SPAN > memory, respectively. </P ><P > <TT CLASS="function" >Database</TT > returns the name of the current database, useful in titling reports. <TT CLASS="function" >program</TT > returns the name of the current report program. <TT CLASS="function" >Version</TT > returns the version of the running <TT CLASS="application" >LifeLines</TT > program, eg, <TT CLASS="literal" >3.0.61</TT >. </P ><P > <TT CLASS="function" >System</TT > executes its string argument as a <SPAN CLASS="acronym" >UNIX</SPAN > (or <SPAN CLASS="acronym" >MS-Windows</SPAN > as appropriate) shell command, by invoking the system shell. This will not occur if the user has chosen to disallow report system calls (via the DenySystemCalls user option). </P ><P > The <TT CLASS="function" >heapused</TT > function returns the amount of system heap that is in use at the time. This is implemented only on windows. </P ><P > The <TT CLASS="function" >getproperty</TT > function extracts system or user properties. Properties are named group.subgroup.property, group.property or even property. The keys are available at the moment can be found in the ll-userguide under System and User Properties. </P ><P > The <TT CLASS="function" >setlocale</TT > function sets the locale and returns the previous setting of locale. </P ><P > The <TT CLASS="function" >bytecode</TT > function converts the supplied string with escape codes to the current codeset from the internal codeset or from the codeset specified by the optional second parameter if specified. A escaped code is a dollar sign ($) followed by 2 hex characters, e.g. $C1. </P ><P > The <TT CLASS="function" >convertcode</TT > function converts a string to another codeset. In the two argument form, the second argument is the destination codeset, and the source codeset is the internal codeset. In the 3 argument form, the second argument is the source codeset and the third argument is the destination codeset. (See the section of the LifeLines User Guide on codeset conversions.) For example, if your internal codeset is UTF-8, and the report codeset is UTF-8, the following code, <TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="programlisting" > "<p>\n" convertcode(str,"UTF-8//html") </PRE ></TD ></TR ></TABLE > writes the first line of output as it is written, but will apply the html sub-conversion to all the characters in the string str. The special html codes, like the less than or greater than, will be escaped when printing the second string, but not when printing the first string. </P ><P > The <TT CLASS="function" >debug</TT > function turns on or off programming debugging. When enabled gobs of information is printed as a <TT CLASS="application" >LifeLines</TT > program is run. This can be useful to figure out why a program is not behaving as expected. </P ><P > The <TT CLASS="function" >pvalue</TT > function returns a string that represents the contents of a variable in the interpreter. This is present for debug purposes. </P ><P > The function <TT CLASS="function" >free</TT > deallocates space associated with the variable provided as argument 1. Care must be taken when free is used in a function on a variable which is a parameter to the function. free will not effect the variable in the calling program. </P ></DIV ><DIV CLASS="sect1" ><HR><H2 CLASS="sect1" ><A NAME="AEN3813" ></A >Deprecated Functions</H2 ><P > The <TT CLASS="function" >baptism</TT > finds christening (CHR) events. The types of events desired to be found, depend on the nature of the report being written. It is recommended that custom access routines be used instead of <TT CLASS="function" >baptism</TT >. </P ><DIV CLASS="glosslist" ><DL ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3821" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >EVENT <TT CLASS="function" >baptism</TT ></CODE >(<TT CLASS="parameter" ><I >INDI</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > first baptism event of </P ><P > If you want a routine that returns the first event for an individual that is a baptism, LDS baptism, Christening or Adult Christening, the following routine can be used. <TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="synopsis" >func get_baptism(indi) { fornodes(indi,node) { if (index(" BAPM BAPL CHR CHRA ",upper(tag(node)),1)) { return(node) } } return(0) }</PRE ></TD ></TR ></TABLE > If you want to search for additional events or fewer events you can modify the string in the index call acccordingly. Likewise, if you want the to prioritize the results, finding a christening event if one exists, else finding a baptism event if one exists, then finding an LDS baptism event, and finally a christening event, the following function is suggested. <TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="synopsis" >/* get_baptism(indi) returns a baptism event if found events CHR, BAPM, BAPL, and CHRA are considered, in that order */ func get_baptism(indi, prefs) { set(chr, 0) set(bapm, 0) set(bapl, 0) set(chra, 0) fornodes(indi,node) { if (and(eq(upper(tag(node)), "CHR"), not(chr)) { set(chr, node) } if (and(eq(upper(tag(node)), "BAPM"), not(bapm)) { set(bapm, node) } if (and(eq(upper(tag(node)), "BAPL"), not(bapl)) { set(bapl, node) } if (and(eq(upper(tag(node)), "CHRA"), not(chra)) { set(chra, node) } } if (chr) { return(chr) } if (bapm) { return(bapm) } if (bapl) { return(bapl) } return(chra) }</PRE ></TD ></TR ></TABLE > </P ></DD ></DL ></DIV ><P > The functionality of the following three functions, <TT CLASS="function" >getindimsg</TT >, <TT CLASS="function" >getintmsg</TT > and <TT CLASS="function" >getstrmsg</TT > is now available using the optional parameter of <TT CLASS="function" >getindi</TT >, <TT CLASS="function" >getint</TT > and <TT CLASS="function" >getstr</TT >. These functions should no longer be used as they will be removed from a future version of <TT CLASS="application" >Lifelines</TT >. </P ><DIV CLASS="glosslist" ><DL ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3843" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >getindimsg</TT ></CODE >(<TT CLASS="parameter" ><I >INDI_V</I ></TT >, <TT CLASS="parameter" ><I ><TT CLASS="replaceable" ><I >STRING</I ></TT ></I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > identify person through user interface </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3855" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >getintmsg</TT ></CODE >(<TT CLASS="parameter" ><I >INT_V</I ></TT >, <TT CLASS="parameter" ><I ><TT CLASS="replaceable" ><I >STRING</I ></TT ></I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > get integer through user interface </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3867" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >getstrmsg</TT ></CODE >(<TT CLASS="parameter" ><I >STRING_V</I ></TT >, <TT CLASS="parameter" ><I ><TT CLASS="replaceable" ><I >STRING</I ></TT ></I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > get string through user interface </P ></DD ></DL ></DIV ><P > Three functions are available for to generate <SPAN CLASS="acronym" >GEDCOM</SPAN > format output to the report output file of all persons in the argument person set. These functions do not in most cases generate consistent and usable output. This can be done with a program, but it is suggested that these routines are probably not what you really wanted. </P ><P > <TT CLASS="function" >Gengedcom</TT > output contains a person record for each person in the set, and all the family records that link at least two of the persons in the set together. This function is provided for backward compatibility. Source, Event and Other(X) record pointers are output unmodified, but none of their records are output - this yields an inconsistent output. </P ><P > <TT CLASS="function" >Gengedcomweak</TT > output does not contain Source, Event or Other(X) record pointers or their records. <TT CLASS="function" >Gengedcomstrong</TT > includes the Source, Event and Other(X) record pointers and all top-level nodes referenced by them. </P ><DIV CLASS="glosslist" ><DL ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3887" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >gengedcom</TT ></CODE >(<TT CLASS="parameter" ><I >SET</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > generate GEDCOM file from person set </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3897" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >gengedcomweak</TT ></CODE >(<TT CLASS="parameter" ><I >SET</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > generate GEDCOM file from person set </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3907" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >gengedcomstrong</TT ></CODE >(<TT CLASS="parameter" ><I >SET</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > generate GEDCOM file from person set </P ></DD ></DL ></DIV ><P > By the release of version 3.0.6, all string values are local copies, and the <TT CLASS="function" >save</TT > and <TT CLASS="function" >strsave</TT > functions should be entirely unnecessary. <TT CLASS="function" >Save</TT > is present only for compatibility reasons. Previously it duplicated its argument (to prevent strings from becoming stale; this is not currently necessary (and this function no longer does anything). <TT CLASS="function" >Strsave</TT > is the same function as <TT CLASS="function" >save</TT >. </P ><DIV CLASS="glosslist" ><DL ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3924" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >STRING <TT CLASS="function" >save</TT ></CODE >(<TT CLASS="parameter" ><I >STRING</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > save and return copy of string </P ></DD ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3934" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >STRING <TT CLASS="function" >strsave</TT ></CODE >(<TT CLASS="parameter" ><I >STRING</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > same as save function </P ></DD ></DL ></DIV ><P > Use <TT CLASS="function" >detachnode</TT > instead of <TT CLASS="function" >deletenode</TT >. </P ><DIV CLASS="glosslist" ><DL ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3948" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >VOID <TT CLASS="function" >deletenode</TT ></CODE >(<TT CLASS="parameter" ><I >NODE</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > delete a node from a GEDCOM tree </P ></DD ></DL ></DIV ><P > In releases after version 3.0.39, the <TT CLASS="function" >length</TT > function accepts an argument of type <SPAN CLASS="type" >list</SPAN >, <SPAN CLASS="type" >set</SPAN > or <SPAN CLASS="type" >table</SPAN >. the <TT CLASS="function" >lengthset</TT > function is no longer needed. </P ><DIV CLASS="glosslist" ><DL ><DT ><B ><DIV CLASS="funcsynopsis" ><A NAME="AEN3965" ></A ><P ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >INT <TT CLASS="function" >lengthset</TT ></CODE >(<TT CLASS="parameter" ><I >SET</I ></TT >);</CODE ></P ><P ></P ></DIV ></B ></DT ><DD ><P > size of a set </P ></DD ></DL ></DIV ></DIV ></DIV ></DIV ></BODY ></HTML >