db == A small and fast database program for the Amiga. Copyright 1994, - Datadosen All Rights Reserved. Programmed & Designed by: --------------------------- David Ekholm Beta-Testing & Suggestions by: -------------------------------- Richard Ludwig, Mikael Östergren, Anders Callertun. GUI designed using Gadtoolbox --------------------------- Table of contents ================= Disclaimer Preface Introduction Features Future plans System requirements Installing and starting db reference manual The window The gadgets The keys The menus Technical info The RFF file format A note about SpeedRender History of changes Disclaimer ---------- db has been tested and found stable in everyday use. However the author is not responsible for any loss of data, damages to software or hardware that may result directly or indirectly from the use of this program. Preface ------- This program is freeware, this means that you can copy it freely as long as you don't ask any more money for it than a nominal fee for copying. If you want to distribute this program you should keep this document with it. This program cannot be used for commercial purposes without written permission from the author. Special permission is hereby granted to include db in Public-Domain collections such as Fred Fish's Amiga Library. HOW TO GET THE LATEST VERSION OF db The fastest way to get the most recent release of db is to download it from an AmiNet ftp site. For example: ftp.luth.se You may also call the following BBS:es (in Sweden) SUGA: int +46 8 348 523/343 276 DMZ: int +46 8 654 99 50/62 If you have suggestions or remarks about this program, or if you find any bugs, please let me know. Write to the following address: David Ekholm Mantalsvägen 33 s-175 43 Järfälla Sweden You who prefer the faster way may use: phone: int +46 8-580 15668 email: david-ek@dsv.su.se An Introduction to db --------------------- db is a small and fast database program that I wrote after having tested numerous other PD database programs and always found something lacking or irritating me. They might have dozzens of features not found in db, but they lacked font sensitivity and a standard GUI look and OS 3.0 behaviour. My main need was to keep record on addresses and telephone numbers of friends and companies. Currently in this FreeWare release, db is fixed to be just an address and telephone database, but this will change. The program is designed to handle information of your choice, but that ability will probably only be included in a commercial product I plan to call REG. Feature List ------------ A partial list of db's features include: o Dynamic memory handling. Number of records and fields only limited by free memory. o GadTool based, gives a standard look and feel. o Mouse and keyboard driven. o ASL requesters for flexible loads and saves. o Commodore's Clipboard for flexible interaction with other programs. o Font sensitivity. o AppWindow -just drag and drop database icons on db to load. o Online MenuHelp -Press HELP key when selecting a menu item. o Fast and flexible find function using AmigaDOS patterns. o Fast and flexible sort function. Multiple sort orders can be specified. o Label and standard ASCII export feature. Future plans ------------ The following are plans for the future. The main changes will probably only be included in a commercial product called REG. o Filter function. o User definable fields and layout. o Checkbox and Cyclegadgets in database. o Rexx support. o Localization o Multiple views of the same database. o List view of database. o Field and record merge. o Import function. o Relations between databases. System Requirements & Compatibility ----------------------------------- db will only run on AmigaOS 2.04 or higher. db needs to have the whole database in memory to run which limits the number of records to what the memory allows. However modern computers like the Amiga with, say 2 MB of memory, will typically allow databases with more than 5000 records -enough for most uses. The idea is sort of: "one should not drive around with a big trailer in the middle of a city". db is a small and fast citycar. db allocates exactly the amount of memory needed for a particular field. This is a memory efficient model. db has been tested with AmigaOS 2.04, 3.0 and 3.1 and is written in SAS C 6.51. Installing and starting db -------------------------- Installing db is simple - just drag the db program icon to the desired destination drawer. To start db manually from the Workbench simply double-click on its program icon. You can also start db by clicking on a db project icon so that that project gets loaded automatically. Another way to load a project is to simply drag that project over db's window and release the mouse. db Reference Manual =================== This section contains the boring information most people figure out themselves by testing a program. db has on-line help that should be sufficient for most people. I recommend that you experiment with the program first and turn to this section if there is a problem of some kind. The window ---------- The db window always opens on the default public screen, normally the Workbench screen. It uses the screen font and all text and gadgets are sized accordingly. db has a zoom gadget next to the depth gadget to enable the window to be minimized if db isn't needed for a while. db will currently always display one record at a time that we call the current record. db can work in one of three modes: o Normal mode. Enter records and look at the database here. o Find mode. Information entered in the fields will serve as a search pattern. AmigaDOS patterns are accepted. Press enter to start search or press escape to cancel find mode. o Sort mode. Numbers entered in the fields will serve as a sort-order description. Press enter to start sort or press escape to cancel sort mode. The window titlebar can look like this: Adresses/Main view 43/43 16 It indicates a number of things namely: Filename/Layoutname Selected records/Number of records Current record number. Currently db won't allow multiple layouts so layoutname is fixed to 'Main view'. Currently db won't allow filtering of records either so the selected records number will always be equal to the number of records in the database. Gadget Operations ----------------- db's window is made up of two kinds of gadgets, program gadgets and field gadgets. Currently There are only three program gadgets -the record dragbar with it's two arrow keys. These gadgets has two uses, one is to navigate in the database in a quick way. The second is to give a visual feel of where the user is in the database and how big the database is. This is illustrated by the size and position of the dragbar knob. The field gadgets are currently of one type -string type. They can be activated in one of three ways: o Klicking the mouse over the desired field o Pressing the key that corresponds to the underlined character in the field name. o Pressing tab or shift-tab to move between fields. By using string gadgets to enter information it is possible to enter more information than is visible in the gadget. If so, the gadget will start to scroll the entered text. Pressing shift-left or shift-right will move the cursor to the first and last character in a field as usual. Amiga-X will also clear the active gadget. By using PD programs like NewEdit it is also possible to copy and paste information between fields, not just records as supported by db. You have to click outside a string gadget or press enter to be able to to use the other keys to navigate in the database but if you are using the mouse there is no need to press enter to leave a string gadget. Any information entered will be recorded in the database. Key Operations -------------- The following keys can be used to control db (apart from the window shortcuts): This is the action performed in normal mode: Up - Previous record. Down - Next record. Shift Up - First record. Shift Down - Last record. Return - Forward search. Shift Return - Backward search. In find and sort mode these are the active keys: ESC - Leave find or sort mode Return/Enter - Start search or sort. Menu Operations --------------- Note that much of this information can be found online in db by selecting a menuitem and pressing HELP. Project/New: Clears the database and brings up a new empty database. Will ask before clearing the old database if it has unsaved changes. Project/Open...: Brings up a standard ASL file-requester to allow the user to select a new database file to load. Will warn the user before loading ontop of an unsaved database. db databases can also be loaded by draging an icon over a db window. db will only accept files in the RFF file format. See end of documentation. Project/Save: Saves the current database under a known name using db's RFF file format (see end of documentation for details). If no name has been specified, db will automatically call Project/Save as... Project/Save as...: Performs the same behavior as Save item described above except brings up a standard ASL file-requester to let the user select a file and path name for the database. The user will be warned if he types the same name as an existing file. Otherwise a new file and icon will be created and the Workbench will be informed of the icon creation. Project/Output/Labels...: db has no internal label-layout generator. The idea is that other programs, better at layout, like DTP programs should handle that. Instead db outputs a file in a plain ASCII label format suitable for importing in other programs. A label template for PageStream is included. This will bring up a standard ASL requester for the label file. Project/Output/plain ASCII...: This item will bring up a standard ASL requester for saving a plain ASCII file, ie a tab separated textfile with one record per line and the fieldnames in the first line of the file. This is suitable for exporting db databases to programs like Excel for list printouts. Project/About...: Brings up a requester showing information about the author, hidden features, and revision number. Click Ok to make the requester disappear. Project/Quit: First prompts the user with a requester if there is unsaved data and if the action is confirmed removes any currently installed database and exits the program. Edit/Cut: db uses Commodores standard Clipboard to allow copying of information between db and other programs (wordprocessors, DTP...). db writes to two clipboards, Unit 0 (the default clipboard) and Unit 1. Reads are only made from Unit 1. This is what is written: Unit 0: Addresses in a label format. Unit 1: The whole record in a record format like this: fieldname contents fieldname contents ... Cut will copy the contents of the current record to the clipboard and delete the current record. Edit/Copy: Just copies the current record to the clipboard. Se Edit/Cut for more information. Edit/Paste: Will add a new record and paste the contents of the clipboard that matches the fields in this database into the new record. Edit/Paste will paste from Clipboard unit 1 which has a format as described in Edit/Cut. If there is no data in the clipboard that suits the fields, nothing will happen at all. Edit/Add: Adds a new empty record to the database. The new record will be added after the current record. Edit/Kill: The current record is deleted in normal mode. In find and sort mode the fields are cleared instead. You cannot kill a record if it is the only one. Action/Find... Will turn db into find mode. The current record will now indicate the desired search pattern. Enter a search pattern into one or many of the fields. At the press of the enter/return key db will then search the database starting from the top and stop at the first occurence that has a match. Usually only a few letters will do as a search pattern. For example: 'da' will match both 'David' and 'Daniel'. You may also use AmigaDOS patterns. For example: '#?d' or '*d' will match fields ending with a d. (david|micke)' will match both 'David' and 'Micke'. Pressing the escape key returns db to normal mode. Action/Find next This menu item is only supplied for compatibility with other programs. It will continue searching for other matching records. It is better to use enter/return instead and shift-enter/return to search backwards. Action/Sort... Will turn db into sort mode. The current record will now indicate the desired sort order. Just enter numbers in the fields. Anything else than numbers is ignored. For example, entering a '1' in the Zip field and a '2' in the Name field indicates that you want the database sorted on zipcodes in the first hand and sorted on names in the second hand. db will sort the Swedish ÅÄÖ characters correctly unlike most other programs. Pressing the escape key returns db to normal mode. Settings/Display warnings: With this item selected, the user will be warned before a Cut or Kill is performed on a non-empty record. Settings/Sort direction The user may also choose a backward sort direction. db will sort the Swedish ÅÄÖ characters correctly. Settings/Save changes... Edit/Last Saved: This option is currently not available. When it is implemented db will save the changes in it's icon as tooltypes. Technical info ============== The RFF file format ------------------- Just read this if you are interested in writing import filters that can import or export the RFF file format. Note, in this version (1.0) db ignores the information specific to the RFF standard, but writes files in an RFF compatible manner. db uses an extended version of the standard ASCII database format called RFF. The difference between the two is that RFF is capable of storing information on things like layouts, visual fieldnames (as compared to internal fieldnames in standard ASCII file format), maximal fieldlengths, fieldtypes and more. However an RFF file can be converted to a plain ASCII database file by just deleting all lines beginning with @RFF. In the RFF standard all RFF lines has to be in the beginning of the file, before any data lines, but after the first line which is the fieldname line, according to the ASCII database standard. Normally there is one RFF line per layout/view in a file, but the first RFF line describes internal information (as opposed to visual information) like maximum fieldlenghts so an RFF file consisting of only two RFF lines, has one layout/view, ie one window displaying just one way to look at the database. Here is the format of an RFF line: {=[,=]...[]}... That should read: One or more comma separated 'identifier=data' items. Groups of commaseparated identifier=data items may also be tab separated. The idea is that all information that belongs to a layout is collected in a single RFF line, and all information that belongs to a single field in a layout is collected between two tabs just like the field data itself. The first identifier must be @RFF which has version and revision as it's data. Information specific to the first field comes after the first tab and so on. So global information for a layout is collected in the beginning of an RFF line, before the first tab. Unknown identifiers are ignored. This is somewhat like the IFF file way of thinking and allows for future enhancements without loosing backward compatibility. I choosed RFF because it is a READABLE format. Readable to both men and machines of different types. To other database programs an RFF file should show up like a normal ASCII file with some funny records in the beginning, not that bad, right? Here is a list of identifiers defined in RFF 1.1: @RFF= The RFF line identifier itself. Has a version and revision number as it's parameter. Must be the first identifier of an RFF line. A new version number tells an old RFF parser that so big changes has been made to this line that the entire line should be ignored. TYPE= This identifier describes what the current RFF line describes. The parameters can be any of the following: internal -Information not concerning any layout. form -This is a form view/layout list -This is a list view/layout LNAM= This is the name to be displayed in the titlebar of a layoutwindow. FLEN= This identifier describes the maximum allowed fieldlength. It is used to calculate the buffersize for the stringgadgets. NAME= This identifier describes not only the fieldname that should be displayed (could be different from the internal fieldname), but also describes what hotkey to be used to activate it's gadget. This is done by placing an underscore character before the character that is to act as a hotkey. Example: NAME=E_mail, will make the m key act as a hotkey to activate that field. OFFS= This identifier is very important and cannot be omitted. It helps db "connect" a field gadget to the right field in the database as the visual fields and the internal fields can be in different order. There can even be less visual fields than internal fields. This is of course only used on multiple layouts. SIZE= This identifier is used to calculate the horizontal size of stringgadgets. NEXT= This identifier will help db to position the fields correctly. It instructs db how to move it's "pencil" after having drawn a field in a window. Here are the currently defined parameters ( is the default): space -move slightly to the right before drawing the next gadget. tab -move a tab-step to the right before drawing the next gadget. para -move two lines down before drawing the next gadget. CMNT=<"comment string"> This gives us the ability to insert comments in databases. Any string that contains spaces tabs or commas should be enclosed in "". FTYP= Determines the type of the field. These are the currently defined types (string is the default): checkbox -displays a checkbox. A 0 or 1 is entered in the database. cycle -displays a cyclegadget with choices as specified below. calc -a calculated field, contains a formula. external -this field stores the filename of some external file. SFMT= This identifier gives special formatting of strings like the following (no formatting is the default): upper -all capital letters. caps -capital initial letters in words. right -right justified text. CENT= This identifier can occur several times and tells db what choices should appear in a cyclegadget. A note about SpeedRender ------------------------ Someone might wonder what the SPEEDRENDER=YES line in the tooltype field in db's project icons mean, well here it is: I've tried to program db in such a way that it shall work in any future OS version. But in order to achieve resonable speeds in redrawing the window I have adopted a technique called SpeedRender. What SpeedRender does is to copy all the gadgetborder pointers to a private list and then clear the GadgetRender field pointers in the gadgetstructs. Now Intuition doesn't have to redraw the gadgetborders everytime a gadget is updated (happens every time the user uses the dragbar). Setting this flag to NO should turn off SpeedRender. Currently (in v1.0), db ignores the SPEEDRENDER flag so there is no way to turn off SpeedRender. It will be implemented later. History of changes ================== 94-03-04 v1.0 Initial release.