THE "GENSERV2" GENEALOGICAL SERVER Manual (version dated 1 June 1995) CONTENTS 1 INTRODUCTION 2 TO PARTICIPATE IN GENSERV 2.1 Submitting GEDCOM via disk 2.2 Genserv user names and access codes 3 GENSERV COMMANDS 3.1 USER Command 3.2 SPLIT Command 3.3 SEND Command 3.4 EXCLUDE Command 3.5 SEARCH Command 3.6 SOUNDEX Command 3.7 SEARCHCOUNT Command 3.8 SOUNDEXCOUNT Command 3.9 MATCH Command 3.10 REPORT Command 3.10.1 Keyword REPORT 3.10.1.1 Report type: rv2 3.10.1.2 Report type: fam10s1 3.10.1.3 Report type: fam10s2 3.10.1.4 Report type: fam10s3 3.10.1.5 Report type: fam10s4 3.10.1.6 Report type: ahnen1 3.10.1.7 Report type: 4gen 3.10.1.8 Report type: desctree1 3.10.1.9 Report type: desctree2 3.10.1.10 Report type: desc-henry 3.10.2 Keyword DATABASE 3.10.3 Keyword NAME 4 A COMPLETE EXAMPLE 5 FINAL REMARKS 1 INTRODUCTION Genserv contains genealogical data originally submitted as databases (in GEDCOM format) from an ever-growing number of genealogists in the USA and various other countries. These databases contain basic genealogical information such as names, dates of birth, marriage, etc., details of family relationships, and often the details of the sources of this information together with other descriptive text. Automated searches of this information can be requested by means of commands sent to Genserv by electronic mail. (Note: it is not necessary to have full Internet connectivity in order to use Genserv - many other networks, such as Compuserve, Fidonet, etc., have facilities for exchanging electronic mail with the Internet.) These commands can cause it to search its entire set of databases for records related to a given name, and to provide detailed reports, in various formats, on chosen individuals that have been located by such searches. This service is free, but is available ONLY to persons who have submitted a GEDCOM database themselves - the Genserv Project is thus an exercise in cooperative use of modern database and networking technology. As of March 1995 this 'server' had over 600,000 names in GEDCOM data, and that number has been growing fast during the last few months, and even more so now with the posting of an announcement on the ROOTS-L mailing list and the USENET genealogy newsgroup soc.roots. Genserv was conceived and is managed by Cliff Manis. It was implemented by Ron McDowell, based on the use of the LifeLines Genealogical Program and Database written by Thomas Trask Wetmore, and incorporating a search program written by John Smith. This manual was edited by Brian Randell. Jon Rees serves as a point of contact for European users submitting databases. All the databases and reports are being maintained using this system alone, which is running on a Dell 466T system running Dell UNIX SVR4. A first version of this service was launched in October 1991, and a version called Genserv, which has a revised user interface, was made generally available in January 1994. This manual describes the new version of the system and the use of new interface, but for convenience refers to the system simply as Genserv. 2 TO PARTICIPATE IN GENSERV As indicated above, an absolute prior requirement is for you to provide a database in GEDCOM format - such databases can be produced automatically by many different genealogical database management systems. If you wish to participate, you are encouraged to supply a complete database containing all the genealogical data you have accumulated and fitted together via your researches, and to include not just basic data such as names and dates, but also any "Notes" fields. However the database should embody the results of your own researches, not simply be one produced by automatic extraction from some other system such as the IGI CD-ROM system. (The database in fact remains the property of the original submitter - and will not be provided in GEDCOM format to anyone else.) Although GenServ performs searches on up to the entire set of databases that have been submitted to it, the databases remain separate, and associated with the name of their respective submitters. Thus it is possible for you to withdraw a database that you submitted previously and replace it with an updated one. Updates to GEDCOM files presently on the system may only be sent in at six month intervals. Please do not send updates more frequently than this. You can provide several GEDCOM databases to Genserv, including on behalf of other genealogists who do not themselves have the necessary computer and networking facilities - however only persons who have themselves submitted one or more GEDCOM databases can make queries, though these can be on behalf of others. In consequence of the fact that the various databases submitted to Genserv are deliberately kept separate no effort is made to eliminate or merge duplicate individuals found in more than one database, and many duplicates are, in fact, known to exist. Any discrepancies among duplicate entries should be brought to the attention of the respective submitters of those databases. 2.1 Submitting GEDCOM Databases to Genserv Experience gained in operating the Genserv service to date has exposed problems due to Gedcom variability. (There were also difficulties with the receipt of databases sent by email or ftp - a facility which has now been withdrawn.) In theory, a GEDCOM database exported from any genealogical database management system should be acceptable to any system that claims to be able to import GEDCOM. In practice, so many differences exist between the GEDCOM formats used by various systems that a GEDCOM database produced by one system may not load correctly, or at all, into some other systems. You are therefore requested to check, before sending it to Genserv, that your GEDCOM database can be successfully imported by one of the following systems: PAF (LDS) Version 2.1 or later GIM (Genealogical Information Manager) Version 2.* or later Brothers Keeper, any version 1992 or later LifeLines, the UNIX Genealogical Program, any version In the past, GEDCOM databases exported from these systems have loaded without any problems. Note: If you use FTM, make sure to save your GEDCOM as a PAF file (version 4 or 5, using IBM PC character set), with no "indent" and with "abbreviated tags" before checking that it can be successfully imported into one of the above systems. Having performed such a check, you should send your GEDCOM database on a 3.5 inch high or low density floppy disk (in a diskette mailer) as either an ASCII file or compressed with PKZIP, in MSDOS format, either to the following US postal address for Cliff (who is currently living in Seoul, Korea): Cliff Manis HHC, 18th MEDCOM P. O. Box 579 APO AP 96205 USA or - if you live in Europe - to: Jon Rees Church Cottage, Ringsfield, Beccles, Suffolk, NR34 8JU UK. (Apple Macintosh users should use Apple File Exchange or an equivalent utility to produce MSDOS-compatible floppy disks.) NB. Make sure to include your email address, as this will be recorded with your database and used for any reports generated by Genserv in response to your subsequent enquiries, and made available to other users who might wish to contact you and exchange data with you. This email address will also be used for a message notifying you if the database you have submitted cannot be loaded. (No attempt will be made to edit the offending database in order to get it to load.) It is estimated that the period for a new user to obtain access to this new system will take about 30-40 days after a diskette is sent to the postal address above. (Disks will not be returned to the sender.) Updates to GEDCOM databases which are already on the system should also be sent via post on floppy disk, as per the above instructions. Such updates may not be sent more frequently than twice a year. 2.2 Genserv user names and access codes Once one or more GEDCOM databases have been accepted you will be informed of the "User Name", "Access Code" and "Email Address" that Genserv associates with your database(s). It will be necessary to include your User Name and your Access Code in any subsequent request you make to Genserv. The Email Address is the address to which Genserv will send its responses to any messages from you, no matter from where they are actually sent. It is therefore very important that you notify Cliff Manis of any changes to your email address. 3 GENSERV COMMANDS Genserv currently supports the following different types of command: (a) USER - a command which serves to identify and authenticate the person submitting an enquiry to Genserv. (b) SPLIT - a command to control how Genserv divides up long reports into a set of messages before sending them to you. (c) SEND - a command which requests the sending of one of a small set of standard information files. (d) EXCLUDE - a command which controls which of Genserv's databases are to be searched (e) SEARCH - a command to do an index search, i.e. to request a listing of all the individuals with a given name occurring in the currently-selected set of databases held by Genserv. (f) SOUNDEX - like SEARCH, but specifying the Soundex encoding of the surname of interest. (g) SEARCHCOUNT - a command to calculate and return a count of all the individuals with a given name occurring in the currently-selected set of databases held by Genserv. (h) SOUNDEXCOUNT - like SEARCHCOUNT, but specifying the Soundex encoding of the surname of interest. (i) MATCH - this command provides a convenient way of checking whether any of the individuals with given surnames in a particular database is a likely match with any of the individuals recorded in any of the other databases. (j) REPORT - a request for a detailed report (of one of a number of different types) on an identified individual - typically found by means of the SEARCH or SOUNDEX commands. To issue a command or commands, send a regular Email message to: genserv@progcons.com The server does not read the Subject line; it looks only at the body of the message to discover what you want and what to send back to you. The case of requests is unimportant. Multiple commands may be sent in one message, with one command per line (except REPORT commands, which require three lines). All command lines start with a keyword. The server responds separately to each command. (Depending on the length of the response, it may be sent by Genserv as one or more messages.) Note that Genserv automatically responds to the email address that it has stored associated with your User Name - thus you do not have to submit your requests always from the same address. The server is entirely automatic. It attempts to provide error messages for certain kinds of wrongly-formatted user messages, but this error reporting facility is presently rather limited in scope. The server does not as yet reply to all messages with the wrong syntax/format, but it does reply to a valid search request, even if the surname is not found in the database. So, if you do not eventually receive a reply you should assume that the format of your request message was incorrect. All Genserv commands are processed as they are received, but there may be a small delay before the resulting reports are sent by email. Remember that the response can also be delayed, perhaps for hours, by network outages. PLEASE DO NOT send more than 6 requests per 30 minute period to Genserv. PLEASE DO NOT try to get everything in one day - this system will also be available for use next week, and next year! In the following syntax descriptions, uppercase is used for required text, and lowercase items are to be filled in appropriately. However in actual messages to Genserv it does not matter whether upper case or lower case is used, whether for keywords, or for any user-provided items such as names. Blank lines, and lines containing just "-" and "=" symbols, can be used as separator lines to aid readability of a sequence of commands. Such lines will be ignored by Genserv. The following sections describe the use and syntax of each of the commands. Each command line starts with a keyword, which is immediately followed by a colon and a space. Leading spaces and tabs before the keyword are ignored. 3.1 USER Command This should be the first command in your message. It requires your name, spelled exactly as it is in the access database on the Genserv system (complete with any embedded spaces), followed by the "access_code" given to you when the GEDCOM database you submitted to Genserv was accepted, separated from your name by one space. Syntax: USER: username access_code By using this method of authentication, you may send your request from any system anywhere in the world (that can send email to the Internet) and your request will be sent back to your "home-base", i.e. the address listed in the access database held by the server. Examples: USER: Cliff Manis abc123 User: Cliff MANIS ABC123 (Do not bother to try these - the access code is not Cliff's!) 3.2 SPLIT Command Some of the reports produced by Genserv are potentially very long. You can use the SPLIT command, immediately after the USER command, to specify how such long reports are to be split into a sequence of messages before being sent to you. Its parameter is an integer which indicates the maximum number of kilobytes per message. (The split will actually be made at the end of a line in a report.) Example: SPLIT: 20 The standard default, which operates when you do not include a SPLIT command in your message, imposes a 50kbyte limit on each of the messages. (The largest maximum message size is 100kbtes - this limit will be applied even if you specify a parameter more than 100. The smallest maximum message size is 12kbtes - this limit will be applied even if you specify a parameter less than 12.) 3.3 SEND Command You use this command to request a file. Several files are available - all are in ASCII. Currently the files available are: (a) FILESET = A file listing and describing the set of files that are currently available for you to request by means of the SEND command (b) HELP = This manual, describing the capabilities of Genserv. (c) INFO = The same file as HELP (d) RPTSAMP = A file consisting of examples of all the types of reports which are currently available. (e) CONTACTS = A listing of the people who have supplied GEDCOM databases to Genserv, with their email addresses. (f) DATADATE = A complete listing of the databases in Genserv and the date and time that each database was loaded. (g) DATATOT = A listing of the last few databases to be loaded, giving the date and time that each was loaded. Syntax: SEND: file_to_be_sent Examples: SEND: info SEND: Contacts SEND: RPTSAMP 3.4 EXCLUDE Command Genserv, unless instructed otherwise, applies its various search commands to the entire set of databases that it currently holds. You can use the EXCLUDE command to name one or more databases that you do not want to be searched. (For example, you may well not want Genserv to perform searches on the database(s) you have yourself provided.) Various types of search command are described in subsequent sections of this manual as being applied to the "currently-selected set of databases". This set is defined as the full set of databases, less those named in the EXCLUDE command. Example: EXCLUDE: mb5 char4x This will prevent the databases named "mb5" and "char4x" from being searched. Only one EXCLUDE command is accepted for each email message you send. The first EXCLUDE command will be the one used by the server; additional EXCLUDE commands will be ignored. If you wish to specify different EXCLUDEs for different searches, you will need to request these searches in separate email messages. 3.5 SEARCH Command You use this command to request an index of people in the currently-selected set of databases held by Genserv. This is one of the standard preliminares to obtaining detailed information about any of these people. (The other is the MATCH command - see Section 3.9 below.) Syntax: SEARCH: surname Example: SEARCH: manis This example would produce a listing similar to the following: This Index of Surnames has been generated by Genserv INDEX OF SURNAMES FOUND ============================================================================= LAST, First INDI# Spouse name SNDX Birthdate Deathdate Database ----------------- ------ ---------------- ---- ----------- ----------- ------ MANIS, Alda C 171 OWENS, Joyce F M520 11 Mar 1939 mb5 MANIS, Amos ( 1443 FRANCIS, Mary E M520 1805 1840 mb5 MANIS, Annas 12572 JONES, John M520 14 Mar 1791 2 Nov 1874 mb5 MANIS, Annas 486 JONES, John M520 14 Mar 1791 2 Nov 1874 char4x MANIS, Arnold M 1459 M520 18 Jun 1893 19 Jul 1893 mb5 MANIS, Arthur M. 866 MOORE, Ollie Lee M520 8 Sep 1886 27 Mar 1950 mb5 ----------------- ------ ---------------- ---- ----------- ----------- ------ The second column is an identification number that - until the relevant database is modified - you can use in REPORT commands in order to obtain detailed reports on the individual, as an alternative to giving the individual's name. The third column gives the name of the individual's spouse, if one is listed in the database. If an individual had more than one spouse, it will be the name of the first such spouse. The fourth column in the Index gives the Soundex encoding of the individual's Last Name. You can use the SOUNDEX command (see below) to request that searches be performed using such a Soundex code, so as to avoid having to make a whole set of separate searches based on many different similarly-sounding versions of an individual's surname. 3.6 SOUNDEX Command This is exactly the same as the SEARCH command except that instead of specifying the surname of the individual to be searched for in the currently- selected set of databases, you specify the Soundex encoding of the surname. As its name implies the Soundex encoding attempts to group together, under a single code, all words that sound similar when spoken. Various utility programs exist that automate the calculation of Soundex codings - however one of the pieces of information provided by the standard SEARCH command on Genserv is the Soundex encoding of the specified surname. Example: SOUNDEX: m520 You will, presumably, wish to use such SOUNDEX searches to avoid having to specify multiple SEARCH requests, one on each of the possible variants of the spelling of a surname. However if you do this, it is wise to confirm beforehand that all these variants do in fact have the same Soundex encoding. 3.7 SEARCHCOUNT Command The purpose of this command is to allow you to find out how many individuals with a given surname are in the currently-selected set of databases. It may be appropriate to explore this, in the case of common surnames, before using an actual SEARCH or SOUNDEX command, particularly if your email facilities are limited or costly. Examples: SEARCHCOUNT: Manis This will produce a count of all the Manis entries in the currently-selected set of databases. 3.8 SOUNDEXCOUNT Command Equivalent to SEARCHCOUNT, but uses a Soundex encoding rather than an actual surname. Example: SOUNDEXCOUNT: m520 This will produce a count of all the Manis, and similarly sounding, entries in the currently-selected set of databases. 3.9 MATCH Command This command provides you with a very convenient way of checking whether any of the individuals with given surnames in a particular database (presumably, but not necessarily one of your databases) is a likely match with any of the individuals recorded in any of the other databases. Syntax: MATCH: list of names to be matched MATCHDATABASE: database_name For example the command MATCH: ROBINSON ROBERTS MATCHDATABASE: randell1 might produce following results: =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- Possible match[s] for ROBINSON, John 455 R152 1956 randell1 ---------------------------------------- ROBINS, Jami E 652 GILLESPIE, P A R152 10 Dec 1958 rintoul1 ROBINSON, Jenny 1764 R152 Oct 1958 lawrence =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- Possible match[s] for ROBERTS, Henry 488 R163 1852 randell1 ---------------------------------------- ROBERTS, Henry W 381 R163 27 Mar 1836 Oct 1852 gwjones =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- These results show that (i) one of the ROBINSONs listed in the randell1 database (namely JOHN ROBINSON, b. 1956) proves to match two individuals in other databases (JAMI ROBINS in the rintoull database and JENNY ROBINSON in the lawrence database), and (ii) that one of the ROBERTS (HENRY ROBERTS, d. 1852) listed in the randell1 database matches a HENRY ROBERTS in the gwjones database. (Another use of exactly the above request could of course produce more matches next time, if further databases have been added to GenServ.) The assessment of whether two individuals are regarded as matching is based on whatever information is given regarding their surnames, first names, year of birth and year of death. Surnames are matched, using their Soundex encoding. (Note that in the above example ROBINSON matches ROBINS as well as ROBINSON therefore.) First names, if both given in full, are similarly matched using a soundex encoding (e.g. JAMI matches JOHN), but allowance is made for records which give only initials, or which do not give an individual's full names or initials. (Thus above one finds that HENRY W. matches HENRY.) The year comparison is approximate. The report issued by the MATCH command lists all individuals that match using all of these criteria. Thus the two Henry ROBERTS entries match, even though the entry in the randell1 database is missing a middle initial and a birth date, compared to the entry in the gwjones database. The above results demonstrate that some reported matches will often be readily discounted just by inspection, but that some others may well indicate that further investigation (either by use of the REPORT faclity or by contacting the submitter of the relevant database), is called for. This is evidently a very powerful command which can enable you to home in very quickly on all the potentially likely overlaps between your GEDCOM database and the other databases in the GenServ system. However the generation of these reports involves GenServ in considerable processing, so you are asked to limit the number of SURNAMES you ask to be matched to 10, and to avoid requesting more than one MATCH command per hour. 3.10 REPORT Command You can use this command to request a detailed report (the format and contents of which will depend on the type of report specified) for an individual in a given database. This command requires you to use three consecutive lines, each starting with a keyword, followed by a colon and a space. Syntax: REPORT: report_type DATABASE: database_name NAME: name_to_print All three keywords are required for each report requested. Below are listed the various report types that you can specify using the REPORT keyword, and the rules for using the DATABASE and NAME keywords. The various forms of report provided do not include any in GEDCOM format. This is a deliberate policy, since in the early stages on the Genserv Project it became clear that some people would be reluctant to have their original GEDCOM databases made readily available, in whole or in part, and thus were willing to submit their GEDCOM databases to Genserv only on the understanding that GEDCOM export facilities would not be provided. However, submitters' addresses are made available, so that if you do wish to obtain the original GEDCOM you can make an appropriate request direct to the originator. 3.10.1 Keyword REPORT This keyword is used to indicate which of the various types of report you wish to be generated and sent to you. 3.10.1.1 Report type: rv2 This report will provide you with basic genealogical information about the individual, and his/her father, mother, spouses, and children. It will also contain all the Notes (i.e. the NOTE and CONT lines in the GEDCOM database) related to the individual and to his/her children. This is a paginated, formatted report. It is intended that this 'rv2' report will be the main report you use to check for information. Please note that 'rv2' report is a convenient way to find out whether an individual had several spouses. 3.10.1.2 Report type: fam10s1 This report includes any basic genealogical information and any Notes about the requested individual and his/her (first) spouse and children in the database, together with their INDI numbers. This report will NOT work if there is no spouse listed in the database. Only the individual's first family is included in the report (see related reports below). 3.10.1.3 Report type: fam10s2 Report for the individual and his/her second spouse. 3.10.1.4 Report type: fam10s3 Report for the individual and his/her third spouse. 3.10.1.5 Report type: fam10s4 Report for the individual and his/her fourth spouse. 3.10.1.6 Report type: ahnen1 This AHNENTAFEL report will contain the complete, direct ancestry ahnentafel of the individual requested, giving for this individual and each direct ancestor such information as is available concerning his/her name, date of birth, place of birth, date of death, and place of death, together with his/her ahnentafel number. 3.10.1.7 Report type: 4gen This report gives, in a tree format, such information as is available about the names, and dates and places of birth and death, of the chosen individual, and his/her parents, grandparents and greatgrandparents. (Note: this command does not work if the chosen individual does not have a spouse.) 3.10.1.8 Report type: desctree1 This report provides details, in the form of an indented listing, one line per individual, of the descendants of a given individual, with numbered generations. 3.10.1.9 Report type: desctree2 Details of all descendents of a given individual (with vertical lines used to help identify individuals of a given generation). 3.10.1.10 Report type: desc-henry Details of all descendents of a given individual (using the Henry numbering system). 3.10.2 Keyword DATABASE The line starting with this keyword is used to give the name, as shown on the SEARCH listing, of the database containing the information on the individual concerned. 3.10.3 Keyword NAME The line starting with this keyword is used to give either the name, or the INDI number from the SEARCH list, of the individual for whom you wish to obtain a report. The name should be given either just as a surname: Example: NAME: Manis or with one or more forenames and/or initials preceding the surname, in which case the surname must be prefaced by a "/" Examples: NAME: A C /Manis NAME: alda clifford /manis NAME: Alda c /MANIS (Note that, just as with keywords, it does not matter whether you use lower case or upper case.) If the name as specified does not identify an individual uniquely, the report you receive will be on the first individual in the database whose name is as specified. When you wish to receive a report on other than the first of a set of identically named individuals, you will have to identify the individual concerned by specifying his/her INDI number. To print a report for an individual identified by his/her INDI number, just put the INDI number as shown in a SEARCH listing in place of the name. Please note: The INDI number may have changed if the database concerned has been modified since you last requested a report. The INDI number is valid only for the particular database. Examples: REPORT: Rv2 DATABASE: char4x NAME: 486 ---------------------- REPORT: fam10s1 DATABASE: mb5 NAME: Alda C /manis 4 A COMPLETE EXAMPLE -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= USER: cliff Manis 45a31d SPLIT: 64 REPORT: Rv2 DATABASE: mB5 NAME: Alda c /MANIS -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= Exclude: mb5 search: D'anjou search: MANIS search: harris sEARCh: PETERS -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= send: conTACts send: Datadate SEND: info The above example sets a 64kbyte message length limit, requests a Rv2 report on Alda C Manis in database mb5, searches the entire set of databases except database mb5 for individuals with the surnames D'Anjou, Manis, Harris and Peters, and finally requests several information files, including finally (perhaps rather belatedly) this manual. (It also illustrates the ability to use either upper or lower case letters, to interpose separator lines, and to have leading spaces.) 5 FINAL REMARKS As mentioned at the outset, Genserv is an exercise in the cooperative use of modern database and networking technology for genealogical research. Its success therefore depends in large part on both the quantity and the quality of the genealogical information provided by its users. You are therefore invited to encourage other potential users of Genserv who could provide appropriate GEDCOM databases to do so. You are also invited to make suggestions as to ways in which Genserv's facilities and its manual (this document) might be improved, though bear in mind the limitations due to the fact that the Genserv project depends entirely on volunteer labour. Such suggestions should be sent to Cliff Manis . Finally, it is appropriate to repeat the request that you inform the submitters of any databases which you find contain overlapping or inconsistent data. -- Cliff Manis cmanis@progcons.com Seoul, Korea GenServ "Genealogical Server" a service for making GEDCOM data available. For GenServ info, just send a message to: genserv-info@progcons.com WWW Genserv URL: http://www.cs.ncl.ac.uk/genuki/GenServ/ -