File: ll-reportmanual.html

package info (click to toggle)
lifelines 3.0.50-2etch1
links: PTS
area: main
in suites: etch
size: 11,160 kB
ctags: 6,517
sloc: ansic: 57,468; xml: 8,014; sh: 4,489; makefile: 848; yacc: 601; perl: 170; sed: 16
file content (11964 lines) | stat: -rw-r--r-- 162,439 bytes
parent folder | download | duplicates (2)
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>&#13;
THE LIFELINES PROGRAMMING SUBSYSTEM AND REPORT GENERATOR

</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"></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"
>THE <SPAN
CLASS="application"
>LIFELINES</SPAN
> PROGRAMMING SUBSYSTEM AND REPORT GENERATOR</A
></H1
><H2
CLASS="subtitle"
><SPAN
CLASS="application"
>LifeLines</SPAN
> Version 3.0.50</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
>1. <A
HREF="#AEN12"
>Report Programming Manual</A
></DT
><DD
><DL
><DT
>1.1. <A
HREF="#AEN14"
>Introduction</A
></DT
><DT
>1.2. <A
HREF="#AEN28"
>Tutorial Ahnentafel report</A
></DT
><DT
>1.3. <A
HREF="#AEN141"
>Template for creating new reports</A
></DT
></DL
></DD
><DT
>2. <A
HREF="#AEN145"
><SPAN
CLASS="application"
>LIFELINES</SPAN
> PROGRAMMING REFERENCE</A
></DT
><DD
><DL
><DT
>2.1. <A
HREF="#AEN154"
>Procedures and Functions</A
></DT
><DT
>2.2. <A
HREF="#AEN208"
>Comments</A
></DT
><DT
>2.3. <A
HREF="#AEN219"
>Statements</A
></DT
><DT
>2.4. <A
HREF="#AEN326"
>Expressions</A
></DT
><DT
>2.5. <A
HREF="#AEN342"
>Include Feature</A
></DT
><DT
>2.6. <A
HREF="#AEN358"
>Built-in Functions</A
></DT
><DT
>2.7. <A
HREF="#AEN367"
>Value Types</A
></DT
><DT
>2.8. <A
HREF="#AEN464"
>Iterators</A
></DT
><DT
>2.9. <A
HREF="#AEN475"
>Arithmetic and Logic Functions</A
></DT
><DT
>2.10. <A
HREF="#AEN730"
>Trigonometric and Spherical Calculations</A
></DT
><DT
>2.11. <A
HREF="#AEN837"
>Person Functions</A
></DT
><DT
>2.12. <A
HREF="#AEN1314"
>Family Functions</A
></DT
><DT
>2.13. <A
HREF="#AEN1528"
>Other types of records</A
></DT
><DT
>2.14. <A
HREF="#AEN1562"
>List Functions</A
></DT
><DT
>2.15. <A
HREF="#AEN1790"
>Table Functions</A
></DT
><DT
>2.16. <A
HREF="#AEN1854"
>GEDCOM Node Functions</A
></DT
><DT
>2.17. <A
HREF="#AEN1994"
>Event and Date Functions</A
></DT
><DT
>2.18. <A
HREF="#AEN2435"
>Value Extraction Functions</A
></DT
><DT
>2.19. <A
HREF="#AEN2533"
>User Interaction Functions</A
></DT
><DT
>2.20. <A
HREF="#AEN2673"
>String Functions</A
></DT
><DT
>2.21. <A
HREF="#AEN2982"
>Output Mode Functions</A
></DT
><DT
>2.22. <A
HREF="#AEN3173"
>Person Set Functions and GEDCOM Extraction</A
></DT
><DT
>2.23. <A
HREF="#AEN3448"
>Record Update Functions</A
></DT
><DT
>2.24. <A
HREF="#AEN3518"
>Record Linking Functions</A
></DT
><DT
>2.25. <A
HREF="#AEN3545"
>Miscellaneous Functions</A
></DT
><DT
>2.26. <A
HREF="#AEN3721"
>Deprecated Functions</A
></DT
></DL
></DD
></DL
></DIV
><DIV
CLASS="LOT"
><DL
CLASS="LOT"
><DT
><B
>List of Examples</B
></DT
><DT
>1-1. <A
HREF="#AEN32"
>Example of ahnentafel report</A
></DT
><DT
>1-2. <A
HREF="#AEN37"
>Example of ahnentafel report script</A
></DT
></DL
></DIV
><DIV
CLASS="chapter"
><HR><H1
><A
NAME="AEN12"
></A
>Chapter 1. 
Report Programming Manual
</H1
><DIV
CLASS="sect1"
><H2
CLASS="sect1"
><A
NAME="AEN14"
>1.1. Introduction</A
></H2
><P
>&#13;
     The <SPAN
CLASS="application"
>LifeLines</SPAN
> programming subsystem
     lets you produce reports in any style or layout. You may
     generate files in <SPAN
CLASS="application"
>troff</SPAN
>,
     <SPAN
CLASS="application"
>Postscript</SPAN
>,
     <SPAN
CLASS="application"
>TeX</SPAN
>, <ACRONYM
CLASS="acronym"
>SGML</ACRONYM
> or any
     other <ACRONYM
CLASS="acronym"
>ASCII</ACRONYM
>-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
     <SPAN
CLASS="application"
>LifeLines</SPAN
> program that computes the
     relationship between any two persons in a database.

</P
><P
>&#13;
     Each <SPAN
CLASS="application"
>LifeLines</SPAN
> program is written
     in the <SPAN
CLASS="application"
>LifeLines</SPAN
> programming
     language, and the programs are stored in normal files. When
     you direct <SPAN
CLASS="application"
>LifeLines</SPAN
> 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"
>1.2. Tutorial Ahnentafel report</A
></H2
><P
>&#13;
     For example, say you want <SPAN
CLASS="application"
>LifeLines</SPAN
>
     to generate an ahnentafel. Such a report might look
     like:

<DIV
CLASS="example"
><A
NAME="AEN32"
></A
><P
><B
>Example 1-1. 
Example of ahnentafel report   
</B
></P
><P
CLASS="literallayout"
><br>
1.&nbsp;Thomas&nbsp;Trask&nbsp;WETMORE&nbsp;IV<br>
b.&nbsp;18&nbsp;December&nbsp;1949,&nbsp;New&nbsp;London,&nbsp;Connecticut<br>
2.&nbsp;Thomas&nbsp;Trask&nbsp;WETMORE&nbsp;III<br>
b.&nbsp;15&nbsp;October&nbsp;1925,&nbsp;New&nbsp;London,&nbsp;Connecticut<br>
3.&nbsp;Joan&nbsp;Marie&nbsp;HANCOCK<br>
b.&nbsp;6&nbsp;June&nbsp;1928,&nbsp;New&nbsp;London,&nbsp;Connecticut<br>
4.&nbsp;Thomas&nbsp;Trask&nbsp;WETMORE&nbsp;Jr<br>
b.&nbsp;5&nbsp;May&nbsp;1896,&nbsp;New&nbsp;London,&nbsp;Connecticut<br>
d.&nbsp;8&nbsp;November&nbsp;1970,&nbsp;New&nbsp;London,&nbsp;Connecticut<br>
5.&nbsp;Vivian&nbsp;Genevieve&nbsp;BROWN<br>
b.&nbsp;5&nbsp;April&nbsp;1896,&nbsp;Mondovi,&nbsp;Wisconsin<br>
6.&nbsp;Richard&nbsp;James&nbsp;HANCOCK<br>
b.&nbsp;18&nbsp;August&nbsp;1904,&nbsp;New&nbsp;London,&nbsp;Connecticut<br>
d.&nbsp;24&nbsp;December&nbsp;1976,&nbsp;Waterford,&nbsp;Connecticut<br>
7.&nbsp;Muriel&nbsp;Armstrong&nbsp;SMITH<br>
b.&nbsp;28&nbsp;October&nbsp;1905,&nbsp;New&nbsp;Haven,&nbsp;Connecticut<br>
8.&nbsp;Thomas&nbsp;Trask&nbsp;WETMORE&nbsp;Sr<br>
b.&nbsp;13&nbsp;March&nbsp;1866,&nbsp;St.&nbsp;Mary's&nbsp;Bay,&nbsp;Nova&nbsp;Scotia<br>
d.&nbsp;17&nbsp;February&nbsp;1947,&nbsp;New&nbsp;London,&nbsp;Connecticut<br>
9.&nbsp;Margaret&nbsp;Ellen&nbsp;KANEEN<br>
b.&nbsp;27&nbsp;October&nbsp;1859,&nbsp;Liverpool,&nbsp;England<br>
d.&nbsp;10&nbsp;May&nbsp;1900,&nbsp;New&nbsp;London,&nbsp;Connecticut<br>
...&nbsp;lots&nbsp;more</P
></DIV
>

</P
><P
>&#13;
     Here is a <SPAN
CLASS="application"
>LifeLines</SPAN
> program that
     generates this report:

<DIV
CLASS="example"
><A
NAME="AEN37"
></A
><P
><B
>Example 1-2. 
Example of ahnentafel report script   
</B
></P
><PRE
CLASS="programlisting"
>&#13;
/*
 * @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)
    enqueue(alist, 1)
    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
></DIV
>

</P
><P
>&#13;
     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,
     <SPAN
CLASS="application"
>LifeLines</SPAN
> asks:

<PRE
CLASS="screen"
>&#13;What is the name of the report program?
enter string:
</PRE
>

</P
><P
>&#13;
     You enter
     <KBD
CLASS="userinput"
><TT
CLASS="literal"
>ahnentafel_tutorial</TT
></KBD
>. Since the
     program generates a report,
     <SPAN
CLASS="application"
>LifeLines</SPAN
> asks where to write that
     report:

<PRE
CLASS="screen"
>&#13;What is the name of the output file?
enter file name:
</PRE
>

</P
><P
>&#13;
     You enter a file name, say
     <KBD
CLASS="userinput"
><TT
CLASS="filename"
>my.ahnen</TT
></KBD
>.
     <SPAN
CLASS="application"
>LifeLines</SPAN
> reads the program ahnen,
     executes the program, and writes the report output to
     <TT
CLASS="filename"
>my.ahnen</TT
>. <SPAN
CLASS="application"
>LifeLines</SPAN
>
     reports any syntax or run-time errors found while trying to
     run the program.


</P
><P
>&#13;
     A <SPAN
CLASS="application"
>LifeLines</SPAN
> 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
>&#13;     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
>&#13;
     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:

<PRE
CLASS="programlisting"
>&#13;getindi(indi)
list(ilist)
list(alist)
enqueue(ilist, indi)
enqueue(alist, 1)
</PRE
>
</P
><P
>&#13;
     The first <SPAN
CLASS="type"
>statement</SPAN
> calls the
     <CODE
CLASS="function"
>getindi</CODE
> (get individual) <SPAN
CLASS="type"
>built-in
     function</SPAN
>, which causes
     <SPAN
CLASS="application"
>LifeLines</SPAN
> to ask you to identify a
     person using the zip browse style of identification:

<PRE
CLASS="screen"
>&#13;Identify person for interpreted report
enter name:
</PRE
>


</P
><P
>&#13;
     After you identify a person, he or she is assigned to the
     variable <CODE
CLASS="varname"
>indi</CODE
>. The next two
     <SPAN
CLASS="type"
>statements</SPAN
> declare two <SPAN
CLASS="type"
>list
     variables</SPAN
>, <CODE
CLASS="varname"
>ilist</CODE
> and
     <CODE
CLASS="varname"
>alist</CODE
>. <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, <CODE
CLASS="varname"
>ilist</CODE
> holds a list of
     ancestors, in ahnentafel order, who have not yet been reported
     on, and <CODE
CLASS="varname"
>alist</CODE
> holds their respective
     ahnentafel numbers.


</P
><P
>&#13;
     The next two statements call the <CODE
CLASS="function"
>enqueue</CODE
>
     function, adding the first members to both lists. The person
     identified by the <CODE
CLASS="function"
>getindi</CODE
> function is
     made the first member of <CODE
CLASS="varname"
>ilist</CODE
>, and the
     number one, this person's ahnentafel number, is made the first
     member of <CODE
CLASS="varname"
>alist</CODE
>.

</P
><P
>&#13;
The rest of the program is:

<PRE
CLASS="programlisting"
>&#13;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
>

</P
><P
>&#13;
     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
>&#13;
     The loop is a <SPAN
CLASS="type"
>while</SPAN
> loop statement. The line:
<PRE
CLASS="programlisting"
>&#13;while (indi, dequeue(ilist)) {
</PRE
>
removes (via <CODE
CLASS="function"
>dequeue</CODE
>) a person from <CODE
CLASS="varname"
>ilist</CODE
>, and assigns the person to variable <CODE
CLASS="varname"
>indi</CODE
>. As long as there
are persons on <CODE
CLASS="varname"
>ilist</CODE
>, another iteration of the loop follows.

</P
><P
>&#13;
The statement:<PRE
CLASS="programlisting"
>&#13;
set(ahnen, dequeue(alist))</PRE
>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 <CODE
CLASS="varname"
>alist</CODE
> is removed and assigned to variable
<CODE
CLASS="varname"
>ahnen</CODE
>. This is the ahnentafel number of the person just removed from <CODE
CLASS="varname"
>ilist</CODE
>.

</P
><P
>&#13;
The line:<PRE
CLASS="programlisting"
>&#13;
d(ahnen) ". " name(indi) nl()</PRE
>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 <CODE
CLASS="function"
>d</CODE
> function converts its integer
argument to a numeric string. The ". " is a literal (constant) string value. The <CODE
CLASS="function"
>name</CODE
> function returns the
default form of a person's name. The <CODE
CLASS="function"
>nl</CODE
> function returns a string containing the newline character.

</P
><P
>&#13;
The next two lines:

<PRE
CLASS="programlisting"
>&#13;if (e, birth(indi)) { " b. " long(e) nl() }
if (e, death(indi)) { " d. " long(e) nl() }
</PRE
>

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
<CODE
CLASS="varname"
>e</CODE
>, 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 <CODE
CLASS="function"
>long</CODE
> and
<CODE
CLASS="function"
>nl</CODE
> functions. <CODE
CLASS="function"
>Long</CODE
> takes an
<CODE
CLASS="parameter"
>event</CODE
> and returns the values of
the first <CODE
CLASS="structfield"
>DATE</CODE
> and
<CODE
CLASS="structfield"
>PLAC</CODE
> lines in the <SPAN
CLASS="type"
>event</SPAN
>.

</P
><P
>&#13;
Finally in the program is:<PRE
CLASS="programlisting"
>&#13;
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
>

</P
><P
>&#13;
These lines add the father and mother of the current person, if either or both are in the database, to
<CODE
CLASS="varname"
>ilist</CODE
>. They also compute and add the parents' ahnentafel numbers to <CODE
CLASS="varname"
>alist</CODE
>. 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 <CODE
CLASS="function"
>mul</CODE
> and <CODE
CLASS="function"
>add</CODE
> functions.

</P
></DIV
><DIV
CLASS="sect1"
><HR><H2
CLASS="sect1"
><A
NAME="AEN141"
>1.3. Template for creating new reports</A
></H2
><P
>&#13;The following is a good template to use when creating a new report from scratch.
</P
><PRE
CLASS="programlisting"
>&#13;/*
 * @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
></DIV
></DIV
><DIV
CLASS="chapter"
><HR><H1
><A
NAME="AEN145"
></A
>Chapter 2. 

<SPAN
CLASS="application"
>LIFELINES</SPAN
> PROGRAMMING REFERENCE

</H1
><P
>&#13;
<SPAN
CLASS="application"
>LifeLines</SPAN
> programs are stored in files you edit with a screen editor. Programs are not edited from within
the <SPAN
CLASS="application"
>LifeLines</SPAN
> 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 <SPAN
CLASS="application"
>LifeLines</SPAN
> databases. You may set the
<CODE
CLASS="envar"
>LLPROGRAMS</CODE
> shell variable to hold a list of directories that <SPAN
CLASS="application"
>LifeLines</SPAN
> will use to automatically
search for programs when you request program execution.

</P
><DIV
CLASS="sect1"
><HR><H2
CLASS="sect1"
><A
NAME="AEN154"
>2.1. Procedures and Functions</A
></H2
><P
>&#13;
A <SPAN
CLASS="application"
>LifeLines</SPAN
> 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:<PRE
CLASS="synopsis"
>proc name(params) { statements }</PRE
>

</P
><P
>&#13;
<CODE
CLASS="symbol"
>Name</CODE
> is the name of the <SPAN
CLASS="type"
>procedure</SPAN
>, <CODE
CLASS="symbol"
>params</CODE
> is an optional list of <SPAN
CLASS="type"
>parameters</SPAN
> separated by commas,
and <CODE
CLASS="symbol"
>statements</CODE
> 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
>&#13;
A function has format:<PRE
CLASS="synopsis"
>func name(params) { statements }</PRE
>

</P
><P
>&#13;
<CODE
CLASS="symbol"
>Name</CODE
>, <CODE
CLASS="symbol"
>params</CODE
> and <CODE
CLASS="symbol"
>statements</CODE
> 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
>&#13;<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
>&#13;</P
></DIV
><DIV
CLASS="sect1"
><HR><H2
CLASS="sect1"
><A
NAME="AEN208"
>2.2. Comments</A
></H2
><P
>&#13;
You may comment your <SPAN
CLASS="application"
>LifeLines</SPAN
> programs using the following notation:<PRE
CLASS="programlisting"
>&#13;
/*...comment text including any characters except */... */</PRE
>

</P
><P
>&#13;These comments may be inserted anywhere in the program file.
</P
><P
>&#13;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
><PRE
CLASS="programlisting"
>&#13;/*
* @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
><P
>&#13;
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="AEN219"
>2.3. Statements</A
></H2
><P
>&#13;
     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
     <PRE
CLASS="synopsis"
>name(indi)</PRE
>, where <CODE
CLASS="symbol"
>indi</CODE
>
     is a person, returns the person's name and writes it to the
     output file. On the other hand, the expression
     <PRE
CLASS="synopsis"
>set(n, nspouses(indi))</PRE
> assigns the
     variable <CODE
CLASS="varname"
>n</CODE
> the number of spouses that
     person <CODE
CLASS="varname"
>indi</CODE
> has, but since
     <CODE
CLASS="function"
>set</CODE
> returns
     <SPAN
CLASS="returnvalue"
>null</SPAN
>, nothing is written to the
     output file.

</P
><P
>&#13;
     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:

     <PRE
CLASS="synopsis"
>if ([varb,] expr) { statements }
               [ elsif ([varb], expr) { statements } ]*
                    [ else { statements } ]
     </PRE
>

     <PRE
CLASS="synopsis"
>while ([varb,] expr ) { statements }</PRE
>

     <PRE
CLASS="synopsis"
>call name(args)</PRE
>

</P
><P
>&#13;
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
>&#13;
Note that <SPAN
CLASS="type"
>if</SPAN
> treats null strings as false, but empty strings as true. This has the benefit that

<PRE
CLASS="programlisting"
>&#13;if (birth(indi))
</PRE
>

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
>&#13;
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
>&#13;
The <SPAN
CLASS="type"
>call</SPAN
> statement provides procedure calls. <CODE
CLASS="symbol"
>Name</CODE
> must match one of the <SPAN
CLASS="type"
>procedures</SPAN
> defined in the
report program. <CODE
CLASS="symbol"
>Args</CODE
> 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
>&#13;
The following report language statements are commonly encountered only near the top of a report:
<PRE
CLASS="synopsis"
>char_encoding(string)</PRE
>
<PRE
CLASS="synopsis"
>require(string)</PRE
>
<PRE
CLASS="synopsis"
>option(string)</PRE
>
<PRE
CLASS="synopsis"
>include(string)</PRE
>
<PRE
CLASS="synopsis"
>global(varb)</PRE
>

</P
><P
>&#13;
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:


<PRE
CLASS="programlisting"
>&#13;char_encoding("ISO-8859-1")
</PRE
>

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 <CODE
CLASS="parameter"
>string</CODE
> expression is
the name of another <SPAN
CLASS="application"
>LifeLines</SPAN
> 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 <CODE
CLASS="parameter"
>variable</CODE
> to have global scope.  The 
<CODE
CLASS="parameter"
>variable</CODE
> is initialized to 0.

</P
><P
>&#13;
The report language also includes the following statements, which mimic some common programming languages:

<PRE
CLASS="synopsis"
>set(varb, expr)</PRE
>
<PRE
CLASS="synopsis"
>continue()</PRE
>
<PRE
CLASS="synopsis"
>break()</PRE
>
<PRE
CLASS="synopsis"
>return([expr])</PRE
>

</P
><P
>&#13;
The <SPAN
CLASS="type"
>set</SPAN
> statement is the assignment statement; the <CODE
CLASS="parameter"
>expression</CODE
> is evaluated, and its value is assigned
to the <CODE
CLASS="parameter"
>variable</CODE
>. 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="AEN326"
>2.4. Expressions</A
></H2
><P
>&#13;
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
>&#13;
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="AEN342"
>2.5. Include Feature</A
></H2
><P
>&#13;
The <SPAN
CLASS="application"
>LifeLines</SPAN
> programming language provides an <SPAN
CLASS="type"
>include</SPAN
> feature. Using this feature one <SPAN
CLASS="application"
>LifeLines</SPAN
>
program can refer to other <SPAN
CLASS="application"
>LifeLines</SPAN
> programs. This feature is provided by the include statement:<PRE
CLASS="synopsis"
>include(string)</PRE
>where <CODE
CLASS="symbol"
>string</CODE
> is a quoted string that is the name of another <SPAN
CLASS="application"
>LifeLines</SPAN
> 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 <SPAN
CLASS="application"
>LifeLines</SPAN
>
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. <SPAN
CLASS="application"
>LifeLines</SPAN
> will use the <CODE
CLASS="envar"
>LLPROGRAMS</CODE
> 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
>&#13;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="AEN358"
>2.6. Built-in Functions</A
></H2
><P
>&#13;
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 <SPAN
CLASS="application"
>LifeLines</SPAN
> 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="AEN367"
>2.7. Value Types</A
></H2
><DIV
CLASS="glosslist"
><DL
><DT
><B
><SPAN
CLASS="type"
>ANY</SPAN
></B
></DT
><DD
><P
>&#13;union of all types
</P
></DD
><DT
><B
><SPAN
CLASS="type"
>BOOL</SPAN
></B
></DT
><DD
><P
>&#13;boolean (0 represents false; anything else represents true)
</P
></DD
><DT
><B
><SPAN
CLASS="type"
>EVENT</SPAN
></B
></DT
><DD
><P
>&#13;event; reference to substructure of nodes in a <ACRONYM
CLASS="acronym"
>GEDCOM</ACRONYM
> record (reference)
</P
></DD
><DT
><B
><SPAN
CLASS="type"
>FAM</SPAN
></B
></DT
><DD
><P
>&#13;family; reference to a <ACRONYM
CLASS="acronym"
>GEDCOM</ACRONYM
> FAM record (reference)
</P
></DD
><DT
><B
><SPAN
CLASS="type"
>FLOAT</SPAN
></B
></DT
><DD
><P
>&#13;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
>&#13;person; reference to a <ACRONYM
CLASS="acronym"
>GEDCOM</ACRONYM
> INDI record (reference)
</P
></DD
><DT
><B
><SPAN
CLASS="type"
>INT</SPAN
></B
></DT
><DD
><P
>&#13;integer (on most systems a 32-bit signed value)
</P
></DD
><DT
><B
><SPAN
CLASS="type"
>LIST</SPAN
></B
></DT
><DD
><P
>&#13;arbitrary length list of any values (reference)
</P
></DD
><DT
><B
><SPAN
CLASS="type"
>NODE</SPAN
></B
></DT
><DD
><P
>&#13;<ACRONYM
CLASS="acronym"
>GEDCOM</ACRONYM
> node; reference to a line in a <ACRONYM
CLASS="acronym"
>GEDCOM</ACRONYM
> tree/record (reference)
</P
></DD
><DT
><B
><SPAN
CLASS="type"
>NUMBER</SPAN
></B
></DT
><DD
><P
>&#13;union of all arithmetic types (INT and FLOAT)
</P
></DD
><DT
><B
><SPAN
CLASS="type"
>SET</SPAN
></B
></DT
><DD
><P
>&#13;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
>&#13;text string
</P
></DD
><DT
><B
><SPAN
CLASS="type"
>TABLE</SPAN
></B
></DT
><DD
><P
>&#13;keyed look-up table (reference)
</P
></DD
><DT
><B
><SPAN
CLASS="type"
>VOID</SPAN
></B
></DT
><DD
><P
>&#13;type with no values
</P
></DD
></DL
></DIV
><P
>&#13;
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
<CODE
CLASS="varname"
>XXX_V</CODE
>, where <CODE
CLASS="symbol"
>XXX</CODE
> 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
>&#13;
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="AEN464"
>2.8. Iterators</A
></H2
><P
>&#13;
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
>&#13;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
>&#13;     <PRE
CLASS="synopsis"
>children(afam,indi,cnt) { commands }</PRE
>
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
>&#13;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="AEN475"
>2.9. Arithmetic and Logic Functions</A
></H2
><DIV
CLASS="glosslist"
><DL
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN480"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>NUMBER add</CODE
>(NUMBER,
NUMBER
...);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;addition - two to 32 arguments
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN492"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>NUMBER sub</CODE
>(NUMBER,
NUMBER);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;
subtraction

</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN503"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>NUMBER mul</CODE
>(NUMBER,
NUMBER
...);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;
multiplication - two to 32 arguments

</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN515"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>NUMBER div</CODE
>(NUMBER,
NUMBER);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;
division

</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN526"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>INT mod</CODE
>(INT,
INT);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;
modulus (remainder)

</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN537"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>NUMBER exp</CODE
>(NUMBER,
INT);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;
exponentiation

</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN548"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>NUMBER neg</CODE
>(NUMBER);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;
negation

</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN558"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>FLOAT float</CODE
>(INT);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;
convert int to float

</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN568"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>INT int</CODE
>(FLOAT);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;
convert float to int

</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN578"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID incr</CODE
>(NUMBER,NUMBER);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;
increment variable by second argument (or by 1 if no second argument)

</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN589"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID decr</CODE
>(NUMBER,NUMBER);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;
decrement variable by second argument (or by 1 if no second argument)

</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN600"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>BOOL and</CODE
>(BOOL,
BOOL
...);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;
logical and - two to 32 arguments

</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN612"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>BOOL or</CODE
>(BOOL,
BOOL
...);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;
logical or - two to 32 arguments

</P
></DD
><DT
><B
> <DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN624"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>BOOL not</CODE
>(BOOL);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;
logical not

</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN634"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>BOOL eq</CODE
>(ANY,
ANY);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;
equality (not strings)

</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN645"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>BOOL ne</CODE
>(ANY,
ANY);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;
non-equality

</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN656"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>BOOL lt</CODE
>(ANY,
ANY);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;
less than

</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN667"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>BOOL gt</CODE
>(ANY,
ANY
);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;
greater than

</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN678"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>BOOL le</CODE
>(ANY,
ANY);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;
less than or equal

</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN689"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>BOOL ge</CODE
>(ANY,
ANY);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;
greater than or equal

</P
></DD
></DL
></DIV
><P
>&#13;<CODE
CLASS="function"
>Add</CODE
>, <CODE
CLASS="function"
>sub</CODE
>, <CODE
CLASS="function"
>mul</CODE
> 
and <CODE
CLASS="function"
>div</CODE
> do normal arithmetic of integer or floating values.
If any operand is float, the result is float.
Functions <CODE
CLASS="function"
>add</CODE
> and <CODE
CLASS="function"
>mul</CODE
> can have two to
32 arguments; the sum or product of the full set of arguments is computed.
Functions <CODE
CLASS="function"
>sub</CODE
> and <CODE
CLASS="function"
>div</CODE
> have 
two arguments each; <CODE
CLASS="function"
>sub</CODE
> subtracts its second argument
from its first, and <CODE
CLASS="function"
>div</CODE
> divides its first argument by its
second.
The <CODE
CLASS="function"
>mod</CODE
> function returns the remainder after dividing the
first parameter by the second. If the second argument to 
<CODE
CLASS="function"
>div</CODE
> or <CODE
CLASS="function"
>mod</CODE
> is zero,
these functions return 0 and generate a run time error.
<CODE
CLASS="function"
>Exp</CODE
> performs integer exponentiation.
<CODE
CLASS="function"
>Neg</CODE
> negates its argument.
The functions 
<CODE
CLASS="function"
>float</CODE
> and
<CODE
CLASS="function"
>int</CODE
>
can be used to explicitly convert a value to float or int where needed.
</P
><P
>&#13;<CODE
CLASS="function"
>Incr</CODE
> and <CODE
CLASS="function"
>decr</CODE
> 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
>&#13;<CODE
CLASS="function"
>And</CODE
> and <CODE
CLASS="function"
>or</CODE
> 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. <CODE
CLASS="function"
>Not</CODE
> does the logical not operation.
</P
><P
>&#13;<CODE
CLASS="function"
>Eq</CODE
>, <CODE
CLASS="function"
>ne</CODE
>, <CODE
CLASS="function"
>lt</CODE
>, <CODE
CLASS="function"
>le</CODE
>, <CODE
CLASS="function"
>gt</CODE
> and <CODE
CLASS="function"
>ge</CODE
> evaluate the six ordering relationships between two integers.
</P
></DIV
><DIV
CLASS="sect1"
><HR><H2
CLASS="sect1"
><A
NAME="AEN730"
>2.10. Trigonometric and Spherical Calculations</A
></H2
><DIV
CLASS="glosslist"
><DL
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN735"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>FLOAT sin</CODE
>(FLOAT);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;compute sine of argument in degrees
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN745"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>FLOAT cos</CODE
>(FLOAT);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;compute cosine of argument in degrees
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN755"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>FLOAT tan</CODE
>(FLOAT);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;compute tangent of argument in degrees
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN765"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>FLOAT arcsin</CODE
>(FLOAT);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;compute inverse sine of argument
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN775"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>FLOAT arccos</CODE
>(FLOAT);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;compute inverse cosine of argument
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN785"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>FLOAT arctan</CODE
>(FLOAT);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;compute inverse tangent of argument
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN795"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID dms2deg</CODE
>(INT degree,
INT minute,
INT second,
FLOAT_V decimal);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;convert (degree, minute, second) to decimal degrees
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN808"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>void deg2dms</CODE
>(FLOAT decimal,
INT_V degree,
INT_V minute,
INT_V second);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;convert decimal degrees to (degree, minute, second)
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN821"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>FLOAT spdist</CODE
>(FLOAT lat0,
FLOAT long0,
FLOAT lat1,
FLOAT long1);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;compute distance between two locations
</P
></DD
></DL
></DIV
><P
>&#13;The trigonometric functions specify angles using degrees.  The functions
<CODE
CLASS="function"
>deg2dms</CODE
> and <CODE
CLASS="function"
>dms2deg</CODE
>
are provided to convert between (degree,minute,second) notation and decimal
degree representations for angles.
</P
><P
>&#13;<CODE
CLASS="function"
>spdist</CODE
> 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="AEN837"
>2.11. Person Functions</A
></H2
><DIV
CLASS="glosslist"
><DL
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN842"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>STRING name</CODE
>(INDI,
<TT
CLASS="replaceable"
><I
>BOOL</I
></TT
>);</CODE
></P
><P
></P
></DIV
>
</B
></DT
><DD
><P
>&#13;default name of
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN854"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>STRING fullname</CODE
>(INDI,
BOOL,
BOOL,
INT);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;many name forms of
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN867"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>STRING surname</CODE
>(INDI);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;surname of
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN877"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>STRING givens</CODE
>(INDI);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;given names of
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN887"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>STRING trimname</CODE
>(INDI,
INT);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;trimmed name of
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN898"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>EVENT birth</CODE
>(INDI);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;first birth event of
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN908"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>EVENT death</CODE
>(INDI);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;first death event of
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN918"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>EVENT burial</CODE
>(INDI);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;first burial event of
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN928"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>INDI father</CODE
>(INDI);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;first father of
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN938"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>INDI mother</CODE
>(INDI);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;first mother of
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN948"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>INDI nextsib</CODE
>(INDI);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;next (younger) sibling of
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN958"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>INDI prevsib</CODE
>(INDI);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;previous (older) sibling of
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN968"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>STRING sex</CODE
>(INDI);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;sex of
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN978"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>BOOL male</CODE
>(INDI);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;male predicate
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN988"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>BOOL female</CODE
>(INDI);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;female predicate
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN998"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>STRING pn</CODE
>(INDI,
INT);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;pronoun referring to
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN1009"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>INT nspouses</CODE
>(INDI);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;number of spouses of
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN1019"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>INT nfamilies</CODE
>(INDI);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;number of families (as spouse/parent) of
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN1029"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>FAM parents</CODE
>(INDI);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;first parents' family of
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN1039"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>STRING title</CODE
>(INDI);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;first title of
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN1049"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>STRING key</CODE
>(INDI|FAM,
<TT
CLASS="replaceable"
><I
>BOOL</I
></TT
>);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;internal key of (work for families also)
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN1061"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>STRING soundex</CODE
>(INDI);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;SOUNDEX code of
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN1071"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>NODE inode</CODE
>(INDI);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;root GEDCOM node of
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN1081"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>NODE root</CODE
>(INDI);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;root GEDCOM node of
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN1091"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>INDI indi</CODE
>(STRING);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;find person with key value
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN1101"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>INDI firstindi</CODE
>(void);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;first person in database in key order
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN1110"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>INDI lastindi</CODE
>(void);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;last person in database in key order
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN1119"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>INDI nextindi</CODE
>(INDI);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;next person in database in key order
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN1129"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>INDI previndi</CODE
>(INDI);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;previous person in database in key order
</P
></DD
><DT
><B
><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
>
</B
></DT
><DD
><P
>&#13;loop through all spouses of
</P
></DD
><DT
><B
><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
></B
></DT
><DD
><P
>&#13;loop through all families (as spouse) of
</P
></DD
><DT
><B
><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
>
</B
></DT
><DD
><P
>&#13;loop through all persons in database
</P
></DD
><DT
><B
><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
></B
></DT
><DD
><P
>&#13;loop through all female parents of a person
</P
></DD
><DT
><B
><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
>
</B
></DT
><DD
><P
>&#13;loop through all male parents of a person
</P
></DD
><DT
><B
><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
></B
></DT
><DD
><P
>&#13;loop through all familes a person is a child of
</P
></DD
></DL
></DIV
><P
>&#13;These functions take a person as a parameter and return information about him or her.
</P
><P
>&#13;<CODE
CLASS="function"
>Name</CODE
> returns the default name of a person; this is the name found on the first <CODE
CLASS="structfield"
>1 NAME</CODE
> line in the
person's record; the slashes are removed and the surname is made all capitals; <CODE
CLASS="function"
>name</CODE
> 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
>&#13;<CODE
CLASS="function"
>Fullname</CODE
> 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
>&#13;<CODE
CLASS="function"
>Surname</CODE
> returns the surname of the person, as found in the first <CODE
CLASS="structfield"
>1 NAME</CODE
> line; the slashes are
removed. <CODE
CLASS="function"
>Givens</CODE
> returns the given names of the person in the same order and format as found in the
first <CODE
CLASS="structfield"
>1 NAME</CODE
> line of the record. <CODE
CLASS="function"
>Trimname</CODE
> returns the default name of the person trimmed to the
maximum character length given in the second variable.
</P
><P
>&#13;<CODE
CLASS="function"
>Birth</CODE
>, <CODE
CLASS="function"
>death</CODE
>, and <CODE
CLASS="function"
>burial</CODE
> return the first birth, death, and burial event in the
person's record, respectively. An event is a level <CODE
CLASS="structfield"
>1 GEDCOM</CODE
> node. If there is no matching event these
functions return <SPAN
CLASS="returnvalue"
>null</SPAN
>.
</P
><P
>&#13;<CODE
CLASS="function"
>Father</CODE
>, <CODE
CLASS="function"
>mother</CODE
>, <CODE
CLASS="function"
>nextsib</CODE
> and <CODE
CLASS="function"
>prevsib</CODE
> 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 <CODE
CLASS="function"
>father</CODE
>
(<CODE
CLASS="function"
>mother</CODE
>) function returns the first one. These functions return <SPAN
CLASS="returnvalue"
>null</SPAN
> if there is no person in the role.
</P
><P
>&#13;<CODE
CLASS="function"
>Sex</CODE
> 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. <CODE
CLASS="function"
>Male</CODE
> and <CODE
CLASS="function"
>female</CODE
> return <SPAN
CLASS="returnvalue"
>true</SPAN
> if the person is male or female,
respectively, or <SPAN
CLASS="returnvalue"
>false</SPAN
> if not.
</P
><P
>&#13;<CODE
CLASS="function"
>Pn</CODE
> generates pronouns, useful when generating English text;
the second parameter selects the type of pronoun:
</P
><DIV
CLASS="informaltable"
><P
></P
><A
NAME="AEN1242"
></A
><TABLE
BORDER="0"
FRAME="void"
CLASS="CALSTABLE"
><COL
WIDTH="48"><COL><TBODY
><TR
><TD
>0</TD
><TD
>He/She</TD
></TR
><TR
><TD
>1</TD
><TD
>he/she</TD
></TR
><TR
><TD
>2</TD
><TD
>His/Her</TD
></TR
><TR
><TD
>3</TD
><TD
>his/her</TD
></TR
><TR
><TD
>4</TD
><TD
>him/her</TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
><P
>&#13;<CODE
CLASS="function"
>Nspouses</CODE
> returns the number of spouses the person has in the database, and <CODE
CLASS="function"
>nfamilies</CODE
> returns the
number of families the person is a parent/spouse in; these two values are not necessarily the same.
<CODE
CLASS="function"
>Parents</CODE
> returns the first family that the person is a child in.
</P
><P
>&#13;<CODE
CLASS="function"
>Title</CODE
> returns the value of the first <CODE
CLASS="structfield"
>1 TITL</CODE
> line in the record. <CODE
CLASS="function"
>Key</CODE
> returns the key value of a person or
family; it there is a second parameter and it is non-null, the leading <TT
CLASS="literal"
>I</TT
> or <TT
CLASS="literal"
>F</TT
> will be stripped. <CODE
CLASS="function"
>Soundex</CODE
>
returns the Soundex code of the person.
</P
><P
>&#13;<CODE
CLASS="function"
>Root</CODE
> and <CODE
CLASS="function"
>Inode</CODE
> return the root node of the person's <ACRONYM
CLASS="acronym"
>GEDCOM</ACRONYM
> 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
<CODE
CLASS="function"
>root</CODE
> or <CODE
CLASS="function"
>inode</CODE
> function to get the root of the person node tree. <CODE
CLASS="function"
>Root</CODE
> and <CODE
CLASS="function"
>inode</CODE
> are synonyms.
</P
><P
>&#13;<CODE
CLASS="function"
>Indi</CODE
> returns the person who's key is passed as an argument;
if no person has the key <CODE
CLASS="function"
>indi</CODE
> returns
<SPAN
CLASS="returnvalue"
>null</SPAN
>.
INDI  keys are accepted either as Innn or @Innn@.
</P
><P
>&#13;<CODE
CLASS="function"
>Firstindi</CODE
>, <CODE
CLASS="function"
>nextindi</CODE
> and <CODE
CLASS="function"
>previndi</CODE
> allow you to iterate through all persons in the database. <CODE
CLASS="function"
>Firstindi</CODE
>
returns the first person in the database in key order. <CODE
CLASS="function"
>Nextindi</CODE
> returns the next person after the
argument person in key order. <CODE
CLASS="function"
>Previndi</CODE
> returns the previous person before the argument person in key
order.
</P
><P
>&#13;<CODE
CLASS="function"
>Spouses</CODE
> 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
>&#13;<CODE
CLASS="function"
>Families</CODE
> 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
>&#13;<CODE
CLASS="function"
>Families</CODE
> and <CODE
CLASS="function"
>Spouses</CODE
> 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 
<CODE
CLASS="function"
>spouses</CODE
> iterator, but it does show up with the
<CODE
CLASS="function"
>families</CODE
> iterator.  One caution, this situation causes
the 3rd argument of the <CODE
CLASS="function"
>families</CODE
> iterator to be set to
null.  You must check for this.
</P
><P
>&#13;<CODE
CLASS="function"
>Forindi</CODE
> 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
>&#13;<CODE
CLASS="function"
>mothers</CODE
> 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
>&#13;<CODE
CLASS="function"
>Parents</CODE
> 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
>&#13;<CODE
CLASS="function"
>Forindi</CODE
> 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
>&#13;<CODE
CLASS="function"
>fathers</CODE
> and
<CODE
CLASS="function"
>mothers</CODE
> 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="AEN1314"
>2.12. Family Functions</A
></H2
><DIV
CLASS="glosslist"
><DL
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN1319"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>EVENT marriage</CODE
>(FAM);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;first marriage event of
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN1329"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>INDI husband</CODE
>(FAM);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;first husband/father of
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN1339"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>INDI wife</CODE
>(FAM);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;first wife/mother of
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN1349"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>INT nchildren</CODE
>(FAM);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;number of children in
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN1359"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>INDI firstchild</CODE
>(FAM);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;first child of
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN1369"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>INDI lastchild</CODE
>(FAM);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;last child of
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN1379"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>STRING key</CODE
>(FAM|INDI,
<TT
CLASS="replaceable"
><I
>BOOL</I
></TT
>);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;internal key of (works for persons also)
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN1391"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>NODE fnode</CODE
>(FAM);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;root GEDCOM node of
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN1401"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>NODE root</CODE
>(FAM);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;root GEDCOM node of
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN1411"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>FAM fam</CODE
>(STRING);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;find family from key
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN1421"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>FAM firstfam</CODE
>(void);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;first family in database in key order
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN1430"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>FAM lastfam</CODE
>(void);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;last family in database in key order
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN1439"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>FAM nextfam</CODE
>(FAM);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;next family in database in key order
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN1449"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>FAM prevfam</CODE
>(FAM);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;previous family in database in key order
</P
></DD
><DT
><B
><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
></B
></DT
><DD
><P
>&#13;loop through children of family
</P
></DD
><DT
><B
><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
></B
></DT
><DD
><P
>&#13;loop through all husbands and wives of a family
</P
></DD
><DT
><B
><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
></B
></DT
><DD
><P
>&#13;loop through all families in database
</P
></DD
></DL
></DIV
><P
>&#13;These functions take a family as an argument and return information about it.
</P
><P
>&#13;<CODE
CLASS="function"
>Marriage</CODE
> 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
>&#13;<CODE
CLASS="function"
>Husband</CODE
> returns the first husband/father of the family, if any; and <CODE
CLASS="function"
>wife</CODE
> 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
>&#13;<CODE
CLASS="function"
>Nchildren</CODE
> returns the number of children in the family.
</P
><P
>&#13;<CODE
CLASS="function"
>Firstchild</CODE
> and <CODE
CLASS="function"
>lastchild</CODE
> return the first child and last child in a family, respectively.
</P
><P
>&#13;<CODE
CLASS="function"
>Key</CODE
> was described in the section on person functions.
</P
><P
>&#13;<CODE
CLASS="function"
>Root</CODE
> and <CODE
CLASS="function"
>fnode</CODE
> return the root node of a family <ACRONYM
CLASS="acronym"
>GEDCOM</ACRONYM
> 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 <CODE
CLASS="function"
>root</CODE
> or
<CODE
CLASS="function"
>fnode</CODE
> function to get the root of the family node tree. <CODE
CLASS="function"
>Root</CODE
> and <CODE
CLASS="function"
>fnode</CODE
> are synonyms.
</P
><P
>&#13;<CODE
CLASS="function"
>Fam</CODE
> returns the family who's key is passed as an argument;
if no family has the key <CODE
CLASS="function"
>fam</CODE
> 
returns <SPAN
CLASS="returnvalue"
>null</SPAN
>.  Family keys are accepted
either as Fnnn or @Fnnn@.
</P
><P
>&#13;<CODE
CLASS="function"
>Firstfam</CODE
>, <CODE
CLASS="function"
>nextfam</CODE
> and <CODE
CLASS="function"
>prevfam</CODE
> allow you to iterate through all families in the database. <CODE
CLASS="function"
>Firstfam</CODE
>
returns the first family in the database in key order. <CODE
CLASS="function"
>Nextfam</CODE
> returns the next family after the
argument family in key order. <CODE
CLASS="function"
>Prevfam</CODE
> returns the previous family before the argument family in key
order.
</P
><P
>&#13;<CODE
CLASS="function"
>Children</CODE
> 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
>&#13;<CODE
CLASS="function"
>spouses</CODE
> 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
>&#13;<CODE
CLASS="function"
>Forfam</CODE
> 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="AEN1528"
>2.13. Other types of records</A
></H2
><DIV
CLASS="glosslist"
><DL
><DT
><B
><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
></B
></DT
><DD
><P
>&#13;loop through all sources in database
</P
></DD
><DT
><B
><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
></B
></DT
><DD
><P
>&#13;loop through all EVEN nodes in database
</P
></DD
><DT
><B
><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
></B
></DT
><DD
><P
>&#13;loop through all other (notes, etc.) nodes in database
</P
></DD
></DL
></DIV
><P
>&#13;<CODE
CLASS="function"
>forsour</CODE
> 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.
<CODE
CLASS="function"
>foreven</CODE
> 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.
<CODE
CLASS="function"
>forothr</CODE
> 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="AEN1562"
>2.14. List Functions</A
></H2
><DIV
CLASS="glosslist"
><DL
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN1567"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID list</CODE
>(LIST_V);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;declare a list
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN1577"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID clear</CODE
>(LIST);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;clear a list
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN1587"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>BOOL empty</CODE
>(LIST);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;check if list is empty
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN1597"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>INT length</CODE
>(LIST);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;length of list
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN1607"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID enqueue</CODE
>(LIST,
ANY);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;enqueue element on list
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN1618"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>ANY dequeue</CODE
>(LIST);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;dequeue and return element from list
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN1628"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID requeue</CODE
>(LIST,
ANY);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;requeue an element on list
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN1639"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID push</CODE
>(LIST,
ANY);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;push element on list
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN1650"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>ANY pop</CODE
>(LIST);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;pop and return element from list
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN1660"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID setel</CODE
>(LIST,
INT,
ANY);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;array element assignment
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN1672"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>ANY getel</CODE
>(LIST,
INT);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;array element selection
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN1683"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>BOOL inlist</CODE
>(LIST,
ANY);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;is second argument in list.
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN1694"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID sort</CODE
>(LIST,
LIST);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;sort list elements
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN1705"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID rsort</CODE
>(LIST,
LIST);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;reverse sort list elements
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN1716"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>LIST dup</CODE
>(LIST);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;duplicate a list
</P
></DD
><DT
><B
><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
></B
></DT
><DD
><P
>&#13;loop through all elements of list
</P
></DD
></DL
></DIV
><P
>&#13;<SPAN
CLASS="application"
>LifeLines</SPAN
> provides general purpose lists that can be accessed as queues, stacks or arrays. A
list must be declared with the <CODE
CLASS="function"
>list</CODE
> function before it can be used. Redeclaring an existing
variable with the <CODE
CLASS="function"
>list</CODE
> 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
>&#13;A list can have any number of elements. <CODE
CLASS="function"
>Empty</CODE
> returns <SPAN
CLASS="returnvalue"
>true</SPAN
> if the list
has no elements and <SPAN
CLASS="returnvalue"
>false</SPAN
> otherwise. <CODE
CLASS="function"
>Length</CODE
> 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
>&#13;<SPAN
CLASS="inlinemediaobject"
><IMG
SRC="listops.jpg"></SPAN
>
</P
><P
>&#13;<CODE
CLASS="function"
>Enqueue</CODE
>, <CODE
CLASS="function"
>dequeue</CODE
> and <CODE
CLASS="function"
>requeue</CODE
> provide queue access to a
list.  <CODE
CLASS="function"
>Enqueue</CODE
> adds an element to the back of a queue, <CODE
CLASS="function"
>dequeue</CODE
> removes and
returns the element from the front of a queue, and <CODE
CLASS="function"
>requeue</CODE
> adds an element to the front of a queue.
The first parameter to all three is a list, and the second parameter to <CODE
CLASS="function"
>enqueue</CODE
> and
<CODE
CLASS="function"
>requeue</CODE
> is the value to be added to the queue and can be any value.
</P
><P
>&#13;<CODE
CLASS="function"
>Push</CODE
> and <CODE
CLASS="function"
>pop</CODE
> provide stack access to a list. <CODE
CLASS="function"
>Push</CODE
> pushes
an element on the stack, and <CODE
CLASS="function"
>pop</CODE
> removes and returns the most recently pushed element from the
stack. The first parameter to both is a list, and the second parameter to <CODE
CLASS="function"
>push</CODE
> is the value to be
pushed on the stack and can be of any type.
</P
><P
>&#13;<CODE
CLASS="function"
>Setel</CODE
> and <CODE
CLASS="function"
>getel</CODE
> provide array access to a list.  <CODE
CLASS="function"
>Setel</CODE
>
sets a value of an array element, and <CODE
CLASS="function"
>getel</CODE
> 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
<CODE
CLASS="function"
>setel</CODE
> 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
>&#13;<CODE
CLASS="function"
>inlist</CODE
> compares the second argument with each element
in the list.  If it finds a match <CODE
CLASS="function"
>inlist</CODE
> returns
<SPAN
CLASS="returnvalue"
>true</SPAN
>.
</P
><P
>&#13;<CODE
CLASS="function"
>sort</CODE
> and <CODE
CLASS="function"
>rsort</CODE
> 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 <CODE
CLASS="function"
>dequeue</CODE
> 
will remove the smallest element.
</P
><P
>&#13;<CODE
CLASS="function"
>dup</CODE
> creates a copy of a <SPAN
CLASS="type"
>list</SPAN
>.  If b is a 
<SPAN
CLASS="type"
>list</SPAN
>, the function <CODE
CLASS="function"
>set</CODE
>(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 
<CODE
CLASS="function"
>set</CODE
>(a,<CODE
CLASS="function"
>dup</CODE
>(b)).
</P
><P
>&#13;<CODE
CLASS="function"
>Forlist</CODE
> 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="AEN1790"
>2.15. Table Functions</A
></H2
><DIV
CLASS="glosslist"
><DL
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN1795"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID table</CODE
>(TABLE_V);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;declare a table
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN1805"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID insert</CODE
>(TABLE,
STRING,
ANY);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;insert entry in table
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN1817"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>ANY lookup</CODE
>(TABLE,
STRING);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;lookup and return entry from table
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN1828"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>INT length</CODE
>(TABLE);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;size of the table
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN1838"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>BOOL empty</CODE
>(TABLE);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;check if table is empty
</P
></DD
></DL
></DIV
><P
>&#13;These functions provide general purpose, keyed tables. A table must be declared with the <CODE
CLASS="function"
>table</CODE
>
function before it can be used.
</P
><P
>&#13;<CODE
CLASS="function"
>Insert</CODE
> 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
>&#13;<CODE
CLASS="function"
>Lookup</CODE
> 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.
<CODE
CLASS="function"
>length</CODE
> returns the number of elements in the table.
</P
></DIV
><DIV
CLASS="sect1"
><HR><H2
CLASS="sect1"
><A
NAME="AEN1854"
>2.16. GEDCOM Node Functions</A
></H2
><DIV
CLASS="glosslist"
><DL
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN1859"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>STRING xref</CODE
>(NODE);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;cross reference index of
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN1869"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>STRING tag</CODE
>(NODE);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;tag of
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN1879"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>STRING value</CODE
>(NODE);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;value of
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN1889"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>NODE parent</CODE
>(NODE);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;parent node of
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN1899"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>NODE child</CODE
>(NODE);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;first child of
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN1909"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>NODE sibling</CODE
>(NODE);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;next sibling of
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN1919"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>NODE savenode</CODE
>(NODE);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;copy a node structure
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN1929"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>INT level</CODE
>(NODE);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;level of a node
</P
></DD
><DT
><B
><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
></B
></DT
><DD
><P
>&#13;loop through child nodes
</P
></DD
><DT
><B
><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
></B
></DT
><DD
><P
>&#13;loop through notes on a node
</P
></DD
><DT
><B
><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
></B
></DT
><DD
><P
>&#13;loop through all descendent nodes
</P
></DD
></DL
></DIV
><P
>&#13;
These functions provide access to the components of a <ACRONYM
CLASS="acronym"
>GEDCOM</ACRONYM
> node. All take a <ACRONYM
CLASS="acronym"
>GEDCOM</ACRONYM
> node as their
only parameter, and each returns a different value associated with the node.

</P
><P
>&#13;<CODE
CLASS="function"
>Xref</CODE
> returns the cross reference index of the node, if any; <CODE
CLASS="function"
>tag</CODE
> returns the tag of the node; and <CODE
CLASS="function"
>value</CODE
>
returns the value of the node, if any. If there is no cross reference, <CODE
CLASS="function"
>xref</CODE
> returns <SPAN
CLASS="returnvalue"
>null</SPAN
>; if there is no value,
value returns <SPAN
CLASS="returnvalue"
>null</SPAN
>.
</P
><P
>&#13;<CODE
CLASS="function"
>Parent</CODE
> returns the parent node of the node, if any; <CODE
CLASS="function"
>child</CODE
> returns the first child node of the node, if any;
and <CODE
CLASS="function"
>sibling</CODE
> 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 <ACRONYM
CLASS="acronym"
>GEDCOM</ACRONYM
> node
tree.
</P
><P
>&#13;<CODE
CLASS="function"
>Savenode</CODE
> 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
>&#13;The <CODE
CLASS="function"
>level</CODE
> function returns the level of the node.
</P
><P
>&#13;<CODE
CLASS="function"
>Fornodes</CODE
> is an iterator that loops through the child nodes of a <ACRONYM
CLASS="acronym"
>GEDCOM</ACRONYM
> 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
>&#13;<CODE
CLASS="function"
>Fornotes</CODE
> is an iterator that loops through the NOTE nodes 
of a <ACRONYM
CLASS="acronym"
>GEDCOM</ACRONYM
> 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
>&#13;<CODE
CLASS="function"
>Traverse</CODE
> is an iterator providing a general method for traversing <ACRONYM
CLASS="acronym"
>GEDCOM</ACRONYM
> 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="AEN1994"
>2.17. Event and Date Functions</A
></H2
><DIV
CLASS="glosslist"
><DL
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN1999"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>STRING date</CODE
>(EVENT);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;date of, value of first <CODE
CLASS="structfield"
>DATE</CODE
> line
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN2010"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>STRING place</CODE
>(EVENT);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;place of, value of first <CODE
CLASS="structfield"
>PLAC</CODE
> line
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN2021"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>STRING year</CODE
>(EVENT);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;year or, 1st string of 3-4 digits in 1st <CODE
CLASS="structfield"
>DATE</CODE
> line
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN2032"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>STRING long</CODE
>(EVENT);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;date and place, values of 1st <CODE
CLASS="structfield"
>DATE</CODE
> and <CODE
CLASS="structfield"
>PLAC</CODE
> lines
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN2044"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>STRING short</CODE
>(EVENT);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;date and place of, abbreviated from
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN2054"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>EVENT gettoday</CODE
>(void);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;returns the `event' of the current date
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN2063"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID dayformat</CODE
>(INT);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;set day format for stddate calls
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN2073"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID monthformat</CODE
>(INT);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;set month format for stddate calls
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN2083"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID yearformat</CODE
>(INT);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;set year format for stddate calls
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN2093"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID eraformat</CODE
>(INT);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;set era format for stddate calls
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN2103"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID dateformat</CODE
>(INT);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;set date format for stddate calls
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN2113"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID datepic</CODE
>(STRING);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;set custom date format for stddate calls
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN2123"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>STRING stddate</CODE
>(EVENT|STRING);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;date of, in current format
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN2133"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID complexformat</CODE
>(INT);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;set complex date format
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN2143"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID complexpic</CODE
>(INT,
STRING);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;set custom complex date picture string
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN2154"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>STRING complexdate</CODE
>(EVENT|STRING);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;date of, in current complex format
</P
></DD
></DL
></DIV
><P
>&#13;These functions extract information about the dates and places of events.
</P
><P
>&#13;<CODE
CLASS="function"
>Date</CODE
> returns the value of the first <CODE
CLASS="structfield"
>DATE</CODE
> line in an event, a node in a <ACRONYM
CLASS="acronym"
>GEDCOM</ACRONYM
> record tree. <CODE
CLASS="function"
>Date</CODE
>
finds the first <CODE
CLASS="structfield"
>DATE</CODE
> line one level deeper than the event node. <CODE
CLASS="function"
>Place</CODE
> returns the value of the first
<CODE
CLASS="structfield"
>PLAC</CODE
> line in an event. <CODE
CLASS="function"
>Year</CODE
> returns the first three or four digit number in the value of the first <CODE
CLASS="structfield"
>DATE</CODE
>
line in an event; this number is assumed to be the year of the event.
</P
><P
>&#13;<CODE
CLASS="function"
>Long</CODE
> returns the verbatim values of the first <CODE
CLASS="structfield"
>DATE</CODE
> and <CODE
CLASS="structfield"
>PLAC</CODE
> lines in an event, concatenated together
and separated by a comma. <CODE
CLASS="function"
>Short</CODE
> abbreviates information from the first <CODE
CLASS="structfield"
>DATE</CODE
> and <CODE
CLASS="structfield"
>PLAC</CODE
> 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
>&#13;<CODE
CLASS="function"
>Gettoday</CODE
> creates an event that has today's date in the <CODE
CLASS="structfield"
>DATE</CODE
> line.
</P
><P
>&#13;The next seven functions are used to format dates in a variety of ways.
<CODE
CLASS="function"
>Dayformat</CODE
>, <CODE
CLASS="function"
>monthformat</CODE
>,
<CODE
CLASS="function"
>yearformat</CODE
>, <CODE
CLASS="function"
>eraformat</CODE
>, and
<CODE
CLASS="function"
>dateformat</CODE
> select style options for formatting the day,
month, year, era, and overall date structure; <CODE
CLASS="function"
>stddate</CODE
>
returns dates in the selected style.
<CODE
CLASS="function"
>datepic</CODE
> allows specifying a custom pattern that overrides
the date format selected with <CODE
CLASS="function"
>dateformat</CODE
>.  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 <CODE
CLASS="function"
>stddate</CODE
> 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
>&#13;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. 
<CODE
CLASS="function"
>complexformat</CODE
> selects the format to use. The format
effects only the complex picture, not the format of the date itself.
The function
<CODE
CLASS="function"
>complexpic</CODE
> 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.
<CODE
CLASS="function"
>complexdate</CODE
>
formats the date similarly to <CODE
CLASS="function"
>stddate</CODE
>, but with the 
addition of the complex date format string selected.
</P
><P
>&#13;The day format codes passed to <CODE
CLASS="function"
>dayformat</CODE
> are: 
</P
><DIV
CLASS="informaltable"
><P
></P
><A
NAME="AEN2200"
></A
><TABLE
BORDER="0"
FRAME="void"
CLASS="CALSTABLE"
><COL
WIDTH="48"><COL><TBODY
><TR
><TD
>0</TD
><TD
>leave space before single digit days</TD
></TR
><TR
><TD
>1</TD
><TD
>&#13;use leading 0 before single digit days
</TD
></TR
><TR
><TD
>2</TD
><TD
>&#13;no space or leading 0 before single digit days
</TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
><P
>&#13;
The month format codes passed to <CODE
CLASS="function"
>monthformat</CODE
> are:
</P
><DIV
CLASS="informaltable"
><P
></P
><A
NAME="AEN2215"
></A
><TABLE
BORDER="0"
FRAME="void"
CLASS="CALSTABLE"
><COL
WIDTH="48"><COL><TBODY
><TR
><TD
>0</TD
><TD
>&#13;number with space before single digit months
</TD
></TR
><TR
><TD
>1</TD
><TD
>&#13;number with leading zero before single digit months
</TD
></TR
><TR
><TD
>2</TD
><TD
>&#13;number with no space or zero before single digit months
</TD
></TR
><TR
><TD
>3</TD
><TD
>&#13;upper case abbreviation (eg, JAN, FEB) (localized)
</TD
></TR
><TR
><TD
>4</TD
><TD
>&#13;capitalized abbreviation (eg, Jan, Feb) (localized)
</TD
></TR
><TR
><TD
>5</TD
><TD
>&#13;upper case full word (eg, JANUARY, FEBRUARY) (localized)
</TD
></TR
><TR
><TD
>6</TD
><TD
>&#13;capitalized full word (eg, January, February) (localized)
</TD
></TR
><TR
><TD
>7</TD
><TD
>&#13;lower case abbreviation (eg, jan, feb) (localized)
</TD
></TR
><TR
><TD
>8</TD
><TD
>&#13;lower case full word (eg, january, february) (localized)
</TD
></TR
><TR
><TD
>9</TD
><TD
>&#13;upper case abbreviation in English per GEDCOM (eg, JAN, FEB)
</TD
></TR
><TR
><TD
>10</TD
><TD
>&#13;lower case roman letter (eg, i, ii)
</TD
></TR
><TR
><TD
>11</TD
><TD
>&#13;upper case roman letter (eg, I, II)
</TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
><P
>&#13;The year format codes passed to <CODE
CLASS="function"
>yearformat</CODE
> are:
</P
><DIV
CLASS="informaltable"
><P
></P
><A
NAME="AEN2257"
></A
><TABLE
BORDER="0"
FRAME="void"
CLASS="CALSTABLE"
><COL
WIDTH="48"><COL><TBODY
><TR
><TD
>0</TD
><TD
>&#13;use leading spaces before years with less than four digits
</TD
></TR
><TR
><TD
>1</TD
><TD
>&#13;use leading 0 before years with less than four digits
</TD
></TR
><TR
><TD
>2</TD
><TD
>&#13;no space or leading 0 before years
</TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
><P
>&#13;The era format codes passed to <CODE
CLASS="function"
>eraformat</CODE
> are: 
</P
><DIV
CLASS="informaltable"
><P
></P
><A
NAME="AEN2272"
></A
><TABLE
BORDER="0"
FRAME="void"
CLASS="CALSTABLE"
><COL
WIDTH="48"><COL><TBODY
><TR
><TD
>0</TD
><TD
>&#13;no AD/BC markers
</TD
></TR
><TR
><TD
>1</TD
><TD
>&#13;trailing B.C. if appropriate
</TD
></TR
><TR
><TD
>2</TD
><TD
>&#13;trailing A.D. or B.C.
</TD
></TR
><TR
><TD
>11</TD
><TD
>&#13;trailing BC if appropriate
</TD
></TR
><TR
><TD
>12</TD
><TD
>&#13;trailing AD or BC
</TD
></TR
><TR
><TD
>21</TD
><TD
>&#13;trailing B.C.E. if appropriate
</TD
></TR
><TR
><TD
>22</TD
><TD
>&#13;trailing C.E. or B.C.E.
</TD
></TR
><TR
><TD
>31</TD
><TD
>&#13;trailing BC if appropriate
</TD
></TR
><TR
><TD
>32</TD
><TD
>&#13;trailing CE or BCE
</TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
><P
>&#13;The full date formats passed to <CODE
CLASS="function"
>stddate</CODE
> are:
</P
><DIV
CLASS="informaltable"
><P
></P
><A
NAME="AEN2305"
></A
><TABLE
BORDER="0"
FRAME="void"
CLASS="CALSTABLE"
><COL
WIDTH="48"><COL><TBODY
><TR
><TD
>0</TD
><TD
>&#13;da mo yr
</TD
></TR
><TR
><TD
>1</TD
><TD
>&#13;mo da, yr
</TD
></TR
><TR
><TD
>2</TD
><TD
>&#13;mo/da/yr
</TD
></TR
><TR
><TD
>3</TD
><TD
>&#13;da/mo/yr
</TD
></TR
><TR
><TD
>4</TD
><TD
>&#13;mo-da-yr
</TD
></TR
><TR
><TD
>5</TD
><TD
>&#13;da-mo-yr
</TD
></TR
><TR
><TD
>6</TD
><TD
>&#13;modayr
</TD
></TR
><TR
><TD
>7</TD
><TD
>&#13;damoyr
</TD
></TR
><TR
><TD
>8</TD
><TD
>&#13;yr mo da
</TD
></TR
><TR
><TD
>9</TD
><TD
>&#13;yr/mo/da
</TD
></TR
><TR
><TD
>10</TD
><TD
>&#13;yr-mo-da
</TD
></TR
><TR
><TD
>11</TD
><TD
>&#13;yrmoda
</TD
></TR
><TR
><TD
>12</TD
><TD
>&#13;yr  (year only, omitting all else)
</TD
></TR
><TR
><TD
>13</TD
><TD
>&#13;da/mo yr
</TD
></TR
><TR
><TD
>14</TD
><TD
>&#13;(As in GEDCOM)
</TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
><P
>&#13;The complex date formats selected by the <CODE
CLASS="function"
>complexformat</CODE
>
and used by <CODE
CLASS="function"
>complexdate</CODE
> are: 
</P
><DIV
CLASS="informaltable"
><P
></P
><A
NAME="AEN2357"
></A
><TABLE
BORDER="0"
FRAME="void"
CLASS="CALSTABLE"
><COL
WIDTH="48"><COL><COL><TBODY
><TR
><TD
>&nbsp;</TD
><TD
>&#13;Mode
</TD
><TD
>&#13;Example
</TD
></TR
><TR
><TD
>3</TD
><TD
>&#13;use abbreviations in uppercase
</TD
><TD
>&#13;ABT  1 JAN 2002
</TD
></TR
><TR
><TD
>4</TD
><TD
>&#13;use abbreviations in titlecase
</TD
><TD
>&#13;Abt  1 JAN 2002
</TD
></TR
><TR
><TD
>5</TD
><TD
>&#13;use uppercased full words 
</TD
><TD
>&#13;ABOUT  1 JAN 2002
</TD
></TR
><TR
><TD
>6</TD
><TD
>&#13;use titlecased full words
</TD
><TD
>&#13;About  1 JAN 2002
</TD
></TR
><TR
><TD
>7</TD
><TD
>&#13;use abbreviations in lowercase
</TD
><TD
>&#13;abt  1 JAN 2002
</TD
></TR
><TR
><TD
>8</TD
><TD
>&#13;use lowercase full words
</TD
><TD
>&#13;about  1 JAN 2002
</TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
><P
>&#13;The complex date string pictures that can be overridden with the
<CODE
CLASS="function"
>complexpic</CODE
> are:
</P
><DIV
CLASS="informaltable"
><P
></P
><A
NAME="AEN2391"
></A
><TABLE
BORDER="0"
FRAME="void"
CLASS="CALSTABLE"
><COL
WIDTH="48"><COL><COL><TBODY
><TR
><TD
>&nbsp;</TD
><TD
>&#13;Abbreviation
</TD
><TD
>&#13;Full word
</TD
></TR
><TR
><TD
>0</TD
><TD
>&#13;abt %1
</TD
><TD
>&#13;about %1
</TD
></TR
><TR
><TD
>1</TD
><TD
>&#13;est %1
</TD
><TD
>&#13;estimated %1
</TD
></TR
><TR
><TD
>2</TD
><TD
>&#13;cal %1
</TD
><TD
>&#13;calculated %1
</TD
></TR
><TR
><TD
>3</TD
><TD
>&#13;bef %1
</TD
><TD
>&#13;before %1
</TD
></TR
><TR
><TD
>4</TD
><TD
>&#13;aft %1
</TD
><TD
>&#13;after %1
</TD
></TR
><TR
><TD
>5</TD
><TD
>&#13;bet %1 and %2
</TD
><TD
>&#13;between %1 and %2
</TD
></TR
><TR
><TD
>6</TD
><TD
>&#13;fr %1
</TD
><TD
>&#13;from %1
</TD
></TR
><TR
><TD
>7</TD
><TD
>&#13;to %1
</TD
><TD
>&#13;to %1
</TD
></TR
><TR
><TD
>8</TD
><TD
>&#13;fr %1 to %2
</TD
><TD
>&#13;from %1 to $2
</TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
></DIV
><DIV
CLASS="sect1"
><HR><H2
CLASS="sect1"
><A
NAME="AEN2435"
>2.18. Value Extraction Functions</A
></H2
><DIV
CLASS="glosslist"
><DL
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN2440"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID extractdate</CODE
>(NODE,
INT_V,
INT_V,
INT_V);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;extract a date
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN2453"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID extractnames</CODE
>(NODE,
LIST_V,
INT_V,
INT_V);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;extract a name
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN2466"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID extractplaces</CODE
>(NODE,
LIST_V,
INT_V);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;extract a place
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN2478"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID extracttokens</CODE
>(STRING,
LIST_V,
INT_V,
STRING);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;extract tokens
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN2491"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID extractdatestr</CODE
>(VARB,
VARB,
VARB,
VARB,
VARB,
STRING);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;extract date from string
</P
></DD
></DL
></DIV
><P
>&#13;Value extraction functions read the values of certain lines and return those values in extracted form.
</P
><P
>&#13;<CODE
CLASS="function"
>Extractdate</CODE
> extracts date values from either an event node
or <CODE
CLASS="structfield"
>DATE</CODE
> node. The first parameter must be
a node; if its tag is <CODE
CLASS="structfield"
>DATE</CODE
>, the date is extracted 
from the value of that node; if its tag is not <CODE
CLASS="structfield"
>DATE</CODE
>,
the date is extracted from the first <CODE
CLASS="structfield"
>DATE</CODE
> 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
>&#13;<CODE
CLASS="function"
>Extractnames</CODE
> extracts name components from a <CODE
CLASS="structfield"
>NAME</CODE
> line. Its first argument is either an <CODE
CLASS="structfield"
>INDI</CODE
> or a
<CODE
CLASS="structfield"
>NAME</CODE
> node. If it is a <CODE
CLASS="structfield"
>NAME</CODE
> line, the components are extracted from the value of that node; if it is an
<CODE
CLASS="structfield"
>INDI</CODE
> line, the components are extracted from the value of the first <CODE
CLASS="structfield"
>NAME</CODE
> 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
>&#13;<CODE
CLASS="function"
>Extractplaces</CODE
> extracts place components
from a <CODE
CLASS="structfield"
>PLAC</CODE
> node. The first
argument is a node; if its tag is
<CODE
CLASS="structfield"
>PLAC</CODE
>, the places are extracted from
the value of the node; if its tag is not
<CODE
CLASS="structfield"
>PLAC</CODE
>, places are extracted from the
first <CODE
CLASS="structfield"
>PLAC</CODE
> 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
<CODE
CLASS="structfield"
>PLAC</CODE
> value; leading and trailing
white space is removed from the components, while all internal
white space is retained.
</P
><P
>&#13;<CODE
CLASS="function"
>Extracttokens</CODE
> 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
<CODE
CLASS="function"
>extracttokens</CODE
> uses to break the input
string into tokens.
</P
><P
>&#13;<CODE
CLASS="function"
>extractdatestr</CODE
> extracts date values from a .
<CODE
CLASS="structfield"
>STRING</CODE
>.  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="AEN2533"
>2.19. User Interaction Functions</A
></H2
><DIV
CLASS="glosslist"
><DL
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN2538"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID getindi</CODE
>(INDI_V,
<TT
CLASS="replaceable"
><I
>STRING</I
></TT
>);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;identify person through user interface
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN2550"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID getindiset</CODE
>(SET_V,
<TT
CLASS="replaceable"
><I
>STRING</I
></TT
>);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;identify set of persons through user interface
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN2562"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID getfam</CODE
>(FAM_V);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;identify family through user interface
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN2572"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID getint</CODE
>(INT_V,
<TT
CLASS="replaceable"
><I
>STRING</I
></TT
>);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;get integer through user interface
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN2584"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID getstr</CODE
>(STRING_V,
<TT
CLASS="replaceable"
><I
>STRING</I
></TT
>);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;get string through user interface
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN2596"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>INDI choosechild</CODE
>(INDI|FAM);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;select child of person/family through user interface
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN2606"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>FAM choosefam</CODE
>(INDI);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;select family person is in as spouse
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN2616"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>INDI chooseindi</CODE
>(SET);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;select person from set of persons
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN2626"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>INDI choosespouse</CODE
>(INDI);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;select spouse of person
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN2636"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>SET choosesubset</CODE
>(SET);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;select a subset of persons from set of persons
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN2646"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>INT menuchoose</CODE
>(LIST,
<TT
CLASS="replaceable"
><I
>STRING</I
></TT
>);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;select from a list of options
</P
></DD
></DL
></DIV
><P
>&#13;These functions interact with the user to get information needed by the program.
</P
><P
>&#13;<CODE
CLASS="function"
>Getindi</CODE
> 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. <CODE
CLASS="function"
>Getindiset</CODE
> asks the user to identify a set of persons.
<CODE
CLASS="function"
>Getfam</CODE
> asks the user identify a family. <CODE
CLASS="function"
>Getint</CODE
> and <CODE
CLASS="function"
>getstr</CODE
> ask the user enter an integer and string,
respectively.
</P
><P
>&#13;<CODE
CLASS="function"
>Choosechild</CODE
> asks the user select a child of a family or person; its single argument is a person or family;
it return the child. <CODE
CLASS="function"
>Choosefam</CODE
> has the user select a family that a person is in as a spouse; its argument
is a person; it returns the family. <CODE
CLASS="function"
>Chooseindi</CODE
> has the user select one person from a set of persons; its
argument in a set of persons; it returns the chosen person. <CODE
CLASS="function"
>Choosespouse</CODE
> has the user select a spouse of a
person; its argument is a person; it returns the chosen spouse. <CODE
CLASS="function"
>Choosesubset</CODE
> has the user select a subset of
persons from a set of persons; its argument is the chosen subset.
</P
><P
>&#13;<CODE
CLASS="function"
>Menuchoose</CODE
> 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;
<CODE
CLASS="function"
>menuchoose</CODE
> 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="AEN2673"
>2.20. String Functions</A
></H2
><DIV
CLASS="glosslist"
><DL
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN2678"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>STRING lower</CODE
>(STRING);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;convert to lower case
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN2688"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>STRING upper</CODE
>(STRING);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;convert to upper case
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN2698"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>STRING capitalize</CODE
>(STRING);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;capitalize first letter
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN2708"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>STRING titlecase</CODE
>(STRING);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;capitalize first letter of each word
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN2718"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>STRING trim</CODE
>(STRING,
INT);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;trim to length
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN2729"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>STRING rjustify</CODE
>(STRING,
INT);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;right justify in field
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN2740"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>STRING concat</CODE
>(STRING,
<TT
CLASS="replaceable"
><I
>STRING</I
></TT
>
<TT
CLASS="replaceable"
><I
>...</I
></TT
>);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;catenate two strings
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN2754"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>STRING strconcat</CODE
>(STRING,
<TT
CLASS="replaceable"
><I
>STRING</I
></TT
>
<TT
CLASS="replaceable"
><I
>...</I
></TT
>);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;catenate two strings
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN2768"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>INT strlen</CODE
>(STRING);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;number of characters in string
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN2778"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>STRING substring(</CODE
>(STRING,
INT,
INT);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;substring function
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN2790"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>INT index</CODE
>(STRING,
STRING,
INT);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;index function
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN2802"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>STRING d</CODE
>(INT);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;number as decimal string
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN2812"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>STRING f</CODE
>(FLOAT,
INT);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;number as floating point string
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN2823"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>STRING card</CODE
>(INT);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;number in cardinal form (<TT
CLASS="literal"
>one, two, ...</TT
>)
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN2834"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>STRING ord</CODE
>(INT);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;number in ordinal form (<TT
CLASS="literal"
>first, second, ...</TT
>)
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN2845"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>STRING alpha</CODE
>(INT);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;convert number to Latin letter (<TT
CLASS="literal"
>a, b, ...</TT
>)
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN2856"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>STRING roman</CODE
>(INT);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;number in Roman numeral form (<TT
CLASS="literal"
>i, ii, ...</TT
>)
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN2867"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>STRING strsoundex</CODE
>(STRING);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;find SOUNDEX value of arbitrary string
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN2877"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>INT strtoint</CODE
>(STRING);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;convert numeric string to integer
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN2887"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>INT atoi</CODE
>(STRING);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;convert numeric string to integer
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN2897"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>INT strcmp</CODE
>(STRING,
STRING);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;general string compare
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN2908"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>BOOL eqstr</CODE
>(STRING,
STRING);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;compare strings for equality
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN2919"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>BOOL nestr</CODE
>(STRING,
STRING);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;compare strings for inequality
</P
></DD
></DL
></DIV
><P
>&#13;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
>&#13;<CODE
CLASS="function"
>Lower</CODE
> and <CODE
CLASS="function"
>upper</CODE
> convert the letters
in their arguments to lower or upper case, respectively.
<CODE
CLASS="function"
>Capitalize</CODE
> converts the first character of the argument,
if it is a letter, to upper case. <CODE
CLASS="function"
>Lower</CODE
> and
<CODE
CLASS="function"
>upper</CODE
> historically used the buffer return method;
<CODE
CLASS="function"
>capitalize</CODE
> operates on and returns its argument.
<CODE
CLASS="function"
>titlecase</CODE
> converts the first letter of each word if it is
a letter, to upper case and all other characters to lower case.
</P
><P
>&#13;<CODE
CLASS="function"
>Trim</CODE
> 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. <CODE
CLASS="function"
>Rjustify</CODE
> 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. <CODE
CLASS="function"
>Trim</CODE
> historically used the buffer return method; <CODE
CLASS="function"
>rjustify</CODE
> creates and returns
a new string.
</P
><P
>&#13;<CODE
CLASS="function"
>Concat</CODE
> and <CODE
CLASS="function"
>strconcat</CODE
> 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
>&#13;<CODE
CLASS="function"
>Strlen</CODE
> returns the length of the string argument.
</P
><P
>&#13;<CODE
CLASS="function"
>Substring</CODE
> 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.
<CODE
CLASS="function"
>Substring</CODE
> historically used the buffer return method.
</P
><P
>&#13;<CODE
CLASS="function"
>Index</CODE
> 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
>&#13;<CODE
CLASS="function"
>D</CODE
>, <CODE
CLASS="function"
>card</CODE
>, <CODE
CLASS="function"
>ord</CODE
>,
<CODE
CLASS="function"
>alpha</CODE
> and <CODE
CLASS="function"
>roman</CODE
> convert integers
to strings. <CODE
CLASS="function"
>D</CODE
> converts an integer to a numeric string;
<CODE
CLASS="function"
>card</CODE
> converts an integer to a cardinal number string 
(eg, <TT
CLASS="literal"
>one, two, three</TT
>); <CODE
CLASS="function"
>ord</CODE
> converts an
integer to an ordinal number (eg, <TT
CLASS="literal"
>first, second, third</TT
>);
<CODE
CLASS="function"
>alpha</CODE
> converts an integer to a letter
(eg, <TT
CLASS="literal"
>a, b, c</TT
>); and <CODE
CLASS="function"
>roman</CODE
> converts an 
integer to a Roman numeral (eg, <TT
CLASS="literal"
>i, ii, iii</TT
>).
</P
><P
>&#13;The <CODE
CLASS="function"
>f</CODE
> function converts a float to a string.  The
optional second argument specifies the precision of the output.  The default
precision is 2.
</P
><P
>&#13;<CODE
CLASS="function"
>Strsoundex</CODE
> converts an arbitrary string to a SOUNDEX value. Non-ASCII text characters are ignored
in the string.
</P
><P
>&#13;<CODE
CLASS="function"
>Strtoint</CODE
> converts a numeric string to an integer. <CODE
CLASS="function"
>Atoi</CODE
> is identical to <CODE
CLASS="function"
>strtoint</CODE
>.
</P
><P
>&#13;<CODE
CLASS="function"
>Strcmp</CODE
> 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. <CODE
CLASS="function"
>Eqstr</CODE
> and <CODE
CLASS="function"
>nestr</CODE
> return whether two strings are equal or not equal, respectively.
<CODE
CLASS="function"
>Strcmp</CODE
>, <CODE
CLASS="function"
>Eqstr</CODE
>, and <CODE
CLASS="function"
>nestr</CODE
> 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="AEN2982"
>2.21. Output Mode Functions</A
></H2
><DIV
CLASS="glosslist"
><DL
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN2987"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID linemode</CODE
>(void);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;use line output mode
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN2996"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID pagemode</CODE
>(INT,
INT);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;use page output mode with given page size
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3007"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID col</CODE
>(INT);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;position to column in output
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3017"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>INT getcol</CODE
>(void);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;get current column in output
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3026"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID row</CODE
>(INT);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;position to row in output
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3036"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID pos</CODE
>(INT,
INT);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;position to (row, col) coordinate in output
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3047"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID pageout</CODE
>(void);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;output page buffer
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3056"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>STRING nl</CODE
>(void);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;newline character
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3065"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>STRING sp</CODE
>(void);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;space character
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3074"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>STRING qt</CODE
>(void);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;double quote character
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3083"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID newfile</CODE
>(STRING,
BOOL);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;send program output to this file
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3094"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>STRING outfile</CODE
>(void);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;return name of current program output file
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3103"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID copyfile</CODE
>(STRING);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;copy file contents to program output file
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3113"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>BOOLEAN test</CODE
>(STRING, STRING);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;tests for characteristics of a file
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3125"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID print</CODE
>(STRING,
<TT
CLASS="replaceable"
><I
>STRING</I
></TT
>
<TT
CLASS="replaceable"
><I
>...</I
></TT
>);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;print string to standard output window
</P
></DD
></DL
></DIV
><P
>&#13;Reports can be generated in two modes, line mode and page mode. <CODE
CLASS="function"
>Linemode</CODE
> selects line mode and
<CODE
CLASS="function"
>pagemode</CODE
> selects page mode; line mode is the default. The first parameter to <CODE
CLASS="function"
>pagemode</CODE
> 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 <CODE
CLASS="function"
>pageout</CODE
> 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
>&#13;<CODE
CLASS="function"
>Col</CODE
> 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. <CODE
CLASS="function"
>Col</CODE
>
works in both modes.
<CODE
CLASS="function"
>Getcol</CODE
> returns the current column in the output.
</P
><P
>&#13;<CODE
CLASS="function"
>Row</CODE
> positions output to the first character in the given row; <CODE
CLASS="function"
>row</CODE
> can only be used in page mode.
</P
><P
>&#13;<CODE
CLASS="function"
>Pos</CODE
> positions output to a specified row and column coordinate; the first argument specifies the row, and
the second specifies the column. <CODE
CLASS="function"
>Pos</CODE
> can only be used in page mode.
</P
><P
>&#13;<CODE
CLASS="function"
>Nl</CODE
> write a new line character to the output file; <CODE
CLASS="function"
>sp</CODE
> writes a space character to the output file; and <CODE
CLASS="function"
>qt</CODE
>
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
>&#13;<CODE
CLASS="function"
>Newfile</CODE
> 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. <CODE
CLASS="function"
>Newfile</CODE
> 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 <CODE
CLASS="function"
>newfile</CODE
>; if it is not used then <SPAN
CLASS="application"
>LifeLines</SPAN
> automatically asks for the name of the report output file.
</P
><P
>&#13;<CODE
CLASS="function"
>Outfile</CODE
> returns the name of the current report output file.
</P
><P
>&#13;<CODE
CLASS="function"
>Copyfile</CODE
> 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 <CODE
CLASS="envar"
>LLPROGRAMS</CODE
> 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
>&#13;<CODE
CLASS="function"
>Test</CODE
> 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
>&#13;<CODE
CLASS="function"
>Print</CODE
> prints its argument string to the standard output window; <CODE
CLASS="function"
>print</CODE
> may have one to 32 arguments.
</P
></DIV
><DIV
CLASS="sect1"
><HR><H2
CLASS="sect1"
><A
NAME="AEN3173"
>2.22. Person Set Functions and GEDCOM Extraction</A
></H2
><DIV
CLASS="glosslist"
><DL
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3178"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID indiset</CODE
>(SET_V);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;declare a set variable
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3188"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID addtoset</CODE
>(SET,
INDI,
ANY);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;add a person to a set
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3200"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID deletefromset</CODE
>(SET,
INDI,
BOOL);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;remove a person from a set
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3212"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>INT length</CODE
>(SET);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;size of a set
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3222"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>SET union</CODE
>(SET,
SET);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;union of two sets
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3233"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>SET intersect</CODE
>(SET,
SET);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;intersection of two sets
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3244"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>SET difference</CODE
>(SET,
SET);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;difference of two sets
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3255"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>SET parentset</CODE
>(SET);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;set of all parents
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3265"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>SET childset</CODE
>(SET);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;set of all children
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3275"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>SET spouseset</CODE
>(SET);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;set of all spouses
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3285"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>SET siblingset</CODE
>(SET);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;set of all siblings
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3295"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>SET ancestorset</CODE
>(SET);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;set of all ancestors
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3305"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>SET descendentset</CODE
>(SET);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;set of all descendents
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3315"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>SET descendantset</CODE
>(SET);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;same as descendentset; spelling
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3325"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>SET uniqueset</CODE
>(SET);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;remove duplicates from set
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3335"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID namesort</CODE
>(SET);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;sort indiset by name
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3345"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID keysort</CODE
>(SET);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;sort indiset by key values
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3355"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID valuesort</CODE
>(SET);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;sort indiset by auxiliary values
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3365"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID genindiset</CODE
>(STRING,
SET);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;generate indiset from GEDCOM name string
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3376"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>BOOL inset</CODE
>(SET,
INDI);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;<SPAN
CLASS="returnvalue"
>true</SPAN
> if the Individual is in the set.
</P
></DD
><DT
><B
><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
></B
></DT
><DD
><P
>&#13;loop through all persons in person set
</P
></DD
></DL
></DIV
><P
>&#13;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 <CODE
CLASS="function"
>indiset</CODE
> function before it can be used.
</P
><P
>&#13;<CODE
CLASS="function"
>Addtoset</CODE
> 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. <CODE
CLASS="function"
>Deletefromset</CODE
> 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. 
<CODE
CLASS="function"
>Length</CODE
> returns the number of persons in a person set.
</P
><P
>&#13;<CODE
CLASS="function"
>Union</CODE
>, <CODE
CLASS="function"
>intersect</CODE
> and <CODE
CLASS="function"
>difference</CODE
>
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
>&#13;<CODE
CLASS="function"
>Parentset</CODE
>, <CODE
CLASS="function"
>childset</CODE
>, <CODE
CLASS="function"
>spouseset</CODE
> and <CODE
CLASS="function"
>siblingset</CODE
> 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
>&#13;<CODE
CLASS="function"
>Ancestorset</CODE
> returns the set all ancestors of all persons in the argument set. <CODE
CLASS="function"
>Descendentset</CODE
> returns the
set of all descendents of all persons in the argument set. <CODE
CLASS="function"
>Descendantset</CODE
> is the same as <CODE
CLASS="function"
>descendentset</CODE
>; it allows an alternate spelling.
</P
><P
>&#13;<CODE
CLASS="function"
>Uniqueset</CODE
> sorts a person set by key value and then removes all entries with duplicate keys; the input
set is modified and returned.
</P
><P
>&#13;<CODE
CLASS="function"
>Namesort</CODE
>, <CODE
CLASS="function"
>keysort</CODE
> and <CODE
CLASS="function"
>valuesort</CODE
> sort a set of persons by name, by key and by associated value,
respectively.
</P
><P
>&#13;Each person in a person set has an associated value. When a person is added to a set with <CODE
CLASS="function"
>addtoset</CODE
>, 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 <CODE
CLASS="function"
>parentset</CODE
>, <CODE
CLASS="function"
>childset</CODE
> and
<CODE
CLASS="function"
>spouseset</CODE
> the values are copied from the first input set person that causes the new person to be added
to the set. For <CODE
CLASS="function"
>union</CODE
>, <CODE
CLASS="function"
>intersect</CODE
> and <CODE
CLASS="function"
>difference</CODE
>, the values are copied from the values in the first input
set, except in the case of <CODE
CLASS="function"
>union</CODE
>, when persons are taken from the second set alone, in which case the
values come from there. For <CODE
CLASS="function"
>ancestorset</CODE
> and <CODE
CLASS="function"
>descendantset</CODE
> the value is set to the number of generations
the new person is away from the <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>first</I
></SPAN
> 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. <CODE
CLASS="function"
>Valuesort</CODE
> sorts a person set by the values of these
auxiliary values.
</P
><P
>&#13;<CODE
CLASS="function"
>Genindiset</CODE
> generates the set of persons that matches a string whose value is a name in <ACRONYM
CLASS="acronym"
>GEDCOM</ACRONYM
>
format. <CODE
CLASS="function"
>Genindiset</CODE
> uses the same algorithm that matches names entered at the browse prompt or by
the user interaction <CODE
CLASS="function"
>getindiset</CODE
> function.
</P
><P
>&#13;<CODE
CLASS="function"
>Inset</CODE
> returns <SPAN
CLASS="returnvalue"
>true</SPAN
> if the
the specified individual is in the SET.
</P
><P
>&#13;<CODE
CLASS="function"
>Forindiset</CODE
> 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="AEN3448"
>2.23. Record Update Functions</A
></H2
><DIV
CLASS="glosslist"
><DL
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3453"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>NODE createnode</CODE
>(STRING,
STRING);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;create a GEDCOM node
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3464"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID addnode</CODE
>(NODE,
NODE,
NODE);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;add a node to a GEDCOM tree
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3476"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID detachnode</CODE
>(NODE);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;delete a node from a GEDCOM tree
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3486"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID writeindi</CODE
>(INDI);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;write a person back to the database
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3496"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID writefam</CODE
>(FAM);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;write a family back to the database
</P
></DD
></DL
></DIV
><P
>&#13;These functions allow you to modify an internal <ACRONYM
CLASS="acronym"
>GEDCOM</ACRONYM
> node tree.
</P
><P
>&#13;<CODE
CLASS="function"
>Createnode</CODE
> creates a <ACRONYM
CLASS="acronym"
>GEDCOM</ACRONYM
> node; the two arguments are tag and value strings,
respectively; the value string can be <SPAN
CLASS="returnvalue"
>null</SPAN
>. <CODE
CLASS="function"
>Addnode</CODE
> 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.
<CODE
CLASS="function"
>Detachnode</CODE
> removes a node from a node tree. <CODE
CLASS="function"
>writeindi</CODE
> writes an individual
record back to the database, and <CODE
CLASS="function"
>writefam</CODE
> writes a family record back to the database, allowing the
report to make permanent changes to the database.
</P
><P
>&#13;The node functions only change data in memory; there is no effect on the database until and unless
<CODE
CLASS="function"
>writeindi</CODE
> or <CODE
CLASS="function"
>writefam</CODE
> are called.
</P
></DIV
><DIV
CLASS="sect1"
><HR><H2
CLASS="sect1"
><A
NAME="AEN3518"
>2.24. Record Linking Functions</A
></H2
><DIV
CLASS="glosslist"
><DL
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3523"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>BOOL reference</CODE
>(STRING);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;determine if string is a cross reference
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3533"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>NODE dereference</CODE
>(STRING);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;reference cross reference or key to node tree
</P
></DD
></DL
></DIV
><P
>&#13;These functions allow you to recognize values that are cross references and to read the records they refer
to. <CODE
CLASS="function"
>Reference</CODE
> 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. <CODE
CLASS="function"
>Dereference</CODE
> 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="AEN3545"
>2.25. Miscellaneous Functions</A
></H2
><DIV
CLASS="glosslist"
><DL
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3550"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID lock</CODE
>(INDI|FAM);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;lock a person or family in memory
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3560"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID unlock</CODE
>(INDI|FAM);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;unlock a person or family from memory
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3570"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>STRING database</CODE
>(void);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;return name of current database
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3579"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>STRING program</CODE
>(void);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;return name of current program
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3588"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>STRING version</CODE
>(void);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;return version of <SPAN
CLASS="application"
>LifeLines</SPAN
> program
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3598"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID system</CODE
>(STRING);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;execute string as a UNIX shell command
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3608"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>INT heapused</CODE
>(void);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;amount of heap used for windows
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3617"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>STRING getproperty</CODE
>(STRING);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;extract system or user property.  Function available after v3.0.5.
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3627"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>STRING setlocale</CODE
>(STRING);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;set the locale
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3637"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>STRING bytecode</CODE
>(STRING,
STRING);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;encode a string in a codeset
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3648"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>STRING convertcode</CODE
>(STRING,
STRING,
STRING);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;convert string from one codeset to another
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3660"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID debug</CODE
>(BOOLEAN);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;set interperter debug mode
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3670"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>STRING pvalue</CODE
>(ANY);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;dump information about a pvalue
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3680"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID free</CODE
>(ANY);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;free space associated with a variable
</P
></DD
></DL
></DIV
><P
>&#13;
<CODE
CLASS="function"
>Lock</CODE
> and <CODE
CLASS="function"
>unlock</CODE
> are used to lock a
person or family into <ACRONYM
CLASS="acronym"
>RAM</ACRONYM
> memory, and to unlock a person or family
from <ACRONYM
CLASS="acronym"
>RAM</ACRONYM
> memory, respectively.

</P
><P
>&#13;<CODE
CLASS="function"
>Database</CODE
> returns the name of the current database, useful
in titling reports. <CODE
CLASS="function"
>program</CODE
> returns the
name of the current report program. <CODE
CLASS="function"
>Version</CODE
> returns the
version of the running <SPAN
CLASS="application"
>LifeLines</SPAN
> program, eg, <TT
CLASS="literal"
>3.0.50</TT
>.
</P
><P
>&#13;<CODE
CLASS="function"
>System</CODE
> executes its string argument as a
<ACRONYM
CLASS="acronym"
>UNIX</ACRONYM
> (or <ACRONYM
CLASS="acronym"
>MS-Windows</ACRONYM
> 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
>&#13;The <CODE
CLASS="function"
>heapused</CODE
> function returns the amount of system heap
that is in use at the time.  This is implemented only on windows.
</P
><P
>&#13;The <CODE
CLASS="function"
>getproperty</CODE
> 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
>&#13;The <CODE
CLASS="function"
>setlocale</CODE
> function sets the locale and returns
the previous setting of locale.
</P
><P
>&#13;The <CODE
CLASS="function"
>bytecode</CODE
> 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
>&#13;The <CODE
CLASS="function"
>convertcode</CODE
> 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,
<PRE
CLASS="programlisting"
>       "&#60;p&#62;\n"
       convertcode(str,"UTF-8//html")
</PRE
>
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
>&#13;The <CODE
CLASS="function"
>debug</CODE
> function turns on or off programming debugging.
When enabled gobs of information is printed as a 
<SPAN
CLASS="application"
>LifeLines</SPAN
> program is run.  This can be useful
to figure out why a program is not behaving as expected.
</P
><P
>&#13;The <CODE
CLASS="function"
>pvalue</CODE
> function returns a string that represents
the contents of a variable in the interpreter.  This is present for debug
purposes.
</P
><P
>&#13;The function <CODE
CLASS="function"
>free</CODE
> 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="AEN3721"
>2.26. Deprecated Functions</A
></H2
><P
>&#13;The <CODE
CLASS="function"
>baptism</CODE
> 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 
<CODE
CLASS="function"
>baptism</CODE
>.
</P
><DIV
CLASS="glosslist"
><DL
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3729"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>EVENT baptism</CODE
>(INDI);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;first baptism event of
</P
><P
>&#13;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.

    <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
>
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.

    <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
>

</P
></DD
></DL
></DIV
><P
>&#13;The functionality of the following three functions,
<CODE
CLASS="function"
>getindimsg</CODE
>,
<CODE
CLASS="function"
>getintmsg</CODE
> and
<CODE
CLASS="function"
>getstrmsg</CODE
>
is now available using the optional parameter of
<CODE
CLASS="function"
>getindi</CODE
>,
<CODE
CLASS="function"
>getint</CODE
> and
<CODE
CLASS="function"
>getstr</CODE
>.
These functions should no longer be used as they will be removed from a future
version of <SPAN
CLASS="application"
>Lifelines</SPAN
>.
</P
><DIV
CLASS="glosslist"
><DL
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3751"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID getindimsg</CODE
>(INDI_V,
<TT
CLASS="replaceable"
><I
>STRING</I
></TT
>);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;identify person through user interface
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3763"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID getintmsg</CODE
>(INT_V,
<TT
CLASS="replaceable"
><I
>STRING</I
></TT
>);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;get integer through user interface
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3775"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID getstrmsg</CODE
>(STRING_V,
<TT
CLASS="replaceable"
><I
>STRING</I
></TT
>);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;get string through user interface
</P
></DD
></DL
></DIV
><P
>&#13;Three functions are available for to generate <ACRONYM
CLASS="acronym"
>GEDCOM</ACRONYM
>
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
>&#13;<CODE
CLASS="function"
>Gengedcom</CODE
> 
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
>&#13;<CODE
CLASS="function"
>Gengedcomweak</CODE
> 
output does not contain Source, Event or Other(X) record pointers 
or their records.
<CODE
CLASS="function"
>Gengedcomstrong</CODE
> 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"
><P
></P
><A
NAME="AEN3795"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID gengedcom</CODE
>(SET);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;generate GEDCOM file from person set
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3805"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID gengedcomweak</CODE
>(SET);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;generate GEDCOM file from person set
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3815"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID gengedcomstrong</CODE
>(SET);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;generate GEDCOM file from person set
</P
></DD
></DL
></DIV
><P
>&#13;By the release of version 3.0.6, all string values are local copies, and the <CODE
CLASS="function"
>save</CODE
> and
<CODE
CLASS="function"
>strsave</CODE
> functions should be entirely unnecessary.
<CODE
CLASS="function"
>Save</CODE
> 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).
 <CODE
CLASS="function"
>Strsave</CODE
> is the same function as <CODE
CLASS="function"
>save</CODE
>.
</P
><DIV
CLASS="glosslist"
><DL
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3832"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>STRING save</CODE
>(STRING);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;save and return copy of string
</P
></DD
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3842"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>STRING strsave</CODE
>(STRING);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;same as save function
</P
></DD
></DL
></DIV
><P
>&#13;Use <CODE
CLASS="function"
>detachnode</CODE
> instead of
<CODE
CLASS="function"
>deletenode</CODE
>.
</P
><DIV
CLASS="glosslist"
><DL
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3856"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>VOID deletenode</CODE
>(NODE);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;delete a node from a GEDCOM tree
</P
></DD
></DL
></DIV
><P
>&#13;In releases after version 3.0.39, the 
<CODE
CLASS="function"
>length</CODE
> function accepts an argument of type 
<SPAN
CLASS="type"
>list</SPAN
>, <SPAN
CLASS="type"
>set</SPAN
> or <SPAN
CLASS="type"
>table</SPAN
>.  the
<CODE
CLASS="function"
>lengthset</CODE
> function is no longer needed.
</P
><DIV
CLASS="glosslist"
><DL
><DT
><B
><DIV
CLASS="funcsynopsis"
><P
></P
><A
NAME="AEN3873"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>INT lengthset</CODE
>(SET);</CODE
></P
><P
></P
></DIV
></B
></DT
><DD
><P
>&#13;size of a set
</P
></DD
></DL
></DIV
></DIV
></DIV
></DIV
></BODY
></HTML
>