---

Ancestor+

The manual for our exclusive full version.

Appendix

Report Template files

As explained in the section on Reports, only the first four items on the menu are fixed. Everything after these four is generated by a Template File. These are stored in a directory 'Reports' in the 'User' sub-directory of the application directory.

Report templates are an extremely powerful feature of Ancestor+. They can consist of (almost) any type of file. Text files are simplest, but other types can be used, subject to certain restrictions. When a template file is used the program loads it and saves a copy of the file, substituting data taken from the database about the person or persons for certain 'tags' in the file. These tags consist of '\' followed by a three letter upper case mnemonic. One consequence of this is that you cannot use the '\' character anywhere in your document. If you do need to use it, then use two, one after the other, and the resulting file will then contain just one.

Use of this system means that the user is not restricted to a series of 'forms' for data export. You decide exactly how you want your reports to look, and you can create many different formats for different purposes.

Because the text which is substituted for the tag will normally be longer or shorter than the four characters used for the tag the resulting file will, if direct substitution is used, normally be longer than the template. With text files this is unimportant. However, for many types of file it is not possible to substitute data of a different length, so an alternative technique must be used. The 'fixed text' that makes up the form can be anything you like. However, the format of the text objects that hold the tags must be correct. When using a Drawfile the first such object you create must be the tag '\OVW' (OVerWrite). This text won't actually appear in the output file, so you can place it anywhere, but it must be created before any of the subsequent tags so it's found first when the Drawfile is 'scanned'. With a wordprocessor file this tag must appear before any other tag. Each subsequent object must begin with the tag and then have enough 'trailing spaces' to leave room for the data that will be substituted. If you don't include enough spaces the resulting file will be corrupt.

Some tags cannot be used in Overwrite mode. In fact, it's not actual tags than can't be used but structures. These are pairs of tags which form a 'loop' which is repeated a number of times until the appropriate data is 'used up' For example, when reporting a person's family links the number of links is variable. It could be none, or it could be half a dozen. Because the outcome is unpredictable it isn't possible to use a fixed format, so these structures can only be used in Insert mode. This does not preclude their use with wordprocessors like Ovation Pro or Impression. What you have to do is create your Template file as usual, but you do not need to leave any space for data, just type the tags. Now, don't save the file in the usual way. With Ovation Pro use 'Save story' and select DDL format, with Impression use 'Save text story' with 'Styles' enabled, with EasiWriter save the file as Rich Text (RTF).

All these are just special forms of textfile with font and formatting data. Unlike the 'real' document files created by the programs they can be modified and manipulated by Ancestor+ and the substitutions made and yet still re-loaded into the appropriate program, normally by dragging them to the program's icon on the icon bar.

When using RTF files with EasiWriter there is a 'quirk' that you need to be aware of. RTF uses the '\' character to precede formatting commands, and although this should not be a problem EasiWriter does seem to have difficulties where a tag follows a Tab in the original document. The solution is simple. After pressing the Tab key in EasiWriter and before you type the tag insert a single space. If you don't do this the first word or character of the data may be lost.

The following tags can be used. Those marked with '**' cannot be used in Overwrite mode.

\NUM	Person, Family or Child's number
\FOR	Forename
\SUR	Surname
\NAM	Full name (forename(s) followed by surname)
\BYN	Byname
\TTL	Title
\DOB	Date of birth
\DOD	Date of death
\POB	Place of birth
\POD	Place of death
\YOB	Year of Birth
\YOD	Year of Death
\STA	Status
\SEX	Sex
\UN1 to \UN5	Names of User Field 1 to 5
\US1 to \US5	Contents of User Field 1 to 5
\NOT  **	Insert Notes file
\UFN  **	Insert Unformatted Notes file (see text)
\INS	Insert mode (default)
\OVW	Overwrite mode
\ADO	Text used for an Adopted child (see text)

The following structures can be used, and some tags can only be used within these structures.

\FAM	Begin Family structure
\ENF	End Family structure
\CHI	Begin Child structure
\ENC	End Child structure

The Child Structure can only be used from within a Family structure. In addition, the following tags can only be used within a Family structure -

\DOM	Date of Marriage
\DOE	Date of End of Marriage
\YOM	Year of Marriage
\YOE	Year of End of Marriage
\POM	Place of Marriage
\TYP	Type of union
\RFE	Reason for ending
\NCH	Number of Children
\COM	'Notes' field in Family window (COMment)
\NOT	Notes file for the family
\UFN	Unformatted Notes file for the family

The \NAM, \FOR, \SUR, \TTL and \BYN tag can be used within a Family structure but it will return the appropriate data for the spouse of the person from whose record the family structure was used.

Within a Child structure the following tags can be used.

\NUM	Number
\FOR	Forename
\SUR	Surname
\NAM	Full name (forename(s) followed by surname)
\BYN	Byname
\TTL	Title
\DOB	Date of birth
\DOD	Date of death
\POB	Place of birth
\POD	Place of death
\YOB	Year of Birth
\YOD	Year of Death
\SEX	Sex
\ADO	If child is adopted, insert appropriate text

If you want to insert Family and Child(ren) data but don't want to bother designing your own structures then Ancestor+ has two pre-defined systems. If you use the \CHI tag immediately followed by the \ENC tag thus;

     \CHI\ENC

then you will get the children of a family reported as -

    1st child name, born year of birth
    2nd child name, born year of birth

where the text in italics will be the actual data for that child.

If you use the \FAM tag immediately followed by the \ENF tag then the family will be reported in a standard format, thus;

    Family links: number of links
    1st spouse name, year of marriage to end of marriage, num. children
    2nd spouse name, year of marriage to end of marriage, num. children

There is also an 'overall' structure which can be enclosed within the two tags \REP and \ENR (Repeat and End Repeat). This is used for multi-person reports where you may wish to include a 'preamble' text or heading that you don't want repeated for each person. Ancestor+ will only repeat the structure inside the \REP and \ENR tags for each individual, and so you preamble and anything you may wish to add at the end of the file will appear only once. If these tags aren't used then, when creating multiple reports, the whole of the file will be repeated for each person.

The \ADO tag is used within a \CHI structure to insert a word where a child is adopted into that family. By default the word is (Adopted), in brackets as shown, and with a leading space. If you want to change this, for example, you might prefer to shorten it to just '(A)', then insert the \ADO tag somewhere in the text before the first structure begins. All of the text on the line following the \ADO tag will then be inserted in a \CHI structure where the \ADO tag appears the child is adopted.

Leading spaces after the \ADO tag are normally stripped when the tag is used to define the word(s) to be used. If you want leading spaces insert an '=' character, then everything after the '=' sign will be used, including spaces, eg.

     \ADO = (Adopted)

As there are two spaces between '=' and '(Adopted)' there would be two leading spaces whenever the word was used.

There are several example files included in the Reports sub directory of the User directory with the distribution copy of Ancestor+. Although these all work, they are not really intended for serious use, but just as examples for you to see how the system operates. The whole point of Template files is that you can use the method to create documents just the way you want, and it will be worthwhile spending some time experimenting with the system.

CSV file format

When a complete database is saved from Ancestor+ in CSV format a directory is created containing two CSV files named People and Unions. Ancestor+ can accept data in the form of CSV files but it must be in exactly the same format as described. These may be used by people writing conversion utilities for other programs, and is the system used by !AncConv.

The 'People' file

The file begins with three lines -

      Line 1  Always 'Ancestor+ People'
      Line 2  Database title
      Line 3  Number of People records

There then follows the data, one person per line, with a linefeed terminating each line. Each CSV field contains the following data.

      Record number
      Surname
      Forename(s)
      Byname(s)
      Sex
      Status
      Title
      Date of Birth
      Place of Birth
      Date of Death
      Place of Death
      User Field 1
      User Field 2
      User Field 3
      User Field 4
      User Field 5

All dates must be in the correct format, ie. dd-mm-yyyy, using numbers for the months. Day and/or month may be omitted. The last one or two digits of the year can be '?' as described in the section on Dates. A 'modifier' character (a, b, c, e, +) can be attached as a prefix, and a 'J' or 'G' as a suffix.

Because of the length of the Name and User fields the length of a line in the People file can be quite large, over 700 characters. Many programs cannot accept lines longer than 255 characters.

The 'Unions' file

The file begins with three lines -

      Line 1  Always 'Ancestor+ Families'
      Line 2  Database title
      Line 3  Number of Family records

There then follows the data, one family record per line, with a linefeed terminating each line. Each CSV field contains the following data.

      Record number
      Type of union code
      Place of marriage
      Date of marriage
      Date of end of marriage
      Marriage ended by code
      Notes field
      Reference number of first partner
      Reference number of second partner
      Number of children

If the number of children is >0 there then follows a number of additional fields, each containing the reference number of the child. All people and children MUST be defined in the accompanying People file.

Keystroke shortcuts

Ancestor+ accepts various keyboard shortcuts. As with all program Ancestor+ must have the 'input focus' for these to operate. Some of these are 'context sensitive'.

    F3  Open 'Save' box
    F4  Open 'Search' window
    F8  Restore Details or Family window to last Updated state ('undo')
    F9  Clear all fields in Details or Family window
    Shift-Ctrl-Insert  Same as pressing Add or Update in Detail or Family windows
    Shift-Ctrl-A  Same as clicking on Add when adding new people or families
    Ctrl F1 to F9  Type macro (only in Details and Family windows)

The arrows keys can be used to move up and down between writable fields in most windows.

Database limitations

The maximum number of people that can be accommodated is 20,000, and the maximum number of families 10,000. These could be increased by about 50% without alteration of the database structure should the need arise. Up to 255 children can be linked into a family, but at the moment the sorting and re-ordering are only able to cope with 40. At present the maximum number of family links (ie. marriages) that any person can have is 20. Again this could be increased if necessary without any alteration in the database structure.

A person can be linked to only one 'natural' and one adopted set of parents.

Unlike some other systems Ancestor+ accepts same sex 'marriages' and, although it will issue warnings, it will permit you to create families where the date of birth of a child is widely outside the normally accepted range, thereby anticipating such developments as AID and surrogate mothers. Many programs will reject a date of birth of a child that is what it considers too long after the death of the Father or Mother.

A family does not require two parents. It is quite possible to create a 'social' family unit consisting of a single parent and several (presumably) adopted children.

The database itself uses variable length records, so it can be kept fairly compact while still allowing quite large fields. The maximum size of these fields is therefore set by the capacity of the various windows, and is -

In the Details window -

      Surname, Forename, Byname and Title  50 characters
      Place of Birth, Place of Death    100 characters
      User fields        100 characters

In the Family window -

      Place of Marriage      100 characters
      Note        100 characters

If at any time in the future it was found necessary to increase these this could be done with no alteration in database structure.

There are no specific fields for items like Baptism and Burial dates and details. This is because it was felt that where these are required it would be better if the user simply used one of the User fields for that purpose. Where such data is not required (eg. anyone compiling a database of non-Christian subjects would find a Baptism field redundant) having dedicated fields would just add clutter. The five User fields can be readily adapted for data like baptism, burial, education, occupation, bar mitzvah, etc.

RISCWorld