================================= TeleReg V1.00 -- On-line database Documentation - June 26, 1992 - ================================= Copyright (c) 1992 by Sam Yee. All rights reserved. ====================================================================== COPYRIGHT ========= The program, TeleReg and its documentation are written and copyrighted by Sam Yee. The UNREGISTERED version of TeleReg may be distributed freely providing the following restrictions are satisfied: o Distributors may not charge more than the cost of a diskette used in the distribution of this program. o Distributors may only distribute the unmodified copy of the original program, along with its documentation, and copyright notices intact. o Commercial distribution is only possible with written permission from the author. The REGISTERED versions of TeleReg may not be redistributed. Redistribution is illegal, immoral, and strictly prohibited. ====================================================================== DISCLAIMER ========== This program and its documentation are provided "as is". No warranties are made with respect to the accuracy, reliability, performance or operation of this software and information. You are using this program at your own risk. The author is not liable for any damages that may have been caused by using this software. ====================================================================== INTRODUCTION ============ TeleReg is an on-line database, quite similiar to many commercial databases, except it offers data sharing between multiple users of bulletin board system (BBS). It could be used as a database to store user registries, ie. to store information about the users of a system. It could also be used to store information about other BBSes. The possibilities are limitless. TeleReg can also be run without a BBS. TeleReg allows simultaneous accesses to the database by many users. The registered version of TeleReg also allows many databases to be on-line at the same time. For example, you can have databases of catalogs, users, BBSes, cooking recipes, etc. On-line help is provided on each command. Information on each field in a record is also provided from the menu. By default, the database is configured as a user registry. Users are able to quickly look up other users' records, display the names of all records in the database, and search any field of the records of the other users. All documentation in this file is directed to the system operator, not other users of TeleReg. Users of TeleReg should read the on-line help on how to use each command on the TeleReg menu. ====================================================================== LIMITS ====== - The unregistered version of TeleReg can handle atmost 200 records in one database, while the registered version can handle unlimited records in unlimited databases (provided you have the storage space). To register, fill in the DOOR:ASI/doc/TeleReg.registration form and send it to me by mail (not electronic!). - Field names have a limit of 79 characters. - Field length of each record has a limit of 65535 characters. - Record names are limited to 35 characters. ====================================================================== REQUIREMENTS ============ This program runs on any Amiga(tm) with version 2.04 of the OS. A system with 512K would suffice for single user accesses. The harddrive space required to hold the records are dependent on the size of each record you defined and the number of records. ====================================================================== INSTALLATION ============ You must put TeleReg and it's accompanying files into the assigned directory called DOOR:ASI. DOOR: is the proposed device for doors (or BBS utilities) by many system operators and door programmers. ASI is a directory where you should put the BBS utilities written by me. You must also create several directories within DOOR:ASI. The directories are: DOOR:ASI/bin/ -- Where all executable files go. DOOR:ASI/config/ -- Where all configuration files go. DOOR:ASI/data/ -- Where all the data files go. DOOR:ASI/doc/ -- Where all the documents go. DOOR:ASI/help/ -- Where all the help files go. DOOR:ASI/key/ -- Where all the key files go. DOOR:ASI/text/ -- Where all other text files go. The files pertaining to TeleReg are as follows: DOOR:ASI/bin/TeleReg -- The database client program each user calls. DOOR:ASI/bin/TeleRegEditor -- Edit the fields of each record. DOOR:ASI/bin/TeleRegKillServer -- Aborts started servers. DOOR:ASI/bin/TeleRegRebuildBase -- Rebuilds the database to eliminate wasted space. DOOR:ASI/bin/TeleRegServer -- This is the database server program. DOOR:ASI/bin/TeleRegShowRecord -- View a record without running DOOR:ASI/bin/TeleReg. DOOR:ASI/config/TeleRegX.FIELDS -- All the fields to a record. DOOR:ASI/data/TeleRegX.RECORDS -- All the records to the database. This file is auto-generated by the database server. Note that when a record is deleted the space taken up by this record is not freed, but instead it will be marked as invalid (empty), and will be used by any new records. The purpose of this feature is to improve performance because this file would not have to be rebuilt when a record is deleted. DOOR:ASI/data/TeleRegX.NAMES --Record name indices for record lookups. This file is auto-generated by the database server as well. DOOR:ASI/help/TeleReg/X/ -- Help files for on-line help. DOOR:ASI/key/TeleReg.key -- The key for a registered version of TeleReg. * X - denotes the database number. The first thing you must do to get the database running is to install the server, by executing DOOR:ASI/bin/TeleRegServer (see next section). To actually use the database, execute DOOR:ASI/bin/TeleReg. ====================================================================== USAGE ===== TeleReg ------- Usage: TeleReg ... important keys: SERVER Database server number. The default is 0. If you want to run several databases, run several copies of TeleRegServer with different numbers. Note that this is only possible with the registered version of TeleReg. NAME Record's name. If you want to use this as a user name, then it should be in thef form of "First Last", or First_Last. The name must be 35 characters in length or less, or else truncation takes effect. All "_" characters will be translated to spaces, and the first letter of each word is capitalized. DISPLAY This determines whether to display ANSI color or not. The possible values are MONO or COLOR. The Default is COLOR. COLS The number of columns supported by the user's terminal. The default is 80. ROWS The number of rows supported by the user's terminal. The default is 24. HEADER The header to be displayed on the TeleReg menu, and at the prompt. The default is "User Registry". If you are using TeleReg as a BBS listings database, a HEADER like "BBS Listings" would be effective. SEARCH Search ([S]) feature on? YES (default) or NO. This option is here because searching is an expensive feature especially when a database is large (eg. 1000's of records). For small systems (eg. 1 or 2 lines), this feature should be on, but on big systems (eg. 5, 6 or more lines) the system performance can degrade drastically if a user is searching 1000's of records. A general rule is to set search on, and if a user, who is not the one doing searches, feels significant slow down of system performance, then this feature should be turned off. READONLY Make this database read only, so that users cannot add records to it. NEWNAME Allow the record name to be changed at the menu. After the record name has been changed and the name is already in the database, it would load the record in. If the record name is new, it would prompt you if you want to clear the working record. Example: TeleReg NAME "Joe Sixpack" DISPLAY COLOR SERVER 0 TeleRegServer ------------- Usage: TeleRegServer [SERVER_NUM] Start the database server so clients could access the database. Note that you need not "run" this command, as it detaches from the Shell. If you are running multiple databases use a different SERVER_NUM for each. Example: TeleRegServer 0 TeleRegKillServer ----------------- Usage: TeleRegKillServer ... Stop any database servers that have been started. Example: TeleRegKillServer 0 1 2 3 4 TeleRegEditor ------------- Usage: TeleRegEditor [COLOR|MONO] [FIELD_DATA_FILE] The first keyword is optional. COLOR (by default) or MONO determines if your terminal supports ANSI color. [FIELD_DATA_FILE] is the file name for the fields data file, eg. DOOR:ASI/config/TeleReg0.FIELDS. Example: TeleRegEditor COLOR DOOR:ASI/config/TeleReg0.FIELDS TeleRegShowRecord ----------------- Usage: TeleRegShowRecord SERVER DISPLAY NAME .. This command simply displays records from a particular database. Example: ShowReg SERVER 0 DISPLAY COLOR NAME John#? Bob#? - If server 0 handles the user registries, this will display all records with first name John and Bob. TeleRegRebuildBase ------------------ Usage: TeleRegRebuildBase In the event that your database had a lot of records deleted, but no new records to use the space previously allocated by these deleted records, and that you want to reclaim the storage space for something else, use this command to rebuild the database with all the useless space freed. determines which database you want to rebuild. denotes the filename of the newly created record name indices file. is the name of the file to store the newly created records file, with all the useless dead records removed. Example: TeleRegRebuildBase 0 RAM:rebuilt.names RAM:rebuilt.records COPY RAM:rebuilt.names TO DOOR:ASI/data/TeleReg0.NAMES COPY RAM:rebuilt.records TO DOOR:ASI/data/TeleReg0.RECORDS DELETE RAM:rebuit.#? ====================================================================== TELEREG EDITOR ============== Execute DOOR:ASI/bin/TeleRegEditor to edit any of the fields in a record. Supply the field definition file as an argument. An example of such a file is DOOR:ASI/config/TeleReg0.FIELDS. WARNING: Whenever you alter the record definitions, other than the name of a field, all other database files must be deleted. For example, if you added an extra field to the record definition, you must delete DOOR:ASI/data/TeleRegX.NAMES and DOOR:ASI/data/TeleRegX.RECORDS. The same applies if you changed the field length of a field or deleted a field. Note that this is not a bug because when you alter the fields the original database becomes inconsistent with your new record definition. If you have made changes to the record definition, please document it in DOOR:ASI/text/TeleRegX.FieldsInfo.txt, so the users get updated information on the fields. The entries in the menu are as follows: [L] - List fields ----------------- This will list all the fields in the record. The field number, field name, and field length will be displayed. [A] - Add field --------------- Add a new field to the end of the record. First you are prompted with the field name, and then the field length. Note that the field length you give includes the null character. So if you enter 80, the first 79 characters are used to store a value for the field, while the last one is used to null-terminate the field. To abort adding fields simply press return on a blank line. [E] - Edit field ---------------- Edit any attribute of a field. First you are asked to change to field name. Next you will be asked for the new field length. Press return on any prompt to use the default. [D] - Delete field To delete any field of the record definition. You will be asked for the field number to delete. Enter "*" to delete all the fields. [M] - Move field ---------------- Move a field from one location to another. First you will be prompted for the field number to move from, and then the field number to move infront of. [C] - Change summary -------------------- This command changes the field number of the summary field. The summary is the field that is displayed when a database record names list is generated (with the [L] command from the TeleReg). If you enter 0, no summaries will be displayed with the [L] command. [Q] - Quit ---------- Exit back to where you came from. ====================================================================== CONFIGURING DATABASES ===================== For most of this section, it is only applicable for those who registered for TeleReg. For big systems, one database may not be enough. You might want databases for different things. For example, a database for hockey card collectors, so that users can trade or buy. You might want a database for products you might sell, commonly known as a shopping database. How about a database for a dating service? You teenagers will like this one. :-) Again, the possibilities are limitless. The first thing you should do is configure the fields. Think it over thoroughly before designing the fields. A poor initial design decision is fatal because it can (and will, "Murphy's Law") cause all your records to be useless. You might want to reserve certain fields by giving them the name "Reserved #1", "Reserved #2", etc. If this database is editable by the users, make sure you tell them not to enter anything in reserved fields. As explained above, to edit the fields you execute TeleRegEditor. Next, you would start the server by supplying a server number. Read the USAGE section for server installation. When you created a new database you should document the record fileds in the text file in DOOR:ASI/text/TeleRegX.FieldsInfo.txt, where X is the database number. You should also document the commands by editing DOOR:ASI/help/TeleReg/X/. You should use the format in DOOR:ASI/help/TeleReg/0/. Suggestions for TeleReg arguments --------------------------------- 1. User editable databases should have TeleReg called with "NAME , "READONLY NO" and "NEWNAME NO". 2. User read only databases should be called with "READONLY YES" and "NEWNAME NO". 3. The databases that are editable only by the SYSOP should be called with "READONLY NO" and "NEWNAME YES". ====================================================================== UPDATES ======= Registered users are privileged to free updates (excluding magnetic media cost and postal charges), when they are ready, for ONE year, from the day of purchase. Bugs will be fixed, but I make no promise that new features will be added. After a year, updates will require a minimal fee. Note that since I'm still a student, I don't always have free time (especially during semesters) to update the software. ====================================================================== ACKNOWLEDGMENT ============== Greg Bastow -- For providing an excellent BBS for the Amiga Community. Tunnel Vision BBS (4 lines 604-535-9784/9785/9826/9846, 1.2Gigs, Fish!). David Riley -- Preliminary testing, and documentation editing. Dana Huggard -- For letting me beta-test my software on his BBS. and for helping me distribute my utilities. Terra Firma BBS (604-434-3665 1:153/765) ====================================================================== PRODUCTS RELEASED AND UNDER DEVELOPMENT ======================================= Released: - ECopy V1.00 (Hard/floppy drive utility) - TeleWho V1.00 (DLG(tm) BBS utility) - TelePage V1.00 (DLG(tm) BBS utility) - RawIN.lib V1.00 (Input handling library for BBS door programmers) - Multi-Talk V0.911 (Multi-user teleconference system) - TeleReg V1.00 (User registry database allowing concurrent users) Under Development: - TeleBank (DLG(tm) BBS utility, a time/credit accounting system) - an outdialer (BBS utility for dialing out from a multi-line system) - GooeyTerm (Graphics terminal program) - .snd/8SVX-IFF sound player (joint effort with Jeremy McDonald) - numerous other minor utilities Most of these programs are public domain, while the rest are shareware. ====================================================================== TRADEMARKS ========== Amiga, and AmigaDOS are trademarks of Commodore-Amiga. DLG is a trademark of TelePro Technologies. ====================================================================== LAST WORDS ========== I'm available for custom programming for the Amiga. If you need something programmed for your business, drop me a line. Thank you for using this program! Questions, ideas, comments, bug reports, etc. should go to: Home Address: Sam Yee 4595 Nanaimo St. Vancouver, B.C. Canada V5N-5J5 Internet: samy@sfu.ca (starting September '92) flui@sfu.ca (before September '92) FidoNet: 1:153/765 (Terra Firma BBS 604-434-3665)