ARM Club 1

home *** CD-ROM | disk | FTP | other *** search

/ ARM Club 1 / ARM_CLUB_CD.iso / contents / apps / databases / progs / addr_book / !Addr_Book / Manual < prev next >

Wrap

Text File | 1993-03-31 | 31.5 KB | 761 lines

*********************************************** * * * A D D R E S S B O O K D A T A B A S E * * * * Version 1.7 * * * *********************************************** Relocatable Module freeform database for the Archimedes Copyright David Holden 1989,90,91,92,93 CONTENTS Page Preliminaries Licence to Use ........ 1 How to Register ........ 1 Licence to Copy ........ 2 Using Address Book General Description ........ 3 Loading the Module ........ 4 The 'Ab_Reg' file ......... 4 The Commands Name ........ 5 Address ........ 5 Phone ........ 5 Data ........ 5 Paddress ........ 6 Next ........ 6 Prev ........ 6 More ........ 6 Sort ........ 7 Unsort ........ 7 Adrload ........ 7 Adrsave ........ 7 Cname ........ 7 Caddress ........ 7 The 'Hot Key' Method of Operation ........ 8 How to use it ........ 8 Speed ........ 8 The File Format General ........ 9 The Name ........ 9 The Address ........ 9 Phone Numbers ........ 9 Data ........ 10 End of Record ........ 10 File Rules Summary ........ 10 Number of Records ........ 11 Simple Label Printer ........ 11 Making Text Files ........ 12 Phone Number List ........ 12 Page 1 --->> LICENCE TO USE <<--- This program is subject to copyright. It is distributed as SHAREWARE and is NOT Public Domain. This means that the Author retains full copyright and expects a reward for his efforts. You are Licensed to use this program for evaluation and testing ONLY for a maximum period of THIRTY DAYS. At the end of this time you must either stop using it or REGISTER. Registration costs just Eight Pounds and entitles you to free upgrades to any subsequent versions. I am always willing to listen to problems or comments, even if you have not registered. If you write please enclose an SAE. If you phone I am normally available on weekday evenings. If you require a customised version with special fields please contact me. So far as I know the Module is error free but it is a primary rule of computer programming that 'there is always just one more bug'. Please tell me if you find it. If you don't tell me I can't fix it! --->> HOW TO REGISTER <<--- To make things easier I have made the last page of this Manual a registration form. Please fill it in and send it to me with your cheque for £8 at the address below. I will send you a copy of the latest version of the program and your personal Ab_Reg file which will disable the start-up message. The normal licence is for a single user on a single computer. If you are using more than one computer please contact me to ask about a site licence. I will often grant this without further fee. Use of this program in any EDUCATIONAL ESTABLISHMENT or for any EDUCATIONAL or TRAINING purposes without the express permission of the Author is STRICTLY FORBIDDEN. In the case of State Supported (ie. non fee paying) schools or colleges this will normally be granted without further charge. David Holden 39 Knighton Park Road Sydenham London SE26 5RN 081 778 2659 Page 2 --->> LICENCE TO COPY <<--- You may only distribute copies of this program strictly subject to the following conditions. 1. Any private individual may GIVE copies of this program to his/her friends subject only to the conditions in items 4 and 5 provided that no charge is made for the program or its transfer. 2. If you charge ANY fee for distributing this program, whether in cash or in kind, or if you run a BBS or other service from which Address Book is available you MUST ask for permission before distributing Address Book. Permission will not unreasonably be withheld from reputable distributors but I will treat as Breach of Copyright any person or organisation who distributes Address Book without this permission. 3. You may not charge a fee or fee in kind for the program or any additional material that you supply but you may charge a reasonable fee for media, postage and distribution costs. 4. You must copy the program complete with the !Run, !Boot, !Sprites and Manual (this) file and at least one example file. You may not make any alteration to the program or documentation although you may alter the !Run file to load an alternative example file or to suit the organisation of your distribution discs. 5. You must not under any circumstances distribute ANY version of the program which does not display the 'Start Up' message. You must ensure that you do not copy the Ab_Reg file. This is for the personal use of Registered users ONLY. Page 3 --->> USING ADDRESS BOOK <<--- General Description: Address Book is a Relocatable Module, and so remains resident in the machine without affecting other programs, even those that don't multi task. It is a development of a 'Sideways RAM' program that I wrote for my own use on a Model 'B' and I have been using it in both incarnations for several years. All it's functions are operated by '*' commands so it can be accessed from the desktop or from within any competently written application, eg. Twin, from BASIC or even when using a program like Interword or Wordwise under the 6502 emulator. You can even insert Embedded Commands into the text with Interword or Wordwise for mail merging, etc. Because it is '*' command driven you can write very simple Basic programs which can be used to print labels, lists of phone numbers and so on. You are not limited to the facilities of 'normal' databases in this respect but anyone with an elementary knowledge if programming can easily write programs to produce lists as required. Version 1.6 upward also have a 'Hot Key' system which enables you to insert a name and address into your text when using most wordprocessors. This feature has been introduced for the first time in this version and is not guaranteed 'bug free'. It will be improved and expanded in future versions and your suggestions and reports of any errors are requested. Unlike most 'card index' databases the program does not use a fixed format for it's data but instead the data is text file prepared on any wordprocessor which can save text in ASCII format. Edit is ideal for this, but all W.P.'s have a way of saving a file as pure ASCII text. This means that there are no 'fields', no Surname, First Name, etc. but just a few 'markers' and a couple of simple rules. As well as name, address and phone number(s) each entry can also have 'data' associated with it. This is just some text which can be any notes, etc. you wish to keep about the person. These notes are not limited in length or format. You could have 50 pages of text with an entry if you wished. As a self-employed contractor I find this invaluable. If someone phones me when I am in the middle of doing something one '*' command can display all the notes I have so that I can answer any queries instantly without upsetting what I am doing. Page 4 Loading the Module: To load the module the command is *RMLOAD ADDR_BOOK <filename> where <filename> is the full path and filename of the address file. In fact you should not normally use it in this way but simply 'double-click' on the !Addr_Book application icon. The !Run file on this disk will load the module by issuing this command with the name of the sample file 'ADDR_FILE'. You can either rename this file and substitute your own with the old name or edit the !Run file to contain the name of your own file. In this instance the file is in the application directory as this enables its path to be defined by the 'Obey$Dir' variable. This is not necessary. You can edit the !Run file to load any valid file. If you don't include <filename> or the module can't find the file it will be loaded and initialised correctly but it will not be able to respond to commands because it will have no data to respond with! The same problem can arise if the module is loaded correctly but is unable to claim it's workspace because there is not enough room in the RMA. This will normally only happen if you try to load the Module from the BASIC '>' prompt. If this happens you should *QUIT if you are in BASIC or return to the desktop and increase the RMA area. You can then either *RMKILL ADDRESSBOOK and try again or use *ADRLOAD <filename> if the Module loaded but couldn't claim workspace. A similar difficulty can be experienced if you load the Module with a short file and then later use *ADRLOAD to try to load a longer file. If you for any reason a file is not loaded initially you can still use '*ADRLOAD' to load a file subsequently. The 'Ab_Reg' file: This is special file encoded with the name of the registered user. If it is present in the application directory then the start-up message will be bypassed when you load the module. This file is for the personal use of Registered users ONLY. If you pass on copies of Address Book to your friends make sure that you do NOT give away copies of this file. The Ab_Reg file will work with any version of Address Book after 1.7 so if you get a later version from a BBS or PD Library you can simply copy your Ab_Reg file into the !Addr_Book directory to disable the message. You can therefore get updates from any source. NOTE - Address Book searches for the Ab_Reg file as <Obey$Dir>.Ab_Reg so if you are not loading the module from the application directory as supplied you must ensure that Ab_Reg is present in the <Obey$Dir> path or you will get the start-up message and delay. Page 5 --->> THE COMMANDS <<--- This section describes all the commands which control the Module. The command is shown with a short description of its effects and uses. Commands can be issued from the desktop by pressing F12 or from BASIC or any other language or application which offers a Command Line Interface. Because Address Book works in this way it is very easy to write a simple program in BASIC or any other language to print labels, print out an alphabetical list of telephone numbers etc. Some examples of the way in which this can be done are shown later. Note: In the following descriptions a parameter enclosed by < > means it is compulsory, enclosed by [ ] means it is optional. All commands and parameters are case insensitive and can be abbreviated, eg. '*ADDRESS SMITH' is the same as '*addr. Smit'. When a command is abbreviated you should terminate it with a full stop. In this case there need not be a space between the command and any following parameter. *NAME [name] This just displays the full name of the person followed by a space. Not a lot of use on it's own but it is useful for mail-merging when used with *NEXT or in it's other incarnation *CNAME. Used without [name] *NAME will display all the names in the file. *ADDRESS [name] Displays the name and address of the person. Used without [name] it displays all the names and addresses. *PHONE [name] Displays the name and phone number(s) of the person. Without [name] it displays all the names which have a phone number and their number(s). *DATA [name] Displays name, address, phone number(s) and any text added to the entry. Again, without [name] it displays all the entries. Page 6 *PADDRESS <name> (Print Address) This displays the name and address exactly as *ADDRESS but also sends the output to the printer. It was added to make it easy to address an envelope without using CTRL-B and CTRL-C and getting the BASIC '>' or OS '*' prompt printed. *NEXT This displays the next entry in the file in the last used format. eg. if the last command was *ADDRESS <name> then *NEXT will print the name and address of the next person in the file. When you reach the end of the file it will 'wrap around' to the beginning. It can be used to step through the file or as an embedded command for mail merging or label printing with a simple BASIC program. *PREV This is the same as *NEXT but it displays the previous entry and so steps backwards through the file. When it reaches the start of the file it will 'wrap around' to the last entry. *FIND <string> This will search through all parts of all the records for <string>, which can be any text string. Each time it finds a record which contains <string> it will display the 'name'. For example to find everyone who lives in Chertsey you could use '*FIND Chertsey' or to find everyone who has a Fax machine you could use '*FIND #f'. You can then use the other commands to display more data on the names. An alternative is *ADRFIND to avoid conflict with Toolkit modules which may contain a 'FIND" command to find a text string or sequence of bytes somewhere in the computers memory. *MORE This will search for the next match after a name, address, phone, etc. command. You can use it if your original command was not precise enough to give you exactly what you wanted. For example, if you wanted John Smith's phone number you could use '*PHONE SMI,J'. This would be O.K. unless you had a 'James Smith' as well. In this case '*MORE' would get the next match which should be 'John Smith', unless of course you also had a 'Joan Smith', in which case you can just enter '*MORE' again. Page 7 *SORT Sorts the entries into alphabetical order at the 'index point',(see below in section on file format). This is always done when a file is loaded so that the 'natural' state for a file is already sorted. This command may also be entered as *ADRSORT to avoid conflict with Toolkit Modules which may have a Sort utility. *UNSORT Sounds fairly useless. How do you unsort a file and why would you want to? This command doesn't 'randomise' the entries but actually restores the file to the order the entries were in when it was loaded. It is used for label printing, etc. where you may wish to print, for example, the first 20 addresses in the file which may not be the first 20 alphabetically. *ADRLOAD <filename> This loads and sets up a new address file without loading a new Module. It will replace the current file. It is possible for it to generate an 'Unable to claim workspace' error if the new file is longer than the original. *ADRSAVE <filename> This will save the current file to disc as an ASCII text file <filename> with markers ready for reloading into Address Book or a W.P. for editing. This command will enable a sorted version of the original file to be created. Note that the end of line character will be the same as was used in the original, eg either CR or LF (ASCII 13 or 10) so that you can load it back into the same editor you used when you created the original file. *CNAME (Current Name) Displays the name of the last selected person. This has no use from the command line but is used in mail merging where it can be used as an embedded command in the text to print the name of the person. *CADDRESS (Current Address) Works as *CNAME but displays the name and address. Page 8 --->> THE 'HOT KEY' <<--- Method of operation: The aim of this feature is to enable you to insert the name and address of a person into the text as you type a letter. At present it is limited to name and address only although I will probably add a feature to insert the name only at a later date. It works by constantly checking for the ALT-SHIFT-INSERT combination and when it is found the complete name and address of the last accessed person is inserted into the keyboard buffer. This means that if you are using the desktop the characters will appear in whichever 'Window' has the 'Input Focus' just as if you had typed it in. By using this method the 'Hot Key' will work with almost anything that accepts keyboard input. How to use it: Place the cursor at the position you wish the name and address to appear. This would normally be at the left hand side at the top of the page if you are writing a letter and want to type the addressee's name and address. Now press F12 to get the CLI prompt and type 'ADDRESS <name>' where <name> is the person you are writing to. The name and address will be displayed and this enables you to check that it is the correct person, essential if you have abbreviated the name. If it's the wrong person you can either try again or use 'PREV' or 'NEXT'. When you have the correct person press RETURN on its own to get back to the desktop. Now hold down the ALT and SHIFT keys and press INSERT. The name and address should appear in your wordprocessor just as if you had typed them. Because Address Book is a Relocatable Module and not a desktop task all the '*' commands and the 'Hot Key' operate outside the Desktop environment. They even work with the 6502 Emulators so you can use the 'Hot Key' from within Interword or other BBC wordprocessors. Speed: I have restricted the speed at which characters are inserted into the keyboard buffer to to about 16 per second. This was found necessary because if this speed is exceeded then some programs, notably Pipedream, are unable to cope. The symptoms of this are lost characters or, in the case of Pipedream, an entire line of the address may disappear. Edit, for example, loses every fortieth character if the speed is too fast. First Word Plus appears to have properly buffered input and will accept the characters at any speed. This is of little consequence in practice as it only takes a few seconds for the complete address to appear, however I may make this delay variable in a later version. Page 9 --->> THE FILE FORMAT <<--- General: This should be a text file without any formatting commands except as mentioned below in the 'data' section. It doesn't matter whether your W.P. uses an ASCII '10' or '13' for an end of line character, either will be accepted. You cannot use a LF/CR or CR/LF combination but this is not normal on the Archimedes so the problem should not arise. If you load the demonstration file 'ADDR_FILE' into Edit you will be able to see exactly how it is made up. The Name: The first line is the 'name'. This should not have any leading spaces, if it does they will be stripped, but the following 'Address' lines can have leading spaces to 'slope' them if you wish. If you do not wish the entry to be sorted and matched by the start of this line then insert a '*' character at the point at which you do wish it to be matched; eg. John *Smith This will be sorted as 'SmithJohn' and can be found by *NAME Smith. If you wish to distinguish John Smith from Fred Smith then you can use a comma in the command line to make the program return to the start of the line to continue matching, eg. *NAME SMI,J will find John Smith and reject Fred Smith. You should not put a space immediately after the '*' or it will be removed. If you wish the name to be printed as 'John Smith' the entry should be 'John *Smith' and not 'John* Smith' The Address: These are the lines following the name up to a '#', '$' or the end of the entry. If you don't have an address then just leave them out. The only compulsory line is the first line, all others are optional. Phone Numbers: These follow the address. Each number should be on a new line and preceded by a '#'. If you immediately follow the '#' by a lower case 'h' the program will display 'Home' before the number, if you use 'w' it will display 'Work' and if you use 'f' it will display 'Fax'. Page 10 Data: This is any text after the phone numbers and preceded by a '$' marker. It can be any length and is printed out using the OS 'Pretty Print' routine. This means that it will be 'wordwrapped' (ie. words will not be split at the end of a line) and embedded Tabs (ascii 9) can be used. The fact that this is not a 'field' in the way that this word is used with a conventional database means that the text can be as long as you like. Because Address Book uses a text file as its data input you can import letters, estimates, reminders of things you want to say the next time the person phones etc. into this section if you wish. If you do this you must ensure that the imported text does not include two blank lines anywhere (see below). You could also use the OS dictionary in this section to compress the text if you wish. (See the P.R.M. for details of how to do this.) End of Record: This is defined as THREE cr's in succession, ie. TWO blank lines. You can have more than two blank lines if you wish and the extra lines will just be added to the end of the 'data' text. Note that if you are using a file spooled from 'Interword' as your address file this puts a space before each cr but this doesn't matter as all spaces immediately before cr's are removed by the program. File Rules Summary: From the foregoing you can see that there are only a few simple rules which you must obey. 1. You can't use '$' anywhere in the name, address or phone numbers but you CAN use it in the 'Data' section after the first '$' identifier 2. You can't use '#' anywhere but as a marker for a phone number 3. You can't put two blank lines anywhere in a record, but you can use a single blank line to separate paragraphs in the text or between address and phone numbers and/or phone numbers and text Page 11 Number of Records: In theory the maximum number of records is limited only by the available memory. In practice the Module contains a 'look-up' table which uses four bytes for each entry. As 2K has been allocated for this table in the program as supplied the maximum number of records supported is 512. If this number is exceeded an error message will be displayed and although the module will operate properly only the first 512 records will be accessible. This will probably be sufficient for the vast majority of users but the program can easily be modified to accept more records if required. A program has been included to do this for you. First make a backup copy of the disc and work on the copy in case something goes wrong. If you are using the desktop open the application directory (hold down SHIFT and double-click on the application icon). Now double-click on the file 'SIZE', enter the number of records required when asked and the module IN THAT APPLICATION DIRECTORY will be changed to accept the required number of records. If you are not using the desktop you should *MOUNT the disk, enter *DIR !Addr_Book and then CHAIN "ChangeSize". Simple Label Printer: This is a short BASIC program to show you how easy it is to use Address Book to print labels. The program will probably need to be changed to suit your printer and the size of the labels you are using and should be regarded as an example only. The label size used is on 2 inch centres one label wide. If you are using more than one label wide you will need to do a reverse Form Feed and increase the left margin when moving to the next horizontal label. 10 REM Name and address of 1st person 20 *ADDRESS A. 30 REM Step back to last name ready for 1st 40 *PREV 50 VDU 2 :REM Turn on printer 60 VDU 1,27,1,67,1,0,1,2 :REM Set page length to 2 inches 70 VDU 1,27,1,108,1,4 :REM Left Margin of 4 80 VDU 1,27,1,120,1,1 :REM Select N.L.Q. 90 FOR I%=1 TO 20 :REM Print first 20 addresses 100 REM Print the name and address 110 *NEXT 120 VDU 1,12 :REM Form feed to top of next label 130 NEXT 140 VDU 1,27,1,64 :REM Reset the printer 150 VDU 3 :REM Turn off the printer Page 12 Making Text files of your data: There is no 'built in' means for doing this at present but I intend to introduce it in a later version. However it is possible to do so without special commands as it can be done by the Archimedes O.S. Press F12 and type 'SPOOL <filename> <RETURN>'. Don't use the same name as your original file or add a directory prefix. The disc drive will start up to 'open' the file. Now type 'DATA <RETURN>' (or PHONE for a list of phone numbers, etc.) The whole file in whatever format you requested will be shown on the screen and also sent to the disc. When this is finished and the drive has stopped type 'SPOOL <RETURN>' to close the file. If you load this file into Edit you will find you need to make two changes before you can do anything with it. First you must delete the first line which will be your 'DATA' (or whatever) command. Secondly each line will have a NL (ASCII 10) and a CR (ASCII 13). You need to delete one of these. The easiest way to do this is first position the cursor at the start of the text. Now press F4 for the 'Search and Replace' menu. Enter '\cM' (equivalent to CTRL-M which is ASCII 13) in the Search widow and nothing in the Replace window. Click on the 'Magic characters' box. Now click on the 'Go' box. When the 'Found' window opens click on 'End of file Replace'. This will wipe out all the [0d]'s at the start of the lines. If you intend to load this file into a BBC wordprocessor such as View or Wordwise you will now need to press CTRL-F8 to change the NL's into CR's before Saving it. Making a Phone Number list: If you want a printed list of telephone numbers you can use a similar technique to the previously described label printing program. Again this is only a simple example and if you wanted to make the page size suitable for inserting in your diary or Filofax etc. then you could alter the page size and use Condensed printing. 10 VDU 2 :REM Printer on 20 VDU 1,27,1,78,1,8 :REM Set bottom margin to 8 lines 30 *NEXT 40 VDU 3 :REM Printer off Address Book Version 1.7 -- Registration form Please complete this form and send it with your cheque for £8 to: David Holden, 39 Knighton Park Road, Sydenham, London SE26 5RN ______________________________________________________________________ Your Name and Address ______________________________________________________________________ Where did you obtain Address Book? ______________________________________________________________________ Have you had any problems? ______________________________________________________________________ Do you have any suggestions for improvements?