home *** CD-ROM | disk | FTP | other *** search
/ Amiga MA Magazine 1998 #3 / amigamamagazinepolishissue1998.iso / bazy / kingfisher-distribution / developer / readme < prev    next >
Text File  |  1995-05-30  |  6KB  |  160 lines
  1. KingFisher Release 2 Development Kit
  2. Copyright © 1992,1993,1994,1995 Udo Schuermann
  3. All rights reserved
  4.  
  5.  
  6. The development kit is written with SAS/C 6.55 in mind but may be adaptable
  7. to other compilers.  I have no access to other compilers, so if you send me
  8. information on what changes are required, I will try to incorporate them in
  9. a future release.
  10.  
  11.  
  12. The most important file in the development kit is
  13.  
  14.     kf-api.h
  15.  
  16. This is the one your own project would #include; documentation for all API
  17. (Application Programming Interface) is at the head of every function proto-
  18. type.
  19.  
  20. Once you have gained some understanding (with the help of the kf-api.h file
  21. and this introductory document) you should proceed to compile kf-api.c into
  22. kf-api.o, which is the object file you must link into your final binary.
  23.  
  24. ···········································································
  25.  
  26. Here is a small project to get you started (available as demo.c)
  27.  
  28. ------------------------------(snip snip)------------------------------
  29. #include <stdio.h>
  30. #include "kf-api.h"
  31.  
  32. void main( void ) {
  33.  
  34.   KFHANDLE myHandle;       /* defines an active connection to the server */
  35.   extern BOOL KFAPISilentRun;   /* defined in kf-api.c */
  36.  
  37.  
  38.   KFAPISilentRun = TRUE;   /* stop those pesky status messages while the
  39.                             * server is being started...
  40.                             */
  41.  
  42.   /* try to establish a connection to the server; this will attempt to
  43.    * start the server if it is not already running!
  44.    */
  45.   if( (myHandle = KFLogin("First Test Project")) != NULL ) {
  46.  
  47.     /* If we get here, then the server is running and we are connected
  48.      * to it with a default database ready to be examined!
  49.      */
  50.  
  51.     /* ask the server how many connections it can handle */
  52.     ULONG maxlogins = KFMaxClients( myHandle );
  53.     if( maxlogins <= 2 )
  54.       printf("Unregistered");
  55.     else
  56.     if( maxlogins <= 32767 )
  57.       printf("Beta release");
  58.     else
  59.       printf("Registered");
  60.     printf(" server software is ready!\n");
  61.  
  62.     /* ask the server to give us some status information */
  63.     if( KFStatus( myHandle ) )
  64.       printf("********************\n"
  65.              "%s\n"
  66.              "********************\n",myHandle->Buffer);
  67.     else
  68.       printf("Status information could not be obtained!\n");
  69.  
  70.     /* logout from the server again (i.e. disconnect) */
  71.     KFLogout( myHandle );
  72.   } else
  73.     printf("The KFServer couldn't be started?!\n");
  74. } /* main() */
  75. ------------------------------(snip snip)------------------------------
  76.  
  77. Compile and link this program with the following commands:
  78.  
  79.  sc demo NOLINK
  80.  slink FROM lib:c.o+demo.o+kf-api.o LIBRARY lib:sc.lib+lib:amiga.lib TO demo
  81.  
  82.  
  83. THAT'S ALL THERE IS TO IT!
  84.  
  85. ···········································································
  86.  
  87. Next, you may want to take a look at the ReOrder.c program.  It is a little
  88. longer than our little demo above, but still quite short.  It demonstrates
  89. how ONE program can establish TWO separate connections to the server.  The
  90. ReOrder tool copies a range of records from the first connection and writes
  91. these to the second connection.  This effectively is a copy operation, and
  92. can be used in a variety of ways:
  93.  
  94. 1. Simply duplicate an entire database but perhaps with slightly different
  95.    sections.  See the 1000Fish.kfdb file for an example where a database is
  96.    split into two sections.  You could easily create a file Fishies.kfdb
  97.    and specify something like:
  98.       section=0000,0999,fishies-1.data
  99.       section=1000,1999,fishies-2.data
  100.       section=2000,2999,fishies-3.data
  101.       section=3000,3999,fishies-4.data
  102.       section=4000,4999,fishies-5.data
  103.    or break it up into hundreds of tiny files.  Using ReOrder,  you could
  104.    then produce a new database with a different organization:
  105.  
  106.       ReOrder 1000Fish.kfdb Fishies.kfdb
  107.  
  108. 2. Copy only a portion of one database to a new one.  Repeating this
  109.    process multiple times with various input databases and a single output
  110.    database would effectively collect choice records from several databases
  111.    into a new database.
  112.  
  113. ···········································································
  114.  
  115. The third tool you may wish to look at, CLIent, is the most sizable pile of
  116. junk code you will ever find from me ;-) and there are many reasons why I
  117. say that:
  118.  
  119.    The program does not use the prescribed kf-api files; it uses the
  120.    message port interface directly.  This makes it much more difficult to
  121.    read, understand, maintain, and upgrade.  Avoid writing code like that!
  122.  
  123.    CLIent was the very first interface that I created to test the earliest
  124.    KFServer software, before the kf-api files were written to make the
  125.    whole MESSage port MESS more managable.
  126.  
  127.    If you compare the simplicity of ReOrder.c with the open complexities of
  128.    CLIent.c, you will come to appreciate how much of the ugly details are
  129.    handled for you by the kf-api.
  130.  
  131. ···········································································
  132.  
  133. And that is the end of this introductory overview.  If you think this is
  134. all a bit too complicated, I urge you to compile and run the demo.c program
  135. to get started.  Next, add a command such as:
  136.  
  137.     if( KFGetFish( myHandle, 1 ) )
  138.       printf("Record #1 looks like this:\n\n%s\n",
  139.              myHandle->Buffer);
  140.     else
  141.       printf("Cannot load fish #1\n");
  142.  
  143. and see what that gets you!  Chances are that this will take care of 90% of
  144. your interaction with the server.  The rest is up to you!
  145.  
  146. NIFTY FORMATTING?
  147.     No, the server does not provide data formatting services.  The neat
  148. stuff with wordwrap and all that KingFisher and RexxFisher do is all custom
  149. coded; these routines will not become available in source form, although a
  150. future version of the KFServer *may* provide them as services to clients
  151. that do not wish to implement such code on their own.
  152.  
  153. ···········································································
  154.  
  155. If you have suggestions for improvement to this Developer Kit, please don't
  156. hesitate to let me know what is lacking or what can be enhanced.  Thanks!
  157.  
  158.  ._.  Udo Schuermann
  159.  ( )  walrus@wam.umd.edu
  160.