Amiga MA Magazine 1998 #3

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

/ Amiga MA Magazine 1998 #3 / amigamamagazinepolishissue1998.iso / bazy / quickfile3 / docs / quickfile.doc < prev next >

Wrap

Text File | 1996-06-10 | 49KB | 1,395 lines

Quickfile v3.18.1 copyright 1992-1995 by Alan Wigginton I accept no liability for any loss or damage resulting from the use of this program. Users must evaluate the program and decide its usefulness for their own purposes. QuickFile is not Public Domain, however it can be freely distributed provided all documentation and sample files are included unchanged. QuickFile is a flexible, flat file database. It uses random access with indexing for fast access to records. Files can be larger than available ram, but as much of the file as possible is kept in ram to reduce disk accesses. Features include: - Multiple indexes with unique or non-unique keys - Data types include Character, Date, Time, Integer, Floating Point, Calculation, Cycle, Image and External - Up to 250 characters per field and 250 fields per record. - Form and list style displays and reports. - Unlimited number of views of each file. - Sort over any number of keys, ascending and descending order. - Search operators include Like, Equal, Between, Sounds Like, Not Like and Not Equal. - Fields can be added, changed, or deleted at any time. - ASCII export/import - Multi column label printing. - Multi-level grouping and totalling - Any number of open files each in its own resizable window - Online context sensitive AmigaGuide help - ARexx port supporting macros and commands from external programs - Easy to intuition interface with font sensitivity System Requirements Any Amiga computer with WB 2.04 or later. 1 meg or more RAM recommended Required libraries asl.library mathieeedoubbas.library mathieeedoubtrans.library Optional libraries iffparse.library - to display Image fields rexxsyslib.library - to use ARexx amigaguide.library - to use on-line help QuickFile will work with XFH-handler (a file compression program) but XFH-handler requires that the decompressed file fit completely in ram. To work with QuickFile such programs must support update of an existing file. QuickFile is written in C using DICE version 3.0. ====== CONDITIONS OF USE ===== This version of the program can be used for free on the condition that you write and let me know that you are using it - a postcard will do. The About requester is displayed when the program starts and each time a window is closed. Donations of money, stamps, software etc will be gratefully accepted. If you would like to register for updates, bug fixes and support, please send at least $20.00 to the address below. Overseas users please use international money order or bank draft - not personal cheques. Any cash currency is OK, but you send it at your own risk. Alan Wigginton 23 Carissa St Shailer Park, Queensland 4128. AUSTRALIA Phone 61 7 3208 9441 (from overseas. Remember time differences) 07 3208 9441 (from within Australia) Internet: alanw@powerup.com.au (until 22 June 1996 only) Registration will get you the latest version of the program (without the requester) and prompt attention by email (or snail mail) to any problems you may encounter. You will also be advised when major upgrades are available. I would appreciate any comments or suggestions. You will not get a reply to snail mail unless you send at least enough to cover return postage. I suggest an International Reply Coupon. 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. DO backup your files regularly. When backing up a data base make sure you backup all of the files - definition, data and indexes. To install QuickFile to a hard disk or floppy, drag the QuickFile icon to the drawer of your choice. If you want to use the AmigaGuide help system, copy QuickFile.guide to the same directory. To install AmigaGuide doubleclick on the InstallAmigaGuide icon. Icons are not generated by the program. Sorry, but if you want them you will have to create them yourself. ===== Starting QuickFile ====== QuickFile may be started from Workbench using either the program icon or a project icon. It may also be started from the CLI. The program name may be followed by a file name. QuickFile opens a window on the default public screen. The default window size is a few pixels smaller than the screen size. Window size and position are saved when a view is saved. ===== About Views ====== Views allow you to display data from a file in different ways. There are two basic types FORM and LIST. Each view has its own field titles, positions and lengths, window size and report details. Once you have a view set out the way you want it, you can save it for future use. The Define View requester is used to select or change the fields included in a view. The positions of fields on a form can be changed by dragging them around with the mouse. When you open a file, QuickFile looks for a view called filename.VIEW. To automatically use your favourite view, save it as filename.VIEW in the same directory as the data base. If you want to keep things simple and are happy with the default view, you need not define a view at all. Views are typically used to print labels, export or import selected fields or print lists containing only selected fields. =========== Keyboard =================== The following keys are available when the cursor is not in a string gadget (Press RETURN or ESC to de-activate a string gadget): RETURN Same as OK button ESC Same as CANCEL button TAB Activate first string gadget HELP Displays help. Requires Amigaguide.library in libs: and QuickFile.guide in the same drawer as QuickFile. Down arrow Next record Up arrow Previous record Shift-down arrow Next page Shift-up arrow Previous page In requesters with a single listview, up and down arrows will move through the items. The following keys can be used in string gadgets: TAB Move to next field Shift-TAB Move to previous field Down arrow Move to next field Up arrow Move to previous field Return De-activate string gadget if value is valid ESC De-activate string gadget ignoring errors right Amiga-X Erase all text in the gadget (as does Control-X) 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. ============== MAIN WINDOW ================= Windows can be resized using the sizing or zoom gadgets. The window can be iconified (reduced to a short title bar) using the Project/Iconify menu item ===== Form Display ====== The FORM DISPLAY shows a single record per screen in the format specified by the current view. Field positions can be changed by dragging fields around the window with the mouse. Field sizes can be changed by dragging the bottom right corner of the drag box. Note that although field height can be changed, only images will use more than a single line. Pressing the "R" button displayed at the start of an external field will run the command defined for the field, provided the field is not empty. To add or delete fields, change field titles or displayed lengths, press the VIEW button; ===== List Display ====== The LIST display shows as many records as will fit in the window with a single line per record. To update a record double click on it with the left mouse button Before using the Modify or Delete buttons, select a record using a single press of the left mouse button. In list mode, field position and length can only be changed using the Define View requester. ===== Buttons ===== GoTo GoTo finds a record by key value using the current index. This makes access extremely fast, even on large files. You only need to enter enough of the key to identify the record you want, but you must start at the first key field. Modify Allows you to modify the current record. The horizontal scroll gadget can be used to scroll the display and access fields that do not fit in the window. For images or external fields, you can enter the file name in the string gadget or press the arrow button to get a file requester. Names entered into the string gadget are not validated. Insert Displays a blank form for you to enter values for a new record. The Copy button will copy the contents of the previous record. This is useful if you are entering records with similar values in some fields of each record. Warning - it replaces anything currently on screen. Press Cancel (or ESC) to return to Browse mode. NB When Cancel is pressed any values displayed on the screen will be lost. Press OK to insert the record, then Cancel. Delete Deletes the current record. A requester is displayed to confirm. Once the record has been deleted you cannot get it back. Form/List Toggles the current view between FORM and LIST formats. All/Sel Toggles between all and selected records. Images The Images checkbox in the main window toggles image display on and off for faster processing. ===== Scrolling ===== Scrolling is controlled by two slider type gadgets. Vertical Slider This controls movement through the file and works in the usual way. Scrolling may also be done using the up and down arrow keys for a single record, or the shifted keys for a full screen. Horizontal Slider If there are more fields than will fit in the current window, this can be used to display the next group of fields. ===========PROJECT MENU =================== OPEN Opens a new file in a new window. LOAD Opens a new file, replacing the file in the current window. SAVE Writes all updated blocks and indexes to disk. CLOSE Writes all updated records and indexes to disk and closes the file and window. Closing the last window will exit the program. SAVE AS Creates a new file from the current file. Indexes for the new file are not created - they will be built when you first open the new file. NEW Opens a new window for you to define a new file. ALTER Displays the file definition panel for you to alter the current file definition. Note that the data and any updated views are saved first. EXPORT Writes all, or selected, records to an ASCII file for exchanging data with other applications such as word processors, other data bases etc. The order and length of the fields in the export file is determined by the current view. Before doing the export, you may need to create a new view to give the record layout you want. See export section for details. IMPORT Loads records from an ASCII file into your data base. The sequence and length of fields in the input file are determined from the current view. You should create and select the view before selecting the import function. See Import section for details. REORGANISE Reorganises a file by creating a new optimised version and then copying that version over the main file. Reorganising is not essential, but if you have been doing many additions and deletions, it may reduce file size and will improve performance. During reorganisation 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 reorganising to optimise access with that key. ICONIFY The Project/Iconify menu item shrinks the window to a short title bar. The window can be restored by choosing the menu item again (it acts as a toggle) or by clicking on the window zoom gadget. QuickFile remains active while it is iconified and you can use most of the menu items and keyboard shortcuts. ========= VIEW MENU ========== VIEWS Displays a requester showing a list of currently loaded views for you to choose from. If you have not created or loaded any views, you will have a single view called filename.VIEW. Press the Free button to drop the selected view. You cannot close all views - you must have at least one loaded. NEW Creates a new view called 'unnamed' and displays it in the define View requester. LOAD Loads another view from disk which becomes the current view. If fields in the view cannot be located in the file definition, they will be dropped, and a requester displayed to warn you. This will happen if you delete fields from the file or change field names in the file definition. SAVE Saves changes made to an existing view. If the view has been newly created a file requester will be displayed to confirm the name. SAVE AS Saves the current view under a new name. A view can have any name but the .view suffix should be used for easy identification. ALTER Displays the Define View requester to change the current view. RESET FORM Resets field positioning back to the default. ========== ORDER MENU ========= INDEXES Displays a list of indexes. Choose an index fromt the list to change the display sequence. If you have performed a sort or selection, the list will include "Selected" and/or "Sorted". Pressing the Close Button will remove a "Sort" or "Selection" from memory and free the space used. To remove any permanent index use the Project/Alter menu item to alter the file definition. SORT Displays the sort requester to sort into a new sequence SHOW SORTED Uses last sort for the display sequence. REBUILD INDEX Rebuilds the current index from the data file. This can be used if the index and data files are inconsistent for some reason (eg a system failure). The index is rebuilt from the data file. Try using this if the program is failing with a 'Block not found message' or any messages to the effect that QuickFile could not find a record it looked for. ======= SELECTION MENU =========== QUERY Searches for records matching your selection criteria. See later for full details. SEL/UNSEL RECORD Select or deselect a single record. If you are viewing a selection (using index "Selected"), the current record is removed from the selection. If you are using any other index, the current record is added to the selection. Nothing happens if the record is already in the selection. A message is displayed in the title bar indicating the action performed. For a form view the current record is the one displayed. For a list view the current record is the highlighted record or, if no record is highlighted, the first record on the screen. SHOW SELECTED Displays current selection SHOW ALL Displays all records. The current selection is retained. ======= PRINT MENU =============== DISPLAYED RECORDS Prints the records currently displayed on the screen. This will be a single record for a form display. ALL RECORDS IN CURRENT INDEX Prints all records in the current index (or Sort or Selection). The fields printed and the style (form or list) of report is determined by the current view. See Print Requester for full details =============== OPTIONS MENU ==================== ABOUT Too obvious to explain BUFFERS Displays number of blocks in the file and the maximum and in-use number of RAM buffers. You can change the maximum number of ram buffers. To permanently change the maximum number of buffers, use the Project/Alter menu item to change the file definition. RUN AREXX MACRO You run an ARexx macro by selecting the Options/ARexx macro menu item. This brings up a requester for you to enter the macro name. Pressing the 'File' button brings up the file requester for you to choose the file to be run. If you don't enter a file extension it defaults to ".QuickFile". QuickFile sets the current directory to the database directory before passing the macro to ARexx. ARexx will look in this directory first, then in the REXX: directory. I suggest you put macros written for a particular database in its directory and general macros in the REXX: directory. You can also run an ARexx macro automatically on start up to do things like loading additional views or selecting an index. Name the script filename.STARTUP and place it in the same directory as the file. The display is not normally redrawn until the macro completes. This menu item is disabled if RexxSupport.library is not in your libs: directory. ARexx must also have been started using REXXMAST before you can run a macro successfully. See the Arexx commands documentation for a description of the commands available from ARexx. CONFIGURATION The Configure Requester is obtained by selecting Configuration on the Options menu. The settings are saved in a file called "QuickFile.config" in the same directory as the QuickFile program. Memory Save Checkbox Selecting this checkbox tells QuickFile to reduce memory usage. It defaults to selected. Deselect this to speed up sorting if you are not short of memory. Online Help Selecting this checkbox makes the context sensitive AmigaGuide help available. It defaults to selected. Help will only be available if you have AmigaGuide installed. FONTS To change a font, press the arrow gadget beside the font name. This will bring up a font requester for you to select a typeface and size. Note that very wide fonts may trash some gadget imagery. Standard Font Specifies the font to use for text in most gadgets. This may be a proportional font. List Font This is the fixed width font used for list displays. This includes QuickFile's list display and Listview gadgets. Report Font This font is used for printing reports to the screen. Use a narrow font to display more characters on the screen. This also must be a fixed width font. Save button Saves the settings in the QuickFile.config file and uses the settings. Use button Uses the settings but does not save them for permanent use. Cancel button Cancels any changes made and retains the previous settings ============ DEFINE VIEW REQUESTER ================= Name Identifies the view. This can be changed for a new view, but is display only for an existing view. Available Fields List Lists the fields in the current file. Clicking on a field will add it to the current view. View Fields List Lists the fields in the current view. Clicking on a field in this list will select it and display its title and length below the list box. These can then be changed if required. The changes will only affect the current view. New fields are added before the currently selected item. Type Buttons Choose type of view - FORM or LIST. Headings Check Box Field names are displayed if this is checked. This is normally only turned off for printing labels. Lock Check Box If checked, locks a view to prevent accidental dragging of fields. This should be set to checked and turned off only when you want to arrange fields by dragging them in the view. Field Title String Gadget This is the text gadget under the View Fields list. You can change the field title for this view only. For example you may want a short title for a short field on the list display but use the full name for the form display. The title can be blank. This gadget is disabled unless one of the View Fields is selected. Length String Gadget Use this to reduce or increase the field display length for this view only. IMPORTANT NOTE: You must press enter after changing either the field name or length or your changes will be ignored. Clear Button Deletes all fields from the View Fields list. Delete Button Deletes the selected field from the View Fields list. =================== SORT REQUESTER ================== Sort creates a temporary index which is discarded when the file is closed. The sort sequence will be maintained as you add or delete records. The sort technique used requires that all sort keys be resident in memory, so record buffers are freed to increase the memory available to the sort. If you are short of memory, it may help to sort using less than the full length of long fields. Available Fields Lists the fields defined in this file. Clicking on a field will add it to the Sort Fields. Index Fields Lists the fields to be used for the sort. The order of the fields in this box determines their priority in the sort. The first field is the primary key, the second will only be used for records where the first keys are equal and so on. Clicking on a field in this list will select it and display its name and length below the list box. New fields are inserted before the currently selected field. To add a field to the end of the list, select the "== End ==" entry. Length Changing this length allows you to sort over part of a long field, to save memory and speed sorting IMPORTANT: YOU MUST PRESS ENTER OR RETURN AFTER CHANGING A LENGTH OR YOUR CHANGES WILL BE IGNORED Order Select A..Z for ascending sequence or Z..A for descending. You can mix these on different fields in the same index. Clear Button Deletes all fields from the Index Field List Delete Deletes the selected field from the Index Fields list. ==================== SELECTION ==================== A selection is a subset of the data base that is the result of a Query. QuickFile searches through the whole data base looking for records with fields matching requested values, and creates an index containing these records. You can then browse, print, export or create a new database with the selected records. The selection is updated automatically for deletions and changes but not additions. When displaying a selection, the title bar will show the number of records in the selection. You specify the required sequence for the selected records. The default is the same as the current index. You can run your query against the whole file or the results of the previous query. You can use any number of criteria for a query, but the more you have the slower the search will be. ============== Query Requester ================= The Query Requester displays a list of search criteria with buttons for inserting, modifying and deleting them. Two values can be specified for each item. The second value is primarily for the Between operator, but it can be used to specify an alternative value for the other operators. Clicking on the Insert or Modify displays the Search Details requeste for you to insert or modify the details. For insertions, the new item will be inserted before the selected item. To insert a new item at the end of the list, select the "== End ==" item. Clicking on delete will bring up a requester for you to confirm the deletion of the selected item. Search criteria linked with 'and' will select only records that match both criteria, while search criteria linked with 'or' will select records that match either criteria. 'And' has higher precedence so criteria are formed into groups split by 'or'. All criteria in a group must be satisfied for a record to be selected, but a record will be selected if it matches any group. That is confusing and is probably best explained with an example: Occupation equal programmer and location equal sydney or Occupation equal programmer and location equal canberra This will find all programmers who live in Sydney or Canberra. Note that Occupation had to be repeated. The following would give all programmers who live in Sydney and EVERBODY who lives in Canberra. Occupation equal programmer and location equal sydney or location equal canberra You can also do things like Name like john and Name notlike smith which would find all persons named John, except those named John Smith. ========= Search Details ====================== And, Or Buttons Choose AND or OR to specify how this search item is combined with the previous one. These are not present for the first item. Available Fields List Lists all the fields in the file defintion. The current selection is displayed under the list. Comparison Operator (like, equal etc) Choose the operator to be used for this search item. (see below) Value 1 The primary search value. It is always used. If you want to search for empty fields leave this empty. Value 2 This is the secondary search value. Its primary use is with the between operator but can be used to enter an second search value for the other operators. Note that with Not Equal and Not Like, value 1 and value 2 are joined by AND rather than OR. It will find all records except those that contain value 1 or value 2. Using OR in this situation would select every record. ======= Search Operators =============== Like Matches fields that contain the search string anywhere within them. eg "bit" would find "The Hobbit" and "Bitter Sweet". Equal Matches a field only if it exactly equals the search value. Case is not significant so that dog will match Dog or even dOG. Between Matches a field with a value equal to or between the specified pair of values. This can also be used to perform a less than or greater than search. e.g. 'between 41 and 999' is the same as 'greater than 40'. Sounds Like Matches fields where the first word sounds like the search value. This is really a bit of a gimmick as it is not very smart. NOTE it only looks at the first word of the field. Not Like As for like but only matches records that do not contain the search value. Not Equal As for equal but only matches records that do not match the search value. ====== EXPORT REQUESTER ====== A number of preset formats are provided or you can tailor your own record and field Separators by selecting the Custom format. The headers button determines whether a header record containing the field names is to be included at the start of the file. Pressing the OK Button displays a file requester for you to specify the name of the export file. All records from the current index will be written. If you are displaying Selected records, only the selected records will be written. ====== IMPORT REQUESTER ====== One preset format("...",) is provided or you can tailor your own by selecting Custom and choosing the Record and Field separators. Both sequence and length can be different from that in the database. Also, not all database fields need to be present in the ASCII file. Any fields not present will be set to blank in your data base. NB: It is vital that the sequence and number of fields you set in the selected fields box of the field selector correspond to the sequence of fields in the ASCII file you are importing. Make you sure to backup your database before you import a file into an existing data base. If you get the format wrong, it is easier to restore than to fix or delete all of the incorrect records. Also use plenty of buffers if you are going to import a large number of records. ============ Preset Export/Import Formats ================= A number of preset formats are provided including the mailmerge formats for some wordprocessors: Custom Allows you to define your own format using predefined Separator characters. "...", This is a quote and comma delimited text file such as used for data for BASIC programs. The following preset formats are available only for Export, not Import. Final Copy Interword KindWords 3 ProWrite WordWorth Only the KindWords 3 and Interword versions have been tested. ====== Field and Record Separators ======== You can only select from the predefined delimiter codes. Field Start The character that marks the start of a field. Field End Marks the end of a field. It differs from the field separator in that a separator does not appear after the last field in a record while a field end character appears after every field. Field Separator Separates fields in the record. It does not appear after the last field in the record Record End Marks the end of a record If Field Start is used, a Field End must also be used. If neither Field End nor Field Separator is used, the records will be fixed length with each field padded to its maximum length with spaces. ============= PRINT REQUESTER ===================== Title This is printed, centered, at the top of each page of your report. Current date is printed 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. Left and Right Margins Character position of left and 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. NB QuickFile issues a Form Feed when a new page is required. This relies on your setting the page height on your printer correctly, and may be a limitation with some printers. If you have a problem with this, let me know and I will look at using the preferences paper size. A value of zero will suppress the report title and page breaks. Print Pitch Cycle Gadget. As for Workbench printer preferences. Also shows the number of characters per line for an 80 column printer using the selected pitch. Lines Per Inch Cycle Gadget This button toggles between 6 and 8 lines per inch. Output To Cycle Gadget Allows you to send the report to the printer, window or a file. The file will not include any printer escape codes. The other objects displayed depend on whether you are printing a List or Form view. FORM View A number of additional fields are displayed for controlling multiple columns such as multi-column address labels. See Labels for full details. LIST View Group By List This lists any report groups for this report. See Report Groups. Summary Only Check Box If checked, only sub-total and total lines are printed. The "Group By" field values are printed with the summary values for the group. Note that an extra 4 characters are added at the start of each line for the summary type (Cnt, Tot, etc). You must define a Report Group for this to work. See the Address Book example database. Wrap Fields Check Box If checked this will wrap fields over succeeding lines where the field length is longer than the width defined for the view. The wrapping is done on word boundaries if possible. Press the OK button to start printing or the cancel button to cancel any changes you have entered. Saving the view will save all of your report settings. ========= Labels ============ Label printing is available for FORM type views only. You will normally define a special view and: Set Field Labels for the view to No Arrange the fields in the top left hand corner of the FORM screen to match the desired label format Use the following fields in the print requester to control your label format. Labels Across Number of labels to print across the page Label Width Width of each label. One additional space will be allowed between labels. If you want to print labels further apart, increase this value. Labels Down Number of labels to print down the page before starting a new column. For example 3 across and 4 down will print in the following sequence: 1 5 9 2 6 10 3 7 11 4 8 12 Label Height Height of each label in lines. An additional blank line will be printed between each label. The default is the number of lines in the form. You will probably want to set Lines Per Page to zero to suppress page breaks as well. If you are printing a single column of labels only, you can leave all of the above fields blank and let the number of lines in the form determine the label height. ======== Report Groups =================== You may know report groups as control breaks. A "group by" field is only printed when its value changes. You can also calculate summary values for each group. Each group can be based on several fields, although usually only one is used. Any number of fields may be summarised for a group. Note that records must be sorted into the correct sequence for this to work correctly. They are not sorted automatically. The types of groups available are Report. Gives a summary value for the whole report. If used, it must be the first group in the list. Page. Groups will start on a new page. Group fields will print before column headings. Subtitle Prints the group fields on a separate line at the start of each group. Reduces line length but best when each group contains a good number of records. Normal Field prints in the first line of the group only, but space is used in each line. You can have several levels of groups of the same type, but they must be listed from highest level to lowest. ============= Report Group Example ============ The following example shows two groups with totals. Group 1 : City Type: Normal Group Fields: City Summaries: Value (total) Group 2 : Salesman Type: Normal Group Fields: Salesman Summaries: Value (total) Resulting report: City Salesman Client Value ---------- ------------- -------------- --------- Brisbane Fred Smith ABC Company 8000.00 XYZ Limited 6400.00 Zip Electronics 12000.00 Salesman Tot 26400.00 John Brown ZZZ Computers 5000.00 GWZ Peripherals 7200.00 Salesman Tot 12200.00 City Tot 28600.00 Note: The file must be sorted over City and Salesman for this to print correctly. ========== Report Group Requester ============ This defines the type, grouping fields, and summaries for a single report group. Group string gadget Names the group. This name is printed on summary lines. Type Type of group View Fields list Lists the fields available in the current view. The selected field in this list can be added to either the Group Fields or Summaries lists. Group Fields list Lists the fields used for gouping. A new group starts when any of these fields change. A group field is not required for a Report level group. Summaries list Lists the fields to be summarised for this group. Selecting an item from this list will update the check boxes to show the summaries requested. Use the INS button to add the selected view field to this list. Tot, Cnt, Avg check boxes Show the summaries required for the currently selected Summary field. Any or all may be checked for one field. OK and Cancel Buttons Return to the Print Requester. ============== DEFINING FILES =================== Use the Project/New menu item to define a new file. Use the Project/Alter menu item to change the definition for the current file. You can change just about everything in a file definition, except the block size, even after you have loaded data to the file. You can change field names, types and lengths. You can add or delete fields, and add or delete indexes. Caution should be used when changing the type for fields that contain data. WARNING: Deleting a field makes its data inaccessible, even if you re-add the same field. If you accidentally delete a field, reload the definition without saving your changes and start your changes again. The fields defined for this file are listed in the box at the right of the window. Use the buttons beside the window to add, change or delete fields. If a field is highlighted when you press add, the new field will be added before the selected field. To add a field to the end of the list, select the "== End ==" item. The indexes (indices?) are listed in the box at the lower left. Use the buttons to add, change or delete indexes. ================ File Details ================= The file details are shown at the top left of the QFDefine window 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. The only way to change block size is to export the whole file, define a new data base and use import to recreate your file. Block size must be larger than the maximum record size plus free space, plus some space for control fields (2 bytes per field plus 2 bytes for the record length). Free Space 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 Maximum number of buffers QuickFile will use for holding blocks of records in memory. Unless you have very large files or are short of memory, use a large figure such as 100. QuickFile will never use more buffers than are required for the whole file. The more of the file in memory, the faster QuickFile works. The memory used is approximately (number of buffers * buffer size). WARNING. If you using a compression program like XFH-handler with QuickFile, set the number of buffers to 3. XFH will already have the decompressed copy of the file in ram. Ext. Path This is a default path used for images and external files. The file name in each record is stored as a name relative to this path, which can reduce the number of characters in each record. =========== Field Requester =========== Name string gadget Enter a name of up to 12 characters for the field. Note that changing the field name does not change the field title in any existing views. Length 60 characters is a practical maximum length as no left and right scrolling is provided and more characters cannot be displayed. The maximum is 250. The minimum length of a date field is 11 characters. Space is used only for the number of characters entered in each record, not for the maximum field length. In fact, if a field is empty it takes up no space at all. Decimals Number of decimals stored and displayed for the field. Values entered in the field will be rounded to this number of decimals. Type Listview Choose type of field. See below for the available types Mandatory Check Box If checked, the field must have a value in all records. You will not be able to add a new record without a value in this field. Justify Right Check Box If checked, the field is right justified. Integer, Float, and Caculated fields default to right, character and date fields default to left. Expression String Gadget Contents depend on field type Calc: The expression to calculate the field value Cycle: The list of possible values See field types for more detail. Command For an External field, this is the command string to be run to process the field content. =============== Field Types =============== Character General character string. Integer Whole number, no decimals. Float. Real numbers with decimals. Calculated The field value is calculated from other fields, which may themselves be calculated fields. Enter the calculation in the expression string gadget. The expression can contain field names, constants and operators. Field names containing spaces must be enclosed in double quotes ("). Normal precedence rules apply and brackets may be used to control evaluation order. Fields must be defined before they can be referenced. For numeric fields (Float, Integer and Time) the operators are add (+), subtract (-), multiply (*) and divide (/). Example: Cost + Cost * Markup / 100 For all other fields only concatenate operators can be used. Use + to leave a space between values. Use | to join fields without leaving a space. Constants are preceded by the letter c, enclosed in double quotes and can be no longer than 7 characters. You can include any field type in the expression for a character field. Example: c"Dear" + Title + LastName or Pathname | FileName Date These have a minimum length of 11 characters and are always entered as day/month/year. The separator can be any of /-. or a space. Month can be entered as a number or a three character name. Year can be entered as two or four digits. If two digits are used, a number greater than 50 is assumed to be this century, 50 or less, the next century. For example 03/08/93 3-8-93 3.aug.93 03 aug 1993 are all valid Dates are always displayed in the format 14-Apr-1993. Time These are in the format of hh:mm:ss. For entering data, the separator can be either : or a space. You can omit trailing (low order) values and they will default to zero. Examples: 3:10 will be taken as 03:10:00, 2 will be taken as 02:00:00 Cycle A list of values is associated with a cycle field. The value is maintained using a cycling button instead of a string gadget. Enter the list of values, separated by commas, in the expression string gadget. Any spaces you enter will be included in the value - you probably don't want leading spaces. for example Blue,Green,Light Blue,Red instead of Blue, Green, Light Blue, Red Image An image that is displayed in the QuickFile window. Only the file name is stored in the database. External Stores strings (typically file names) that are passed to an external program for processing. This can be used for images, sounds, text files, animations or whatever. Enter the command line in the Command string gadget when defining the field. Use %s to indicate where the field value is to be inserted. For example: dh0:utilities/display %s The full path name of the command is required unless it is in the c: logical device. ============== Indexes ============= You must define at least one index. If you are not sure pick any field that will give a useful sequence, such as surname, title etc. Each index can use a number of fields to give precise control of sequence. You can have any number of indexes but you should limit yourself to those you are going to use regularly. You can index on any field type including calculated fields. You can also define an index as unique to prevent duplicate records being created. If you change an index on an existing file, it will be rebuilt when you return to the main display panel. Select the index from the list and press the appropriate button. The Index Requester is used to define or alter an index definition. Indexes are maintained automatically as you add, modify and delete records on your file so they reduce the need for sorting and resorting. ============ Define Index Requester ================= Name Identifies the index and is also used to form the index file name. Unique CheckBox If checked, duplicate index entries will not be allowed. Available Fields Lists fields defined in this file. Clicking on a field will add it to the fields selected for this index. Index Fields Lists fields in the current index. The order of the fields in this box determines their priority in the sort. The first field is the primary key, the second will only be used for records where the first keys are equal and so on. Clicking on a field in this list will select it and display its name and length below the list box. If a field is highlighted, any new fields will be added before the highlighted field, otherwise new fields will be added at the end. To remove highlighting click in the blank part of the box. Length Changing this length allows you to index on part of a long field. This reduces memory usage and may increase speed. IMPORTANT: YOU MUST PRESS ENTER OR RETURN AFTER CHANGING A LENGTH OR YOUR CHANGES WILL BE IGNORED Order Buttons Select A..Z for ascending order or Z..A for descending order. You can mix these on different fields in the same index. Delete Deletes the highlighted field from the Index Fields list. ===== FILE NAMES ============= QuickFile uses four types of file distinguished by extension. Changing these with an 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. VIEW files usually have an extension of .View INDEX FILES have an extension of .nameX where 'name' is the name of the index as specified in the file definition. ========== POSSIBLE PROBLEMS ================= You add a field to a file and but it does not display in a form or list. This happens because fields are not added to a view automatically. If you add a file to a file, you must also add it to any views using the View/Alter menu item. Note that if you have not saved a view, QuickFile generates a default view which will be updated automatically. Error message: "getblock: Block not found". This is usually due to a mismatch between the index and data files. To correct this you can rebuild an index by selecting the Rebuild Index item from the QuickFile tools menu, or you can delete the index file (called filename.indnameX). When you next open the file, the index will be rebuilt. INTEGRITY PROBLEMS It is possible for an index and data file to get out of synchronisation. This can be caused by not closing a file properly, typically because of a guru or power loss with a file open. If you suspect an index has been corrupted in some way, you can delete the index file (called filename.indnameX). When you next open the file, the index will be rebuilt. This is indicated by a message such as "getblock: Block not found" being displayed in the Console window. You can also rebuild an index by selecting the Rebuild Index item from the QuickFile Order menu. IF YOU ARE SHORT OF MEMORY Some tips for reducing memory requirements: Disable the online help. You can do this using the Configuration item on the Options menu Ensure the Memory Save checkbox is checked in the Config requester. This will reduce the memory used during sorts. Define only a single index. That is still one more than most programs allow. Hard drive users can reduce the number of buffers. This will also work with floppies but may be unacceptably slow. If you are using a compression program such as XFH-handler, reduce the number of buffers in the file definition to 3. Otherwise both XFH and QuickFile will be holding the file in ram: BUGS The program has been reasonably tested, but only on my A500. Some bugs refuse to show up until you hit exactly the right combination of conditions, so please let me know of any problems you find. Known problems (limitations really) are: - If you drag a field off the bottom of the window, the drag box is drawn over the border but is not erased properly if you release the mouse button. - A Field is clipped horizontally, but not vertically, if it does not fit completely in the visible window. This causes images to disappear instead of being clipped if you make the window too small. - No attempt is made to remap image palettes. You may get odd colours or a block of a single colour. - Switching views from an ARexx macro can cause a series of window redraws to occur after the macro has completed. This is because switching views can cause window resize messages to be sent by Intuition and these are not seen by QuickFile until the macro completes. - Disk thrashing can occur on startup if the file contains images because QuickFile is trying to load an image while AmigaGuide is scanning the QuickFile.guide file. If you write to me with a problem you would like fixed, it is much easier for me if you send a copy of your database, the version of the program you are using, and instructions on how to duplicate the problem. ========== Program Limits ============== Field Length While up to 250 characters are allowed per field, this is not very useful as each field is limited to one line. Number of Records per File The theoretical limit is currently 65,535. In practice it is much lower because of the indexing technique which will run out of either memory or processor speed. Each index requires a contiguous area of RAM 4(n + 200) bytes in size, where n is the number of records in the file. The sort technique also limits the size of the file. The sort loads all sort keys to ram and also requires 8 bytes per record in one contiguous area. A realistic maximum is probably in the order of 10,000 to 20,000. Number of fields per record 250. But I got bored at about 60, so you take your chances if you want to try more. Number of indexes No limit.