                          Origins ARexx Functions
                        1992 by The Puzzle Factory

This documentation is intended to illustrate the ARexx interface to  Origins.
It  is  not  intended  to explain how to use Origins or ARexx, or how various
functions operate.  Please see the Origins or  ARexx documentation  for  more
information.

The accompanying ARexx program, ATest.rexx, will help you to  understand  how
these  functions  are to be used.  Make sure that you change the arguments to
the functions to match records in YOUR database  before  trying  to  use  the
test program or the functions.

The following symbolic arguments are used in this documention:

  NUM     = A cardinal number
  CNUM    = Person Record number of a Child
  FNUM    = Person Record number of a Father
  MNUM    = Person Record number of a Mother
  HNUM    = Person Record number of a Husband
  WNUM    = Person Record number of a Wife
  SNUM    = Person Record number of a Spouse
  PNUM    = Person Record number
  ONUM    = Ordinance Record number
  MARNUM  = Marriage Record number
  SNAME   = Surname (Last name)
  GNAME   = Given name (First name possibly plus middle name(s))
  DATE    = A string taking two possible forms.  Either the more common
            'dd mmm yyyy' or the form 'c.yyyy'.
  YEAR    = A numeric string indicating a year, i.e. '1973'.
  CITY    = The name of a city.
  STATE   = The name of a state.  Alternately, the postal abbreviation,
            i.e. 'OR'.
  COUNTRY = The name of a country.  Alternately, the international
            abbreviation, i.e. 'USA'.
  CODE    = A numeric string from 0 to 65535.  The meaning of this code
            is entirely up to you.  The value of 0 is a null code.
  GENDER  = The character 'M' for male, or 'F' for female.
  (args)  = The argument list for a function.  '|' is used as an OR symbol
            meaning this function may use this argument list OR that
            argument list.  All arguments MUST be supplied to all functions
            unless otherwise noted.  If an argument is unknown, the null
            string "''" must be used.
  'STR'   = A literal string.
  {arg}   = This is used when several strings are to be combined into
            one argument.
  [arg]   = This is used when an argument is optional.

In the examples, ">>>" will be used to show console output.
-----------------------------------------------------------------------------
Origins ARexx Functions:
========================
GENADDMARRIAGE(MARNUM,HNUM,WNUM,CODE,DATE,CITY,COUNTY,STATE,COUNTRY,COMMENT)
GENADDORDINANCE(ONUM,PNUM,BAPTISM,CONFIRM,SPOUSE1,SPOUSE2,SPOUSE3,
                ARRIVED,ARRDATE,OCCUPATION)
GENADDPERSON(PNUM,FNUM,MNUM,SNAME,GNAME,GENDER,CODE,
             BIRTHDATE,{BIRTHCITY,BIRTHCOUNTY,BIRTHSTATE,BIRTHCOUNTRY},
             DEATHDATE,{DEATHCITY,DEATHCOUNTY,DEATHSTATE,DEATHCOUNTRY},
             BURIALDATE,{BURIALCITY,BURIALCOUNTY,BURIALSTATE,BURIALCOUNTRY})
GENAPPENDRECORDS('PERSON',NUM) | ('ORDINANCE',NUM) | ('MARRIAGE',NUM)
GENCONVERTSOUNDEX(SNAME)
GENCREATEINDEX('PC') | ('MARRIAGE')
GENFINDCHILDREN(FNUM,MNUM)
GENFINDMARRIAGE(MNUM) | ('SEARCH') | ('NEXT') | (HNUM,WNUM)
GENFINDORDINANCE(ONUM) | ('SEARCH') | ('NEXT')
GENFINDPARENTS(CNUM)
GENFINDPERSON(PNUM) | ('SEARCH') | ('NEXT')
GENGETNUMBER('PERSON') | ('ORDINANCE') | ('MARRIAGE') [ACTIVE]
GENSETSEARCH(SNAME,GNAME,YEAR,CITY,COUNTRY,CODE,GENDER)
-----------------------------------------------------------------------------
GENADDMARRIAGE(MARNUM,HNUM,WNUM,CODE,DATE,CITY,COUNTY,STATE,COUNTRY,COMMENT)

Arg1=MARNUM:      Type=Numeric, Val = Unsigned 1-PersRecNum
Arg2=HNUM:        Type=Numeric, Val = Unsigned 1-PersRecNum
Arg3=WNUM:        Type=Numeric, Val = Unsigned 1-PersRecNum
Arg4=CODE:        Type=Numeric, Val=Unsigned 0-65535
Arg5=DATE:        Type=Alphanumeric, Len=12 chars including NULL.
Arg6=CITY:        Type=Alphanumeric, Len=20 chars including NULL.
Arg7=COUNTY:      Type=Alphanumeric, Len=20 chars including NULL.
Arg8=STATE:       Type=Alphanumeric, Len=20 chars including NULL.
Arg9=COUNTRY:     Type=Alphanumeric, Len=20 chars including NULL.
Arg10=COMMENT:    Type=Alphanumeric, Len=50 chars including NULL.

If MARNUM = 0, attempts to add a new ordinance record to the current
database.  If MARNUM = 0, HNUM and WNUM must point to a valid Person records,
or this function will return a bad argument error.  You may want to check if
this record already exists before you add a new one.

If MARNUM <> 0, attempts to update an existing record.  If MARNUM <> 0, HNUM
and WNUM must be 0, or this function will return a bad argument error.

Note: Except as noted above, all arguments except are optional and may be
null.  If any string argument is null, it will clear the corresponding field
in the record.

EXAMPLE:
	/* Attempt to add new ordinance record to database. */
	Call GENADDMARRIAGE(0,5,6,14,'01 Jun 1946','Topeka','','Kansas','USA',,
	               'The weather was absolutely perfect for a June wedding')
	Say Result
	>>> 'Created record 53'

RETURNS:
	If successful and this was a new record:
	   Result1=RC_OK
	   Result2='Created record %ld' where %ld is the new record number
	If successful and this was an existing record:
	   Result2='Updated record %ld' where %ld is the old record number
	   Fills in these marriage record fields:
	   mar_Husband = HNUM
	   mar_Wife    = WNUM
	   mar_Code    = CODE
	   mar_Date    = DATE
	   mar_City    = CITY
	   mar_County  = COUNTY
	   mar_State   = STATE
	   mar_Country = COUNTRY
	   mar_Comment = COMMENT

	If improper, or the wrong number of arguments:
	   Result1=RC_WARN
	   Result2=NULL
	   GEN.LASTERROR='100: Bad arguments'
	If either MARNUM, HNUM or WNUM record number is out of range:
	   Result1=RC_WARN
	   Result2=NULL
	   GEN.LASTERROR='101: Out of range'
	If either MANUM, HNUM or WNUM person records do not exist:
	   Result1=RC_WARN
	   Result2=NULL
	   GEN.LASTERROR='103: No record'
	If either MARNUM, HNUM or WNUM person records could not be read:
	   Result1=RC_FATAL
	   Result2=NULL
	   GEN.LASTERROR='105: Read error'
	If this marriage record could not be written:
	   Result1=RC_FATAL
	   Result2=NULL
	   GEN.LASTERROR='106: Write error'
-----------------------------------------------------------------------------
GENADDORDINANCE(ONUM,PNUM,BAPTISM,CONFIRM,SPOUSE1,SPOUSE2,SPOUSE3,
                ARRIVED,ARRDATE,OCCUPATION)

Arg1=ONUM:        Type=Numeric, Val = Unsigned 1-PersRecNum
Arg2=PNUM:        Type=Numeric, Val = Unsigned 1-PersRecNum
Arg3=BAPTISM:     Type=Alphanumeric, Len=50 chars including NULL.
Arg4=COMFIRM:     Type=Alphanumeric, Len=50 chars including NULL.
Arg5=SNUM:        Type=Numeric, Val = Unsigned 1-PersRecNum
Arg6=SNUM:        Type=Numeric, Val = Unsigned 1-PersRecNum
Arg7=SNUM:        Type=Numeric, Val = Unsigned 1-PersRecNum
Arg8=ARRIVED:     Type=Alphanumeric, Len=50 chars including NULL.
Arg9=ARRDATE:     Type=Alphanumeric, Len=12 chars including NULL.
Arg10=OCCUPATION: Type=Alphanumeric, Len=50 chars including NULL.

If ONUM = 0, attempts to add a new ordinance record to the current database.
If ONUM = 0, PNUM must point to a valid Person record, or this function will
return a bad argument error.  You may want to check if this record already
exists before you add a new one.

If ONUM <> 0, attempts to update an existing record.  If ONUM <> 0, PNUM must
be 0, or this function will return a bad argument error.

Note: Except as noted above, all arguments except are optional and may be
null.  If any string argument is null, it will clear the corresponding field
in the record.

Note: If you provide values for SNUM and the records do not exist, the
function will fail, even if the other arguments are correct.  If the values
for SNUM are null, the fields will be cleared!

EXAMPLE:
	/* Attempt to add new ordinance record to database. */
	Call GENADDORDINANCE(0,165,'Down by the riverside',,
	                  'Our Lady of Perpertual Responsibility',49,2,0,,
	                  'Steamship "Hosannah", stearage class','23 Sep 1903',,
	                  'Part-time manure salesman')
	Say Result
	>>> 'Created record 147'

RETURNS:
	If successful and this was a new record:
	   Result1=RC_OK
	   Result2='Created record %ld' where %ld is the new record number
	   Fills in these ordinance record fields:
	   ord_Link       = PNUM
	   ord_Baptism    = BAPTISM
	   ord_Confirm    = CONFIRM
	   ord_Spouse1    = SPOUSE1
	   ord_Spouse2    = SPOUSE2
	   ord_Spouse3    = SPOUSE3
	   ord_Arrived    = ARRIVED
	   ord_ArrDate    = ARRDATE
	   ord_Occupation = OCCUPATION

	If successful and this was an existing record:
	   Result1=RC_OK
	   Result2='Updated record %ld' where %ld is the old record number
	   Fills in these ordinance record fields:
	   ord_Baptism    = BAPTISM
	   ord_Confirm    = CONFIRM
	   ord_Spouse1    = SPOUSE1
	   ord_Spouse2    = SPOUSE2
	   ord_Spouse3    = SPOUSE3
	   ord_Arrived    = ARRIVED
	   ord_ArrDate    = ARRDATE
	   ord_Occupation = OCCUPATION

	If improper, or the wrong number of arguments:
	   Result1=RC_WARN
	   Result2=NULL
	   GEN.LASTERROR='100: Bad arguments'
	If either ONUM or PNUM record number is out of range:
	   Result1=RC_WARN
	   Result2=NULL
	   GEN.LASTERROR='101: Out of range'
	If either ONUM or PNUM person records do not exist:
	   Result1=RC_WARN
	   Result2=NULL
	   GEN.LASTERROR='103: No record'
	If either ONUM or PNUM person records could not be read:
	   Result1=RC_FATAL
	   Result2=NULL
	   GEN.LASTERROR='105: Read error'
	If this ordinance record could not be written:
	   Result1=RC_FATAL
	   Result2=NULL
	   GEN.LASTERROR='106: Write error'
-----------------------------------------------------------------------------
GENADDPERSON(PNUM,FNUM,MNUM,SNAME,GNAME,GENDER,CODE,
             BIRTHDATE,{BIRTHCITY,BIRTHCOUNTY,BIRTHSTATE,BIRTHCOUNTRY},
             DEATHDATE,{DEATHCITY,DEATHCOUNTY,DEATHSTATE,DEATHCOUNTRY},
             BURIALDATE,{BURIALCITY,BURIALCOUNTY,BURIALSTATE,BURIALCOUNTRY})

Arg1=PNUM:        Type=Numeric, Val = Unsigned 1-PersRecNum
Arg2=FNUM:        Type=Numeric, Val = Unsigned 1-PersRecNum
Arg3=MNUM:        Type=Numeric, Val = Unsigned 1-PersRecNum
Arg4=SNAME:       Type=Alphanumeric, Len=20 chars including NULL.
Arg5=GNAME:       Type=Alphanumeric, Len=32 chars including NULL.
Arg6=GENDER:      Type=Char, Val = M or F
Arg7=CODE:        Type=Numeric, Val=Unsigned 0-65535
Arg8=BIRTHDATE:   Type=Alphanumeric, Len=12 chars including NULL.
Arg9=BIRTHPLACE:  Type=Combined Alphanumeric, Len=77 chars including NULL.
Arg10=DEATHDATE:  Type=Alphanumeric, Len=12 chars including NULL.
Arg11=DEATHPLACE: Type=Combined Alphanumeric, Len=77 chars including NULL.
Arg12=BURIALDATE: Type=Alphanumeric, Len=12 chars including NULL.
Arg13=BURIALPLACE:Type=Combined Alphanumeric, Len=77 chars including NULL.

If PNUM = 0, attempts to add a new Person to the current database.
You may want to check if this person already exists before you add a new
record.

If PNUM <> 0, attempts to update an existing record.

Note: All arguments except for SNAME and GENDER are optional and may be
null.  SNAME and GENDER are required!

Note: If any string argument, or any part of a combined string argument
is null, it will clear the corresponding field in the record.

Note: DO NOT provide a value for FNUM or MNUM unless you know that their
records exist.  If you provide these values and the records do not exist,
the function will fail, even if the other arguments are correct.

EXAMPLE:
	/* Attempt to add new person to database.  Parents records are unknown,
	   and there death and burial information is also unknown at this time. */
	Call GENADDPERSON(0,0,0,'Squirrel','Rocket J.','M',0,,
	                  'c.1968','Frostbite Falls,,MN,USA','','','','')
	Say Result
	>>> 'Created record 126'

RETURNS:
	If successful and this was a new record:
	   Result1=RC_OK
	   Result2='Created record %ld' where %ld is the new record number
	If successful and this was an existing record:
	   Result2='Updated record %ld' where %ld is the old record number
	   Fills in these person record fields:
	   per_Father        = FNUM
	   per_Mother        = MNUM
	   per_LastName      = SNAME
	   per_FirstNames    = GNAME
	   per_Sex           = GENDER
	   per_Code          = CODE
	   per_BirthDate     = BIRTHDATE
	   per_BirthCity     = BIRTHCITY
	   per_BirthCounty   = BIRTHCOUNTY
	   per_BirthState    = BIRTHSTATE
	   per_BirthCountry  = BIRTHCOUNTRY
	   per_DeathDate     = DEATHDATE
	   per_DeathCity     = DEATHCITY
	   per_DeathCounty   = DEATHCOUNTY
	   per_DeathState    = DEATHSTATE
	   per_DeathCountry  = DEATHCOUNTRY
	   per_BurialDate    = BURIALDATE
	   per_BurialCity    = BURIALCITY
	   per_BurialCounty  = BURIALCOUNTY
	   per_BurialState   = BURIALSTATE
	   per_BurialCountry = BURIALCOUNTRY

	If improper, or the wrong number of arguments:
	   Result1=RC_WARN
	   Result2=NULL
	   GEN.LASTERROR='100: Bad arguments'
	If either PNUM, FNUM or MNUM person record number is out of range:
	   Result1=RC_WARN
	   Result2=NULL
	   GEN.LASTERROR='101: Out of range'
	If either PNUM, FNUM or MNUM person records do not exist:
	   Result1=RC_WARN
	   Result2=NULL
	   GEN.LASTERROR='103: No record'
	If either PNUM, FNUM or MNUM person records could not be read:
	   Result1=RC_FATAL
	   Result2=NULL
	   GEN.LASTERROR='105: Read error'
	If this person record could not be written:
	   Result1=RC_FATAL
	   Result2=NULL
	   GEN.LASTERROR='106: Write error'
-----------------------------------------------------------------------------
GENAPPENDRECORDS('PERSON',NUM) | ('ORDINANCE',NUM) | ('MARRIAGE',NUM)

Arg1=PERSON:    Type=Boolean keyword
Arg1=ORDINANCE: Type=Boolean keyword
Arg1=MARRIAGE:  Type=Boolean keyword
Arg2=NUM:       Type=Numeric, Val = Signed 1-(2^31-xxxRecNum)

Attempts to add blank Person, Ordinance, or Marriage records.  This number is
desired number of records to add, not total number of records.  Thus, if a
persfile had 100 records, and you called this function with the argument of
NUM=130, you would have 230 person records total.

EXAMPLE:
	/* Add 100 blank person records */
	Call GENAPPENDRECORDS(PERSON,100)
	Say RESULT
	>>> '200 records'

RETURNS:
	If successful:
	   Result1=RC_OK
	   Result2='%ld records' where %ld is the new total number of the
	                        requested type of records.

	If improper, or the wrong number of arguments:
	   Result1=RC_WARN
	   Result2=NULL
	   GEN.LASTERROR='100: Bad arguments'
	If any record could not be written:
	   Result1=RC_FATAL
	   Result2=NULL
	   GEN.LASTERROR='106: Write error'
	If there was a seek error in the file:
	   Result1=RC_FATAL
	   Result2=NULL
	   GEN.LASTERROR='108: Seek error'
-----------------------------------------------------------------------------

GENCONVERTSOUNDEX(SNAME)

Arg1=SNAME:   Type=Alphanumeric, Len=20 chars including NULL.

Attempts to convert SNAME to a soundex code.

EXAMPLE:
	LASTNAME='Smith'
	Call GENCONVERTSOUNDEX(LASTNAME)
	Say "The Soundex representation of" LASTNAME "is" RESULT
	>>> The Soundex representation of Smith is S530

RETURNS:
	If successful:
	   Result1=RC_OK
	   Result2=The converted surname

	If improper, or the wrong number of arguments:
	   Result1=RC_WARN
	   Result2=NULL
	   GEN.LASTERROR='100: Bad arguments'
-----------------------------------------------------------------------------
GENCREATEINDEX('PC') | ('MARRIAGE')

Arg1=PC:        Type=Boolean keyword
Arg1=MARRIAGE:  Type=Boolean keyword

Attempts to create the Parent/Child or Marriage index.

EXAMPLES:
	/* Index existing parent/child relationships */
	Call GENCREATEINDEX('PC')
	Say RESULT
	>>> 'Created PC index'

	/* Index existing marriage relationships */
	Call GENCREATEINDEX('MARRIAGE')
	Say RESULT
	>>> 'Created marriage index'

RETURNS:
	If successful:
	   Result1=RC_OK
	   Result2='Created PC index' if PC argument
	   Result2='Created marriage index' if MARRIAGE argument

	If improper, or the wrong number of arguments:
	   Result1=RC_WARN
	   Result2=NULL
	   GEN.LASTERROR='100: Bad arguments'

	If index file could not be written:
	   Result1=RC_FATAL
	   Result2=NULL
	   GEN.LASTERROR='106: Write error'

	If index file could not be opened:
	   Result1=RC_FATAL
	   Result2=NULL
	   GEN.LASTERROR='107: Open error'

	If could not allocate memory for index file:
	   Result1=RC_FATAL
	   Result2=NULL
	   GEN.LASTERROR='109: No memory'
-----------------------------------------------------------------------------
GENFINDCHILDREN(FNUM,MNUM)

Arg1=FNUM:    Type=Numeric, Val = Unsigned 1-PersRecNum
Arg2=MNUM:    Type=Numeric, Val = Unsigned 1-PersRecNum

Given Person record numbers of both partners, finds only children common to
both, and returns list sorted by birthdate.  Note that there may not be any
children to find.

EXAMPLES:
	Call GENFINDCHILDREN(58,61)
	If value(word(Result,1))>0 then do  /* If any children */
		Say Result
		>>> '3 children found'
		do i=1 to (word(Result,1))
		Say "Child"i" is" CHILD.i
		end i
	end

RETURNS:
	If successful:
	   Result1=RC_OK
	   Result2='%d children found' where %d is the number of children found
	   Fills in these ARexx variables:
	   CHILD.%d where %d is the person record number

	If improper, or the wrong number of arguments:
	   Result1=RC_WARN
	   Result2=NULL
	   GEN.LASTERROR='100: Bad arguments'
	If either person record number is out of range:
	   Result1=RC_WARN
	   Result2=NULL
	   GEN.LASTERROR='101: Out of range'
	If the parent/child index is unavailable:
	   Result1=RC_ERROR
	   Result2=NULL
	   GEN.LASTERROR='104: No index'
	If no child record exists:
	   Result1=RC_WARN
	   Result2=NULL
	   GEN.LASTERROR='103: No record'
	If person records could not be read:
	   Result1=RC_FATAL
	   Result2=NULL
	   GEN.LASTERROR='105: Read error'
-----------------------------------------------------------------------------
GENFINDMARRIAGE (MARNUM) | ('SEARCH') | ('NEXT') | (HNUM,WNUM)

Arg1=MARNUM:  Type=Numeric, Val = Unsigned 1-MarrRecNum
Arg1=SEARCH:  Type=Boolean keyword
Arg1=NEXT:    Type=Boolean keyword

Arg1=HNUM:    Type=Numeric, Val = Unsigned 1-PersRecNum
Arg2=WNUM:    Type=Numeric, Val = Unsigned 1-PersRecNum

If given one number, returns data on that marriage.

If given two numbers, attempts to translate the person numbers into a
marriage number.  If successful, returns data on that marriage.  This
form has less overhead than a search.

If given the SEARCH flag, attempts to locate the first record that matches
the described person.  If successful, attempts to translate the person number
into a marriage number.  If successful, and if there was only one marriage,
returns data on that marriage.  If successful, and there were multiple
marriages, returns a list of spouses.  Uses current settings of search
buffers.

If given the NEXT flag, attempts to locate the next record that matches the
described person.  If successful, attempts to translate the person number
into a marriage number.  If successful, and if there was only one marriage,
returns data on that marriage.  If successful, and there were multiple
marriages, returns a list of spouses.  Uses current settings of search
buffers.

EXAMPLES:
	Call GENFINDMARRIAGE('SEARCH')
	If Result = 'Found marriage' then do     /* If a single marriage */
	   Say Result
	   >>> 'Found marriage'
	   Say "Record #:" MARRIAGE.RECORD
	   Say "Husband: " MARRIAGE.HUSBAND
	   ...
	   Say "Comment: " MARRIAGE.COMMENT
	end

	If DataType(word(Result,1))=NUM then do  /* If multiple marriages */
		Say Result
		>>> '2 marriages found'
		do i=1 to (word(Result,1))
		Say "Spouse"i" is" MARRIAGE.SPOUSE.i
		end i
	end

	/* Find the next marriage that matches the previously described person */
	Call GENFINDMARRIAGE('NEXT')

	/* Find marrigae record 27 */
	Call GENFINDMARRIAGE(27)

	/* Find the marriage record for these two people  */
	/* Will not find multiple marriages - only single */
	Call GENFINDMARRIAGE2(102,103)


RETURNS:
	If successful and a single marriage:
	   Result1=RC_OK
	   Result2='Found marriage'
	   Fills in these ARexx variables:
	   MARRIAGE.RECORD  = mar_Record
	   MARRIAGE.HUSBAND = mar_Husband
	   MARRIAGE.WIFE    = mar_Wife
	   MARRIAGE.CODE    = mar_Code
	   MARRIAGE.DATE    = mar_Date
	   MARRIAGE.CITY    = mar_City
	   MARRIAGE.COUNTY  = mar_County
	   MARRIAGE.STATE   = mar_State
	   MARRIAGE.COUNTRY = mar_Country
	   MARRIAGE.COMMENT = mar_Comment

	If successful and multiple marriages:
	   Result1=RC_OK
	   Result2='%d marriages found' where %d is the number of marriages found
	   Fills in these ARexx variables:
	   MARRIAGE.SPOUSE.%d where %d is the person record number

	If improper, or the wrong number of arguments:
	   Result1=RC_WARN
	   Result2=NULL
	   GEN.LASTERROR='100: Bad arguments'
	If the person record number is out of range:
	   Result1=RC_WARN
	   Result2=NULL
	   GEN.LASTERROR='101: Out of range'
	If search failed:
	   Result1=RC_ERROR
	   Result2=NULL
	   GEN.LASTERROR='102: Search failed'
	If the marriage record does not exist:
	   Result1=RC_WARN
	   Result2=NULL
	   GEN.LASTERROR='103: No record'
	If the marriage index is unavailable:
	   Result1=RC_ERROR
	   Result2=NULL
	   GEN.LASTERROR='104: No index'
	If record could not be read:
	   Result1=RC_FATAL
	   Result2=NULL
	   GEN.LASTERROR='105: Read error'
-----------------------------------------------------------------------------
GENFINDORDINANCE (ONUM) | ('SEARCH') | ('NEXT')

Arg1=ONUM:    Type=Numeric, Val = Unsigned 1-OrdRecNum
Arg1=SEARCH:  Type=Boolean keyword
Arg1=NEXT:    Type=Boolean keyword

If given a number, returns data on that ordinance.

If given the SEARCH flag, attempts to locate the first record that matches
the described person.  If successful, attempts to translate the person number
into an ordinance number.  If successful, returns data on that ordinance.
Uses current settings of search buffers.

If given the NEXT flag, attempts to locate the next record that matches the
described person.  If successful, attempts to translate the person number
into an ordinance number.  If successful, returns data on that ordinance.
Uses current settings of search buffers.

EXAMPLE:
	/* Find the first record that matches the previously described person */
	Call GENFINDORDINANCE('SEARCH')
	Say Result
	>>> 'Found ordinance'

	Say ORDINANCE.RECORD
	Say ORDINANCE.BAPTISM
	    ...
	Say ORDINANCE.OCCUPATION

	/* Find the next record that matches the previously described person */
	Call GENFINDORDINANCE('NEXT')
	Say Result
	>>> 'Found ordinance'

	/* Find ordinance record 27 */
	Call GENFINDORDINANCE(27)
	Say Result
	>>> 'Found ordinance'

RETURNS:
	If successful:
	   Result1=RC_OK
	   Result2='Found ordinance'
	   Fills in these ARexx variables:
	   ORDINANCE.RECORD       = ord_RecNo
	   ORDINANCE.BAPTISM      = ord_Baptism
	   ORDINANCE.CONFIRMATION = ord_Confirm
	   ORDINANCE.SPOUSE1      = ord_Spouse1
	   ORDINANCE.SPOUSE2      = ord_Spouse2
	   ORDINANCE.SPOUSE3      = ord_Spouse3
	   ORDINANCE.ARRIVED      = ord_Arrived
	   ORDINANCE.ARRDATE      = ord_ArrDate
	   ORDINANCE.OCCUPATION   = ord_Occupation

	If improper, or the wrong number of arguments:
	   Result1=RC_WARN
	   Result2=NULL
	   GEN.LASTERROR='100: Bad arguments'
	If the person record number is out of range:
	   Result1=RC_WARN
	   Result2=NULL
	   GEN.LASTERROR='101: Out of range'
	If search failed:
	   Result1=RC_ERROR
	   Result2=NULL
	   GEN.LASTERROR='102: Search failed'
	If the ordinance record does not exist:
	   Result1=RC_WARN
	   Result2=NULL
	   GEN.LASTERROR='103: No record'
	If record could not be read:
	   Result1=RC_FATAL
	   Result2=NULL
	   GEN.LASTERROR='105: Read error'
-----------------------------------------------------------------------------
GENFINDPARENTS(CNUM)

Arg1=CNUM:    Type=Numeric, Val = Unsigned 1-PersRecNum

Given Person record number of a Child, returns both parents.  If there is
only one parent, the other variable will be cleared.  Note that there may not
be any parents to find.

EXAMPLES:
	Call GENFINDPARENTS(132)
	Say "Father is" FATHER
	Say "Mother is" MOTHER

RETURNS:
	If successful:
	   Result1=RC_OK
	   Result2='Found parents'
	   Fills in these ARexx variables:
	   FATHER = Father
	   MOTHER = Mother

	If improper, or the wrong number of arguments:
	   Result1=RC_WARN
	   Result2=NULL
	   GEN.LASTERROR='100: Bad arguments'
	If person record number is out of range:
	   Result1=RC_WARN
	   Result2=NULL
	   GEN.LASTERROR='101: Out of range'
	If no parent records exist:
	   Result1=RC_WARN
	   Result2=NULL
	   GEN.LASTERROR='103: No record'
	If the parent/child index is unavailable:
	   Result1=RC_ERROR
	   Result2=NULL
	   GEN.LASTERROR='104: No index'
	If record could not be read:
	   Result1=RC_FATAL
	   Result2=NULL
	   GEN.LASTERROR='105: Read error'
-----------------------------------------------------------------------------
GENFINDPERSON(PNUM) | ('SEARCH') | ('NEXT')

Arg1=PNUM:    Type=Numeric, Val = Unsigned 1-PersRecNum
Arg1=SEARCH:  Type=Boolean keyword
Arg1=NEXT:    Type=Boolean keyword

If given a number, returns data on that person.

If given the SEARCH flag, attempts to locate the first record that matches
the described person.  If successful, returns data on that person.  Uses
current settings of search buffers.

If given the NEXT flag, attempts to locate the next record that matches the
described person.  If successful, returns data on that person.  Uses current
settings of search buffers.

EXAMPLE:
	/* Find the 1st record that matches the previously described person */
	Call GENFINDPERSON('SEARCH')
	Say Result
	>>> 'Found person'

	Say PERSON.RECORD
	Say PERSON.FATHER
	    ...
	Say PERSON.BURIALCOUNTRY

	/* Find the next record that matches the previously described person */
	Call GENFINDPERSON('NEXT')
	Say Result
	>>> 'Found person'

	/* Find person record 27 */
	Call GENFINDPERSON(27)
	Say Result
	>>> 'Found person'

RETURNS:
	If successful:
	   Result1=RC_OK
	   Result2='Found person'
	   Fills in these ARexx variables:
	   PERSON.RECORD       = per_RecNo
	   PERSON.FATHER       = per_Father
	   PERSON.MOTHER       = per_Mother
	   PERSON.SURNAME      = per_LastName
	   PERSON.GIVNAME      = per_FirstNames
	   PERSON.SEX          = per_Sex
	   PERSON.CODE         = per_Code
	   PERSON.BIRTHDATE    = per_BirthDate
	   PERSON.BIRTHCITY    = per_BirthCity
	   PERSON.BIRTHCOUNTY  = per_BirthCounty
	   PERSON.BIRTHSTATE   = per_BirthState
	   PERSON.BIRTHCOUNTRY = per_BirthCountry
	   PERSON.DEATHDATE    = per_DeathDate
	   PERSON.DEATHCITY    = per_DeathCity
	   PERSON.DEATHCOUNTY  = per_DeathCounty
	   PERSON.DEATHSTATE   = per_DeathState
	   PERSON.DEATHCOUNTRY = per_DeathCountry
	   PERSON.BURIALDATE   = per_BurialDate
	   PERSON.BURIALCITY   = per_BurialCity
	   PERSON.BURIALCOUNTY = per_BurialCounty
	   PERSON.BURIALSTATE  = per_BurialState
	   PERSON.BURIALCOUNTRY= per_BurialCountry

	If improper, or the wrong number of arguments:
	   Result1=RC_WARN
	   Result2=NULL
	   GEN.LASTERROR='100: Bad arguments'
	If the person record number is greater than the total size of the
	database, or the returned record is not an active record:
	   Result1=RC_WARN
	   Result2=NULL
	   GEN.LASTERROR='101: Out of range'
	If search failed:
	   Result1=RC_ERROR
	   Result2=NULL
	   GEN.LASTERROR='102: Search failed'
	If record could not be read:
	   Result1=RC_FATAL
	   Result2=NULL
	   GEN.LASTERROR='105: Read error'
-----------------------------------------------------------------------------
GENGETNUMBER('PERSON') | ('ORDINANCE') | ('MARRIAGE') [ACTIVE]

Arg1=PERSON:    Type=Boolean keyword
Arg1=ORDINANCE: Type=Boolean keyword
Arg1=MARRIAGE:  Type=Boolean keyword
Arg2=ACTIVE:    Type=Boolean keyword, optional

Finds the number of current Person, Ordinance, or Marriage records.  This
number is total records, not active records.  Thus, in a newly created
persfile, there would be 100 records.

EXAMPLE:
	/* Find out how many person records currently exist */
	Call GENGETNUMBER(PERSON)
	Say RESULT
	>>> '100 records'

	/* Find out how many marriage records currently are in use */
	Call GENGETNUMBER(MARRIAGE,ACTIVE)
	Say RESULT
	>>> '58 records'

RETURNS:
	If successful:
	   Result1=RC_OK
	   Result2='%ld records' where %ld is the number of the requested type
                               of records.

	If improper, or the wrong number of arguments:
	   Result1=RC_WARN
	   Result2=NULL
	   GEN.LASTERROR='100: Bad arguments'
	If the 'ACTIVE' argument is used, this function may also return:
	   Result1=RC_FATAL
	   Result2=NULL
	   GEN.LASTERROR='105: Read error'
-----------------------------------------------------------------------------
GENSETSEARCH(SNAME,GNAME,YEAR,CITY,COUNTRY,CODE,GENDER)

Arg1=SNAME:   Type=Alphanumeric, Len=20 chars including NULL.
Arg2=GNAME:   Type=Alphanumeric, Len=32 chars including NULL.
Arg3=YEAR:    Type=Numeric, Val=Unsigned 1-9999 (see Origins docs)
Arg4=CITY:    Type=Alphanumeric, Len=20 chars including NULL.
Arg5=COUNTRY: Type=Alphanumeric, Len=20 chars including NULL.
Arg6=CODE:    Type=Numeric, Val=Unsigned 0-65535
Arg7=GENDER:  Type=Char, Val = M or F

Sets up the search buffers with the supplied arguments.  All strings may be
partial names.  A null arguments will clear its respective buffer.  All
arguments are required.  This function also clears the LastSearch result.

EXAMPLE:
	/* Put the arguments into variables, perhaps from the command line */
	SNAME='Doe';GNAME='John';YEAR=1955;CITY='Toledo';COUNTRY='USA'
	CODE=4;GENDER='M'
	Call GENSETSEARCH(SNAME,GNAME,YEAR,CITY,COUNTRY,CODE,GENDER)

	/* or supply the arguments directly */
	Call GENSETSEARCH('Doe','John',1955,'Toledo','USA',4,'M')
	Say Result
	>>> Search buffers set

	/* You must supply all arguments to this function,
	but any	string arguments may be partial, or any
	arguments may be set to null as follows */
	Call GENSETSEARCH('Doe','',1955,'Tol','USA','','M')
	Say Result
	>>> Search buffers set

RETURNS:
	If successful:
	   Result1=RC_OK
	   Result2='Search buffers set'

	If improper, or the wrong number of arguments:
	   Result1=RC_WARN
	   Result2=NULL
	   GEN.LASTERROR='100: Bad arguments'
-----------------------------------------------------------------------------
