Frozen Fish 1: Amiga

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

/ Frozen Fish 1: Amiga / FrozenFish-Apr94.iso / bbs / alib / d8xx / d820 / quickfile.lha / QuickFile / QuickFile.doc < prev next >

Wrap

Text File | 1993-02-15 | 25.3 KB | 690 lines

QuickFile v1.2 16th January 1993 ============== CONDITIONS ============================================= This program is not Public Domain, however it can be freely distributed provided 1. All documentation and sample files are included unchanged. 2. A reasonable copying fee may be charged but must not exceed the charge made by Fred Fish for his AmigaLibDisks. This program may not be included in any commercial product without the written permission of the author. I accept no liability for any loss or damage resulting from the use of this program. Each user must evaluate it and decide its usefulness for his or her own purposes. If you find this program useful, please send a donation (suggested $20). This ensures that you get the latest version of the program and entitles you to free support and bug fixes (as they become available). Overseas users - please do not send personal cheques. Please send an overseas bank draft in Australian Dollars drawn on an Australian bank. This should be readily available from your bank. Any cash currency is also OK. I intend to develop the program further if enough interest is shown and would appreciate any constructive comments you may have, even if you decide not to use it. Enclosing a stamped self addressed envelope will ensure a personal reply. Donations, comments and bug reports should be sent to: Alan Wigginton 23 Carissa St Shailer Park, Queensland 4128. AUSTRALIA ====================================================================== PROGRAM DESCRIPTION A flexible, fast and easy to use flat file database using random access with intelligent buffering to minimise disk access, multiple indexes for fast access to records, form and list style screens and reports, and fast sorting and searching. Files are quickly and easily defined, and fields can be added, changed or deleted at any time. WARNING. QuickFile is a random access data base that buffers records in memory. Failure to exit the program properly after updates are made will result in lost updates. ALWAYS exit the program before a reboot or power off. USING THE DEMONSTRATION DATABASES. Two demonstration databases are provided. Click on one of these icons to start Quickfile and display the first record in the file. It is a good idea to browse through this document to get a feel for the program before trying to do too much. It is strongly suggested that you copy QuickFile to a work disk before you try adding or updating records. The easiest way to do this is to drag the QuickFile icon into another disk window. ======== ENHANCEMENTS SINCE VERSION 1.0 ==================== 1. Support for the ASL and ARP file requesters. Note that you can still use QuickFile even if you don't have either of these. 2. Choice of FORM or LIST (column) style reports. 3. Reporting options provided allowing - User specified report Title - Override of printer preferences values for margins, print size, line spacing, lines per page - Suppression of pagination and field titles to provide a primitive label printing facility. ======== GETTING STARTED ========= QuickFile can be started from the WorkBench using the QuickFile icon or a project icon for a data base. It can also be started from the CLI and accepts a file name (optional) as a parameter. Icons are not generated by the program. Sorry, but if you want them you will have to create them yourself. If you start QuickFile with a file (from a project icon or from the CLI), the Form display appears showing the first record. If you do not specify a file, the screen will be blank. You can select either Open or Define New from the project menu. The window title bar is used to display a status line and status messages. The status line contains Name of the file being used. Name of the index being used. Current record number. Total number of records. QuickFile uses indexes to sequence the records and to provide rapid access by field value. You can have a number of indexes, all of which are automatically maintained as you add, change and delete records. The current index is displayed in the title line. If other indexes are available you can choose them with Use Index on the View menu. Standard Amiga text gadgets are used for entering data. These provide the following editing keys right Amiga-X Erase all text in the gadget (Control-X does the same) right Amiga-Q Restores the text that was present before you changed it. Shift-left arrow Moves the cursor to the beginning of the field. Shift-right arrow Moves the cursor to the end of the field. Shift-Del Erases all characters from the cursor to the end of the gadget. Shift-Backspace Erases all characters to the left of the cursor. ============== PROGRAM FUNCTION ================== This section describes the two main display formats, followed by an explanation of each menu item. FORM DISPLAY This is the initial display you are shown after you open a file. It has fields displayed down the screen and a row of buttons across the bottom. The button functions are: Next, Back. Use these to browse forward and backward through the database one record at a time. GoTo This brings up a requester for you to enter the key of the required record. Pressing the OK button or RETURN on the last key field will perform the GoTo. If the key you enter does not exist, the next higher record is displayed. You can enter "SM" to position on the record for SMITH followed by SMITHERS, SMITHFIELD etc. Insert Displays a blank screen and lets you enter values. Press RETURN on each field to move you to the next field. Press the Copy button to copy the contents of the last record displayed or added. This is useful if you are entering records with similar values in some fields of each record. Press Insert to store the details and clear the fields ready for the next record. Press Cancel to return to Browse mode. NB When Cancel is pressed any values displayed on the screen will be lost. Press Insert if you want them stored. Modify Displays the current record for you to make changes. Press Update to store the changes. Press Cancel to keep the current values. Delete Brings a requester asking you to confirm the deletion. Press OK to delete the record. Press Cancel if you really want to keep it. LIST DISPLAY This is obtained by selecting List from the VIEW menu. It displays as many records as will fit in the window with a single line per record. The first time you select List you will be presented with a requester to select the fields to display. There is currently no sideways scrolling so you must select the fields you want to see or they may fall of the edge of the screen. Select Fields Requester You select fields from the Available fields box on the left by clicking on them. Each field you select appears in the Selected Fields box on the right with its length. You can reduce this length to display only part of the field and thus fit more fields on the screen. The Clear button clears all current selections for you to start again. You cannot add or delete individual fields that have been selected. Record Selection You can select a record by clicking on it so that it is high- lighted. Double clicking on a record will change to the Form display of that record. List Display Buttons Next, Back These move you forward or back by one screen. Pressing the Next or Back button with a record selected, will position that record at the top or bottom of the screen respectively. GoTo This functions as for the Form display. Layout This brings up the Select Fields requester to change the fields displayed. ============= MENU FUNCTIONS ================= PROJECT MENU NOTE: QuickFile supports the ASL and ARP file requesters. The ASL requester (WB2) will be used if asl.library is in your LIBS: directory. The ARP requester will be used if arp.library is in your LIBS: directory. If you have neither, QuickFile will use a requester with simple string gadgets for you to enter Drawer and File names. Open Brings up a file requester for you to select the file to process. Always enter the definition name - the one with no suffix. Save Writes all updated blocks and indexes to disk. You should use this periodically during a long update session. Close Writes all updated records and indexes to disk and closes the file but leaves the program running. Define New Displays the definition screen for a new data base. If a file is open it will be closed after asking you for confirmation. See below for definition details. Alter Displays the definition of the current file for you to make changes. The file will be closed before you can do this. You will be asked for confirmation before this is done. BackUp Creates a copy of the definition and data files (not the indexes). A requester is displayed for you to enter the backup file name. The default is filename.bkp. Backup uses the current index. You can write selected records to another file by choosing Selected from the View menu before Backup. If you choose Backup while viewing selected records, you will be asked for confirmation to avoid accidental loss of data. The file is reorganised during backup so a backup followed by a restore will reorganise your file. Free space is adjusted to the value specified in the file definition and records are physically stored in the sequence of the active key. Select your most used key sequence before doing the backup to ensure fastest access in the reorganised file. The backup file is a QuickFile data base so you can open it like any other database file. Restore Restores from a copy made using the backup menu item. You will be asked for two file names (using the requester) 1. The file to be restored from (source) 2. The file to be restored (target) After the file is restored, the indexes are automatically rebuilt. Exit Writes all updated records and indexes to disk, closes the file and exits the program. Selecting the Close gadget on the screen has the same effect. A requester is displayed to confirm your choice. VIEW MENU Form Changes to or refreshes the Form display. List Changes to the List display. See above. Use Index This has a sub-menu showing a list of indexes for you to choose from. The first sub-menu item selects the "Sorted" sequence but will be ghosted until you perform a sort. When you change indexes, the same record is displayed but the file will be in a new sequence. e.g. You can use this to find a book by a particular author and then select the subject index to list all other books on the same subject. Selected Allows you to display previously selected records. This will be ghosted unless your have used Select from the Tools menu. See Tools menu for more details. TOOLS MENU Sort Brings up a requester for you to select fields to sort on. Sort effectively creates a temporary index that is updated automatically as you add, delete and change records. The Sort index is discarded when the file is closed but until then, you will not need to re-sort because you have added more records or changed key fields. Sort Requester This is identical to the List requester. You can sort over more than one field at a time, although you can currently only sort into ascending sequence. You can reduce the field length used for the sort to reduce the memory required for sorting. Press OK to start the sort, or Cancel if you have changed your mind. Sorting is quite fast so you shouldn't have to wait long. A sort (over one field) of the 1300 records on my largest file takes 22 seconds. This is on a 1MB standard A500. The sort technique used requires that all sort keys be resident in memory, so record buffers are freed to maximise available memory before the sort is started. You may notice that disk activity increases after a sort as buffers are reloaded. Select Searches through the data base looking for records with fields matching requested values. A blank screen is displayed for you to enter your selection criteria. Only fields in which you enter a value are used in the search, and a field matches if it contains the search string anywhere within it. (eg "bit" would find "The Hobbit" and "Bitter Sweet". The search ignores case so that "DOG" matches "Dog" and even doG. Press Search to start the search or Cancel to return to the previous screen. The selected data will be in the same sequence as the current Index. The title bar will now show the number of records selected. Don't panic, you haven't lost you file. The full number will be displayed when you choose another index. A Selection of records is an index which is updated automatically for deletions and changes but not additions. Build Index Rebuilds the current index. This can be used if the index and data files are inconsistent for some reason (eg a system failure). This will rebuild the index from the data file. PRINT MENU Print Screen Prints the records currently displayed on the screen. All Records Prints all records in the current index (or Sort or Selection). The first time a report item is selected in a session, the Select Fields requester is displayed for you to choose the fields to be printed. Pressing OK then brings up the print requester which contains: Title Allows you to enter a title to be printed at the top of each page of your report. The title line will also show the current date at the left margin and the page number at the right margin. The title line is only printed if you enter a Title. Note that even a single space will print a blank title. Use CTRL-X to ensure that all characters are deleted. Left and Right Margins Allows you to temporarily override the current preferences settings. QuickFile will not print beyond the character position specified in the right margin. Lines/Page This controls the number of lines QuickFile will use on each page. The default is paper size minus 8 to provide a top and bottom margin. A value of zero will suppress the report title and page breaks. Print Size. This button operates like a WB2 cycle gadget. Each time you press it displays the next value from the following 10 cpi (PICA) 12 cpi (ELITE) 17 cpi (FINE) The Commodore manuals call this 15-Fine, but on my Epson compatible printer it prints at 17 cpi. Lines Per Inch This button toggles between 6 and 8 lines per inch. Field Names? Toggles between YES and NO. NO suppresses field names. Report Type Toggles between FORM and LIST. These are similar to the screen types. FORM prints the fields down the page with the field names on the left. LIST prints fields in columns across the page with the field names at the top of each column. OK Button This will start printing the report. Layout This brings up the Select Fields requester for changing the fields to be printed. Cancel Returns to the main display and cancels any changes entered into the requester. To print labels: . Use Lines/Page of zero to suppress the title and page breaks. . Use NO for the Field Names? button. . Select one field for each line on the label. (You may need to define a dummy field that is always blank. It will use no space). You can place only one field on each line and all fields will start in the same position. To print lines of 136 characters (useful for LIST reports) . Press the Print Size button until 17cpi is displayed. . Set left margin to 1 and right margin to 136 (80 column printer). OPTIONS MENU About Displays the version number of this copy of QuickFile. Buffers Displays the number of buffers currently in use. This will start at 1 and gradually increase as you access records until the entire file is in memory or the maximum allowed is reached. The maximum buffers can be changed by altering the definition (see below) ============== FILE DEFINITION ================== Selecting either Define New or Alter from the Project Menu places you in the definition sreen. CHANGING A FILE DEFINITION You can change just about everything in a file definition except the block size. You can change field names, types and lengths. You can add or delete fields, and add or delete indexes. The OK button on the definition screen will save the definition and return you to the main screen. The cancel button will reload the original definition to undo any changes you have made. WARNING: Deleting a field makes its data inaccessible, even if you re-add the same field. If you accidentally delete a field, press the Cancel button to cancel the changes to the definition and start again. DEFINING A NEW FILE The following describes all of the fields in the sequence you will normally enter them FILE DETAILS Block Size QuickFile does not read and write single records at a time, but builds them into blocks. This reduces the number of disk reads and writes required. Around 2000 seems to give good results. There is currently no way to change block size on an existing file. Block size must be larger than the maximum record size plus free space plus some space for control fields. Free Space Specifies the amount of free space to be left in each block to allow for records to expand. As QuickFile only stores the actual data entered (not trailing blanks), additional space is required if a change makes a field longer. 100 seems to work OK. Records are moved to another block if necessary, so this is not critical. Buffers This is the maximum number of buffers QuickFile will use for holding blocks of records in memory. I usually specify 40 which will use up to approximately 80k (with 2000 byte blocks). Unless you have large files this does not matter, as QuickFile will never allocate more buffers than are required for the whole file. If you have a large file and enough memory, make this large enough to hold the whole file in memory. FIELDS Use the Add button to add a field. A requester will appear for the field details. If a field is highlighted when you press add, the new field will be added above the highlighted field, otherwise it is added to the end of the list. To change or delete fields, click on the field, then press the appropriate button. A requester will appear for you to make or changes or to confirm the deletion. The number of fields is currently limited by screen size. You could use an interlace screen to give more fields if you were desperate. The Field Requester contains the following fields Name Enter a name of up to 12 characters for the field. Type Fields can be either numeric (N) or character (C). You will only be able to enter integers (no decimals) into numeric fields. Length Enter the required length. 60 characters is a practical maximum length as no left and right scrolling is provided and more characters cannot be displayed. (You can scroll within fields on the update screen, but this is pretty tedious. All of these values can be changed at any time without any unexpected effects. If you reduce the length of a field, excess data is only discarded from records as they are updated. Increasing the field length will restore the old data except for records you have changed. Note that backup/restore will update all records. INDEXES You must define at least one index to be used for sequencing your records, and using GoTo to instantly locate a record. If you are not sure pick any field that will give a useful sequence, such as surname, title etc. Fields cannot be added to or deleted from indexes, so changes are made by deleting and redefining the index. This should not be much of a problem as they are easy to define. Selecting insert brings up a requester. You must give the index a name (up to 8 characters) and select the fields to be used. You can use part of a long field for an index by changing the default length. This will reduce sort storage requirements when rebuilding indexes. Limit yourself to indexes you are going to use often. I find it difficult to see how more than 2 or 3 would be useful, particularly as sorting is quite fast. Indexes are maintained automatically as you add, modify and delete records on your file so they reduce the need for sorting and resorting. ================ ADDITIONAL INFORMATION ================== FILES QuickFile uses three types of file distinguished by extension. These are not text files and cannot be edited with most text editors. Using a hex editor will probably corrupt the file. YOU HAVE BEEN WARNED. The DEFINITION FILE has no extension. This is the name you enter when specifying a file name for QuickFile. The DATA FILE has an extension of .Data. INDEX FILES have an extension of .nameX where 'name' is the name of the index as specified in the file definition. INDEX FILE PROBLEMS If you are suspect an index has been corrupted in some way, you can delete the index file (called filename.indnameX). When you open the file next and select that index, it will display 0 records. Select Build Index and any problems with the index should be fixed. ========================= HISTORY ================================ 1.2.1 16 Feb 93 1 Included list style reports 2 Included ASL and ARP file requesters 3 New print requester to improve control of reports 4 The index field size is now updated correctly if you change the length of an existing field used as an index. 5 Index record memory dynamically reallocated if necessary. 6 If you add an index to an existing file, the index will be rebuilt automatically when you open the file again. 7 You are now warned if you attempt a backup while displaying selected records. Only the selected records will be written to the backup file. 8 You can now open a file where the drawer contains only a drive or disk name with no directory. eg df0: 1.0.0 24 Nov 92 Initial Release ======================= BUGS ========================== None known ==================== LIMITATIONS ====================== While QuickFile has a point and click user interface, this is not as polished as it could be. List boxes for example do not scroll and there is no file requester. I hope to improve this in future versions Number of Fields per Record This is limited by screen size. It should be ample for most purposes. If you have reduced the window size, fewer fields can be displayed in the definition window. Increasing the size will increase the maximum number of fields. If you want lots of fields you could use an interlaced Workbench. Number of Records per File The theoretical limit is something like 16 million. In practice this will be limited by the indexing technique which will run out of either memory or processor speed. Each index requires 4 bytes per record and this must be a single block. My largest file is just over 1300 records and it is fine. I expect it to be able to handle several thousand records without problems. While files can be larger than available memory, it will run much faster if you can set the number of buffers large enough to contain the whole file. I would be interested to hear from anyone using it with larger files. Fonts QuickFile requires an 8 x 8 font such as Topaz80. It will run with Topaz 60, but the displays get a bit messy. Error Handling Some error handling is still less than adequate. Memory allocation errors may cause the program to fail with an error message rather than give a warning for you to free some memory. A "disk full" error will also cause an immediate termination.