home *** CD-ROM | disk | FTP | other *** search
/ Frozen Fish 1: Amiga / FrozenFish-Apr94.iso / bbs / alib / d5xx / d599 / rxilshell.lha / RxilShell / rxil_shell.doc < prev    next >
Text File  |  1992-02-01  |  7KB  |  185 lines
  1.    rxil_shell
  2.    ==========
  3.  
  4.    This program is not in the public domain, but it may be freely copied
  5.    and distributed for no charge providing this header is included.
  6.    The code may be modified as required, but any modifications must be
  7.    documented so that the person responsible can be identified. If someone
  8.    else breaks this code, I don't want to be blamed for code that does not
  9.    work! The code may not be sold commercially without prior permission from
  10.    the author, although it may be given away free with commercial products,
  11.    providing it is made clear that this program is free and that the source
  12.    code is provided with the program. 
  13.    
  14.    Executables resulting from linking with this code are subject to no 
  15.    distribution restrictions. This includes the use of STSAutoRequest(),
  16.    which normally requires the payment of a licence fee to SciTech Software.
  17.    When used *only* as part of rxil_shell, this licence fee is waived.
  18.  
  19. ****************************************************************************
  20.  
  21.    Description:
  22.    ============
  23.    
  24. *  The Rxil library makes calls to ARexx far easier. Error handling, etc.
  25.    is done for the programmer. Rxil_Shell makes these calls even easier.
  26.    Some flexibility is missing from these calls (although, when needed,
  27.    this can be re-introduced by direct calls to Rxil or ARexx itself).
  28.  
  29.    
  30. *  The following Rxil routines have been modified:
  31.    
  32.    RxilCheckPort()      Fix to memory allocation. ARG0() macro was getting
  33.                         expanded wrongly causing MungWall hits.
  34.    display_message()    Changed call to AutoRequest() to use MyAutoRequest()
  35.                         which looks nicer under V1.3. This is in the 
  36.                         STSLib.lib link library.
  37.    RxilHandleReturn()   Given a second parameter to control internal display
  38.                         of returns from functions. Also returns a flag to
  39.                         indicate whether a return value was obtained.
  40.    
  41.    The modified/corrected routines are in the rxil_fix subdirectory.
  42.  
  43.  
  44. *  The Rexx command table, an array of RxilFunction's must be created and
  45.    passed to SetupREXX(). A line of NULL's and 0's is used to mark the end
  46.    of the table. For example:
  47.  
  48.    struct RxilFunction rexx_cmd_table[] = {
  49.       { "help",   &rexx_parse,      0, 10,   FALSE,   RXIL_PUBLIC },
  50.       { "quit",   &rexx_parse,      0, 10,   FALSE,   RXIL_PUBLIC },
  51.       { "command",&cmd_launch_cmd,  0,  1,   FALSE,   RXIL_PUBLIC },
  52.       { "func",   &cmd_launch_func, 0, 16,   FALSE,   RXIL_PUBLIC },
  53.       { NULL,     NULL,             0,  0,   FALSE,   0           }
  54.    };
  55.    
  56.    The structure members are:
  57.    (char *)    Command name (in lower case)
  58.    (void *)()  Function to be called for this command
  59.    int         Min number of arguments required
  60.    int         Max number of arguments required
  61.    BOOL        Should command matching be case sensitive
  62.    int         Privilege. RXIL_PUBLIC or RXIL_SECRET. Specifies which port
  63.                the command is valid from. If REXX_PUBLIC, command may be
  64.                executed through either port.
  65.  
  66.  
  67. *  The functions specified in the command table are called with a single
  68.    parameter, a pointer to a RexxMsg structure. The example command table
  69.    shows 2 calls to rexx_parse(). This implies an additional layer of
  70.    parsing is supplied by the client program. If required, the routine 
  71.    BuildComLine() may be called in such a parser to rebuild the command
  72.    line. The following example shows how this might be done:
  73.    
  74.    void rexx_parse(struct RexxMsg *rexxmsg)
  75.    {  char  buffer[200];
  76.    
  77.       BuildComLine(buffer);                        Rebuild the command line
  78.       Interpret(buffer);                           Call our own parser
  79.    }
  80.    
  81.  
  82. *  The only Rexx specific external which needs to be specified by the client
  83.    program (and then only if the client is interested in returns from 
  84.    macros) is:
  85.  
  86.    extern char *Rexx_return;
  87.  
  88. ****************************************************************************
  89.  
  90.    Usage:
  91.    ======
  92.    
  93.    SetupREXX(portname, extension, conspec, synch, comtab, startup)
  94.    ---------------------------------------------------------------
  95.    Input:   char                 *portname   Port name
  96.             char                 *extension  Default extension
  97.                                              NULL: "rexx"
  98.                                              else: taken a string pointer
  99.             char                 *conspec    Console spec for macros to use.
  100.                                              NULL: none (use CLI)
  101.                                              1:    default
  102.                                              else: taken a string pointer
  103.             int                  synch       Are macros to be synchronous?
  104.                                              0: Synchronous
  105.                                              1: Asynchronous
  106.             struct RxilFunction  comtab[]    ARexx command table (see above)
  107.             char                 *startup    Name of Startup macro
  108.                                              NULL: No startup
  109.    Returns: void
  110.    
  111.    Sets up public and private REXX ports and specifies various parameters
  112.    for Rexx. Also runs a startup macro if required; thus any other 
  113.    preparation routines should be called before SetupREXX().
  114.    comtab[] should be prepared as shown above.
  115.  
  116.  
  117.    ProcessReturns()
  118.    ----------------
  119.    Input:   void
  120.    Returns: void
  121.    
  122.    This routine is for programs which launch macros. Handles any ARexx 
  123.    invocation returns which may be back. Informs of any problems and
  124.    allocates and sets the Rexx_return string if a function returned
  125.    with a value.
  126.  
  127.  
  128.    CloseREXX(wind, force)
  129.    ----------------------
  130.    Input:   struct Window        *wind       Pointer to window
  131.             int                  force       0: Don't force;  1: Do force
  132.    Returns: int                              0: Didn't close; 1: Did
  133.    
  134.    Clean up all REXX stuff. Unless force is set, will ask whether it 
  135.    should proceed IF there are any macros waiting. This is done by posting
  136.    a requester in wind (or Workbench if wind is NULL).
  137.  
  138.  
  139.    LaunchCmd(buf)
  140.    --------------
  141.    Input:   char                 *buf        Command macro to be launched
  142.    Returns: void
  143.    
  144.    Launch a REXX command.
  145.  
  146.  
  147.    SetFuncParam(pos, string)
  148.    -------------------------
  149.    Input:   int                  pos         Parameter number (0--15)
  150.             char                 *string     Parameter string
  151.    Returns: int                              0: OK; 1: Failed
  152.    
  153.    Allocate space to put a function parameter and copy in the parameter
  154.    string. The name of the function to be called should be placed in
  155.    position 0. Returns 0 if succeeded; 1 if not
  156.  
  157.  
  158.    LaunchFunc()
  159.    ------------
  160.    Input:   void
  161.    Returns: void
  162.  
  163.    Launch a REXX function. Uses data created by calls to SetFuncParam()
  164.  
  165.  
  166.    RexxReturnUsed()
  167.    ----------------
  168.    Input:   void
  169.    Returns: void
  170.  
  171.    Free memory used for Rexx_return. Also sets Rexx_return back to NULL
  172.    so its value can be tested to see of we've got a value back from a
  173.    function call.
  174.  
  175.  
  176.    BuildComLine(buffer)
  177.    --------------------
  178.    Output:  char                 *buffer     Pointer to character string
  179.    Returns: void
  180.    
  181.    Rebuilds the command line into buffer (which must be pre-allocated).
  182.    This is useful if you want to parse commands separately from the
  183.    built-in parser.
  184.  
  185.