GEDView 1.05 - Beta test release - 5 Mar 1995 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ USAGE: GV [-n] [scriptname [argument]] The GEDCOM data format was developed by the LDS Church as a way to exchange genealogical data between two systems. GEDView does this: * indexes, searches and displays GEDCOM database files, even large ones, very quickly, * organizes each record into a readable format, * easily accesses related records by tabbing to or clicking on a GEDCOM "pointer" in the current record, * translates tag names (field names) into descriptive words or phrases. * toggles between GEDCOM or "enhanced" display mode, * saves or appends selected records to file in GEDCOM or "enhanced" style, * has the facility to generate user-designed reports through its script command set, * supports color monitors and a Microsoft mouse, * accepts commands via pull-down menus, mouse buttons, textual prompt-style commands or scripts. SPECIFICATIONS ~~~~~~~~~~~~~~ I used the specifications for the proposed GEDCOM standard, draft release 5.3. Not all GEDCOM files are created equal. In fact, some are downright inferior. For that reason, GEDView may not work on all files purported to be GEDCOM. GEDView will handle * files sizes up to 2 gigabytes and will read as many records as can be squeezed into that, * records up to 32,000 bytes in length, * scripts having up to 8,000 lines. GEDView was written to be fast. It will index and create look-up tables at the rate of about 10 seconds per megabyte and will do a global search in about 8 seconds per each megabyte (as performed by on my 386DX-33). Please note the following ~~~~~~~~~~~~~~~~~~~~~~~~~ Tag names that are not described by GEDCOM draft 5.3, are displayed in caps, preceded by an asterisk (*). GEDView will create several new files for *each* GEDCOM file that is read -- and they are not deleted when the program ends (the -n switch can be used on the command line to suppress the indexing of an already indexed file.) Be sure there is plenty room on your disk. WRITING SCRIPTS ~~~~~~~~~~~~~~~ I have a text editor in the works and will make it available in a future release. In the meantime, GEDView scripts can be written using any editor or word processor -SAVED AS AN ASCII FILE. GEDView does very little syntax error checking. And I have done little to discover the results of bad code. For that reason, I must insist on the standard disclaimer.* The best advice I can give right now is to be careful. A poorly-written script, can cause any number of "undefined" conditions, such as freezing your system. Although the basic core or engine of GEDView is very fast and efficient, its scripting capability is _very_ slow and needs more work. And, although the script command set is greatly expanded in this version, it is still rather clunky and simplistic. A script name and its argument may be specified at the DOS command line: GV -n SAMPLE.GED INDENT.PRG SAMPLE2.GED That command will start GEDView, will not index (because the -n switch is used -- an accurate index is presumably known to exist) and will start up the script INDENT.PRG. The output file, SAMPLE2.GED, will be created. The program can be automatically terminated by including the GEDView command, QUIT. The script commands are found in the Help menu. * Always conclude your script with an END statement. * The resulting of an IF statement must go on the next line. * Do not call a script from within another. * GOSUBs can be nested, DO-REPEATs cannot be nested. * Variable names ($ARG, $FULLNAME, $COUNTER, etc.) must be capped. Otherwise, case does not matter. * The system must have sufficient memory resources for the system command. The DOS sort, for instance, in SDX.PRG will easily fail. Return Values ~~~~~~~~~~~~~ Most GEDView functions will return a value. The FAILED value can be thought as being 0, no, negative, unsuccessful, not equal, etc. The EQUAL value can be thought of as yes, 1, positive, successful, etc. If a GEDView command is not successful, the FAILED flag is set. -- An IFFAILED will check the status of the command IMMEDIATELY preceding it. Therefore, nothing, not even a GOTO, comment or a label can come between the two lines (the command to be checked and the IFFAILED). Failed (0) and equal (1) can be returned from a GOSUB as an argument of the RETURN statement: RETURN 1 Below is the INDENT.PRG sample script. To invoke it, type RUN INDENT.PRG at the dot prompt or select Run Script from the Reports Menu. An output file name may also be included. If a file name has not been given, INDENT.PRG will create a new copy of the opened GEDCOM file with the name NEW.GED. Each line will be indented by 2 spaces times the line's level. For instance, a level 2 line will be indented by four spaces. If your program is recursive -- that is, returns to the top over and over -- you must check for a failed condition to end the execution. Otherwise, you will be stuck in an "infinite loop" and will probably have to reboot your system. Remember, GEDCOM files can be very different from one another. Because a script may work for one GEDCOM it will not necessarily work for another. -- set bell off remember record compare $ARG ifequal goto set-default-name set #outfile $ARG save $OUTFILE "" go 1 :the-top show creating $OUTFILE .... get line iffailed goto the-end :do-record set #counter -1 gosub check-level append $OUTFILE $LINE append $OUTFILE "\J" get next line ifequal goto do-record next iffailed goto the-end goto the-top :the-end go record set bell on end :check-level add 1 #counter ifescape goto the-end compare $FIELD1 $COUNTER iffailed goto check-level do $COUNTER append $OUTFILE " " repeat return :set-default-name set #outfile new.ged save $OUTFILE go 1 goto the-top These scripts are included in this release. They are simple examples intended only to illustrate GEDView's capabilities. Improvements will be included in future releases and/or archived in a presently-undetermined directory at genealogy.emcee.com. I'll be happy to include additional scripts of merit in my FTP site. AHNEN.PRG creates ahnentafel for INDI FATHER.PRG displays father of INDI FGS.PRG creates Group Sheet for FAM FLINE.PRG displays earliest paternal ancestor for INDI HTML.PRG creates Web page for FAM INDENT.PRG created indented GEDCOM file MOTHER.PRG displays mother of INDI SAVE-ALL.PRG creates file in 'enhanced' format SDX.PRG creates and sorts Soundex report SEARCH.PRG creates file of records with matching argument UPCOMING RELEASES ~~~~~~~~~~~~~~~~~ The basic plan for GEDView is to keep it small and fast but to give it the capability for virtually unlimited flexibility through scripting and other features. These three points will be at the top of the list: * Further improve the core speed. * Greatly increase GEDView's script performance and enhance the command set. * Fix bugs. * Improve the doc. * Internal sort. Some intended features include: * Pop-up directory listing. * Configurable default data directory. * Hot-key definitions and macros. RELEASE HISTORY ~~~~~~~~~~~~~~~ 1.00 - 4/8/94 Early unofficial pre-beta in limited circulation. 1.01 - 7/5/94 First beta release. Added keys to Viewer Redesigned buttons Incl command SET PRINT Added help button 1.02 - 7/20/94 Revised to update FAT table after file creation. 1.03 - 8/3/94 Fixed F10/Next freeze-up. 1.04 - 8/24/94 Another freeze-up fix. Fixed script command IF FAILED for NEXT / PREV. Modified "formatted" mode for save. Fixed SET EOL command. 1.05 - 2/24/95 Clears screen when terminated. Changed Save / Append hotkeys to F4 and alt-F4. Search is no longer case sensitive. Many bugs fixed. Several new script commands. IF FAILED changed to IFFAILED. REMEMBER $RECORD changed to REMEMBER RECORD. I have made many changes in the last couple of weeks, particularly relating to scripting. There has not been much time to thoroughly test the results. Undoubtedly, various situations will arise that had not as yet been contemplated. It will be a big help to me to have any and all bugs reported to me via email. Michael Cooley, Mar 1995 email: michael@emcee.com * This version of GEDView is neither commercial nor shareware software but is freely distributed under the terms, conditions and understanding of the following: GEDView is still in the early stages of development and has been tested on only one machine - mine. Any number of conditions can be present - including the manufacture of equipment and the operators mood -- which can influence the performance of this program. Therefore, I bear no responsibility for loss of data or damage to equipment or operator's personality resulting from the use of GEDView and/or its by-products. The user uses at his/her own risk.