@database 000f0818-0 @master //Distrib/AB/AB.guide @$VER: Last change: 29-3-96 @author "Lawrence Manning (E-mail: manningl@ee.port.ac.uk)" @(c) "(c) 1995-96 Lawrence Manning" @remark Created with Heddley v1.1 (c) Edd Dumbill 1994 @node "Main" "Contents page" @{b}AB v1.2 by Lawrence Manning@{ub} This program is @{i}FREEWARE!@{ui} @{b}CONTENTS@{ub} @{"     Distribution    " link "distribution" 0} FREEWARE notice. @{"     Introduction    " link "introduction" 0} What this program does. @{"     Installation    " link "installation" 0} The system requirements are listed here too. @{"    Starting up AB   " link "starting" 0} Loading up through Workbench or CLI. @{"      Operation      " link "operation" 0} The main section. @{"        Menus        " link "menus" 0} Description of the menus. @{"     Configuring     " link "configure" 0} Setting up AB to suit you. @{"    AREXX support    " link "arexx_support" 0} All about AB'S ARexx port. @{"   Version History   " link "history" 0} Fascinating... @{"       Author        " link "author" 0} My beta-testers are listed here too. @{b}AB and its documentation are (c) 1995-96 Lawrence Manning@{ub} @endnode @node "distribution" "AB is FREEWARE!" @{b}Distribution and Warranty@{ub} AB is FREEWARE. There are no limitations to how it may be distributed, provided that the original archive remains intact, and none of the files are removed or modified. It can be put in public domain libraries, on Fred Fish CDS and the like, provided I am notified of this. If it is included on any magazine cover-disks, then I would also like to be informed. The archive contains the following files: AB Executable. AB.info The executable's icon. AB.guide Documentation. AB.guide.info Documentation's icon. ARexx Directory containing some example scripts. ARexx.info Above directory's icon. ARexx/simple_list.rexx Example script showing listing of project. ARexx/dial.rexx Example script showing searching and dialling. ARexx/search.rexx Example script showing searching and hide/show. ARexx/import.rexx Example script showing text file importing. Please do not powerpack (or similar) any of the files, as this can decrease compatible with any future systems. No warranty is given for use of this program. Use it at your own risk! I can not be held responsible for any loss of data, or damage to equipment. So if your hard disk crashes when you use the program, don't go moaning to me. It wasn't my fault, honest! @endnode @node "introduction" "Introduction to AB" @{b}Introduction@{ub} AB (short for Address Book) is a little utility for storing and accessing the names of addresses of people you know. It was primarily designed to be small, and easy to use. There is also no limit to the length of the individual fields. Actually, the limit is 200 characters, but this should be acceptable to everyone. You can store the following pieces of information for each person: the name, address (five lines), phone number, E-mail address, and a comment about the individual. All fields are optional, except for the person's name. After entering the details, it is possible to search for specific people, and also produce printouts of people in the database. Another handy feature is the ability to use the Amiga's audio output to tone-dail someone's phone number. The program can also be controlled via ARexx scripts. @{b}Features@{ub} * Unlimited number of entries. Memory permitting of course. * Field text length limited to 200 characters. Should be enough for everyones' needs. * Configurable printing support. * Font-sensitive GUI. * Tone-dial using Amiga's audio output. * Almost entirely controllable using ARexx scripts. Example scripts included in distribution. * Installs as a commodity. See: @{"Installation" link "installation" 0}, @{"Starting up AB" link "starting" 0} and @{"Operation" link "operation" 0} @endnode @node "installation" "Installing AB" @{b}System Requirements@{ub} The only system requirement is that your Amiga has OS 3.0 installed. It will run fine from a floppy based system, and has very small memory requirements. @{b}Installation@{ub} Simple. Make a directory on your hard disk, and drag the icons across. AB does not need any external libraries, besides those present on the standard Workbench disk. @endnode @node "starting" "Loading AB from the Workbench and CLI" @{b}Starting AB@{ub} Workbench usage AB can be started from the Workbench, either through the program icon, or through a suitably configured project icon. AB can also be @{"configured" link "configure" 0} by setting tooltypes in the program icon. If you are going to run AB via the WBStartup drawer, it is advisable to set the DONOTWAIT tooltype. CLI usage If the program is launched through a CLI, you can also automatically load an AB project by supplying its filename as an argument. eg: AB s:addresses would attempt to load s:addresses into AB on startup. @endnode @node "operation" "Program operation" @{b}Operation@{ub} Upon loading, you will be presented with the main window. This is where you can access the menus, add new people to the database, and obtain print-outs. Most of this window is used to display record details. At the bottom of the window are buttons for moving through the database (First, Prev, Next, and Last), as well as buttons for adding new people, editing the currently viewed record, and removing people from the database. To add a new person, click on the button marked New. You will be presented with another window, where you should type in the details for this new person. Any boxes can be left blank, except the name one. When you have finished, click on the Ok button at the bottom. If you decide not to add this person, click on Cancel, or just close the window. If you want to edit the currently displayed person's details, click on Edit. You will be presented with the same window as described above. Change the fields which need changing, and click on Ok. Cancel aborts any changes you have made. Once you're done adding everyones' details, you can get a printout by selecting Print from the Project menu. It is possible to configure the output that is sent to the print using the Settings menu. It is also possible to search the database, and to have your Amiga dial a persons phone number for you. AB also installs as a commodity, so it is possible to control it via the Exchange program. See: @{"Menus" link "menus" 0}, @{"Tone-dial usage" link "tonedial" 0} and @{"Configuring" link "configure" 0} @endnode @node "menus" "Description of the menus" @{b}Menus@{ub} The menus are divided into three sections: @{"   Project    " link "project_menu" 0} @{"   Edit       " link "edit_menu" 0} @{"   Settings   " link "settings_menu" 0} @endnode @node "project_menu" "Description of the Project menu" @{b}Project Menu@{ub} New (shortcut Amiga-N) This clears the current address book from memory. Open... (shortcut Amiga-O) This loads a new address book database into memory. If the database could not be loaded for some reason, then you will loose the currently viewed database. Save (shortcut Amiga-S) This saves the currently named project. If the project has no filename, then you will be asked to enter one using the standard file requester. Save As... (shortcut Amiga-A) This saves the current project under a new name. Print (shortcut Amiga-P) This prints entries from the current project. The actual format of the entries printed depends on choices made in the @{"settings" link "settings_menu" 0} menu. About... (shortcut Amiga-?) Displays some information about the program. Hide (shortcut Amiga-H) Removes AB's GUI, but does not quit the program. You can open the GUI again either by pressing the user-definable hotkey (by default it is ctrl alt a) or by using the Commodities Exchange program. Quit (shortcut Amiga-Q) I wonder what this does? @endnode @node "edit_menu" "Description of the Edit menu" @{b}Edit Menu@{ub} Search (shortcut Amiga-F) This option searches for a specific record. It will open up a new window where you can type in the search details. A cycle button selects the type of search to perform. Name, phone number and E-mail address searches are possible. The search string entered can be a partial string so you could, for example, search for people with a London phone number. Another use for this is if you can only remember the first name of a person you are searching for. If the person is found, then you will be taken to that record, else you'll hear a beep. Search Again (no shortcut) This option repeats a previously defined record search. @endnode @node "settings_menu" "Description of the Settings menu" @{b}Settings Menu@{ub} Print Headers? (no shortcut) Check this menu to print the "--- Entry x of y ---" text that appears at the top of every printed entry. Print All? (no shortcut) Check this menu item to make AB print all entries in the current project. If this is not checked, then only the current entry is printed. Save Settings (no shortcut) This option saves current window positions into the program's tooltypes. See @{"Configuring" link "configure" 0} for more information. @endnode @node "tonedial" "Tone-dial usage" @{b}Using AB's tone-dial feature@{ub} AB has a built in feature that allows the user to dial the phone number of the currently viewed person. To use it, hold the handset near the left speaker of your Amiga setup. Then press the Dial button at the bottom of AB's main window. You'll then hear the dial-tones. When the last number has been 'dialled' the call should have been made. If you have problems getting audio output to work, you may have an application running which is using the audio channels. Close that program down and try clicking on Dial again. AB does not 'hog' the audio channels like some programs; it allocates the channels only when it actually needs to dial the number. It is possible to configure AB's tone-dial feature in order to change the duration of the dial-tones, and the delay between successive tones. See: @{"Configuring" link "configure" 0} @endnode @node "configure" "Configuring AB" @{b}Configuring AB@{ub} The following tooltypes are supported by AB: MAIN_WINDOW_LEFT : Horizontal position of the main window. MAIN_WINDOW_TOP : Vertical position of the main window. EDIT_WINDOW_LEFT : Horizontal position of the edit window. EDIT_WINDOW_TOP : Vertical position of the edit window. DIAL_DURATION : The length of an individual tone-dail tone, in 50ths of a second. DIAL_DELAY : The time-gap between each tone-dial tone, in 50ths of a second. PUBLIC_SCREEN : Name of the public screen that AB should try to open on. If it can't open on this screen then it will try the default public screen. PRINT_HEADERS : YES prints entry headers, NO doesn't. PRINT_ALL : YES prints every entry, NO only prints the currently displayed one. CX_PRIORITY : Commodity priority. CX_POPKEY : The hot key which when pressed will open AB's main window. Default is ctrl alt a. CX_POPUP : If this is YES then the main window will open automatically when AB is started. NO means it will not. All settings have sensible defaults. See: @{"Tone-dail usage" link "tonedial" 0} and @{"Settings menu" link "settings_menu" 0} @endnode @node "arexx_support" "AB supports ARexx" @{b}AB supports ARexx@{ub} The ARexx port AB uses is called "AB_AREXX". This port allows you to control AB using ARexx scripts. You can do nearly all the things you would do with AB's ARexx port as you would with the GUI. The following code shows how to set up a script to give commands to AB: /* Fragment of code showing how to access AB's ARexx port. */ /* First check that AB is running. */ if ~(show(PORTS, 'AB_AREXX')) then do say 'AB is not currently running! Please start it and try again.' exit end /* Now direct commands to AB. */ address 'AB_AREXX' The code above directs ARexx to send commands to AB. For instance, the line: 'DIAL_ENTRY' would make AB tone-dial the currently displayed person. @{b}About AB's return-codes@{ub} After you call one one AB's functions you can see if it succeeded or not by looking at the RC variable. It can take one of four values, depending on the severity of the error: RC = 0 Command was executed successfully. RC = 5 Command failed to execute, but was syntactically correct. RC = 10 Command's parameter(s) was not specified, or was invalid. RC = 20 Command was not recognised by AB. Also, several commands return the ARexx variable RESULT, which contains additional information. For instance, the @{"GET_ENTRY_DETAILS" link "arexx_commands" 138} command uses the RESULT variable to tell the script the contents of a particular field in the current record. As is usual for ARexx scripts, the command 'options results' must be issued in order to receive the commands RESULT value. See: @{"ARexx commands" link "arexx_commands" 0} and @{"Example scripts" link "example_scripts" 0} @endnode @node "arexx_commands" "AB supports loads of commands!" @{b}ARexx command list@{ub} Command: QUIT [NO_CONFIRM] Function: QUIT quits AB. If NO_CONFIRM is specified, then there will be no confirmation requester if the project has changed. Results: RC is always 0. Command: HIDE Function: Removes AB's GUI from the screen. Results: RC is always 0. Command: SHOW Function: Opens AB's GUI. If the selected public screen is no longer open, then AB will appear on the default screen, which is usually Workbench. Results: RC is always 0. Command: FIRST_ENTRY, PREV_ENTRY, NEXT_ENTRY and LAST_ENTRY Function: These commands navigate about the project. Results: See @{"ARexx support" link "arexx_support" 30}. Command: DELETE_ENTRY Function: This command deletes the current entry. Results: See @{"ARexx support" link "arexx_support" 30}. Command: DIAL_ENTRY Function: This command dials the currently viewed entry, using the Amiga's audio output. Results: Command fails (RC of 5) if any of the following occur: Project is empty, current entry does not contain a phone number, audio.device fails to open, or the audio channels are stolen by another application during playing of the dial-tones. Command: DIAL_NUMBER Function: This command can be used to dial the phone number specified in . Results: RC will be 5 if AB was not able to dial the phone number. Command: NEW_PROJECT, OPEN_PROJECT , SAVE_PROJECT, SAVE_AS_PROJECT Function: These four commands load, save and remove projects in the same way as if the command was selected from the project menu. is the name of the project file to use. Results: See @{"ARexx support" link "arexx_support" 30}. Command: SEARCH Function: Starts a search for . The type of search depends on the specified: 1 Name searches. 2 Phone number searches. 3 E-mail address searches. If the search is successful, then the matching entry will be displayed. Note that the presently displayed entry will also be searched, so if that entry matches the search parameters then nothing will appear to have changed. Results: RC will be 0 regardless of weather a match is found or not. If a match is not found then RESULT will be 'Not found'. See the @{"example scripts" link "example_scripts" 0} for a demonstration of searching. Command: SEARCH_AGAIN Function: Repeats a previously defined search. Note that the search starts at the next entry after the current one. Results: See the results section of the command @{"SEARCH" link "arexx_commands" 95}. Command: SAVE_SETTINGS Function: This command saves the current settings the the program icon's tooltypes. Results: See @{"ARexx support" link "arexx_support" 30}. Command: GET_ENTRY_DETAILS Function: This command extracts information from the currently viewed entry. is the number of the field that you wish to look at: 1 Name field. 2 to 6 Address fields one through five. 7 Phone number field. 8 E-mail address field. 9 Comment field. Results: If the field is empty, then RESULT will contain the string 'Field empty'. Otherwise, RESULT will be the string contained in the relevant field of the current entry. Command: NEW_ENTRY Function: This command creates a new entry with the name set to . It is made the currently viewed entry. Results: See @{"ARexx support" link "arexx_support" 30}. Command: PUT_ENTRY_DETAILS Function: This command changes the text in the specified field to that of . The used is the same as for the @{"GET_ENTRY_DETAILS" link "arexx_commands" 138} command. Note that if the name field is changed, then the ordering of the entries within the project will change also. This is because the entries are sorted alphabetically with respect to the names. Passing a of 'Field empty' (case is important) will clear the selected field. It is not possible to clear the Name field of an entry in this way though. Result: See @{"ARexx support" link "arexx_support" 30}. @endnode @node "example_scripts" "AB comes with some example scripts" @{b}Example scripts@{ub} AB's archive contains an additional directory (called ARexx) which contains some example scripts for you to look at, and see how the various commands function. To use these scripts, run AB and then open a Shell window. CD to the ARexx directory and then type RX