DOCS: Diskbase
From: Michael Current (aa700@cleveland.Freenet.Edu)
Date: 01/28/92-10:46:35 PM Z
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: currentm@carleton.edu / UUCP: ...!umn-cs!ccnfld!currentm
BITNET: currentm%carleton.edu@interbit / Cleveland Free-Net: aa700
-----------------------------------------
Return to message index
