home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 5 / FreshFish_July-August1994.bin / tools / kingfisher / rexxfisher.doc < prev    next >
Text File  |  1994-05-30  |  8KB  |  208 lines
  1. RexxFisher 1.4
  2. Copyright © 1992-1994 by Udo Schuermann
  3. All rights reserved
  4.  
  5.  
  6.  
  7. All commands sent to RexxFisher have an RF_ prefix to prevent confusion
  8. with standard ARexx commands.  I think QUIT is a normal ARexx command, and
  9. so might be a few others here or there.  You can use these commands in any
  10. mix of upper and lower case letters that you like.
  11.  
  12. The only commands you can execute WITHOUT a prior RF_HELLO command are
  13. the following; they do not access the database and in fact do not even
  14. require that KFServer is running!
  15.  
  16.     RF_VERSION    Returns RexxFisher's version tag, without the $VER:
  17.             portion, of course.  This will ALWAYS use the
  18.             standard Style Guide compliant format such as:
  19.                 RexxFisher 1.4 (30.5.94)
  20.  
  21.     RF_HELP        Returns a list of all acceptable commands as well
  22.             as some sort of command template to help you figure
  23.             out what sort of parameters you might be able to
  24.             get away with.
  25.  
  26.     RF_QUIT        Tells RexxFisher to shutdown.  In a real
  27.             environment, you might want to issue a command such
  28.             as "RF_DISABLE RF_QUIT" to prevent the QUIT command
  29.             from being recognized.  This will also suppress the
  30.             command from being listed by RF_HELP.
  31.                 Despite a disabled RF_QUIT, RexxFisher will
  32.             respond to a CTRL_C signal such as those sent by
  33.             the c:BREAK command.
  34.  
  35.     RF_DISABLE    Disables a command so that RexxFisher will no
  36.             longer be able to execute it.  This prevents
  37.             accidental shutdown of RexxFisher, for example by a
  38.             "rogue script"
  39.  
  40.  
  41. The following command will attempt to start the KFServer, unless it is
  42. already running:
  43.  
  44.     RF_HELLO    Needs no previous login and will establish a
  45.             connection to the KFServer.  If the KFServer is not
  46.             running, RexxFisher will attempt to start it in the
  47.             exact same way that KingFisher (the GadTools
  48.             client) tries to start KFServer.  The only problem
  49.             is that RexxFisher cannot (yet) be told to look in
  50.             a place OTHER than the default directory for the
  51.             KFServer.  Start RexxFisher in the same directory
  52.             where KFServer is located and all will be fine.
  53.  
  54.             You should give a nice and descriptive name along
  55.             with the RF_HELLO, such as:
  56.                 RF_HELLO "BLAZEFISHER ARexx Script"
  57.                         (my apologies, Dan! :^)
  58.  
  59.             If you issue RF_HELLO when already connected, then
  60.             RexxFisher will issue an implicit RF_BYE command to
  61.             the server to disconnect you.  RexxFisher will also
  62.             do this when it is made to shutdown (either with
  63.             RF_QUIT or through a c:BREAK signal.)
  64.  
  65.  
  66. The following commands can be issued only if you have issued a successful
  67. RF_HELLO command:
  68.  
  69.     RF_BYE        Sign off from the KFServer.  This terminates your
  70.             access to the server.  If you forget this, then
  71.             RexxFisher keeps the connection active for the next
  72.             script, which may be confusing.  RexxFisher has no
  73.             idea, of course, if your script has terminated or
  74.             is just idling around for no particular reason.
  75.  
  76.     RF_LIST        This obtains a list of all available databases from
  77.             the server.  The format of this list is as follows:
  78.                 "Description\1database.kfdb\n
  79.                  Description\1database.kfdb\n"
  80.             Which means that there are one or more lines of
  81.             text each of which begins with a nice descriptive
  82.             text for the database followed by a \1 character
  83.             (which is an ASCII 1, ^A symbol) and followed then
  84.             by the .kfdb name which you would need to give to
  85.             the server through the RF_USE function to make a
  86.             selection.
  87.  
  88.     RF_USE        This selects a database by giving it the name of a
  89.             .kfdb file.  Please see RF_LIST above for more
  90.             information.
  91.  
  92.     RF_FIND        This command is suffering from extreme lack of
  93.             implementation :-/  All the hooks are in place and
  94.             you're welcome to see how far it will take you, but
  95.             it's not yet finished.  Here is what it WILL do:
  96.  
  97.             RF_FIND "expression"
  98.                 Allows the use of the same expression
  99.                 syntax as KingFisher.  See KingFisher.DOC
  100.                 for details.  The expression is compiled
  101.                 and the function begins a search at once.
  102.                 If you receive an error, the result string
  103.                 is in the format "Error X in column Y"
  104.                 where the error values are these:
  105.  
  106.                 1  Comparison Expected ($ = != < > >= <=)
  107.                 2  Operator Expected (AND, OR, XOR)
  108.                 3  Invalid Comparison (ex: <! >< ... are bogus)
  109.                 4  Mismatched Parentheses
  110.                 5  Field Expected (must use "field op value")
  111.                 6  Unsupported Feature (no hints yet :)
  112.                 7  Internal Error
  113.                 8  Incomplete Expression
  114.  
  115.             RF_FIND AGAIN
  116.                 Search onward with the previously used
  117.                 expression.  You must have an expression
  118.                 compiled, otherwise this will not work.
  119.  
  120.             RF_FIND OPTION x
  121.                 Alter the behavior of the FIND command
  122.                 according to the option x:
  123.                 FORWARD        Search forward
  124.                 BACKWARD    Search backward
  125.                 CASEIGNORE    Upper/lower case ignored
  126.                 CASEEXACT    Upper/lower case important
  127.                 TRIMBLANKS    Trim trailing blanks off search-strings
  128.                 NOTRIMBLANKS    Do not trim blanks
  129.                 SIMPLEEXPRESSION   Uses original KF1.40 expressions
  130.                 COMPLEXEXPRESSION  Uses new KF2.0 expressions
  131.                 SHOW        List current options
  132.  
  133.             There is no way to interrupt a search at this time.
  134.  
  135.     RF_GETFISH    Retrieve a specific fish by record number.  The
  136.             command has a second, optional parameter that
  137.             determines if the resulting string is formatted or
  138.             retrieved in raw form.  A positive number for the
  139.             2nd parameter indicates the column width of the
  140.             display that the text should fit.  The resulting
  141.             text, when formatted, will have an appearance much
  142.             like that in KingFisher's ListView.
  143.                 A 3rd parameter specifies a display format
  144.             other than the default.  Please read KingFisher.DOC
  145.             for more information on how to construct such
  146.             format strings.
  147.  
  148.     RF_OBTAIN    Obtains a variety of information from the server,
  149.             according to the parameter given:
  150.  
  151.             DISK    The current disk number.
  152.  
  153.             FISH    The current fish number, usable as the 1st
  154.                 parameter to the RF_GETFISH command.
  155.  
  156.             FLAGS    The flag bits of the current fish; the
  157.                 values currently defined, although not
  158.                 necessarily setup for each fish, are:
  159.  
  160.                 0x0100  Marked for retrieval
  161.                 0x0200  Marked for ownership
  162.                 0x0400  Marked to stay hidden in searches
  163.                 0x0800  Marked to be deleted
  164.  
  165.                 Bits in the range 0x0001 through 0x0080 are
  166.                 user defined.
  167.  
  168.             PVER    The fish number of the PREVIOUS VERSION;
  169.                 the value 0 is returned if no previous
  170.                 version exists.
  171.  
  172.             NVER    The fish number of the NEXT VERSION; the
  173.                 value 0 is returned if no next version
  174.                 exists.
  175.  
  176.             DBNAME    The descriptive name of the database in
  177.                 use.
  178.  
  179.             DBFILE    The filename (ending with .kfdb) of the
  180.                 database in use.  Such a filename can be
  181.                 passed to the RF_USE command.
  182.  
  183.             DBSIZE    The number of records in the current
  184.                 database, which is also the highest fish
  185.                 number you can pass to the RF_GETFISH
  186.                 command.
  187.  
  188.     RF_STATUS    Retrieves status information from the server.  This
  189.             is effectively the same as what KingFisher displays
  190.             in the Status command (rightAmiga-I) except that it
  191.             applies to RexxFisher.
  192.  
  193.  
  194. A demonstration script, RexxDemo.kfrx, is supplied for your enjoyment.
  195. This script assumes that you have started KFServer and RexxFisher and that
  196. they are running in the background.  Enter "rx rexxdemo.kfrx" to run the
  197. demo script.
  198.  
  199.  
  200. Bugs:    If RexxFisher tries to startup the KFServer and this fails (because
  201.     the KFServer cannot be made to startup for one reason or another)
  202.     then RexxFisher may crash the system with an Illegal Instruction.
  203.     This problem will be taken care of in a future release!
  204.  
  205.  
  206.  ._.  Udo Schuermann
  207.  ( )  walrus@wam.umd.edu
  208.