Visit Atarimax Store


Free-Net Logo
The Atari SIG Historical Archive
Created and hosted by: atarimax.com
[ HOME | GO ATARI | 8-BIT | ST/TT | PORTFOLIO | LYNX | JAGUAR | LIBRARY ]


Article #119 (145 is last):
Newsgroups: freenet.sci.comp.atari.library
From: aa700@cleveland.Freenet.Edu (Michael Current)
Subject: DOCS: Diskbase
Posted-By: xx004 (aa700 - Michael Current)
Reply-To: aa700@cleveland.Freenet.Edu (Michael Current)
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: currentm@carleton.edu / UUCP: ...!umn-cs!ccnfld!currentm
      BITNET: currentm%carleton.edu@interbit / Cleveland Free-Net: aa700





Visit Atarimax Store