-------------------------------------------------------------------------------- db - A small and fast database program -------------------------------------------------------------------------------- Table of contents ================= 'Disclaimer' 'Preface' 'Introduction' 'Features' 'Future plans' 'System requirements' 'Installing and starting' 'Settings' 'db reference manual' 'The window' 'Views' '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 postcardware, ie like 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 like the program, please send a postcard to the author (address below). If you want to distribute this program then you must supply the whole archive (packed in .lha or unpacked). 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. I really like response from users. 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 Beta-Testing & Suggestions by: Mikael Östergren, Anders Callertun. Icon artwork by Mikael Östergren. Thanks to Jan van den Baard for GadToolsBox -------------------------------------------------------------------------------- -------------------------------------------------------------------------------- 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. Before this release db was fixed to be just an address and telephone database, but this has changed now. The program is designed to handle information of your choice. Currently you have to use a file editor to specify the database fields and layout as there is no GUI for that. Anyway that's a one time job, then you just USE the database and have fun. Complete GUI support 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 User definable fields and layout. o Multiple views of the same database. o Commodore's Clipboard for flexible interaction with other programs. o AppWindow -just drag and drop database icons on db to load. o Online MenuHelp -Press HELP key when selecting a menu item. o Font sensitivity. o ASL requesters for flexible loads and saves. o Localized o Dial numbers using a modem o WB and Shell usage with Commodore's template parsing o Fast and flexible find function using AmigaDOS patterns. o Filter function. o Fast and flexible sort function. Multiple sort orders can be specified. o 'Export View' and two standard ASCII export features. o Automatic ASCII import (tab-separated ASCII) -------------------------------------------------------------------------------- -------------------------------------------------------------------------------- Future plans ------------ The following are plans for the future. The main changes will probably only be included in a commercial product called REG. o Checkbox and Cyclegadgets in database. o Rexx support. o List view of database. o Field and record merge. o Relations between databases. -------------------------------------------------------------------------------- -------------------------------------------------------------------------------- System Requirements & Compatibility ----------------------------------- db will only run on AmigaOS 2.04 or higher. db needs at least AmigaOS 2.1 to use localized languages. 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 each field. You just specify a maximum number of characters if you want a limit for some reason (zipcodes...). (If you don't specify a limit then there is a default limit of 200 characters) 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 -------------------------- db runs from both Workbench and Shell. See 'Settings' for parameter list. Installing db is simple - just drag the db program icon and the Catalogs drawer to the desired destination drawer. (If you omit the Catalogs drawer, you will only get English text.) To start db from Shell, just enter db followed by an optional parameter list. Enter db ? from Shell to see the parameters. 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. -------------------------------------------------------------------------------- -------------------------------------------------------------------------------- Settings -------- db can be set up either from Shell or from its ToolTypes. The following parameters apply to both environments: DEVICE= -Device used for dialing using a modem. The default is serial.device, but users of internal modems might use modem0.device or something else. UNIT= -For multiple serial units. 0 is default. DIALPREFIX= -String to add before phonenumbers when dialing. Default (for Hayes modems) is ATDT DIALPOSTFIX= -As the above, but this will be added after the phonenumbers (+ a return code) The default ;H returns the modem to command state and hangs up immediately. (you take over from there) AREACODE= -This will strip the from the beginnng of phone numbers beginning with in order not to confuse some telephone systems. Let's say our area code is (08). Entering that code into AREACODE will make numbers like (08)123456 to be dialed as 123456. FONTNAME -You can specify a custom font to use other than the default which is the screen font. The name has to be typed with the .font addition, for example FONTNAME=times.font FONTSIZE -Size of font, se above. If the font makes the window to big to open, db will try the screenfont and at last topaz 8. NOICONS -This will supress iconsaving for projects. NOSPEEDRENDER -Turns off 'SpeedRender'. NORETURNSTEP -Turns off the ability to use the return key or enter key to step between fields. NOSERIAL -This ToolType has currently no function. This will in turn disable dialing. -------------------------------------------------------------------------------- -------------------------------------------------------------------------------- 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 (or your specified 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 16/43 It indicates a number of things namely: Filename/Viewname Current record number/Number of records. -------------------------------------------------------------------------------- -------------------------------------------------------------------------------- Views ----- The visual information in the database can now be divided into many views. This enables the user to view the database in different ways. One view may only contain address specs, while another view contains special information on the persons study results for example. This is also useful when doing exports for label-printing if a label-looking view is designed. Another reason to use views is to enable db to have more fields than is possible to show on the screen at one time. If you don't understand the idea, try some of the example programs and try playing with the menuitems under the View menu and see what happens. (Only some of the examples has multiple Views) -------------------------------------------------------------------------------- -------------------------------------------------------------------------------- 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 Clicking 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. Use the HELP key or right mouse button to de-activate a field gadget. See 'Key operations' for more information. By using string gadgets to enter information makes it 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 makes it 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. To move between fields you use Tab and Shift-tab as is the standard today. You may also use the return or enter key if the NORETURNSTEP ToolType is not specified. -------------------------------------------------------------------------------- -------------------------------------------------------------------------------- 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 from all records, but keeps all fields. 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 accepts plain tab-separated ASCII files and files in the 'RFF file format'. Project/Save: Saves the current database under a known name using db's 'RFF file format' 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 optional icon creation. Project/Output/View...: 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 an ASCII file formatted as the current 'View' which may look like a label or something else suitable for importing in other programs. A label template for PageStream is included. This will bring up a standard ASL requester for the View file. The user will be asked if all records should be exported or only those matched by the 'Find record' function. Project/Output/Comma-separated 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. The user will be asked if all records should be exported or only those matched by the 'Find record' function. Project/Output/Tab-separated ASCII...: This item will bring up a standard ASL requester for saving comma-separated ASCII file, ie like the format above, but with commas as separators and quotes "" around the names. This is suitable for exporting db databases to programs like ProWrite for mailmerge printouts. The user will be asked if all records should be exported or only those matched by the 'Find record' function. 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. View menu: Use these menuitems to switch between different 'Views' of the database (if there are more than one of course). Se Views section for more information. 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. * Press Enter/Return to leave the fields * At the 2:nd 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. Note: The export function uses this function to filter records 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. Action/Dial number db will dial a phonenumber using your modem. See 'Settings' for how to configure db to your modem and serial device settings. To dial a number, do the following: 1. Select the gadget containing a valid phonenumber (ie, at least one digit) 2. Select this menuitem or press return followed by the menu shortcut Amiga-D. (The gadget will be de-selected, but db remembers the last selected gadget as the one to use in dialing.) 3. When db starts to dial, lift the hook and wait. As soon as there is a connection, db will hang up and you can take over. To interrupt db when dialing. Simply press Amiga-D once again. This should work with most modems Settings/Display warnings: With this item selected, the user will be warned before a 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... This option is currently not available. When it is implemented db will save the changes in it's icon as tooltypes. Edit the tooltypes manually! -------------------------------------------------------------------------------- -------------------------------------------------------------------------------- Technical info ============== The RFF file format ------------------- db is a general database program, ie it has no longer a fixed set of fields. But currently there is no GUI (graphical user interface) for editing the set of fields you want. In order to make a custom database using db you therefore have to edit a db datafile manually. db stores all information other than fieldnames in the so called RFF lines of a file. (The fieldnames are stored in the first line of a file as in the ASCII-text standard for database files) Note, in previous versions (1.1 & 1.0) db ignored the information specific to the RFF standard, but wrote 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 '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 view, ie one window displaying just one way to look at the database. Here is the format of an RFF line: {=[,=]...[]}... Example: NAME=_Firm,OFFS=0,SIZE=37 NAME=_Name,OFFS=1,SIZE=14,NEXT=space That should read: One or more comma separated 'identifier=data' items. Groups of commaseparated identifier=data items may also be tab separated. Case is not significant. If you need to use a comma or space as data, enclose the data in "quotes" The idea is that all information that belongs to a view is collected in a single RFF line, and all information that belongs to a single field in a view 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 view is collected in the beginning of an RFF line, before the first tab. Unknown identifiers are ignored but kept in the program for saving. 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: (Only the following are currently implemented in db 2.1: @RFF TYPE (internal and form) TABSIZE FLEN LNAM NAME SIZE OFFS NEXT) '@'RFF= (Ignore the 'quotes') 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 view. form -This is a form view list -This is a list view LNAM= This is the name the view to be specified. It will show up in the menus and in the titlebar of a database window when that view is selected. (layoutname was the old name for a view) If you omit LNAM the filename is used as name. TABSIZE= New tag for db2.1! When using a tabstep to visually separate fields (se NEXT tag below), this tag sets the distance between two tab positions (measured in characters). If you omit TABSIZE a default of 6 is used. FLEN= This identifier describes the maximum allowed fieldlength. It is used to calculate the buffersize for the stringgadgets. If you omit FLEN a default of 200 is used. 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. I you omit NAME, the internal fieldname is used (the first line of the file) OFFS= This identifier is very important. 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 views. If you omit OFFS, the last OFFS+1 is used. SIZE= This identifier is used to calculate the horizontal size of stringgadgets. If you omit SIZE, a default of 25 characters is used. NEXT= This tag controls the position of the fields in the window. Not by x-y coordinates as in some other programs, but by telling db how to move it's invisible "pen" when a field has been drawn. db starts drawing in the top-left corner. Here are the currently defined parameters (newline 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 (NOSPEEDRENDER) ToolType in db's tool icon mean, well here it is: I've tried to program db in such a way that it shall work with 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 turns off SpeedRender. -------------------------------------------------------------------------------- -------------------------------------------------------------------------------- History of changes ================== 94-08-20 v2.1 * The return and enter keys can now be used to step between fields. (Use the NORETURNSTEP ToolType to only allow the tab key for this like before v2.1) * Added a TABSIZE tag to the RFF format to simplify layout work. * The RFF parser will parse all 1.x files not just RFF 1.1 files. * Saves and loades are faster. 94-08-13 v2.0 * Major changes. db is now a general database, not just a telephone and address database. db now uses the field- and layout specifications found in the datafiles (the RFF lines) * Multiple views implemented. * Added Amiga-W shortcut for "Save as..." menuitem * Commaseparated ASCII export implemented (user request) * When exporting records: filtering of records can be specified. * Custom fontname and fontsize can be specified * db now moves one titlebar down from the top left corner of the screen when zoomed. * NOICONS can be specified to supress icon saving (user request) * before 2.0 db didn't intentionally remember the last exported filename. This has been changed. * Before v2.0: If the user made a change to a project and performed an ASCII export and then quit. db wouldn't put up a project-not-saved warning. This has been corrected. * Fixed bug where db sometimes sorted records incorrectly in projects where there were records which had blank fields which were also part of the sort order. 94-06-04 v1.1 * Added modem-dialing feature. * db now runs from Shell as well as from Workbench * Settings can now be made from Shell using Commodores template parsing or from db's icon using ToolTypes. * db now moves to the top left corner of the screen when zoomed. * Gadget positions and sizes somewhat adjusted. * Selecting Cut won't incorrectly put up the delete warning requester. * minor code changes made. 94-03-04 v1.0 Initial release.