Gold Fish 1/GoldFishApril1994_CD1.img/kingfisher/kingfisher.doc

Text File | 1994-04-15 | 19KB | 462 lines

KingFisher 2.0
Copyright © 1992-1994 by Udo Schuermann
All rights reserved



0  NOTICE -----------------------------------------------------------------

This document is a preliminary copy that describes some features of
KingFisher 2.0 that may not all be functional.  Please be aware of the fact
that KingFisher 2.0 is currently a BETA release and not a finished product
by any stretch of the imagination.  Much, MUCH, *MUCH* more is coming!
(Just look at what is "hidden" in the menus for a HINT of the future.)



1  INTRODUCTION -----------------------------------------------------------

Despite rapid growth of KingFisher Release 1 (1.0 through 1.40) KingFisher
has retained largely the same interface.  It was my first serious project
for the Amiga, through which I not only learned how to program the machine,
but also how to listen to users and work towards a more flexible solution
that offers the necessary growth potential.

The result of this effort is KingFisher 2.0, not just a rewrite of the
original, but a complete redesign of the underlying concepts.  This makes
KingFisher 2.0 a significantly more powerful product.  Alas, it has also
grown somewhat in complexity.

This document attempts to outline the concepts behind KingFisher 2.0 to
give you the necessary understanding of what KingFisher has grown up to
become.



2  FEATURES ---------------------------------------------------------------

Before we dwell on the implementation details, let us examine what this new
KingFisher can do for you:

1. You get a fully (proportional) font-sensitive GadTools interface that
   runs in a window on the default public screen.  You can resize this
   window to your heart's content,

2. You can run two or more copies of KingFisher, run them side-by-side in
   their own windows, use one to search, and the other to examine data,

3. You can access more than just a single database!  You can now view the
   Original Fred Fish database (Disks 1 through 1000) then switch to the
   Aminet Database, then select your club's disk collection.  Run two
   copies of KingFisher and search one database while viewing another, or
   search two databases simultaneously!

Do you like it so far?

4. KingFisher now supports Fred Fish's new field-oriented database format
   (which I helped design) so you can perform relational searches based on
   only specific fields,

5. Were the original six search expressions not enough for you?  Would you
   have liked to maintain a larger set of expressions to reference later?
   KingFisher now supports a list of search expressions whose size limit is
   yours to set and revise as you like,

6. Did you ever wish you could easily scan through all fish that a search
   revealed without having to perform lengthy backward searches?  This is
   now a reality with Search Sets, any number of which you can even save to
   disk and retrieve at later times!

Sounding better than ever?

7. Avoid finding, over and over again, programs you already have, or ones
   which you already have evaluated, or are not interested in.  KingFisher
   2.0 lets you mark fish in the database so that searches will never find
   them if you want them to stay hidden.

8. Parlez-vous Français?  Sprechen Sie Deutsch?  Habla Español?  Parla
   Italiano?  KingFisher is fully localized, ready to speak YOUR language.
   Change KingFisher's language to one you don't know and learn a foreign
   language.  Amaze your friends!  Amaze yourself!  ;-)

9. Localized, context sensitive AmigaGuide®-based help and information is
   just a keystroke away.

Can't wait to see this marvel in action?  Then read on:



3  CLIENT-SERVER ARCHITECTURE ---------------------------------------------

KingFisher 2.0 is no longer a single, self-contained application.  As such,
it is not enough to start a single program, use it, and shut it down again.
At the heart of this new-found flexibility lies a concept known as the
Client-Server Model.  The concept is simple:

One program (the Server) handles access to the databases and responds to
access requests from one or more clients.  The clients need to know nothing
of the database format itself, and the server needs to know nothing about
how to present the data.  Each is highly specialized and can therefore be
more expert in its field.

The "KingFisher 2.0 Database Server" is the server application which must
run in the background.  The program will consume about 50K of memory while
it is running.  You can close its status window if it bothers you and it
will open it again only when it wants to inform you of something.

You can then run one or more client applications which will connect to the
server and let you access the database.  The "KingFisher 2.0 Package" comes
with several such client applications in addition to the ever-needed
server:

1. KingFisher 2.0
   This is the GadTools interface which we introduced above.  Documentation
   for KingFisher will be given in another place.
   NOTE: As of the BETA 2 release, KingFisher will start the KFServer if it
         is not running; this requires that the KFServer program is in the
         default directory (as far as KingFisher is concerned.)

2. RexxFisher 1.0
   This is an ARexx interface to the Server through which a BBS can access
   the server.  Run multiple copies of RexxFisher to offer multiple BBS
   users access to the database!

3. CLIent 1.1
   A CLI-based interface for the Server.  It is useful for simple lookup
   and testing.  It performs no formatting on the data retrieved from the
   server, so it is not especially pretty to use.
        Registered users will obtain source code to this program!

4. ReOrder 1.1
   A CLI-based tool which allows you to copy a range of records from one
   KingFisher database to another.  Multiple invocations could copy ranges
   of fish from multiple databases to produce a new database.
        Registered users will obtain source code to this program!


Developers:  Contact the author about development of additional client
             programs.  A MUI®-based client is especially desired.



4  STARTING KINGFISHER ----------------------------------------------------

When you start KingFisher, it will attempt to connect to the KingFisher 2.0
Database Server (KFServer); if it cannot locate the server, it will attempt
to start the server, which will work only if the KFServer is located in the
default directory.  Without the server operational, KingFisher cannot
access a database.
    The Server will open a default database and then wait for clients
to connect.  It will also open a status display window.  You can close this
window with the close gadget; this does not shutdown the server.  See below
for ways to shutdown the server.

NOTE: If the Server cannot open its default database, it will shutdown
again.  The default database is described by the contents of the
KFServer.kfdb file.  It must be named that, and its contents should be
something along these lines:

    # KingFisher 2.0 Server preferences
    #
    # Database is known to clients as
    database-name=Frozen Fish Database

    # Database Sections (StartEntry,EndEntry,Filename)
    section=00000,00999,FrozenFish:FrozenFish01.data
    section=01000,01999,FrozenFish:FrozenFish02.data
    section=02000,02999,FrozenFish:FrozenFish03.data
    section=03000,03999,FrozenFish:FrozenFish04.data
    section=04000,04999,FrozenFish:FrozenFish05.data
    section=05000,05999,FrozenFish:FrozenFish06.data
    section=06000,06999,FrozenFish:FrozenFish07.data
    section=07000,07999,FrozenFish:FrozenFish08.data
    section=08000,08999,FrozenFish:FrozenFish09.data
    section=09000,09999,FrozenFish:FrozenFish10.data

    # Main index is to be stored ... (OnDisk or InRam)
    index=inram
    index-increment=100
    index-name=FrozenFish:FrozenFish.Index

    # Field index
    # This one's not being used at this time
    field-index-field=name
    field-index-name=FrozenFish:FrozenFish-Name.Index

    # THE FOLLOWING WILL ONLY WORK IN THE DEFAULT FILE,
    # i.e. THE 'KFSERVER.KFDB' FILE:
    #
    # Maximum number of clients permitted
    maxclients=2

    # Output window
    window=CON://640/200/KingFisher 2.0 Server Messages/AUTO

    # How talkative shall the server be?
    # MUTE, TERSE, QUIET, CHATTY, DEBUG
    verbosity=MUTE

You can verify that the Server is functional by running it again with the
parameter STATUS from the CLI:

    kfserver status

This will print a technical status detailing all open databases, clients
that are connected to the server, some traffic information on the clients,
etc.  Try redirecting this output to a file and scan it with MORE or an
editor of your choice.  Lots of hardcore techie information there!

After the server is running, you can run KingFisher from the CLI:

    KingFisher

or from the Workbench.



5  SEARCH EXPRESSIONS -----------------------------------------------------

KingFisher 2.0 supports search expressions that have expanded on the ones
available in KingFisher Release 1.  As such, you now specify not single
substrings to be located but "real" expressions.  An expression consists of
a field name, a comparison operator, and a substring:

    description $ aquarium

This specifies that the field "description" is to be checked if it contains
($) the substring "aquarium."  Any record in the database that matches this
value will cause KingFisher to stop searching.

    description$aquarium & name$fish

This matches all records whose description-field contains "aquarium" and
(&) whose name-field contains "fish."  The use of parentheses is not needed
here (although you are welcome to use them.)

    description$aquarium & name$fish | name$aqua

Here is where parentheses must come into play.  Without parentheses,
KingFisher will evaluate the expression left-to-right, effectively using
the following order (exemplified at hand of parentheses):

    ( ( description$aquarium ) & name$fish ) | name$aqua

You can easily alter the order of evaluation by specifying parentheses in
your expression:

    description$aquarium & ( name$fish | name$aqua )

The following symbols are defined (some synonyms exist!):

    Logical AND        &
    Logical OR        |
    Logical XOR        ^    (exclusive or)
    Logical NOT        ~  !    (negation)

    Less than        <
    Less than or equal    <=
    Greater than        >
    Greater than or equal    >=
    Equal            =  ==
    Not equal        !=  <>

At this time, string comparisons are made without sensitivity to case,
meaning that "kInGfIsHeR" is equivalent to "KINGfishER."

Here is a KingFisher Release 1 expression:

    game & ( graphics | sound ) & ~( demo & commercial )

Here is the same thing as a KingFisher Release 2 expression:

    description$game & ( description$graphics | description$sound ) &
        ~ ( description$demo & description$commercial )

It's longer, true, and looks much more complicated, but it also provides
much more definition and fine-control in the future.  Various enhancements
are planned to make these expressions easier to use.  Your feedback and
your support will drive the development of these features.

NEWSFLASH: As of BETA 4, a new "meta" field has been added, specified with
           the symbol '*':

    *$game & ( *$graphics | *$sound ) & ~( *$demo & *$commercial )

is now the exact equivalent to the Release 1 expression shown above.
    Please note that the * symbol is NOT a wildcard in the sense that
it represents multiple characters.  It represents a collection of "all
fields in the current database record."  You CANNOT specify "re*$2.04" to
include both "REstrictions" and "REquirements" fields but no others.  The
parser will reject a '*' in your fieldname 're' and complain that it
expected a comparison operator, such a $, <=, !=, etc.

NOTE: Further enhancements to the expression syntax are planned.
NOTE: As of BETA 6 the meta field is buggy and VERY likely to crash
      your machine.  My apologies.  Time is short.  Register.  Incite
      me to fix this fast! ;-)



6  SHUTTING DOWN THE SERVER -----------------------------------------------

The server will wait in the background, servicing requests.  You can shut
it down with a CTRL_D break signal.  A CTRL_C break signal will also shut
it down, but will not wait for clients to disconnect, thereby risking the
loss of some operating memory.

Notice that the Server will flush various files (such as a modified index)
only when it shuts down.  It is highly recommended to make at least SOME
effort to shutdown the server properly.  The behavior of the server will
undergo some changes in the future to prevent accidental loss of data.

Here is a nice table:

    Break
    Signal    Effect
    ---------------------------------------------------------
    CTRL_C    Cancel.  This shuts down the Server regardless of
        how many clients are currently using the program.
        It's a very rude thing to do and not recommended.
        Use CTRL_D if you want to be nicer.
    ---------------------------------------------------------
    CTRL_D    Down.  This shuts down the Server but first sends
        notification to all clients.  It then waits for a
        response from every client and shuts down only
        after every client has acknowledged the shutdown.
        This is much nicer than CTRL_C but may not always
        work; when a client has crashed, for example, and
        hasn't properly signed off the server.  In such a
        case, CTRL_C may be the only way to shutdown the
        Server.
    ---------------------------------------------------------
    CTRL_F    Front.  Asks the Server to open its window after
        you have closed it.
    ---------------------------------------------------------

You can use the CLI command C:BREAK to send KingFisher these signals.  This
is a quick way to shutdown the Server:

    1> status
    Process  1: Loaded as command: L:WBStart-Handler
    Process  2: Loaded as command: Workbench
    Process  3: Loaded as command: l:fifo-handler
    Process  4: Loaded as command: sys:utilities/clock
    Process  5: Loaded as command: sys:utilities/sunclock
    Process  6: Loaded as command: :bin/snap
    Process  8: Loaded as command: emacs
    Process  9: Loaded as command: status
    Process 10: Loaded as command: kfserver

    1> break 10 d

The number (10) you use depends on which of the CLI Processes is the
KingFisher 2.0 Database Server (kfserver.)  The "d" is the CTRL_D break
signal.



7  REGISTERING KINGFISHER -------------------------------------------------

You received KingFisher for free.  You may have paid for a package, such as
one of Fred Fish's CD-ROMs, but KingFisher came free with the package.
This is because Fred and I have a deal: he gets to distribute KingFisher as
part of his great CD-ROMs, and you get a program with both a past and a
future.

But what do I, the programmer, get for all the time I spent on KingFisher?
I cannot live off thank-you notes (although I appreciate all I get) and
CD-ROMs make a poor diet (even when served with wine and cheese ;-) so you
can imagine that I am hoping for something more substantial to reward me
for my efforts, and I am hoping that you will show your appreciation for my
work!
    The original KingFisher was my return of favors to the Amiga
Community.  It was free, it was fun, it taught me a lot.  But best of all
(for you) it was free.  KingFisher 2.0 is no longer free.  You need to
register the program.

Now, why should you register a program that came to you free?  It's simple:
You get to use and evaluate it.  If you decide you like it and wish to
continue using it, you should send me a registration fee.  And if you live
in Europe, you can register with someone I know in Germany!

Here is what you get for registering:

    · KFServer that is able to allow an unlimited number of clients to
      connect.  For you BBS operators, that means you can serve dozens,
      hundreds, thousands(!) of users!  (Billions and billions! ;-)

    · KingFisher will allow you to save and restore Search Sets, which
      are subset databases constructed from all matches of a search.
      It will also allow you to keep a history of search expressions
      from which you can choose.

    · You will receive Programming Documentation so your own programs
      can connect to the KingFisher 2.0 Database Server.  Are you the
      author of BBS software?  Would you like to write a "Door" or
      other interface, rather than going through RexxFisher?  Do you
      want to try your hand at writing a (gasp!) better KingFisher?

    · Technical Support via electronic mail and a KingFisher Mailing
      List.  You will also be the first to receive new versions of the
      included software (even maintenance releases which won't always
      make it to the general public.)

    · My pledge that as long as there is demand for KingFisher, I will
      continue to support it, regardless of where Commodore is going.

    · Your conscience will let you sleep better at night, knowing that
      you are really supporting your favorite computer.  What good is
      your Amiga if nobody wrote software for it anymore?  Support your
      software authors today, because tomorrow it may be too late!


What it will cost you to register:

In the U.S. or North America you should send $15(US) to:

    Udo Schuermann
    6000 42nd Avenue, Apt. 405
    Hyattsville MD  20781-1518
    USA

    email: [e-mail]
    Phone: [phone] (evenings, EST)

    Personal checks drawn on U.S. funds, money orders, international
    money orders, postal money orders, and cash in U.S. Dollars are
    accepted.

In Europe, send DM25 to:

    Uwe Schürkamp
    Jöllenbecker Weg 4
    32051 Herford
    GERMANY

    email: [e-mail]

    Personal checks drawn on a German bank, EuroCheque, and cash in
    Deutsche Mark are accepted.


COMMERCIAL REGISTRATIONS ARE ALSO AVAILABLE.  CONTACT THE AUTHOR!

Sending cash is discouraged for reasons that it's untracable. In the event
that it gets lost in the mail, the loss would be yours to carry.  If you
live in a land far, far away from either Europe or the USA, then your best
bet may be to send cash, as many (international) banks do not cater to the
exchange of small sums.

As a final word of encouragment, should you feel hesitant about registering
KingFisher: With the original KingFisher I hope to have established that
quality software and quality support are important to me.  You will receive
nothing less from me in the future.  KingFisher 2.0 is my first attempt to
get some return on my investment of time through the good-will of you, the
appreciating user.  With your support, KingFisher 2.0 will grow far beyond
what you see before you today.
    Consider your registration a vote.  Vote for the Amiga's growth!
WITHOUT your support it may never achieve its full potential.  Don't take
that chance.  Register today and support your existing investment!

#EOT