













                                        

                 ***********************************************
                 *                                             *
                 *   A D D R E S S  B O O K  D A T A B A S E   *
                 *                                             *
                 *               Version 1.80                   *
                 *                                             *
                 ***********************************************



             Relocatable Module freeform database for the Archimedes



                     Copyright David Holden 1989,90,91,92,93

                                        

                                _______
                           ____|__     |               (R)
                        --|       |    |-------------------
                          |   ____|__  |  Association of
                          |  |       |_|  Shareware
                          |__|   o   |    Professionals
                        -----|   |   |---------------------
                             |___|___|    MEMBER







                              CONTENTS                      Page


                        Preliminaries

                              Licence to Use        ........  1
                              How to Register       ........  1
                              Licence to Copy       ........  2
                              A.S.P. message        ........  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 6 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.



                Association of Shareware Professionals:

          This program is produced by a member of the Association of 
          Shareware Professionals (ASP). ASP wants to make sure that the 
          Shareware principle works for you. If you are unable to resolve a 
          shareware related problem with an ASP member by contacting the 
          member directly, ASP may be able to help. The ASP Ombudsman can 
          help you resolve a dispute or problem with an ASP member, but 
          does not provide technical support for members' products. Please 
          write to the ASP Ombudsman at 545 Grover Road, Muskegon, MI 
          49442-9427, U.S.A. or send a CompuServe message via CompuServe 
          Mail to ASP Ombudsman 70007,3536 or FAX 616-788-2765. 



                                                                   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 6 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?
