home *** CD-ROM | disk | FTP | other *** search
/ Frozen Fish 2: PC / frozenfish_august_1995.bin / bbs / d07xx / d0745.lha / ARexxBox / doc / ARexxBox.doc < prev    next >
Text File  |  1992-10-12  |  12KB  |  398 lines
  1. TABLE OF CONTENTS
  2.  
  3. ARexxBox/ARexxDispatch
  4. ARexxBox/CloseDownARexxHost
  5. ARexxBox/CommandShell
  6. ARexxBox/DoShellCommand
  7. ARexxBox/ExpandRXCommand
  8. ARexxBox/FindRXCommand
  9. ARexxBox/FreeRexxCommand
  10. ARexxBox/ReplyRexxCommand
  11. ARexxBox/SendRexxCommand
  12. ARexxBox/SetupARexxHost
  13. ARexxBox/ARexxDispatch                                 ARexxBox/ARexxDispatch
  14.  
  15.    NAME
  16.     ARexxDispatch -- get ARexx command from MsgPort and execute it
  17.  
  18.    SYNOPSIS
  19.     ARexxDispatch( rexxhost );
  20.  
  21.     void ARexxDispatch( struct RexxHost * );
  22.  
  23.    FUNCTION
  24.     ARexxDispatch fetches and executes all queued commands from
  25.     the given RexxHost's message port.
  26.     
  27.     If a reply for some previously (with SendRexxCommand()) sent
  28.     command comes in, the counter variable for still outstanding
  29.     replies will be decreased by one and the RexxMsg and it's
  30.     associated memory will be freed by FreeRexxCommand().
  31.     
  32.     In the main program, you should just check for the signal
  33.     of the host's message port and call ARexxDispatch()
  34.     without actually getting the message. All work will be
  35.     done by the dispatcher.
  36.  
  37.    INPUTS
  38.     rexxhost - pointer to an active RexxHost structure with
  39.            a valid MsgPort
  40.  
  41.    RESULTS
  42.  
  43.    SEE ALSO
  44.     SendRexxCommand(), SetupARexxHost(), DoShellCommand()
  45.  
  46. ARexxBox/CloseDownARexxHost                       ARexxBox/CloseDownARexxHost
  47.  
  48.    NAME
  49.     CloseDownARexxHost -- close & free ARexx host
  50.  
  51.    SYNOPSIS
  52.     CloseDownARexxHost( rexxhost );
  53.  
  54.     void CloseDownARexxHost( struct RexxHost * );
  55.  
  56.    FUNCTION
  57.     CloseDownARexxHost() waits until replies for all pending
  58.     ARexx commands have been received and then closes the
  59.     ARexx port and frees all memory associated with that
  60.     RexxHost structure.
  61.     
  62.     All messages sent to a closing host will be replied
  63.     immediately with an error "Host closing down".
  64.  
  65.    INPUTS
  66.     rexxhost - the RexxHost to close down
  67.  
  68.    RESULTS
  69.  
  70.    SEE ALSO
  71.     SetupARexxHost(), SendRexxCommand()
  72.  
  73. ARexxBox/CommandShell                              á    ARexxBox/CommandShell
  74.  
  75.    NAME
  76.     CommandShell -- process Commands from a file
  77.  
  78.    SYNOPSIS
  79.     CommandShell( rexxhost, fhin, fhout, prompt );
  80.  
  81.     void CommandShell( struct RexxHost *, BPTR, BPTR, char * );
  82.  
  83.    FUNCTION
  84.     CommandShell() sets the Flag ARB_HF_CMDSHELL in the
  85.     RexxHost's flag field and then processes input from fhin
  86.     until EOF or the CmdShell flag in the RexxHost being cleared
  87.     (e.g. by the standard Rexx command "CMDSHELL CLOSE").
  88.     
  89.     The input is read line-wise, with newline as EOL. Each
  90.     line will be parsed and executed just like a built-in custom
  91.     ARexx command, exactly like it was called via an ARexx host
  92.     messageport.
  93.     
  94.     The parsing and execution of each line is done by the
  95.     function DoShellCommand().
  96.     
  97.     If fhout is not NULL, the output of the commands will be
  98.     printed to fhout. The output of the commands will NOT be
  99.     assigned to any variables, as there is no underlying ARexx
  100.     script program that could hold these variables. Instead,
  101.     the output will be formatted to be human-readable.
  102.     
  103.     The prompt string (if not NULL) will be printed to fhout
  104.     as an input request before reading an input line.
  105.     
  106.     New (ARB 0.99d): The rexxhost parameter has to point to a
  107.     valid RexxHost structure. This is for identifying which
  108.     command shell belongs to which window/instance of the main
  109.     process.
  110.     
  111.     New( ARB 0.99e):  To support the "RX" command sending
  112.     asynchronous messages to ARexx, this function now catches
  113.     the replies of those messages and frees them using
  114.     FreeRexxCommand().  Messages sent _to_ this host will be
  115.     replied immediately with an error "CommandShell Port".
  116.  
  117.    INPUTS
  118.     rexxhost - an initialized RexxHost structure
  119.     fhin - the input FileHandle (see dos.library/Open())
  120.     fhout - the output FileHandle (or NULL)
  121.     prompt - the prompt string (or NULL)
  122.  
  123.    RESULTS
  124.  
  125.    SEE ALSO
  126.     DoShellCommand(), ARexxDispatch(), dos.library/Open()
  127.  
  128. ARexxBox/DoShellCommand                               ARexxBox/DoShellCommand
  129.  
  130.    NAME
  131.     DoShellCommand -- parse & execute a command line
  132.  
  133.    SYNOPSIS
  134.     DoShellCommand( rexxhost, commandline, fhout );
  135.  
  136.     void DoShellCommand( struct RexxHost *, char *, BPTR );
  137.  
  138.    FUNCTION
  139.     DoShellCommand parses the given string assuming it contains
  140.     an ARexx-style command line.
  141.     
  142.     New (ARB 0.99e):  If normal parsing fails, the external
  143.     function ExpandRXCommand() will be called to expand any
  144.     macros.  If the expansion fails or the expanded command
  145.     can't be recognized either, an error will be returned.
  146.     
  147.     If no errors occur during parsing, it tries to execute the
  148.     command with the given arguments. The results of the command's
  149.     execution will be printed in a human-readable format to fhout
  150.     if fhout is not NULL.
  151.     
  152.     If errors occur, DoShellCommand prints a string describing
  153.     the error to fhout (if not NULL).
  154.     
  155.     New (ARB 0.99d): The rexxhost parameter has to point to a
  156.     valid RexxHost structure. This is for identifying which
  157.     command shell belongs to which window/instance of the main
  158.     process.
  159.  
  160.    INPUTS
  161.     rexxhost - an initialized RexxHost structure
  162.     commandline - the string to be parsed & executed
  163.     fhout - the output FileHandle (or NULL)
  164.  
  165.    RESULTS
  166.     none
  167.  
  168.    SEE ALSO
  169.     CommandShell(), ExpandRXCommand(), <dos/dos.h>
  170.  
  171. ARexxBox/ExpandRXCommand                             ARexxBox/ExpandRXCommand
  172.  
  173.    NAME
  174.     ExpandRXCommand -- expand macros and/or aliases (V0.99e)
  175.  
  176.    SYNOPSIS
  177.     newcommand = SendRexxCommand( rexxhost, oldcommand )
  178.  
  179.     char *ExpandRXCommand( struct RexxHost *, char * );
  180.  
  181.    FUNCTION
  182.     This is an 'external' function you should provide if you
  183.     want to have command aliases or the like. The minimal
  184.     version of this function is just a return(NULL) as generated
  185.     in the rxif module.
  186.     
  187.     ExpandRXCommand() will be called by the parser if it doesn't
  188.     know how to interpret a command string. Expansion could now
  189.     for example be a look up in the host's macro table.
  190.     
  191.     Any strings returned by this function have to be allocated
  192.     explicitly using the standard C memory functions.  The
  193.     calling parser will free() them.
  194.  
  195.    INPUTS
  196.     rexxhost - the RexxHost we are working on
  197.     oldcommand - the commandline the parser doesn't know
  198.  
  199.    RESULTS
  200.     newcommand - an explicitly allocated memory area con-
  201.              taining the expanded command (or NULL)
  202.  
  203.    SEE ALSO
  204.     DoShellCommand(), ARexxDispatch()
  205.  
  206. ARexxBox/FindRXCommand                                 ARexxBox/FindRXCommand
  207.  
  208.    NAME
  209.     FindRXCommand -- search the ARexxBox command table (V0.99e)
  210.  
  211.    SYNOPSIS
  212.     rxscmd = FindRXCommand( command )
  213.  
  214.     struct rxs_command *FindRXCommand( char * );
  215.  
  216.    FUNCTION
  217.     This function returns a pointer to the given command's entry
  218.     in the ARexxBox-generated command table.  It exists to
  219.     support those functions working on/with commands, like HELP
  220.     or ENABLE/DISABLE.
  221.     
  222.     This function does no macro expansion.  The comparisons are
  223.     case independant so you don't have to convert your input to
  224.     upper case beforehand.  As this is exactly the routine used
  225.     by the parser to find a command, it will handle
  226.     abbreviations.
  227.  
  228.    INPUTS
  229.     command - the command name to search for
  230.  
  231.    RESULTS
  232.     rxscmd - the rxs_command structure of that command
  233.          (or NULL if command not found)
  234.  
  235.    SEE ALSO
  236.  
  237. ARexxBox/FreeRexxCommand                             ARexxBox/FreeRexxCommand
  238.  
  239.    NAME
  240.     FreeRexxCommand -- free the associated memory of a RexxMsg
  241.  
  242.    SYNOPSIS
  243.     FreeRexxCommand( rexxmessage );
  244.  
  245.     void FreeRexxCommand( struct RexxMsg * );
  246.  
  247.    FUNCTION
  248.     This is basically a PD ARexx routine provided by William S. Hawes.
  249.     
  250.     It frees all memory associated with a particular (previuosly sent)
  251.     ARexx message structure. It will also close any stdin/stdout
  252.     channels associated to that Rexx message.
  253.     
  254.     You normally shouldn't have to bother with this one because the
  255.     dispatcher will call it for you.
  256.  
  257.    INPUTS
  258.     rexxmsg - the rexx message to free
  259.  
  260.    RESULTS
  261.  
  262.    SEE ALSO
  263.     SendRexxCommand()
  264.  
  265. ARexxBox/ReplyRexxCommand                           ARexxBox/ReplyRexxCommand
  266.  
  267.    NAME
  268.     ReplyRexxCommand -- reply a rexx message from rexxmast
  269.  
  270.    SYNOPSIS
  271.     ReplyRexxCommand( rexxmsg, primary, secondary, result );
  272.  
  273.     void ReplyRexxCommand( struct RexxMsg *, long, long, char * );
  274.  
  275.    FUNCTION
  276.     This is a PD ARexx routine provided by William S. Hawes.
  277.     
  278.     It replies a given rexx message to the rexx master process,
  279.     filling in a primary and a secondary return code plus
  280.     optionally a supplied result string.
  281.     
  282.     The result string will only be converted to an ARexx string,
  283.     if the primary return code equals 0, and will then destroy the
  284.     contents of the secondary return code. So you provide either
  285.     primary and secondary return codes or a result string.
  286.     
  287.     You normally shouldn't have to call this function!
  288.     It is only mentioned here, because it is not part of the
  289.     ARexxBox routines, but part of the original ARexx distribution
  290.     by William S. Hawes.
  291.     
  292.     New (ARB V0.99d): Now creates an ARexx variable "RC2" for the
  293.     secondary return code. If primary is positive, secondary is
  294.     interpreted as a long, if primary is negative, secondary is
  295.     interpreted as a char *. RC will become positive in any case.
  296.     
  297.     RC2 will only be assigned if the ARexx RESULT flag is set.
  298.  
  299.    INPUTS
  300.     rexxmsg - the message structure to reply
  301.     primary - the primary return code (rc)      ( >0      <0   )
  302.     secondary - the secondary return code (rc2) (long or char *)
  303.     result - the result string
  304.  
  305.    RESULTS
  306.  
  307.    SEE ALSO
  308.     SendRexxCommand(), FreeRexxCommand()
  309.  
  310. ARexxBox/SendRexxCommand                             ARexxBox/SendRexxCommand
  311.  
  312.    NAME
  313.     SendRexxCommand -- invoke rexx command script
  314.  
  315.    SYNOPSIS
  316.     rexxmsg = SendRexxCommand( rexxhost, command, filehandle )
  317.  
  318.     struct RexxMsg *SendRexxCommand( struct RexxHost *, char *, BPTR );
  319.  
  320.    FUNCTION
  321.     This is basically a PD ARexx routine provided by William
  322.     S. Hawes.
  323.     
  324.     This function sends the given command string to the ARexx
  325.     master process for execution as an ARexx command. The
  326.     command string contains the file name of the ARexx script
  327.     to be started. If the filehandle is not NULL, it will be
  328.     used as stdin and stdout for the Rexx script. If it is
  329.     NULL, the Rexx program will use stdin/stdout of the
  330.     calling process.
  331.     
  332.     If necessary, the default extension (defined in the
  333.     generated header file under the name REXX_EXTENSION) will
  334.     be added to the file name.
  335.     
  336.     Messages sent using this function will be replied to by
  337.     the ARexx master process as soon as the execution of the
  338.     command script stops. The application MUST NOT close
  339.     it's messageport before all replies have been received!
  340.     To simplify things, ARexxBox does this book-keeping for you.
  341.     CloseDownARexxHost() will wait for all missing replies to
  342.     arrive before closing down the messageport.
  343.     
  344.     The dispatcher will automagically detect any replies,
  345.     count them and do a FreeRexxCommand() for each reply, so
  346.     you don't have to bother with this either.
  347.  
  348.    INPUTS
  349.     rexxhost - the RexxHost to be used to send the command
  350.     command - the file name of the ARexx script
  351.     filehandle - Filehandle for stdin/stdout or NULL
  352.  
  353.    RESULTS
  354.     rexxmsg - the sent rexx message structure (for comparisons)
  355.  
  356.    SEE ALSO
  357.     FreeRexxCommand(), CloseDownARexxHost(), ARexxDispatch()
  358.  
  359. ARexxBox/SetupARexxHost                               ARexxBox/SetupARexxHost
  360.  
  361.    NAME
  362.     SetupARexxHost -- initialize and open an ARexx host
  363.  
  364.    SYNOPSIS
  365.     rexxhost = SetupARexxHost( basename );
  366.  
  367.     struct RexxHost *SetupARexxHost( char * );
  368.  
  369.    FUNCTION
  370.     This function allocates and initializes a RexxHost
  371.     structure. It opens a public message port under the
  372.     given basename. If no basename (NULL) was specified,
  373.     the default basename as entered in the ARexxBox window
  374.     will be used instead.
  375.     
  376.     Anyway, if a public port of that name already exists,
  377.     SetupARexxHost() will start adding numbers to the name
  378.     until a unique name is found. So if for example the
  379.     basename is "myhost" and there is already a port of that
  380.     name in the system, the name will be changed to
  381.     "myhost.1" (then to "myhost.2" and so on).
  382.     
  383.     The actual name will be copied to the portname field of
  384.     the RexxHost structure. It is a good idea to tell the
  385.     user about the actual port name of the new host.
  386.  
  387.    INPUTS
  388.     basename - the messageport basename or NULL
  389.  
  390.    RESULTS
  391.     rexxhost - the initialized RexxHost structure, ready to
  392.            go. Pass this pointer to CloseDownARexxHost(),
  393.            ARexxDispatch() and SendRexxCommand().
  394.  
  395.    SEE ALSO
  396.     CloseDownARexxHost(), ARexxDispatch(), SendRexxCommand()
  397.  
  398.