home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 339.lha / SerMod / Docs / SerMod.doc.pp / SerMod.doc
Text File  |  1990-02-08  |  10KB  |  265 lines
  1.  
  2.     In this article, we will look at the first module implemented as part of
  3. ROBBS (Rexx Object Building Block System); SerMod, the serial module.  Full
  4. source code will not be presented, but will be available on a Transactor disk.
  5. We will look at some of the code that illustrates the principles of the ARexx
  6. interface to this module, and show complete syntax for the commands it will
  7. recognize.
  8.  
  9.  
  10.     First, let's look at the syntax of the commands that SerMod knows about.
  11. Remember, these commands are the only way that SerMod can be made to do
  12. anything at all. Figure 1 shows a table of commands, a brief description of
  13. their purpose, and the type of arguments they take.
  14.  
  15. -----------------------------------------------------------------------------
  16. Command                Purpose                                  Arguments
  17. -----------------------------------------------------------------------------
  18. RXD        Serial receiver enable                   ON | OFF
  19. TXD        Serial trasnmit enable                   ON | OFF
  20. SEND       Send string to serial port               STRING
  21. LSEND      Send line to serial port (with linefeed) STRING
  22. MATCH      Watch for a match from serial data       NUMBER STRING
  23. SCAN       Enable/disable match checking.           ON | OFF
  24. CONNECT    Attach receive or transmit to module     PORTNAME COMMAND
  25. CTRL       Attach to another control port.          PORT
  26. COMM       Set serial parameters                    BAUD DUPLEX XON/OFF TRANSLATE
  27. ABORT      Stop sending (flush sendstrings)         NONE
  28. STATUS     Return info about ROBBS                  NONE
  29. DIE        Unload ROBBS                             NONE
  30. REALLY_DIE Emergency quit if script has terminated  NONE
  31. ----------------------------------------------------------------------------
  32.                    Fig. 1
  33.  
  34.     All commands must be in upper case. If you do not quote the command string
  35. within your ARexx program, it will be passed to SerMod in upper case
  36. automatically. The same can be said for any argument required, so if you are
  37. sending data that must be in mixed case, you will need to quote it in the ARexx
  38. program.
  39.  
  40. ----------------------------------------------------------------------------
  41.  
  42. TXD and RXD take an ON or OFF argument. This is in the form of a string, and
  43. the argument must be in upper case. The purpose of these two commands is to
  44. allow other programs to use the serial port. The other program wishing to open
  45. the serial port must do so in 'shared mode' in order to be successful.
  46.  
  47. Examples:
  48.  
  49.     RXD ON
  50.     RXD OFF
  51.     TXD ON
  52.     TXD OFF
  53.  
  54. -----------------------------------------------------------------------------
  55.  
  56. SEND and LSEND are exactly the same, in that they will both send a string out
  57. the serial port, except that LSEND will automatically append a linefeed to the
  58. string it is sending.  LSEND is provided to allow easier use of SEND, since the
  59. only way to SEND an explicit linefeed out the serial port from an ARexx program
  60. is to use hex string notation; '0a'x.  Both SEND and LSEND take a string as an
  61. argument.  Remember to quote the string if you want it to be sent as you typed
  62. it in, without conversion to upper case.
  63.  
  64. Examples:
  65.  
  66.     SEND 'This string will have no linefeed'
  67.     LSEND ', but this one will.'
  68.  
  69. Result:
  70.  
  71.    This string will have no linefeed, but this one will.
  72.  
  73. -------------------------------------------------------------------------
  74.  
  75. MATCH allows you to set up 10 strings for SerMod to watch for in the incoming
  76. data from the serial port. Each MATCH string may be assigned a number, from 0
  77. through 9, and if any part of the incoming data matches one of the strings, a
  78. message will be sent to the control port, specifying that a match has occured,
  79. and the number of the string that matched. Each string may be up to 100
  80. characters long, and may include embedded linefeeds or carriage returns, making
  81. it possible to set up multi-line match strings.
  82.  
  83. Examples:
  84.  
  85.     MATCH 0 'login:'
  86.     MATCH 1 'Password:'
  87.    MATCH 2 'You have email waiting.' || '0a'x || 'Read it now? (Y/N)'
  88.     MATCH 1
  89.     MATCH C
  90.  
  91. Result:
  92.  
  93.    Whenever one of the above strings matches with data coming in on the serial
  94. port, SerMod will send a message to the control port (specified by the CTRL
  95. command). If 'login:' arrives, the message would look like this:
  96.  
  97.     MATCH 0
  98.  
  99.     Note that the example for MATCH 2 has an embedded linefeed, and will only
  100. match an incoming string if there is a linefeed in the incoming data, in the
  101. same position as specified in the match string.
  102.  
  103.     Using a number by itself, with no string, will cause that matchstring to be
  104. cleared, meaning that no matches will happen for that string.  The MATCH C is
  105. used to clear all match strings, and is provided as a convenience to the
  106. programmer.
  107.  
  108. ----------------------------------------------------------------------------
  109.  
  110. SCAN is provided because you sometimes want to disable string matching. Good
  111. examples of this are when you are initializing the matchstrings from your
  112. ARexx program.  If you were to receive 'MATCH' messages at this time, your
  113. program might not be ready to process them.
  114.  
  115. Examples:
  116.  
  117.     SCAN ON
  118.     SCAN OFF
  119.  
  120. Results:
  121.  
  122.     ON enables matching, OFF disables matching.
  123.  
  124. ------------------------------------------------------------------------------
  125.  
  126. CONNECT provides a means to hook the incoming serial port data more directly to
  127. the program it is destined for. While ARexx is fast enough for many operations,
  128. it is not fast enough to process large amounts of data coming in at high
  129. speeds. This command tells SerMod where to send incoming data.
  130.  
  131. Examples:
  132.  
  133.     CONNECT 'ROBBS_disp' TEXT
  134.  
  135. Result:
  136.  
  137.     All data received on the serial port will be sent via a message to the port
  138. named 'ROBBS_disp', using the command, 'TEXT'. It is worth noting that the
  139. message will be indistinguishable to the receiver from a message sent from an
  140. ARexx script. This provides a degree of flexibility, allowing any program to be
  141. the actual control program, or for many programs to communicate with one
  142. module.
  143.  
  144. ---------------------------------------------------------------------------
  145.  
  146. CTRL is similar to CONNECT, but isntead of redirecting the data received from
  147. the serial port, it redirects other messages, such as the 'MATCH' messages.
  148. This lets you use more than one ARexx progam as a control for the ROBBS
  149. modules, or even to use a program written in virually any other language, to be
  150. used as the controlling program. There is only one argument, a string naming
  151. the new CTRL port.
  152.  
  153. Example:
  154.  
  155.     CTRL 'ROBBS_graphic_control'
  156.  
  157. Result:
  158.  
  159.     Any messages originating from SerMod (except incoming serial character
  160.     messages), will be sent to the port named 'ROBBS_graphic_control'
  161.  
  162. ----------------------------------------------------------------------------
  163.  
  164. COMM lets you set up the serial port parameters. All arguments are mandatory.
  165.  
  166. Examples:
  167.  
  168.     COMM 2400 N XE T
  169.     COMM 1200 E XD N
  170.  
  171. Results:
  172.  
  173.     The first example sets the serial port to 2400 baud, no echo (full duplex),
  174. Xon/Off enabled, and Translate ON (7 bits only). The second example sets 1200
  175. baud, echo (half duplex), Xon/Off disabled, and no translation (8 bits
  176. received).
  177.  
  178. ----------------------------------------------------------------------------
  179.  
  180. ABORT lets you stop sending any string that has been sent via the SEND or LSEND
  181. commands. This is provided for those applications, like BBS's, which can detect
  182. an action on the part of the caller and stop sending the current line.
  183.  
  184. Example:
  185.  
  186.     ABORT
  187.  
  188. Result:
  189.  
  190.     The string currently being sent out the serial port is flushed without the
  191. rest being sent.
  192.  
  193. -----------------------------------------------------------------------------
  194.  
  195. STATUS is a way for the controlling program to find out what SerMod is doing at
  196. present. You must have previously used the line 'OPTIONS RESULTS' in your ARexx
  197. program, in order for STATUS to return anything, and the result of the STATUS
  198. command will be returned in the special ARexx variable RESULT.
  199.  
  200. Example:
  201.  
  202.     STATUS
  203.  
  204. Result:
  205.  
  206.     SerMod replies to the message, filling in the RESULT variable, if OPTIONS
  207. RESULTS is in effect. RESULT will contain something like:
  208.  
  209.     2400 NOECHO XENABLED TRANSLATE TALKON LISTENON SCANOFF ROBBS_disp ROBBS_ctrl
  210.     2406A0 240840
  211.  
  212.     In order, these signify:
  213.  
  214.     2400 baud, full duplex, Xon/Off enabled, 7 bit receive, transmit enabled,
  215.     receive enabled, not checking for matches, current CONNECT port,
  216.     current CTRL port, serial IO port (IOReq) for read, and serial IO port
  217.    for write.
  218.  
  219. ------------------------------------------------------------------------------
  220.  
  221. DIE is a command that will cause SerMod to finish what it is doing, clean up
  222. everything, exit, and unload from memory. Note that it is not necessary to
  223. unload SerMod and reload it for every application that needs to use it. You
  224. must, however, be aware that before an ARexx program stops, it should set
  225. things up so that no messages will be sent to the CTRL port or the CONNECT
  226. port, if the CONNECT port is no longer there.
  227.  
  228. Example:
  229.  
  230.     DIE
  231.  
  232. Result:
  233.  
  234.     Sermod cleans up and exits. If there are outstanding messages that have been
  235. sent from SerMod, and have not been replied to, SerMod will print a warning
  236. message on the CLI it was started from, and will not yet exit. If you know that
  237. there can be no replies to the messages, which could easily happen if your
  238. ARexx program is under development, and a bug caused it to exit prematurely,
  239. you can use the REALLY_DIE command to force SerMod to exit.
  240.  
  241. -------------------------------------------------------------------------------
  242.  
  243. REALLY_DIE is provided for emergencies. Suppose your ARexx program (or any
  244. other program that receives messages from SerMod) exits prematurely because of
  245. a bug. In this case, SerMod will not send any more messages to the exited
  246. program's port, since the port is checked for existence before a message is
  247. sent. However, the program that exited may have been sent a message that it did
  248. not yet reply to. In this case, SerMod, when told to exit via the DIE command,
  249. will not exit, but will await the reply to its outstanding message. The
  250. REALLY_DIE command should be used at the user's discretion to force SerMod to
  251. free the memory allocated for outstanding messages, and then to exit. If you
  252. should be so careless as to use the DIE and REALLY_DIE commands while there is
  253. a message outstanding, and then the other program or module does reply, the
  254. GURU is likely to be offended enough to come to visit you.
  255.  
  256. Example:
  257.  
  258.     REALLY_DIE
  259.  
  260. Result:
  261.  
  262.     Force cleanup and exit of SerMod.
  263.  
  264. --------------------------------------------------------------------------------
  265.