DOCS: DiskbaseFrom: Michael Current (aa700@cleveland.Freenet.Edu)
Date: 01/28/92-10:46:35 PM Z
- Next message by date: Michael Current: "DOCS: DeTerm"
- Previous message by date: Michael Current: "The Freezer: cold-boot & protect RAMdisk"
- Return to Index: Sort by: [ date ] [ author ] [ thread ] [ subject ]
From: aa700@cleveland.Freenet.Edu (Michael Current) Subject: DOCS: Diskbase Date: Tue Jan 28 22:46:35 1992 Reprinted from the A.C.E.C. BBS (614)-471-8559 DISKBASE 1.0 Documentation April 1988 Todd Bake 722 Clairepointe St. Clair Shores, Mi. 48081 DISKBASE is a public domain database program for Atari 8-bit computers. Designed for ease of use, DISKBASE has many powerful features such as the ability to print records and fields selectively, to read data from ascii files, to copy all or some records or just the data "structure", and to sort files of over 2500 records (regardless of record size) without any additional disk space required! DISKBASE requires 48K and can be used with any DOS with a MEMLO of $1D00 or less (this includes Atari DOS 2.0 and 2.5, DOS XL, and SpartaDOS). IMPORTANT NOTE: If you are using SpartaDOS, do NOT use the "TDLINE" program, as this interferes with DISKBASE's functioning. Also you should set KEY OFF, since DISKBASE has it's own "fast key" feature (assuming you're using an XL or XE). Each of DISKBASE's features are discussed below. MAIN MENU After DISKBASE loads, the Main Menu is displayed. Besides the choices listed in the menu, there are the following additional features: Pressing "!" causes the write verify feature of DOS to be toggled on and off. Turning write verify off speeds up the write-to-disk process a little, and usually it's safe enough to do without it; if you want to be cautious, though, the verify feature can be left on (the default). You may also press "?" to see the amount of free memory left, although this has no bearing on how much space is left for new records (that depends on disk space only); it merely reflects the remaining memory buffer space. Generally speaking, you don't need to worry about this; it will only affect the maximum number of records that can be sorted, which will vary depending on the record size. Each of the items on the Main Menu is discussed below. page 1 DOS FUNCTIONS These are the same as the usual DOS functions and fairly self-explanatory, with the exception of COPY RECORDS and WRITE STRUCTURE. Since DISKBASE files use absolute sector/byte pointers, you should not use the regular DOS Copy feature to duplicate them; if you do, the new file will not contain valid pointers for its new location on the disk. Instead, use this built-in COPY routine. Unfortunately, because of the small amount of buffer space available to the program, you need two drives (or a RAMdisk) to copy a file between disks, as disk switching isn't supported. The DOS Duplicate Disk function can be used, however. NOTE: If you're using SpartaDOS, then you CAN use the DOS Copy function to copy DISKBASE files after all, since Sparta returns relative file pointers, not absolute. If you copy Sparta files to or from other DOS's, though, you must use DISKBASE's COPY feature. Besides copying entire files, COPY RECORDS lets you copy just selected records if you choose. After being prompted for the destination filename, you are asked to input a conditional expression describing which records you want to be included in the new file. Just press RETURN to copy the whole file, or enter a conditional expression as described under the PRINT RECORDS section of this documentation, if you want only certain records transferred. WRITE STRUCTURE is the same as COPY, except that only the file header information (field names/lengths, etc.) is copied, not the data itself. You can use this to start a new file with the same field definitions, but different data. Press "M" to return to the Main Menu. OPEN FILE This is used to create a new file or open an old file for changes or additions. When you select this option, you are prompted for a filename. If the file is not found, then DISKBASE assumes you want to start a new file. (If you made a mistake, you can press ESC to abort, here and most other places in the program.) If any file is already open when you select this option, it is saved and closed before the "new" file is opened. Opening a New File You will be prompted for the number of fields you want in each record, which can be from 1 to 255. Then you are asked for the field name length; this is simply the size of the "label", which is the same for all fields. It can be from 1 to 20. Obviously, if you have a large number of fields, you'll want to keep the field name length short; remember you'll still need room in the buffer for a least one record! page 2 Next the field name/length entry screen will appear, and you will be prompted to enter a name and length for each field. Pressing RETURN moves the cursor from Field Name to Field Length, or from Field Length to Field Name on the next line. You can use the up and down arrow keys to move from one line to another if you wish to make changes to what you have already entered. If you specified more fields than can fit on one screen, then the screen will scroll up when you reach the end; or it will scroll down again if you move the cursor back up past the top. You don't HAVE to enter a name for each field now, and you can come back and change field names (but not lengths!) later, but if you don't enter names, you won't be able to specify fields for the PRINT and SORT and SEARCH routines until you do, so enter something. Field lengths can be from 1 to 255. When you're sure the file has been defined the way you want it, press ESC. The file will be created, and you will be returned to the Main Menu. Opening an Old File After you enter the filename, the file will be opened and you will be returned to the Main Menu. Whenever a file is open, its name will be displayed at the bottom of the Main Menu screen. Needless to say, you should NEVER remove the disk when a file is open! ALTER FIELDS If you want to change the field names of an already created file, as stated above, this function allows you to do so. The file must be open; then selecting ALTER FIELDS will take you to the field name/length entry screen as described above. You will not be able to change field lengths at this point, however, only names. Press ESC when you're finished and the changes will be recorded. CHANGE RECORDS Once a file is opened, select CHANGE RECORDS to change or add data. This will take you to the edit screen, where the first record will be displayed. The Edit Screen At the top of the edit screen, the name of the currently open file is displayed, as well as the current record number followed by the total number of records in the file separated by a slash (e.g., "1/12"). Also shown is the number and length of the field that the cursor is currently positioned on. Below this information, the name and contents of each field is displayed. For instance: page 3 Name :Todd Bake Address :722 Clairepointe City :St.Clair Shores State :Mi Zip :48081 If a field is too long to fit on the screen, then only part of it will show. However, this "window" can be scrolled to view or edit the entire contents of the field. In CHANGE mode, moving the cursor past the end of the line will cause the window to scroll left; moving the cursor back past the beginning of the window will cause it to scroll right. You can also use TAB and CTRL-TAB to move the cursor and scroll the window by larger amounts. In VIEW mode (see below), the cursor will appear on the colon separating the field name from the data; pressing the left or right arrow keys, TAB or CTRL-TAB will scroll the window. Pressing the up and down arrow keys will move the cursor from one field to another. Pressing RETURN will also move you to the next field. If there are too many fields to fit on one screen, then the screen will scroll up or down when the cursor moves past the bottom or top. You can also press CTRL-U to scroll up a whole page or CTRL-D to scroll down a page, or CTRL-T to go to the "top" (first field) or CTRL-B to go to the "bottom" (last field). (You don't have to press CTRL if you're in VIEW mode.) To edit the contents of a field in CHANGE mode, simply type in the data you wish. Note that all the usual editing keys such as insert and delete function normally within the window. (All fields are interpreted as strings, so you should right-justify any numerical data, if you think you will want to sort records by those fields later.) Press CTRL-N to go to the next record, or CTRL-P to go to the previous record (just N or P in VIEW mode). You will also go to the next record automatically if you press RETURN while in the last field. The Options Menu Line Pressing ESC in CHANGE or VIEW modes causes the Options Menu Line to appear at the bottom of the screen. These options are each described below. GOTO # To go to a particular record, press "G" at the Options Menu, then enter the desired record number. FIND To search for a record with a particular contents, press "F". You will be prompted for a field name and a string to search for. page 4 You don't have to enter the entire field name, just enough of it to distinguish it from any other field; likewise anything that begins with the string you entered will match. You will also be asked if you want the search to proceed forward or backward from the current point, or to be global (search the whole file). Press "+" to search forward, "-" to search backward, or "G" to search the whole file starting at the beginning. When a record containing the specified data is found, you are asked if you want the search to continue. Press "Y" to continue to search past that record, or "N" to stop there for further editing/viewing. You may also cancel the search at any time by pressing ESC. DELETE Press "D" to delete the current record. You will be asked to verify that you want the record deleted, and if you then respond "Y", the record will be removed. Deleted records CANNOT be "undeleted", so make sure that's really what you want before you confirm! (Technical note: deleted records are actually placed at the end of the file as blanks, so deleting a record will not reduce the file size. If you need to free up some space on your disk, you can COPY the file to another name, then erase the old file containing the extra blank records. Of course, the blanks at the end of the file are used for the new records that you add, so there is no need to go through the copying procedure if you know you will be adding new records.) BOF Press "B" to go to the Beginning of the File, i.e., record number 1. EOF Press "E" to go to the End of the File, the last record. CHANGE/VIEW In either the CHANGE or VIEW mode, you can switch to the alternate mode by pressing "C" or "V", as appropriate, from the Options Menu. Press M to return to the Main Menu. Press ESC to return to editing/viewing if you don't wish to select any of these options. VIEW RECORDS Selecting VIEW RECORDS from the Main Menu is much the same as CHANGE RECORDS, except as noted above. page 5 READ RECORDS By selecting this option, you can read data into the currently open file from an ascii file. This allows you to use your favorite word processor to create data files, then enter them to DISKBASE for management. Such ascii files can also be created by DISKBASE itself, and files in this form can of course be copied using the standard Copy function of whatever DOS you're using, unlike regular DISKBASE files. When you select READ RECORDS you will be prompted for a filename, and if the file is found, its contents will be read in and added to the end of the open database. You can interrupt the READ process by pressing START. When creating ascii files using a word processor, each field should end in a RETURN. Do NOT put an extra RETURN between records. Essentially READ treats input from the file you specify as if it were keyboard input, after first going to the end of the file and entering CHANGE mode. (You could conceivably take advantage of this fact by placing characters in the ascii file corresponding to various DISKBASE keypresses, to achieve macro-like effects.) PRINT RECORDS DISKBASE allows you to send records to a printer, disk file, or the screen, in three different formats. You can print all or just certain fields, of all or just certain records. First you are prompted as to where you want the output sent. If you choose printer output, you are also given the option of entering a printer control string, i.e., a string of characters to format your particular printer for whatever kind of pitch or page spacing that you prefer; see your printer manual for specifics. If you select disk output, you are prompted for a filename. (Remember you can press ESC at any of these points to cancel the procedure.) You are then prompted to select the format of the output. Pick "1-regular format" to print records in a form resembling the way they appear on the edit screen, "2-horizontal format" to print one record per line across the page, or "3-data only" to create ascii files that DISKBASE can READ back in again. Press the corresponding number key. Next you are asked to specify which fields to print. Just enter a blank if you want to print all fields, otherwise enter the names of the fields you want to be printed, one at a time. When you're finished, enter a blank to continue. Finally you are asked to type a conditional expression to specify which records you want printed. Just press RETURN to print all records. Otherwise, enter the conditional expression in this form: page 6 #=integer ...or... fieldname="string" You are not limited to the equals sign; you can use =, <, >, <=, >=, or <> as comparisons. "#=integer" specifies which record numbers to print. Literally, you might enter: #=3 ...to print record 3, or #<127 ...to print all records less than 127. Or: #>=34 ...to print records greater than or equal to 34. Examples of fieldname/string comparisons are: city="Detroit" ...or... LastName<"Smith" ...and so on. Note that you DO NOT put quotes around the field name, but you DO put quotes around the comparison string. Note also that as with the Search function described previously, any field that begins with the specified string will match, regardless of what characters follow. To avoid undesired matches of this sort, you could enter: LastName="Smith " ...with some trailing blanks to insure that something like "Smithley" wouldn't match. You can also use parentheses, "&" (for AND) and "" (for OR), to create as complex an expression as you wish. For example: #<100 & (name="Smith" name="Jones") ...would print records less than 100 whose "name" field was "Smith" or "Jones". Note that "&" takes precedence over "" unless parentheses are used. Without the parentheses, the above example would print records less than 100 whose "name" field was "Smith", and also ANY records whose "name" was "Jones". (If you're in doubt about page 7 precedence, just use parentheses.) Nested parentheses are okay too. Note that the conditional expression may be up to 250 characters, although the input window is only 24 characters wide; it will scroll if necessary the same as input windows on the edit screen. After you enter the expression, printing proceeds. Press ESC to cancel printing. (All of the above rules also apply to the conditional expression entered when using COPY RECORDS, mentioned previously.) SORT Since all of the available buffer space is used by the Sort routine, whatever file is currently open (if any) is saved and closed when you make this selection. You are asked for the name of the file you want sorted. If the file is extraordinarily huge (over 2600 records or so depending on record size, field name length, etc.), DISKBASE may not be able to sort it. (Three bytes are required for each record in the file, and the free memory area is about 8K; also space is needed for the field names and lengths.) In any case, DISKBASE will let you know if the file is too big to sort. If all is well, you will then be asked if you want an ascending (A-Z) or descending (Z-A) sort. Press "+" for ascending, "-" for descending. DISKBASE will report as it indexes, sorts, then relinks the file in sorted order. The contents of the records is not actually moved, only the pointers connecting the records. This means that the links between the records will be somewhat convoluted after the sort; record 1 may be near the beginning of the physical file and record 2 near the end, etc. This will cause no problem for DISKBASE's handling of the file, but it may slow down subsequent Search and Print procedures somewhat. Therefore, it's highly recommended that, if possible, you use the Copy function to first move any file to be sorted to RAMdisk, sort it there, then Copy it back to the floppy disk. The sort will be MUCH faster on the RAMdisk, and when the file is Copied back to floppy, the pointers will be "untangled" so that consecutive records will actually be next to each other on the disk. ESC: Close File Pressing ESC from the Main Menu saves the buffer and closes the currently open file. Be SURE to do this before leaving the program, or you may lose changes in your data or even foul up the file irreparably. When you are ready to leave the program, do so by pressing RESET. TECHNICAL STUFF In case anyone wants to write their own programs to manipulate page 8 DISKBASE files, or just happens to be curious, here are some notes on the file structure. DISKBASE files consist of a header, followed by records in the form of a doubly-linked list. When the file is first created, the list will consist of all blank records; when the user adds records beyond the last blank, a new block of blanks is appended (a message to this effect is displayed at the bottom of the screen when this occurs). The size of a block is equal to the number of records in the memory buffer. The minimum buffer size is a half K; if the user defines a record size smaller than that, then there will be a number of records in the buffer. If the record size is larger than 512 bytes, then the buffer is expanded to accommodate at least one record. A DISKBASE file will always contain a number of actual records (counting blanks) evenly divisible by the number of records in the buffer. Even a file with no records input by the user will contain one block of blanks into which newly entered records will be placed. Each record begins with 6 bytes of pointer information: the sector/byte location of the previous record, and the sector/byte location of the next record. (The sector value is 2 bytes, LSB first.) Record 1 points to 0,0 as its previous record, and the final record points to a random location as its next record (actually it points to where the next record would be appended, if it were appended at that time, but that may change). Following the pointer information is the actual data of the record. Fields are not delimited in any way. The header consists of the following: 1 byte: the version number (1) (files that don't begin with this byte will be rejected by DISKBASE when the user tries to open them). 2 bytes: LSB,MSB of the number of non-blank records in the file. 2 bytes: LSB,MSB of the total number of records in the file, including blanks. page 9 3 bytes: file pointer (sector LSB,MSB; byte) to the last record in the file, including blanks. 1 byte: the number of fields in each record. 1 byte: the field name length. n bytes: the field names; the size of this part of the header equals the number of fields times the field name length. n bytes: the field data lengths; the size of this part is equal to the number of fields, each byte signifying the length of the corresponding field. 3 bytes: file pointer (sector LSB,MSB; byte) to the first record in the file. 3 bytes: file pointer (sector LSB,MSB; byte) to the last non-blank in the file. A FINAL NOTE DISKBASE can handle up to 65536 records. Since each record must consist of at least 7 bytes, that many records would take up 458,752 bytes, which is more than even a double-sided, double-density disk contains. Just in case you're one of those rare people rich enough to afford a hard drive, however, consider yourself warned. (Though I can't imagine anyone typing in two-to-the-sixteenth-power records anyway!) ------------------------------------------------------------------- page 10 -- Michael Current, Cleveland Free-Net 8-bit Atari SIGOp -->> go atari8 <<-- The Cleveland Free-Net Atari SIG is the Central Atari Information Network Internet: firstname.lastname@example.org / UUCP: ...!umn-cs!ccnfld!currentm BITNET: currentm%carleton.edu@interbit / Cleveland Free-Net: aa700
- Next message by date: Michael Current: "DOCS: DeTerm"
- Previous message by date: Michael Current: "The Freezer: cold-boot & protect RAMdisk"
----------------------------------------- Return to message index