home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 291.lha / ArexxInterfaceLibrary_v.8 / Rxil.doc < prev    next >
Encoding:
Text File  |  1992-09-02  |  31.2 KB  |  1,465 lines
  1.  
  2.     Documentation for the ARexx Interface Library (Rxil)
  3.             Release X0.8
  4.  
  5.  
  6.  
  7. Copyright © 1989 by Donald T. Meyer, Stormgate Software
  8. All Rights Reserved
  9.  
  10.  
  11.  
  12. Chapters:
  13.  
  14.     Function Glossary
  15.  
  16.     Variable Glossary
  17.  
  18.     Defined Symbol Glossary
  19.  
  20.     Structure Descriptions
  21.  
  22.     Tutorial
  23.  
  24.     Notes
  25.  
  26.  
  27.  
  28.  
  29.  
  30. In the following document, several terms and documantation conventions
  31. will be observed:
  32.  
  33.     When refering to ARexx message ports, "private" and "secret" refer
  34.     to the same port.
  35.  
  36.     The code that uses this library may be refered to as the "client".
  37.  
  38.  
  39.  
  40. --------------------------------------------------------------------------
  41.  
  42.     ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  43.     ::                            ::
  44.     ::        Function Glossary            ::
  45.     ::                            ::
  46.     ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  47.  
  48.  
  49.  NAME
  50.         RxilCheckPort
  51.  
  52.  SYNOPSIS
  53.         RxilCheckPort();
  54.  
  55.  FUNCTION
  56.         Called by the client program's eventloop upon recieving a message
  57.         at one of the ports.
  58.         This handles the dispatching ( via RxilDispatch() ) of ARexx
  59.         commands, the launching of "looped back" macros, and receiving
  60.         the replys to macro invocation messages which we have sent to
  61.         Rexxmaster.
  62.  
  63.         This is a "safe" call in that if the ARexx library was unopened
  64.         or the port opening failed, nothing will go boom!
  65.  
  66.  INPUTS
  67.         None
  68.  
  69.  RESULT
  70.         None
  71.  
  72.  SIDES
  73.  
  74.  HISTORY
  75.         01-Aug-89   Creation.
  76.  
  77.  BUGS
  78.  
  79.  SEE ALSO
  80.         RxilInit(), RxilDispatch()
  81.  
  82.  
  83. ----------------------------------------------------------------------
  84.  
  85.  
  86.  NAME
  87.         RxilHandleReturn
  88.  
  89.  SYNOPSIS
  90.         RxilHandleReturn( rxi );
  91.  
  92.         struct RxilInvocation *rxi;
  93.  
  94.  FUNCTION
  95.         Take appropriate action (i.e., notify user) for the return
  96.         from an ARexx macro program.
  97.  
  98.         NOTE: This function is not yet in it's final form.  The final
  99.         form will probably use a requester, whereas the current
  100.         implementation merely sends text to the CLI.
  101.  
  102.  INPUTS
  103.         rxi = pointer to a RxilInvocations structure that has been
  104.             replyed by the RexxMaster.
  105.  
  106.  RESULT
  107.         None
  108.  
  109.  SIDES
  110.  
  111.  HISTORY
  112.         01-Aug-89   Creation.
  113.  
  114.  BUGS
  115.  
  116.  SEE ALSO
  117.  
  118.  
  119.  
  120. ----------------------------------------------------------------------
  121.  
  122.  
  123.  NAME
  124.         RxilDeletePort
  125.  
  126.  SYNOPSIS
  127.         RxilDeletePort( port );
  128.  
  129.         struct MsgPort *port;
  130.  
  131.  FUNCTION
  132.         This will safely delete a message port used to recieve commands
  133.         from ARexx.
  134.         This is acomplished by setting a failure return code and
  135.         replying the message if it is from ARexx.
  136.         If the message is not from ARexx, it is merely replied.
  137.  
  138.         WARNING: If the port was/is used to recieve replys, there must
  139.         be no chance of a reply being pending when this function is
  140.         called!
  141.  
  142.  INPUTS
  143.         port = pointer to a MsgPort.  Normally one that was opened
  144.             for receiving ARexx commands.
  145.  
  146.  RESULT
  147.         None
  148.  
  149.  SIDES
  150.  
  151.  HISTORY
  152.         01-Aug-89   Creation.
  153.  
  154.  BUGS
  155.  
  156.  SEE ALSO
  157.  
  158.  
  159.  
  160. ----------------------------------------------------------------------
  161.  
  162.  
  163.  NAME
  164.         RxilInit
  165.  
  166.  SYNOPSIS
  167.         rdef = RxilInit( flags, portname );
  168.  
  169.         struct RxilDef *rdef;
  170.  
  171.         int flags;
  172.         char *portname;
  173.  
  174.  FUNCTION
  175.         Open the ARexx library and setup our message ports.  Then
  176.         allocate a RxilDef structure and do some default initialization
  177.         of it.
  178.  
  179.         Even though this may fail, that should probably not be fatal
  180.         since the ARexx functionality is optional.  The RxilCheckPort()
  181.         function is smart enough to just return if the rexx initialization
  182.         was not successsfull.  Not to mention that RxilCheckPort() should
  183.         never get called since the rexx_sig_bit mask should be zero.
  184.  
  185.  INPUTS
  186.         flags       These are various defined constants which control
  187.                     which ports get opened.
  188.  
  189.         portname    This is the name to use for the public ARexx port
  190.                     that commands will be received at.  It is suggested
  191.                     that this be in uppercase and contain no spaces.
  192.  
  193.  RESULT
  194.         A pointer to a RxilDef structure.  Return is NULL for failure
  195.         to initialize the ARexx ports.
  196.  
  197.  SIDES
  198.  
  199.  HISTORY
  200.         01-Aug-89   Creation.
  201.  
  202.  BUGS
  203.         This should probably share one signal bit between both ports
  204.         to avoid "hogging" signal bits.
  205.  
  206.  SEE ALSO
  207.         RxilCleanup()
  208.  
  209.  
  210. ----------------------------------------------------------------------
  211.  
  212.  
  213.  NAME
  214.         RxilCreateRxi
  215.  
  216.  SYNOPSIS
  217.         rxi = RxilCreateRxi( name, type );
  218.  
  219.         struct RxilInvocation *rxi;
  220.  
  221.         char *name;
  222.         ULONG type;
  223.  
  224.  FUNCTION
  225.         Allocate a RxilInvocation structure and initialize it to
  226.         the defaults which are contained in the global RxilDef
  227.         structure.
  228.  
  229.  INPUTS
  230.         name = character string containing the name of the ARexx
  231.             program that will be launched with the structure.
  232.         type = determines wether this will be used to launch commands
  233.             or functions.  Must be set to either RXCOMM or RXFUNC.
  234.  
  235.  RESULT
  236.         A pointer to a newly allocated and initialized RxilInvocation
  237.         structure, or NULL if one could not be allocated.
  238.  
  239.  SIDES
  240.  
  241.  HISTORY
  242.         01-Aug-89   Creation.
  243.  
  244.  BUGS
  245.  
  246.  SEE ALSO
  247.         RxilDeleteRxi()
  248.  
  249.  
  250. ----------------------------------------------------------------------
  251.  
  252.  
  253.  NAME
  254.         RxilDeleteRxi
  255.  
  256.  SYNOPSIS
  257.         RxilDeleteRxi( rxi );
  258.  
  259.         struct RxilInvocation *rxi;
  260.  
  261.  FUNCTION
  262.         Remove the structure allocated by a call to RxilCreateRxi() from
  263.         the linked list, and then frees it's memory.
  264.  
  265.  INPUTS
  266.         rxi = a pointer to the RxilInvocation structure to delete.
  267.             This must have been allocated by a call to RxilCreateRxi().
  268.  
  269.  RESULT
  270.         None
  271.  
  272.  SIDES
  273.  
  274.  HISTORY
  275.         01-Aug-89   Creation.
  276.  
  277.  BUGS
  278.  
  279.  SEE ALSO
  280.         RxilCreateRxi()
  281.  
  282.  
  283. ----------------------------------------------------------------------
  284.  
  285.  
  286.  NAME
  287.         RxilOpenConsole
  288.  
  289.  SYNOPSIS
  290.         RxilOpenConsole( console, rexxmsg );
  291.  
  292.         char *console;
  293.         struct RexxMsg *rexxmsg;
  294.  
  295.  FUNCTION
  296.         This will open an AmigaDOS stream as specified by the console
  297.         string.  The filehandle is then placed in the rm_Stdin and
  298.         rm_Stdout fields of the RexxMsg.
  299.  
  300.  INPUTS
  301.         console = a string which defines the console stream to be opened.
  302.             This will normally be something like "CON:0/0/400/100/".
  303.         rexxmsg = pointer to the RexxMsg that the AmigaDOS file handles
  304.             are to be set into.
  305.  
  306.  RESULT
  307.         None
  308.  
  309.  SIDES
  310.  
  311.  HISTORY
  312.         01-Aug-89   Creation.
  313.  
  314.  BUGS
  315.  
  316.  SEE ALSO
  317.         RxilCloseConsole()
  318.  
  319.  
  320. ----------------------------------------------------------------------
  321.  
  322.  
  323.  NAME
  324.         RxilCloseConsole
  325.  
  326.  SYNOPSIS
  327.         RxilCloseConsole( rexxmsg )
  328.  
  329.         struct RexxMsg *rexxmsg;
  330.  
  331.  FUNCTION
  332.         This will close the AmigaDOS file handles contained in the
  333.         rm_Stdin and rm_Stdout fields of the RexxMsg.  If the handles
  334.         are the same, only one close is performed.
  335.         This clears the fields.  If the fields are NULL, then no action
  336.         is taken.
  337.         This function supports the rm_Stdin and rm_Stdout being seperate
  338.         handles, even though it's complimentary function,
  339.         RxilOpenConsole() does not do this.
  340.  
  341.  INPUTS
  342.         rexxmsg = pointer to the RexxMsg whose IO streams are to be
  343.             closed.
  344.  
  345.  RESULT
  346.         None
  347.  
  348.  SIDES
  349.  
  350.  HISTORY
  351.         01-Aug-89   Creation.
  352.  
  353.  BUGS
  354.  
  355.  SEE ALSO
  356.         RxilOpenConsole()
  357.  
  358.  
  359. ----------------------------------------------------------------------
  360.  
  361.  
  362.  NAME
  363.         RxilCmdLock
  364.  
  365.  SYNOPSIS
  366.         RxilCmdLock( rexxmsg );
  367.  
  368.         struct RexxMsg *rexxmsg;
  369.  
  370.  FUNCTION
  371.         This is a "command" which would be called from the dispatch
  372.         function.  This would handle the "LOCK" command that an ARexx
  373.         program could send to the application requesting access to
  374.         the private port.
  375.  
  376.  INPUTS
  377.         rexxmsg     A pointer to a RexxMsg structure.
  378.  
  379.  RESULT
  380.         None
  381.  
  382.  SIDES
  383.  
  384.  HISTORY
  385.         01-Aug-89   Creation.
  386.  
  387.  BUGS
  388.  
  389.  SEE ALSO
  390.         RxilCmdUnlock()
  391.  
  392.  
  393. ----------------------------------------------------------------------
  394.  
  395.  
  396.  NAME
  397.         RxilCmdUnlock
  398.  
  399.  SYNOPSIS
  400.         RxilCmdUnlock( rexxmsg );
  401.  
  402.         struct RexxMsg *rexxmsg;
  403.  
  404.  FUNCTION
  405.         This is a "command" which would be called from the dispatch
  406.         function.  This would handle the "UNLOCK" command that an
  407.         ARexx program could send to the application requesting
  408.         access to the private port.
  409.  
  410.          Note: The privlege level for this command should be "secret",
  411.          since anyone who locked us will be able to meet that level,
  412.          and those who have not locked us can't slip the lock out
  413.          from under those who did (so to speak).
  414.  
  415.  INPUTS
  416.         rexxmsg     A pointer to a RexxMsg structure.
  417.  
  418.  RESULT
  419.         None
  420.  
  421.  SIDES
  422.  
  423.  HISTORY
  424.         01-Aug-89   Creation.
  425.  
  426.  BUGS
  427.  
  428.  SEE ALSO
  429.         RxilCmdLock()
  430.  
  431.  
  432. ----------------------------------------------------------------------
  433.  
  434.  
  435.  NAME
  436.         RxilLaunch
  437.  
  438.  SYNOPSIS
  439.         result = RxilLaunch( rxi )
  440.  
  441.         LONG result;
  442.  
  443.         struct RxilInvocation *rxi;
  444.  
  445.  FUNCTION
  446.         Launch an ARexx program by sending an invocation message
  447.         to the RexxMaster process.  The RxilInvocation structure
  448.         which is allocated prior to this call via RxilCreateRxi()
  449.         contains the information neccessary to launch the program.
  450.  
  451.  INPUTS
  452.         rxi     A pointer to an initialized RxilInvocation structure.
  453.  
  454.  RESULT
  455.         Zero if the launch was successful, non-zero otherwise.
  456.  
  457.  SIDES
  458.  
  459.  HISTORY
  460.         01-Aug-89   Creation.
  461.  
  462.  BUGS
  463.  
  464.  SEE ALSO
  465.         RxilCreateRxi(), RxilDeleteRxi()
  466.  
  467.  
  468. ----------------------------------------------------------------------
  469.  
  470.  
  471.  NAME
  472.         RxilDispatch
  473.  
  474.  SYNOPSIS
  475.         RxilDispatch( rexxmsg, cmd );
  476.  
  477.         struct RexxMsg *rexxmsg;
  478.         char *cmd;
  479.  
  480.  FUNCTION
  481.         This is really an "internal" function which is used by
  482.         the RxilCheckPort() function to dispatch commands.
  483.  
  484.         It is not static, since it may be usefull by itself, or
  485.         it may desireable to replace it with a custom version
  486.         in some applications.  This can be done simply by overriding
  487.         it, rather than editing the library itself.
  488.  
  489.         This is NOT a "safe" call, since it should never be called
  490.         directly from client code.
  491.         It is however safe if the client fails to initialize the command
  492.         table pointer.
  493.  
  494.  
  495.  INPUTS
  496.         rexxmsg = pointer to the RexxMsg structure for the command we
  497.             are dispatching.
  498.         cmd = the command name string.
  499.  
  500.  RESULT
  501.         None
  502.  
  503.  SIDES
  504.  
  505.  HISTORY
  506.         01-Aug-89   Creation.
  507.  
  508.  BUGS
  509.  
  510.  SEE ALSO
  511.         RxilCheckPort()
  512.  
  513.  
  514. ----------------------------------------------------------------------
  515.  
  516.  
  517.  NAME
  518.         RxilToRexx
  519.  
  520.  SYNOPSIS
  521.         result = RxilToRexx( cmd, arg0, arg1, arg2, arg3 );
  522.  
  523.         LONG result
  524.  
  525.         ULONG cmd
  526.         STRPTR arg0
  527.         STRPTR arg1
  528.         STRPTR arg2
  529.         STRPTR arg3
  530.  
  531.  FUNCTION
  532.         Send a command packet to the Rexx Master.
  533.         This is an asynchronous send, no success or failure will be
  534.         observed.
  535.  
  536.  INPUTS
  537.         cmd = the command to send.
  538.         arg0 = a null-terminated string to convert into an Argstring.
  539.         arg1 = a null-terminated string to convert into an Argstring.
  540.         arg2 = a null-terminated string to convert into an Argstring.
  541.         arg3 = a null-terminated string to convert into an Argstring.
  542.  
  543.  RESULT
  544.         Zero for success, non-zero to indicate failure.
  545.  
  546.  SIDES
  547.  
  548.  HISTORY
  549.         01-Aug-89   Creation.
  550.  
  551.  BUGS
  552.  
  553.  SEE ALSO
  554.  
  555.  
  556.  
  557. ----------------------------------------------------------------------
  558.  
  559.  
  560.  NAME
  561.         RxilDumpRdef
  562.  
  563.  SYNOPSIS
  564.         RxilDumpRdef( rdef );
  565.  
  566.         struct RxilDef *rdef;
  567.  
  568.  FUNCTION
  569.         This function is for debug and testing purposes.  It will
  570.         dump information about the current ARexx environment to the
  571.         CLI.
  572.  
  573.  INPUTS
  574.         rdef = pointer to the global RxilDef structure.
  575.  
  576.  RESULT
  577.         None
  578.  
  579.  SIDES
  580.  
  581.  HISTORY
  582.         01-Aug-89   Creation.
  583.  
  584.  BUGS
  585.  
  586.  SEE ALSO
  587.  
  588.  
  589.  
  590. ----------------------------------------------------------------------
  591.  
  592.  
  593.  NAME
  594.         RxilCleanup
  595.  
  596.  SYNOPSIS
  597.         RxilCleanup( rdef )
  598.  
  599.         struct RxilDef *rdef;
  600.  
  601.  FUNCTION
  602.         Cleanup the entire ARexx port.
  603.         This will set the Abort flag, then wait till all ARexx program
  604.         invocations which we have made are completed.
  605.         At this time, all ARexx message ports will be closed.
  606.         Any remaining RxilInvocation structures which were allocated
  607.         via RxilCreateRxi() and not yet deleted via RxilDeleteRxi()
  608.         will be cleaned up and freed.
  609.         The ARexx library will be closed.
  610.         Finally, the RexxDef structure itself will be freed.
  611.  
  612.  INPUTS
  613.         rdef = pointer to the RxilDef structure returned by a call to
  614.             RxilInit().
  615.  
  616.  RESULT
  617.         None
  618.  
  619.  SIDES
  620.  
  621.  HISTORY
  622.         01-Aug-89   Creation.
  623.  
  624.  BUGS
  625.  
  626.  SEE ALSO
  627.         RxilInit(), RxilPending()
  628.  
  629.  
  630. ----------------------------------------------------------------------
  631.  
  632.  
  633.  NAME
  634.         RxilSetResult
  635.  
  636.  SYNOPSIS
  637.         RxilSetResult( rexxmsg, string );
  638.  
  639.         struct RexxMsg *rexxmsg;
  640.         char *string;
  641.  
  642.  FUNCTION
  643.         This can be called to handle the details of placing a result
  644.         string into the rexx message packet as the result Argstring.
  645.         If the string pointer is NULL, a general failure code will
  646.         be set.
  647.         This will deal with inability to allocate the Argstring by
  648.         setting a failure code in the RexxMsg.
  649.  
  650.  INPUTS
  651.         rexxmsg = pointer to the RexxMsg that the reply is being set
  652.             into.
  653.         string = pointer to a null terminated text string which will
  654.             be converted to an Argstring and returned.
  655.  
  656.  RESULT
  657.  
  658.  
  659.  SIDES
  660.  
  661.  HISTORY
  662.         01-Aug-89   Creation.
  663.  
  664.  BUGS
  665.  
  666.  SEE ALSO
  667.  
  668.  
  669.  
  670. ----------------------------------------------------------------------
  671.  
  672.  
  673.  NAME
  674.         RxilGetReturn
  675.  
  676.  SYNOPSIS
  677.         rxi = RxilGetReturn();
  678.  
  679.         struct RxilInvocation *rxi;
  680.  
  681.  FUNCTION
  682.         This will return a pointer to any RxilInvocation message
  683.         that has been replyed (but not yet cleaned up and available).
  684.         NULL will be returned if all RxilInvocation structures which have
  685.         been allocated are available or pending.
  686.  
  687.  INPUTS
  688.         None
  689.  
  690.  RESULT
  691.         A pointer to a RxilInvocation structure.  If none have been
  692.         replied and are available to be handled, this will return a NULL.
  693.  
  694.  SIDES
  695.  
  696.  HISTORY
  697.         01-Aug-89   Creation.
  698.  
  699.  BUGS
  700.  
  701.  SEE ALSO
  702.  
  703.  
  704.  
  705. ----------------------------------------------------------------------
  706.  
  707.  
  708.  NAME
  709.         RxilCleanupReturn
  710.  
  711.  SYNOPSIS
  712.         RxilCleanupReturn( rxi );
  713.  
  714.         struct RxilInvovcation *rxi;
  715.  
  716.  FUNCTION
  717.         This will take a pointer to a RxilInvocation structure and
  718.         free what needs to be freed.
  719.         The RexxMsg pointer is then NULL'ed and the structure's state
  720.         set to AVAILABLE.
  721.  
  722.         This should be called by the main program to cleanup after
  723.         a function or command has returned and after the main program
  724.         has done whatever it wanted to with the result.
  725.         This will close the extension filehandles for Stdin and Stdout.
  726.  
  727.  INPUTS
  728.         rxi = pointer to the RxilInvocation structure to be cleaned up.
  729.  
  730.  RESULT
  731.         None
  732.  
  733.  SIDES
  734.  
  735.  HISTORY
  736.         01-Aug-89   Creation.
  737.  
  738.  BUGS
  739.  
  740.  SEE ALSO
  741.         RxilCreateRxi(), RxilDeleteRxi(), RxilGetReturn()
  742.  
  743.  
  744. ----------------------------------------------------------------------
  745.  
  746.  
  747.  NAME
  748.         RxilPending
  749.  
  750.  SYNOPSIS
  751.         flag = RxilPending();
  752.  
  753.  FUNCTION
  754.         If any ARexx functions or commands have been launched via
  755.         a call to RxilLaunch(), and have not yet terminated, this will
  756.         return TRUE.
  757.  
  758.  INPUTS
  759.         None
  760.  
  761.  RESULT
  762.         A boolean flag which indicates if any launches are in progress.
  763.  
  764.  SIDES
  765.  
  766.  HISTORY
  767.         01-Aug-89   Creation.
  768.  
  769.  BUGS
  770.  
  771.  SEE ALSO
  772.         RxilLaunch(), RxilCmdPending(), RxilFuncPending()
  773.  
  774.  
  775. ----------------------------------------------------------------------
  776.  
  777.  
  778.  NAME
  779.         RxilCmdPending
  780.  
  781.  SYNOPSIS
  782.         flag = RxilCmdPending();
  783.  
  784.  FUNCTION
  785.         If any ARexx commands have been launched via
  786.         a call to RxilLaunch(), and have not yet terminated, this will
  787.         return TRUE.
  788.  
  789.  INPUTS
  790.         None
  791.  
  792.  RESULT
  793.         A boolean flag which indicates if any launches are in progress.
  794.  
  795.  SIDES
  796.  
  797.  HISTORY
  798.         01-Aug-89   Creation.
  799.  
  800.  BUGS
  801.  
  802.  SEE ALSO
  803.         RxilLaunch(), RxilPending(), RxilFuncPending()
  804.  
  805.  
  806. ----------------------------------------------------------------------
  807.  
  808.  
  809.  NAME
  810.         RxilFuncPending
  811.  
  812.  SYNOPSIS
  813.         flag = RxilFuncPending();
  814.  
  815.  FUNCTION
  816.         If any ARexx functions have been launched via
  817.         a call to RxilLaunch(), and have not yet terminated, this will
  818.         return TRUE.
  819.  
  820.  INPUTS
  821.         None
  822.  
  823.  RESULT
  824.         A boolean flag which indicates if any launches are in progress.
  825.  
  826.  SIDES
  827.  
  828.  HISTORY
  829.         01-Aug-89   Creation.
  830.  
  831.  BUGS
  832.  
  833.  SEE ALSO
  834.         RxilLaunch(), RxilPending(), RxilCmdPending()
  835.  
  836.  
  837. ----------------------------------------------------------------------
  838.  
  839.  
  840.  NAME
  841.         RxilCheckResult
  842.  
  843.  SYNOPSIS
  844.         RxilCheckResult( rexxmsg );
  845.  
  846.         struct RexxMsg *rexxmsg;
  847.  
  848.  FUNCTION
  849.         Verify that the secondary result field in a RexxMsg is
  850.         appropriatly set.
  851.         This should be called for a RexxMsg just prior to replying
  852.         it.  This will deal with the case of a result string being
  853.         set when the calling program did not request it.
  854.         It will be freed, and an error code
  855.         set to indicate to the calling program that it should be
  856.         requesting a result for this command.
  857.  
  858.  INPUTS
  859.         rexxmsg = pointer to the RexxMsg structure to be checked.
  860.  
  861.  RESULT
  862.         None
  863.  
  864.  SIDES
  865.  
  866.  HISTORY
  867.         01-Aug-89   Creation.
  868.  
  869.  BUGS
  870.  
  871.  SEE ALSO
  872.  
  873.  
  874.  
  875. ----------------------------------------------------------------------
  876.  
  877.  
  878.  NAME
  879.         RxilCancel
  880.  
  881.  SYNOPSIS
  882.         RxilCancel();
  883.  
  884.  FUNCTION
  885.         Sets the abort condition for ARexx macros.  This is accomplished
  886.         by setting the Abort flag in the RxilDef structure.
  887.         All ARexx messages received at the ARexx ports while this flag
  888.         is set will be returned with an error code.
  889.         Unless the RXIL_NO_CLEAR_ABORT flag is set, the Abort flag will
  890.         be cleared automaticly when the last ARexx program launched by
  891.         this application has finished.
  892.  
  893.  
  894.  INPUTS
  895.         None
  896.  
  897.  RESULT
  898.         None
  899.  
  900.  SIDES
  901.  
  902.  HISTORY
  903.         01-Aug-89   Creation.
  904.  
  905.  BUGS
  906.  
  907.  SEE ALSO
  908.  
  909.  
  910.  
  911. ----------------------------------------------------------------------
  912.  
  913.  
  914.  NAME
  915.         RxilCheckCancel
  916.  
  917.  SYNOPSIS
  918.         flag = RxilCheckCancel();
  919.  
  920.         BOOL flag;
  921.  
  922.  FUNCTION
  923.         Checks to see if the button on the cancel macro requester has
  924.         been clicked by the user or not.
  925.         This will return FALSE if the cancel requester is not posted.
  926.  
  927.  INPUTS
  928.         None
  929.  
  930.  RESULT
  931.         A boolean TRUE if the cancel requester has been clicked.
  932.  
  933.  SIDES
  934.  
  935.  HISTORY
  936.         01-Aug-89   Creation.
  937.  
  938.  BUGS
  939.  
  940.  SEE ALSO
  941.         RxilPostCancel(), RxilEndCancel()
  942.  
  943.  
  944. ----------------------------------------------------------------------
  945.  
  946.  
  947.  NAME
  948.         RxilPostCancel
  949.  
  950.  SYNOPSIS
  951.         RxilPostCancel();
  952.  
  953.  FUNCTION
  954.         This will post a cancel requester to allow the user to halt
  955.         macro execution by clicking a button on the requester.
  956.         The CancelWindow member of the RxilDef structure controls
  957.         where the requester is posted.
  958.         In the current version, the cancel requester always opens it's
  959.         own window on the same screen as the Window whose pointer is
  960.         in CancelWindow.  If CancelWindow is NULL, the window will open
  961.         on the WorkBench.
  962.  
  963.  INPUTS
  964.         None
  965.  
  966.  RESULT
  967.         None
  968.  
  969.  SIDES
  970.  
  971.  HISTORY
  972.         01-Aug-89   Creation.
  973.  
  974.  BUGS
  975.  
  976.  SEE ALSO
  977.         RxilCheckCancel(), RxilEndCancel()
  978.  
  979.  
  980. ----------------------------------------------------------------------
  981.  
  982.  
  983.  NAME
  984.         RxilEndCancel
  985.  
  986.  SYNOPSIS
  987.         RxilEndCancel();
  988.  
  989.  FUNCTION
  990.         Removes the cancel requester.
  991.  
  992.  INPUTS
  993.         None
  994.  
  995.  RESULT
  996.         None
  997.  
  998.  SIDES
  999.  
  1000.  HISTORY
  1001.         01-Aug-89   Creation.
  1002.  
  1003.  BUGS
  1004.  
  1005.  SEE ALSO
  1006.         RxilPostCancel(), RxilCheckCancel()
  1007.  
  1008.  
  1009.  
  1010. --------------------------------------------------------------------------
  1011.  
  1012.     ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  1013.     ::                            ::
  1014.     ::        Variable Glossary            ::
  1015.     ::                            ::
  1016.     ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  1017.  
  1018.  
  1019.  
  1020.     RexxSysBase
  1021.  
  1022. This is a pointer to the ARexx library opened by RxilInit() and closed
  1023. by RxilCleanup().
  1024. This should never be altered by client code.
  1025. Defined in the Rxil library modules.
  1026.  
  1027.  
  1028.  
  1029.     global_rdef
  1030.  
  1031. The pointer to the global RxilDef structure.  This must be set to the
  1032. value returned from the call to RxilInit().
  1033. Once set by this call, this should not be altered.
  1034. Immediatly after calling RxilCleanup(), this should be set to NULL.
  1035. This must be defined in the client's program.
  1036. Example:
  1037.             global_rdef = RxilInit( RXIL_PUBLIC, "MyPort" );
  1038.             .
  1039.             .
  1040.             .
  1041.             RxilCleanup( global_rdef );
  1042.             global_rdef = NULL;
  1043.  
  1044.  
  1045.  
  1046. --------------------------------------------------------------------------
  1047.  
  1048.     ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  1049.     ::                            ::
  1050.     ::        Defined Symbol Glossary            ::
  1051.     ::                            ::
  1052.     ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  1053.  
  1054.  
  1055. NOTE: THIS SECTION OBVIOUSLY UNFINSHED
  1056.  
  1057.  
  1058.     RXIL_PUBLIC
  1059.     RXIL_PRIVATE
  1060.     RXIL_SECRET
  1061.  
  1062.     RXIL_MAX_ARGS
  1063.     RXIL_NO_ARGCHECK
  1064.     RXIL_ARGV()
  1065.     RXIL_ARCG
  1066.  
  1067.  
  1068.     RXIL_STATE_AVAILABLE
  1069.     RXIL_STATE_PENDING
  1070.     RXIL_STATE_RETURNED
  1071.  
  1072.     RXIL_NOLAUNCH
  1073.     RXIL_NO_CLEARABORT
  1074.     RXIL_NOABORT
  1075.  
  1076.     RXIL_FROM_REXX
  1077.  
  1078.     RXIL_WAITFLAG
  1079.  
  1080.  
  1081.  
  1082. --------------------------------------------------------------------------
  1083.  
  1084.     ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  1085.     ::                            ::
  1086.     ::        Structure Descriptions            ::
  1087.     ::                            ::
  1088.     ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  1089.  
  1090.  
  1091.  
  1092.  
  1093.     ***************   RxilFunction Structure   ****************
  1094.  
  1095.  
  1096.     Name
  1097.  
  1098. The function name.  This can be in upper or lower case.  See the CaseFlag
  1099. member of this structure for more information.
  1100.  
  1101.  
  1102.     Func
  1103.  
  1104. Vector to the function's 'C' code.
  1105.  
  1106.  
  1107.     ArgCount
  1108.  
  1109. Number of args expected.  Set to NO_ARGCHECK if we don't care or will
  1110. ascertain within the function itself.
  1111. Note: This argument count, unlike the value returned by RXIL_ARGC, does
  1112. not include the command name itself.  I.E., if you want to receive one
  1113. argunt, set this to 1.
  1114.  
  1115.  
  1116.     CaseFlag
  1117.  
  1118. If set to boolean TRUE, the command name matching will be case sensitive.
  1119.  
  1120.  
  1121.     Privlege
  1122.  
  1123. Set to either REXX_PUBLIC or REXX_SECRET to control which port(s) this
  1124. command is valid from.  If REXX_PUBLIC, than this command may be executed
  1125. from either port.
  1126.  
  1127.  
  1128.  
  1129.  
  1130.     ***************   RxilDef Structure   ****************
  1131.  
  1132.  
  1133.     Flags
  1134.  
  1135. These are flagbits which can be set to control various things about the
  1136. Rexx Interface Library.
  1137.  
  1138. RXIL_NOLAUNCH        If set, unrecognized commands received at the
  1139.             ARexx port will be returned with an error code
  1140.             rather than "looped" back out to ARexx.
  1141.  
  1142. RXIL_NO_CLEARABORT    Normally, the library will clear the Abort flag
  1143.             whenever the last ARexx program launched by the
  1144.             library returns.  This will disable that feature.
  1145.  
  1146. RXIL_NOABORT        If set, the "Cancel" requester will not appear when
  1147.             an ARexx macro is initiated from the library.
  1148.  
  1149.  
  1150.  
  1151.     PortName
  1152.  
  1153. Name which will be used for the public Exec message port opened to recieve
  1154. commands from ARexx.  This is set when RxilInit() is called, and subsequent
  1155. changes will have no effect.
  1156. Default: none
  1157.  
  1158.  
  1159.     Console
  1160.  
  1161. An AmigaDOS stream which will be set as the default I/O for commands and
  1162. functions launched by the application.  This will normally be a console
  1163. stream, such as "CON:10/10/400/100/ARexxStream".
  1164. This stream will not be used for ARexx programs that have been "looped" back
  1165. out in response to a command.
  1166. Default: "CON:10/10/400/100/"
  1167.  
  1168.  
  1169.     Extension
  1170.  
  1171. This is the extension which will be used by ARexx to search for this
  1172. programs macros.  This should be an application-specific extension.
  1173. Default: ".rexx"
  1174.  
  1175.  
  1176.     HostPort
  1177.  
  1178. The Exec Message Port name that command and function invocation messages
  1179. will be sent to.  This is normally "REXX", but may also be "AREXX" if
  1180. the 1.10 version of ARexx is in use.  If "AREXX", commands and functions
  1181. will "detach", and no return status or value will be available.
  1182. Default: "REXX"
  1183.  
  1184.  
  1185.     CommandTable
  1186.  
  1187. This is the pointer to an array of RxilFunction structures which is
  1188. used for the dispatching of commands received at the application's
  1189. ARexx port.
  1190. Default: NULL
  1191.  
  1192.  
  1193.     Abort
  1194.  
  1195. When set, this flag will cause commands recieved at the ARexx port to be
  1196. returned with an error code.
  1197. There are several flag bits which may be set in the Flags member of the
  1198. RxilDef structure that affect this flag.
  1199.  
  1200.  
  1201.     SecretPortName
  1202.  
  1203. The name of the "secret" or "private" port which may optionaly be opened
  1204. by RxilInit().  This name is created by concatenating the word "PRIVATE"
  1205. and a unique number onto the PortName.
  1206. This is set when RxilInit() is called, and subsequent changes will have no
  1207. effect.
  1208. Default: none
  1209.  
  1210.  
  1211.     CancelWindow
  1212.  
  1213. If NULL, the cancel requester will be opened upon the WorkBench screen.
  1214. This may be set to a Window pointer, in which case the cancel requester
  1215. will open on the screen containing the window.  Note that the cancel
  1216. requester always opens it own window, this member is merely a means
  1217. of selecting the screen.
  1218.  
  1219.  
  1220.     SigBit
  1221.  
  1222. Contains the Exec signal bit(s) used by the ARexx port(s).  This should
  1223. be read only via the macro RXIL_WAITFLAG.
  1224. This should never be altered by client code.
  1225.  
  1226.  
  1227.     FromRexx
  1228.  
  1229. This contains a value which indicates which port a command is from
  1230. (public or private).  This also indicates that a command is from
  1231. an ARexx port (when non-zero).  Some functions may need to know whether
  1232. they have been called in response to an ARexx command, or through
  1233. the "normal" user interface.  Error handling and reporting will normally
  1234. be handled differently in these cases.
  1235. This should only be read via the macro RXIL_FROMREXX.
  1236. This should never be altered by client code.
  1237.  
  1238.  
  1239.     Arg
  1240.  
  1241. An array of pointers to the argument strings for an ARexx command.
  1242. Like the 'C' argv[] array, the command name will be in the zereoth
  1243. element, with the first actual argument being RXIL_ARGV(1).
  1244. These should only be read via the macro RXIL_ARGV().
  1245. This should never be altered by client code.
  1246.  
  1247.  
  1248.     ArgCount
  1249.  
  1250. The count of arguments from the ARexx commandline.  Again, like the
  1251. argc of 'C', this will be 1 if there were no arguments, 2 if there
  1252. is one argument, etc.
  1253. This should only be read via the macro RXIL_ARGC.
  1254. This should never be altered by client code.
  1255.  
  1256.  
  1257.     LockCount
  1258.  
  1259. If non-zero there is an ARexx program which has been given or acquired
  1260. a "lock" on the private ARexx port.
  1261. This should never be altered by client code.
  1262.  
  1263.  
  1264.  
  1265. Structure members past this point are private, and used only by the
  1266. Rxil internal functions.  They should never be altered by client code,
  1267. and client code should have little reason to ever read them.
  1268.  
  1269.  
  1270.  
  1271.  
  1272.     ***************   RxilInvocation Structure   ****************
  1273.  
  1274.     Next
  1275.  
  1276. This member is private.
  1277.  
  1278.  
  1279.     RexxMsg
  1280.  
  1281. This member is private.
  1282.  
  1283.  
  1284.     Parent
  1285.  
  1286. This member is private.
  1287.  
  1288.  
  1289.     IHostPort
  1290.  
  1291. The name of the Exec message port to send the "launch" mesage to.  This
  1292. will normally be "REXX".
  1293. Default: global_rdef->HostPort
  1294.  
  1295.  
  1296.     State
  1297.  
  1298. The current state of the RexxInvocation structure.  This will indicate
  1299. wether or not the structure is available for use (to launch an ARexx
  1300. program), is waiting for an ARexx program to finish, or that the ARexx
  1301. program has finished and a result is waiting to be cleaned up.
  1302.  
  1303.  
  1304.     Type
  1305.  
  1306. This determines whether or not the ARexx program will be launched as a
  1307. command or a function.  This can be either RXCOMM or RXFUNC.
  1308. Default: Whatever was passed as an argument to CreateRxi().
  1309.  
  1310.  
  1311.     Name
  1312.  
  1313. The command (ARexx program) name.  This must be set by the client code
  1314. prior to calling RxilLaunch().
  1315. Default: None
  1316.  
  1317.  
  1318.     FileExt
  1319.  
  1320. This is the extension which will be used by ARexx to search for this
  1321. program.  This should be an application-specific extension.
  1322. Default: global_rdef->Extension
  1323.  
  1324.  
  1325.     CommAddr
  1326.  
  1327. This will be the default host ADDRESS for the ARexx program when launched.
  1328. Default: The secret port name (if open), otherwise the public port name.
  1329.  
  1330.  
  1331.     Console
  1332.  
  1333. An AmigaDOS stream which will be set as the default I/O for commands and
  1334. functions launched by the application.  This will normally be a console
  1335. stream, such as "CON:10/10/400/100/ARexxStream".
  1336. This stream will not be used for ARexx programs that have been "looped" back
  1337. out in response to a command.
  1338. Default: global_rdef->Console
  1339.  
  1340.  
  1341.     ActionFlags
  1342.  
  1343. These are the rm_Action flag bits.  Whatever is here will be anded with
  1344. the rm_Action field of the ARexx program launch RexxMsg.
  1345.  
  1346.  
  1347.     CountArgs
  1348.  
  1349. If TRUE, the data pointed to by the FuncArg array is not be considered
  1350. NULL terminated ('C' string style).  The argument length must in this
  1351. case be stored in the ArgLen array.
  1352.  
  1353.  
  1354.     FuncArg
  1355.  
  1356. Pointer to argument strings for an ARexx function mode invocation only.
  1357. These are assumed to be NULL terminated 'C' style strings unless the
  1358. CountArgs flag is TRUE.
  1359.  
  1360.  
  1361.     ArgLen
  1362.  
  1363. If the CountArgs flag is TRUE, this array contains the lengths of the
  1364. argument data pointed at by the corresponding members of the FuncArg
  1365. array.
  1366.  
  1367.  
  1368.  
  1369. --------------------------------------------------------------------------
  1370.  
  1371.     ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  1372.     ::                            ::
  1373.     ::            Tutorial            ::
  1374.     ::                            ::
  1375.     ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  1376.  
  1377.  
  1378. NOTE: THIS SECTION OBVIOUSLY UNFINSHED
  1379.  
  1380.  
  1381.  
  1382. This implements a toolkit interface package to facilitate doing
  1383. two things:
  1384.  
  1385.  1) Add a public and/or private ARexx port to an application program.
  1386.  2) Allow launching of an ARexx macro from an application program.
  1387.  
  1388.  
  1389.  
  1390. To do either of the above, three function calls will always be made to
  1391. this package.
  1392.  
  1393.     RxilInit()
  1394.     RxilCheckPort()
  1395.     RxilCleanup()
  1396.  
  1397.  
  1398.  
  1399.  
  1400.  
  1401. To set up to recieve commands, a structure containing command names
  1402. and vectors (plus misc. flags) is defined.  By then calling
  1403. RxilCheckPort(), any valid commands received will then be dispatched
  1404. to the application routine which handles them.  Two types of ports may
  1405. be opened.  A public port, which can recieve commands from any macro,
  1406. and a private port (though it IS on the list of public ports, the name
  1407. will be unique each time the program is run) intended to recieve
  1408. commands from macros launched by the application.
  1409.  
  1410.  
  1411. To launch commands or functions, a call to RxilCreateRxi() will return
  1412. a semi-initialized structure which can then, after some small amount
  1413. of further initilization, be passed to RxilLaunch() which will handle
  1414. the details of invoking the macro.
  1415.  
  1416. All structures allocated by RxilCreateRxi() may be deleted individualy via
  1417. RxilDeleteRxi() or will be released automaticly upon the call to
  1418. RxilCleanup().
  1419.  
  1420.  
  1421.             -------------------
  1422.  
  1423. Commands that we launch will use the secret port as their initial host
  1424. address if it is open.  If not, they will use the public port.
  1425.  
  1426. Functions that we launch will default to having "REXX" as their initial
  1427. host address.
  1428.  
  1429. Note that in all of the above cases, that these are the values placed
  1430. in the RexxInvocation structure when it is created.  They most definitly
  1431. may be changed to anything the caller desires prior to being used to
  1432. launch a macro.
  1433.  
  1434.  
  1435.             -------------------
  1436.  
  1437.     Logical Consistency Caveats:
  1438.  
  1439.  
  1440. If no secret port is opened, then the "lock" and "unlock" commands are
  1441. useless and should NOT be used!
  1442.  
  1443. Also, if no secret port is opened, commands having a privlege of
  1444. REXX_SECRET will never be executed!
  1445.  
  1446.  
  1447.  
  1448. --------------------------------------------------------------------------
  1449.  
  1450.     ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  1451.     ::                            ::
  1452.     ::            Notes                ::
  1453.     ::                            ::
  1454.     ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  1455.  
  1456.  
  1457. Don't forget to clear the "rexx_abort" flag after things have aborted
  1458. if you have set the RXIL_NO_CLEARABORT flag.
  1459.  
  1460.  
  1461.  
  1462.  
  1463. --------------------------------------------------------------------------
  1464.  
  1465.