**************************************************************** * * * Documentation for M2-DB (Modula-2 Database) * * Release 1.10 * * 02/18/89 * * Copyright 1989 by Joseph I. Mortensen * * All Rights Reserved * * * **************************************************************** I. Introduction M2-DB is the product of the author's wish for an easy to use name and address file program. Its most important features are: * Add, edit, delete, search, browse, sort, or print with one-key mnemonic commands. * Search records on any of seven fields. * Printed output of either labels or envelopes. * Print selected group of labels (all of one zip code for example). * Disk output of labels and an ASCII comma-delimited datafile usable by WordStar's MergePrint feature. * A great companion to WordStar. Runs from WS's no file menu with R command. * User-selected printer fonts from within M2-DB (if you have an Epson FX compatible printer). * Ready to run on any Kaypro CP/M computer. Can be installed to run on other Z80 CP/M machines with 80 column by 24 row monitor. To install it for other Z80 CP/M machines see the appendix. M2-DB is issued as SHAREWARE. You are welcome to copy, use, and freely distribute copies of DB.COM and this documentation file. If you like it and decide to use it, please send $10.00 (US) to: Joseph I. Mortensen 4214 Chelsea Ct. Midland, MI 48640 517 835-6923 CompuServe 70037,3161 GEnie J.MORTENSEN3 M2-DB was compiled and linked with Z80 Turbo Modula-2 (Copyright 1986 Borland International). Those who request it may have the Modula-2 source code including support modules. Updates will be sent to those who send their $10. **** Special Note on Version 1.10 **** Version 1.10 has a slightly different file format than previous versions and will not work properly with data files created with them. A conversion utility DBCONVRT.COM is supplied to convert to the new format. It is in the the library file which contains this documentation file. II. Starting M2-DB After making a backup of your original copy of M2-DB insert your working disk in Drive A and enter: A> DB <[du:]filename> The drive/user designation and the filename are optional on the command line. If you omit the filename, M2-DB will prompt you: ______________________________________________________________ | << M2-DB 1.10 >> 02/18/89 | | | | Copyright 1989 by Joseph I. Mortensen | | | | Enter filename: | |____________________________________________________________| If M2-DB does not find the file you specify, you will get this message: NEWFILE not found. Create new file? Y/N If you entered a file name on the command line, the first screen you see looks like this (if you're using a previously opened file): ______________________________________________________________ | << M2-DB 1.10 >> 02/18/89 | | | | Copyright 1989 by Joseph I. Mortensen | | | | NAMEADDR.FIL open for processing, last used on 01/11/89. | | | | | | | | Enter Today's Date: [ skips date entry] | |____________________________________________________________| You will also be asked for the date since M2-DB will automatically put the date entered on each entry you add to the file. If you enter at the date prompt, M2-DB will skip the rest of the date entry and use whatever date it has stored from prior uses. If your file contains any active records, the first one will be displayed like this: SAMPLE.FIL-01/11/89 << M2-DB 1.10 >> 2 records ------------------------------------------------------------------------------- LAST> Farwell FIRST> Geoffrey MID> L. SPOUSE> Erma TITLE> Mr. SALUTATION> Jeff ADDRESS> 9006 Emery Way ADDR2> CITY> Donaldson Corner STATE> CO ZIP> 80386 PHONE NOS> 285-6478 BIRTHDAY> 12/22/38 ANNIVERSARY> 09/05/60 COMMENT> DATE ENTERED> 01/11/89 ------------------------------------------------------------------------------- A>dd D>el E>dit F>ind N>ext P>rev O>utput S>ort C>fg Q>uit The file name and date are displayed in the upper left corner of the display. A count of active records in the file appears in the upper right corner. The name and current version of M2-DB show in the upper center of the screen. III. The Commands M2-DB uses single letter commands which are always shown in the menu line at the bottom of the screen: ------------------------------------------------------------------------------- A>dd D>el E>dit F>ind N>ext P>rev O>utput S>ort C>fg Q>uit The main commands are explained in the following sections. A. A>dd a Record The first time you use M2-DB a blank form will come on the screen with a menu on the bottom line of the screen. To make a new entry you press A for Add. The cursor jumps to the first field in the data form and awaits your input. WordStar-like editing commands (^A,^S,^D,^F) move the cursor. TAB, CR, or ^X moves to the next field. ^E will back up one field. ^Y deletes from cursor to the end of the field. To finish the entry type ^Z in any field or type a carriage return at the end of the last field in the data form. On a new entry you do not need to fill in "Date Entered;" M2-DB does it automatically. The data entry screen looks like this: SAMPLE.FIL-01/11/89 << M2-DB 1.10 >> 2 records ------------------------------------------------------------------------------- LAST> ____________________ FIRST> MID> SPOUSE> TITLE> SALUTATION> ADDRESS> ADDR2> CITY> STATE> ZIP> PHONE NOS> BIRTHDAY> ANNIVERSARY> COMMENT> DATE ENTERED> WordStar-type [^A,^S,^D,^F] keys move cursor. TAB, CR, or ^X moves to next field. ^E backs up. ^Y deletes from cursor to end. ^Z exits. ------------------------------------------------------------------------------- A>dd D>el E>dit F>ind N>ext P>rev O>utput S>ort C>fg Q>uit A When you finish an entry, you can abort it, save it and continue adding new entries, or save and quit adding new ones. The number of entries is limited by the 64K of memory of most Z80 computers. M2-DB limits the number of records which can be sorted to 1200. However, you are limited by disk capacity as follows: SSDD (191K) -- 600 records See section G below for further information on sorting. B. E>dit a Record To edit a record press E and the cursor jumps (exactly as with adding new records) to the first field. The same editing keys apply in editing as in adding new records. Press ^Z to exit and save the changes. Editing a record: SAMPLE.FIL-01/11/89 << M2-DB 1.10 >> 2 records ------------------------------------------------------------------------------- LAST> Alfredson___________ FIRST> Earl MID> R. SPOUSE> Aimee TITLE> Mr. SALUTATION> Earl ADDRESS> 8642 W. Inner Drive ADDR2> CITY> Elberta STATE> MN ZIP> 50876 PHONE NOS> 432-8698 BIRTHDAY> 08/18/43 ANNIVERSARY> 08/23/66 COMMENT> DATE ENTERED> 01/11/89 WordStar-type [^A,^S,^D,^F] keys move cursor. TAB, CR, or ^X moves to next field. ^E backs up. ^Y deletes from cursor to end. ^Z exits. ------------------------------------------------------------------------------- A>dd D>el E>dit F>ind N>ext P>rev O>utput S>ort C>fg Q>uit E C. D>elete a Record To delete a record press D from the menu. M2-DB will ask you if you really mean it before deleting the record. D. F>ind a Record M2-DB allows searches on seven different fields: last name, first name, city, state, birth month, anniversary month, or zipcode. To find a given record you press F from the menu. You will then be prompted for the search item and the search string. As of release 1.03 M2-DB does ambiguous searches for last name, first name, city, or zip code with as little as a single letter or number. To get to the "S" section of your file merely enter "s" as your search string. For zip codes beginning 46... enter "46" as the string. This feature gives you the maximum flexi- bility in searching. In most cases the first three or four letters of the last name will give you the one you want. Don't worry about upper or lower case. The search routine converts everything to upper case. M2-DB will start the search and display the first record that matches the search string. If it is not the one you want, press "N" (for "no") and the search goes on. Press 'Y' if it's the one you want to edit or print. If the search string is not found, M2-DB tells you so. Due to the fairly unsophisticated search routine used in M2-DB searches in very large files will be a bit slow. E. Browse Mode, the N>ext and P>rev Commands One of the nice features of M2-DB is the ability to browse record by record through the file. N (for next) moves to the next record in the file. P (for previous) moves backward through the file. Each time you open an existing record file the first record in the file is displayed. You can browse through the entire file using the N and P commands. F. O>utput Options M2-DB offers several output options. It is preconfigured to produce one inch by 3.5 inch continuous feed labels, single envelopes (small or large), or a datafile in ASCII comma delimited format for use with WordStar MergePrint, dBII/III, and other programs. The ability to write an ASCII datafile opens the extensive options of merge printing to the user. A special printer menu (see below on the C>fg command) allows a choice of printer fonts (Epson FX85 compatibles only). You can continue making selections from the printer menu (combining elite with wide and italic, for example). The configuration is saved with your data file until you choose to change it. You can also have a default return address print on envelopes. Output of labels can be multiple copies of a single name and address, single copies of names you pick one by one, a selected set (only those matching unambiguous search strings, a given zipcode, for example), or the entire file. If you select individual labels or envelopes, you can use the F>ind and N>ext commands to browse the file until you find the record to print. When you have the one you want, press P to print it. If you select Datafile, M2-DB writes out the entire file with all fields in comma-delimited format. G. S>ort the File When you give the S>ort command, M2-DB sorts the file of records by last name and then first name. After the file is sorted, it is rewritten in sorted form on the disk drive you specify. Memory limitations of Z80 computers (and the programming limitations of the author!) restrict the sorting to 1200 records in M2-DB. Previous versions of M2-DB limited the sort to 600. To allow for the increase to 1200 release 1.04 changed the sort routine by truncating last names to ten letters and first names to four. In all but a few cases the sort will work properly. Very large files will take time to sort. For example, a 100 record file takes 70 seconds to sort and rewrite on a 5MHz Kaypro '83 using quad density drives and TurboROM. Since the sorting and rewriting are disk-intensive operations, slower CPU's (2.5 or 4 MHz) take very little longer. Unless you are constantly adding entries to your file, you won't need to sort very often. The sort routine automatically removes deleted records from the file so it does not grow fat on unused bytes. READ THE FOLLOWING CAUTIONS ON SORTING! ** CAUTION ** When M2-DB does a sort, it needs a lot of RAM. It uses a 20+K array to create the index for the sort. The sort routine checks the amount of free memory before beginning the sort to prevent an out of memory error. If you have 21K or more of free memory, you'll have no problem. M2-DB has a command not shown on the menu which tells how much free memory is available. Before you sort, press 'M' at the main menu. The amount of free memory will be displayed on the menu line. M2-DB will do a sort with no problem when run from WordStar 4.0's main menu with Xtrakey 2.6 resident on a 63K Kaypro. As a precaution you may wish to make a backup copy of your datafile on a separate diskette before doing a sort. The sort routine automatically creates a backup file from the original file. You will find it as "BACKUP.DTA" on the disk. ** CAUTION NO. 2 ** Before you do a sort, decide where the new sorted file will go. Since M2-DB writes a new file during the sort operation, you must have disk space enough for the second file. For that reason, the sort routine asks you which drive to put the new file on. One further note: trying to sort an empty file (0 records) -- yes, someone has tried it -- will cause a run-time error. H. C>onfiguration The C>fg command lets you set printing defaults for labels and envelopes. When you open a new file, the configuration program runs automatically. You may change the configuration anytime by pressing 'C' at the main menu. You will see a one line menu of various print modes which you can combine (e.g., proportional and near letter quality) to the extent your printer allows. When you've made your selection, press 'Q' to quit. Your selection is saved in a bit pattern in the data file. C>fg also asks if you want a default return address which will automatically print on envelopes. This is also stored as a special part of the data file. It can be changed anytime you wish. I. Miscellaneous M2-DB recognizes the drive/user areas available in CP/M. Of course, by using unique file names you can have multiple data files in any one user area. If you have difficulties with M2-DB, please advise the author of the bugs. If you have ideas to improve it, do likewise. I may or may not do anything with the suggestions, but I'd like to hear from those who are using it....along with your ten bucks, of course. I have incorporated some users' suggestions into revisions of the code. Appendix To install M2-DB on computers other than Kaypro (and other ADM-3A type displays) use a disk editor or debugging tool (DDT or SuperZap, for example) to patch the following locations: 0368 Screen width (usually 50H) [address corrected from earlier version of documentation] 0369 Screen height (usually 18H) 038A Cursor positioning sequence. First byte is the length of the string. (1BH 2DH [Esc=] for ADM-3A) 039A Row or Column first? 00 for column, 01 for row 039C Row offset (20H for ADM-3A) 039D Column offset (20H for ADM-3A) 03A2 Command to clear screen. First byte is length of the string. (1AH for ADM-3A) 03AE Insert line string. First byte is length. 03B8 Delete line string. First byte is length. 03C0 Clear to end of line string. First byte is length. You may also use the following patch file (M2PAT.ASM) written by Jim Lill who sent it to me via GEnie. It will provide terminal installation for any programs written under Turbo Modula-2 including M2-DB. ; TM2PAT.ASM Turbo Modula-2 Terminal Attribute Patcher ; ; rev 1.0 -Jim Lill 3 Jan 89 Vector Board RCP/M 716-544-1863 ; ; This file will overlay any TM2 compiled code to work with your terminal. ; It was inspired by Joe Mortensen's M2-db104 Database program which was ; supplied with a .COM file and a list of patches. He suggested the use ; of DDT. I find this technique less tedious. I examined other TM2 .COM ; files and found that he had made an error on the first address. I also ; have added a patch to the terminal name for completeness. ; ; No guarantee that all the stuff is here for all terminals but it certainly ; fills the gap left but there being no GINST for TM2 like there was for TP3. ; ; Usage: 1- edit for your terminal ; 2- assemble, ASM M2PAT ; 3- overlay file, MLOAD db110.COM,M2PAT ; ; org 0353h ;make the patch complete with new name! db 'Apple CP/M ';your terminal name ; 123456789012345<---- fifteen chars max to be safe org 0368h db 80 ;Screen width db 24 ;screen height org 038Ah ;Cursor positioning sequence. db 4 ;First byte is the length of the string. db 1Bh db 3Dh org 039Ah ;Row or Column first? db 1 ;0 for column, 1 for row org 039Ch db 20h ;Row offset db 20h ;Column Offset org 03A2h ;Command to clear screen. db 2 ;First byte is length of the string. db 1Bh,2Ah org 03AEh ;Insert line string. db 0 ;First byte is length. org 03B8h ;Delete line string. db 0 ;First byte is length. org 03C0h ;Clear to end of line string. db 2 ;First byte is length. db 1Bh,54h end This documentation written September 19, 1988. Revised 02/18/89