home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
The Fred Fish Collection 1.5
/
ffcollection-1-5-1992-11.iso
/
ff_disks
/
300-399
/
ff369.lzh
/
AQData
/
AquaDoc
< prev
next >
Wrap
Text File
|
1990-08-15
|
12KB
|
225 lines
The following is information provided for those wishing to update and
maintain the Aquarium V1.12 data base files. Aquarium and NewFish are
programs from Disk 301 submitted to the AmigaLib Disk collection by
B Lennart Olsson. The programs are copyright 1989, however, they are
redistributable when the Aquarium.DOC file (copyright header prepended)
is included in the distribution. See AmigaLib Disk 301 documentation
for details.
This document has a short description of the Aquarium V1.12 data base.
The data base is in the Aquarium directory "data", and consists of just
four files (not including the .info file), all of which are described
below.
KeyNames
The KeyNames file contains the text which will appear in the search
key subwindows upon running the Aquarium program. The file has 30 or
more lines. The file is a completely ASCII readable file, which is
easily edited or repaired (if you have even a remotely recent copy and
a fair memory). The file has its own documentation (beyond line 30).
Only the first 15 characters of each of the first 30 lines are used by
the Aquarium program for initialization of the subwindows. Changing
the meaning of any of these keys will in concert require working over
the entire database one fish at a time to therein set or reset the key
in accordance with the newly assigned meaning for each changed key.
This update has utilized the formerly one remaining empty key, giving
it the title "Enhancements". All of the programs in the data base that
have Contents files which mention ARP or Rexx have been thus tagged.
I hope you are not inconvenienced by this; it should help most users
in tracking FD software support for these important Amiga enhancements.
Names
The Names file contains one 20-byte record for each item in the index,
where an item is defined by one left-justified entry in a README.list
or Contents file from an AmigaLib Disk. However, there are instances
where the contents of an entire disk is entered as a generalized item,
such as "Disk#_64". With such global names excepted, the consecutive
printable characters in the item name are followed by spaces, with a
null terminator as the last character. The characters of a properly
installed global name are followed immediately by a null character with
spaces up to the last character; again, the last character is a null
terminator. Spaces are not allowed within names. Note that the update
program included in the Aquarium distribution (NewFish V1.03 (c) 1988
B Lennart Olsson) will not produces global names with this interminary
null character; however, the character can be easily produced whenever
necessary by means of a binary file editor such as NewZap.
Two examples are shown below (note that the spacing count is crucial):
Disk#_64\000 \000
Aquarium \000
The data base in this update has 1836 names; these names are referenced
as "fish" in the Aquarium. Those maintaining their own data base will
have 1846 names if they are current to Disk 360. This data base is
changed in the following ways:
Disk 57 was withdrawn due to copyright problems. It was then
re-issued as Disk 97. The six entries in the V1.12 Aquarium
data base attributable to Disk 57 have thus been removed, and
a retraction notice, such as was already in the data base for
Disk 80, was substituted.
Six other items were removed from the data base, one each for
Disks 173, 221, 230, 238, 305, and 324 as these items have
been withdrawn from distribution (other items on the disks
that are yet in the catalog will be available on these same
disk numbers, but re-issued with an "a" appended to the disk
name). The Aquarium program (Ver 1.12) knows nothing of "a"
disk name extensions, but no matter, only a volume number is
needed in order to examine the currently available contents
of these disks in this data base.
Disk 176, formerly named "Disk#_176" featured an early release
of "AnalytiCalc" and a construct titled "Hypertext." In this
data base they are separately named, resulting in the creation
of an additional item - thus an additional "fish" entry.
Several global entries with multiple null trailers (linefeeds
in Aquarium's printing operations) were changed to conform to
the space-separated two-null global format described above.
index
The index file is the most important file in the data base. If the
index is damaged, the database will be difficult to repair. As Lennart
suggests, always preserve a copy of the data base files before using
the NewFish program or before working on the files with binary file
editors. The index file consists of sequential 14 byte records, as
many records as there are items (fish) in the data base. The meaning
assigned to the bits in each index item record is described next.
The appearance of a short group of records near the end of this update
of the index is shown below:
A B C D E F G H I J K L M N
00 04 34 a0 01 5c 00 08 2d 49 01 61 00 00
04 00 06 b0 01 5d 00 08 2e aa 02 44 00 00
04 40 80 04 01 5e 00 08 30 ee 00 b2 00 00
00 42 12 15 01 5e 00 08 31 a0 00 ef 00 00
00 20 14 04 01 5e 00 08 32 8f 01 b9 00 00
08 00 02 38 01 5e 00 08 34 48 01 af 00 00
00 00 16 10 01 5f 00 08 35 f7 02 5e 00 00
00 80 16 12 01 60 00 08 38 55 01 4b 00 00
The one-byte wide columns have the following assigned content:
A through D Keys Show which of 30 search keys are set.
E through F Disk AmigaLib Disk number
G through J ItemAdr Absolute addrs of data file item texts.
K through L ItemSiz Contents record size including trailer.
M through N Delim Record separator bytes (null).
The Aquarium window has a rectangular area containing 30 search key
subwindows. Each search key is assigned one bit of the first longword
of the record. The two MSBs (lefthand bits) are always zero, and the
others are set by the user via mouse selects in the red "keys" window.
The top leftmost search key is the rightmost bit (LSB) of the longword.
The top next-to-leftmost search item (row 1, column 2) is the 2nd LSB,
and the sixth LSB is again back to the leftmost column next-to-the-top
row (row 2, column 1).
The ItemAdr is the absolute address of the first byte of the Contents
file record in the file "data". It is this construct that makes the
Aquarium data base a quickly readable structure, but it does so at the
cost of serious inflexibility in so far as insert/delete operations are
concerned. To insert or delete an item requires recalculation of all
of the following absolute Contents record addresses. A phase error
between the index file and the data file will result in a "graceful"
termination of the Aquarium program execution and a return of program
resources to the AmigaDOS Exec on exit.
data
This is a variable-length record file which contains the concatenated
AmigaLib Disk README.list and Contents files. The text of each file
consists of lines of characters, each with one null terminator. The
field separator between files is a 56 null character string. The char
count in the separator must be 56 null characters. The separator field
appears as a 57 null character group when the data file is perused with
a binary editor, owing to the seeming inclusion of the null character
that terminates the last line of the file. As explained above, the
index file contains address pointers to the first readable character
of each item, and contains a size value for each item including the
item separator. The data file is easily edited with a binary file
editor such as NewZap. Usually, but quite definitely not always, the
last line of a Contents file has the names of the contributors, i.e.,
Author: Gill Green and Dorsal Fin
This update of the data base contains several minor modifications to
the Contents files found in the original Aquarium release. The bases
track fairly well up to about AmigaLib Disk 163, but then for some
reason there were lots of entries that were different by a few bytes.
Examination of the two data base files revealed that either Lennart
has a Contents file processor that, among other things, trims spaces
at the ends of lines (as are on occasion found in the Contents files
of the AmigaLib disks sent to my by Fred), or Lennart's disks are
different from the ones I have. Lennart does recommend copying the
Contents files from disks that are to be appended to the data base,
and editing them for form. This will help to head off an inappropriate
entry now and then. For my part I ran into various problems in this
regard, ranging from free-format README.list files which did not have
separated items, European characters embedded in Author names (these
cause truncation - see Disk 19 or Disk 163 for example), and failure
to eliminate blank lines in Contents items when constructing the file
manually. (This is an error I would make now and then.) I know I did
a lot of incidental correction, such as adding the name of Bill Nelson
to the otherwise blank Author field on AmigaLib Disk 237 (CType entry).
Truncating the data base
As careful as you may be in adding new fish to the Aquarium, the time
will likely come when you will either enter a poorly formed Contents
file, or will abort during the entry. When this occurs, it will be
necessary to truncate the data base. The description above will allow
you do this via the knowledge of just where it is you must cleave the
forms. If you were caught in the middle of adding a new disk, you must
truncate back to the previous disk number (examine columns E and F of
the index.) A truncated Names file size must be an integral product of
20 bytes times the number of records, and the index file size must be
an integral product of 14 bytes times the same number of records.
The data base provided here has 1836 records per data base file, except
of course, the KeyNames file. The truncation may be accomplished with
a disk editor (DiskX, Sec, etc.), or you may wish to use the FileMaster
program on AmigaLib Disk 298, which has the ability to do binary edits
and to shorten as well as lengthen files. If the data base should be
corrupted, you are in for heavy duty work on the index file once the
data file is corrected because of the need to recalculate some several
hundered absolute data pointers. It would seem an easy task to write
a stdio filter program to do this, though, would it not? Another way
to get this out would be to utilize the assembly language guts of the
DezHexBin program on AmigLib Disk 321 to make an appropriate filter.
Other Maintenance Items
Included in this kit is a list of all of the README.list/Contents
files I found necessary to change in order to deal with the data base.
The file READMElist has these files listed all as README.list###
files since as Contents files they would be indistinguishable from
each another when it comes to placement in a directory for reference.
Bugs
The Aquarium program itself is seemingly bug free. However, as Lennart
himself admits, the NewFish program is rather touchy. If possible, use
NewFish from a Non-Interlaced workbench CLI. If you use interlace, you
will likely experience loss of all of the screen icons upon exit.
There will not likely be any permanent damage to anything as a result
of the condition which comes along with this situation; I have never
had any data base file or icon file destruction as a result of it, and
it does not cause the machine to crash (at least not right away). This
may only be a problem with Aquarium V1.12 in the AmigaDOS environment,
and may be found to have been remedied in future versions - I suppose
you'll have to speak with Lennart if you want help on this one.