home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 310.lha / rexxserdev.library_v1.08 / rexxserdev.doc < prev    next >
Text File  |  1980-12-05  |  8KB  |  226 lines
  1.                   Documentation for rexxserdev.library
  2.  
  3. copyright © 1989       by Joseph M. Stivaletta        All rights reserved.
  4. --------------------------------------------------------------------------
  5.  
  6. This is beta version 1.08 of my serial device function library for ARexx.
  7. Most of the functions have been implemented.  This version performs better
  8. than the previous version.
  9.  
  10. This library uses ARP functions.  Therefore, you must have arp.library in
  11. your LIBS: directory.  You must also place my library into your LIBS:
  12. directory also.  To use the Arexx serial device library, you must add it
  13. to the global library list using the either the addlib() function or the
  14. rxlib() command.
  15.  
  16. The current version number of this library is 1 and the query function offset
  17. is -30.  examples follow:
  18.  
  19.    addlib( 'rexxserdev.library', 0, -30, 1 )
  20.    rxlib rexxserdev.library 0 -30 1
  21.  
  22.  
  23. The rexxserdev.library was written to provide an easy to use interface
  24. between ARexx programs and the Amiga's internal serial device.  The serial
  25. device is opened as shared so take care when accessing the serial device
  26. from more than one application.  All I/O requests to the serial device are
  27. synchronous not asynchronous.  Therefore, a call to a function will not
  28. return to the application until that function is completed.  Due to the
  29. synchronous nature of the library functions the SerStart() and SerStop()
  30. functions may not work as designed for write calls.  The actual effect
  31. of these calls has yet to be determined.  At the current time I still have
  32. not implemented SerStart() and SerStop().
  33.  
  34. The next release will be changed to support additional serial ports.
  35.  
  36. ==========================================================================
  37.                            Using the functions
  38.  
  39.  
  40. SerOpen()
  41. Usage: boolean = SerOpen()
  42. Opens the serial device and allocates the I/O requests and reply ports.
  43. Example:
  44.          say SerOpen()          ==> 1
  45.  
  46.  
  47. SerClose()
  48. Usage: boolean = SerClose()
  49. Closes the serial device and deallocates the I/O requests and reply ports.
  50. Example:
  51.          say SerClose()          ==> 1
  52.  
  53.  
  54. SerClear()
  55. Usage: boolean = SerClear()
  56. Clears the internal read buffer.
  57. Example:
  58.          say SerClear()         ==> 1
  59.  
  60.  
  61. SerFlush()
  62. Usage: boolean = SerFlush({'R' | 'W'})
  63. Aborts all queued I/O requests in either the read or write request queue.
  64. Example:
  65.          say SerFlush( 'R' )    ==> 1
  66.  
  67.  
  68. SerRead()
  69. Usage: charsRcvd = SerRead(buffer,length)
  70. Read a number of characters from the serial port.  The number of characters
  71. read is specified by length.  The buffer is an internal read buffer supplied
  72. by the calling ARexx program.  This buffer is for use by the
  73. rexxserdev.library and not by the ARexx application.
  74. Example:
  75.          block = allocmem( 20 ) 
  76.          addr = c2d( block )
  77.          say SerRead( addr, 20 )    ==> A string of 20 chara
  78.  
  79.  
  80. SerReset()
  81. Usage: boolean = SerReset()
  82. Reinitializes the serial device to it's default state.
  83. Example:
  84.          say SerReset()         ==> 1
  85.  
  86.  
  87. SerStart()
  88. Usage: boolean = SerStart({'R' | 'W'})
  89. Restarts reading or writing stopped by a previous SerStop() function.  Not
  90. yet implemented.
  91. Examples:
  92.          say SerStart( 'W' )       ==> 1
  93.  
  94.  
  95. SerStop()
  96. Usage: boolean = SerStop({'R' | 'W'})
  97. Stops the currently executing read or write command.  Not yet implemented.
  98. Example:
  99.          say SerStop( 'R' )        ==> 1
  100.  
  101.  
  102. SerWrite()
  103. Usage: boolean = SerWrite(buffer,length)
  104. Sends the characters in the buffer to the serial port.
  105. Example:
  106.          text = 'send stuff out port'
  107.          say SerWrite( text, length( text ) )       ==> 1
  108.  
  109.  
  110. SerBreak()
  111. Usage: boolean = SerBreak()
  112. Sends a break signal.
  113. Examples:
  114.          say SerBreak()       ==> 1
  115.  
  116.  
  117. SerQuery()
  118. Usage: status = SerQuery()
  119. Returns status of the serial device.  The first substring indicates the
  120. validity of the rest of the string.  0 indicates that an error was returned
  121. from the query command and no additional information is contained within
  122. the status string.  1 indicates that the call was successful and the string
  123. contains two more substrings.  The second substring is the number in decimal
  124. ASCII of the number of characters currently in the internal read buffer.
  125. The third substring is the status word in decimal ASCII it is defined as 
  126. follows:
  127.             Bit no.     Meaning of Bit
  128.  
  129.             0-2         Reserved
  130.             3           DSR - Data Set Ready (bit = 0)
  131.             4           CTS - Clear To Send (bit = 0)
  132.             5           DCD - Data Carrier Detect (bit = 0)
  133.             6           RTS - Ready To Send (bit = 0)
  134.             7           DTR - Data Terminal Ready (bit = 0)
  135.             8           Read buffer overflow (bit = 1)
  136.             9           Break signal sent (bit = 1)
  137.             10          Break signal received (bit = 1)
  138.             11          Transmit XOFF (bit = 1)
  139.             12          Received XOFF (bit = 1)
  140.             13-15       Reserved
  141. Examples:
  142.          say SerQuery()       ==> 1 23 0 
  143.                                   | |  +--> Status bits
  144.                                   | +-----> Number of characters received
  145.                                   +-------> Validity of status information
  146.  
  147.  
  148. SerSetParms()
  149. Usage: boolean = SerSetParms(baud,databits,paritybits,stopbits,[flowCtl],[brkTime])
  150. Sets the serial device parameters defined below.  The optional brkTime
  151. parameter is not yet implemented.  I have not incorporated SERF_RAD_BOOGIE
  152. so take care when using very high baud rates.  If the flowCtl parameter is 
  153. not supplied, the serial port will default to Xon/Xoff flow control.
  154.  
  155. baud = allowed range is from 110 to 29,200
  156. databits = allowed range from 1 to 8
  157. paritybits = {'N' | 'E' | 'O' | 'M' | 'S'}
  158.               'N' = No parity
  159.               'E' = Even parity
  160.               'O' = Odd parity
  161.               'M' = Mark parity
  162.               'S' = Space parity
  163. stopbits = {'1' | '2'}
  164. flowCtl = {'0' | '1'}
  165.            '0' = Disable Xon/Xoff flow control
  166.            '1' = Enable Xon/Xoff flow control
  167.           the default is enabled Xon/Xoff flow control
  168. brkTime = duration of break signal in microseconds; the default value is
  169.           250,000 microseconds.
  170.  
  171. Examples:
  172.          say SerSetParms( 9600, 7, e, 1 )      ==> 1
  173.  
  174.  
  175. ==========================================================================
  176.                               User rights
  177.  
  178. This is a beta version of my library and I do not guarantee that it is
  179. free from bugs.  It has been tested but not rigorously.  I am making it
  180. available now so that people can begin using it.  I will try to keep
  181. future versions downwardly compatible but make no promises that it will
  182. not change slightly based on user feedback.
  183.  
  184. These programs are freely distributable in the public domain as long as
  185. this document is included.  I retain the rights to their use.  This means
  186. that they cannot be sold for profit by anyone without my written permission.
  187.  
  188.  
  189. ==========================================================================
  190.                             Disclaimer BS
  191.  
  192. If this software, blows up your machine, melts you hard drive, causes
  193. loss of hair, mental anguish, mental disorders, or marital difficuties
  194. ending in divorce, I will not be held liable.  I make no warranties, either
  195. expressed or implied, with respect to the programs described herein, 
  196. their quality, performance, or fitness for any particular purpose.  These
  197. programs are distributed "AS IS." The entire risk as to their quality and
  198. performance is with the user.  I promise only to fix the bugs and to
  199. improve and enhance the code as I deem able in my spare time.
  200.  
  201.  
  202. ==========================================================================
  203.                             Problem reporting
  204.  
  205. If you find any errors or have any problems, your flames can reach me
  206. at the following locations:
  207.  
  208. IDCMP BBS (617-769-3172):
  209. Name: Joe Stivaletta
  210.  
  211. CompuServe:
  212. PIN: 72155,516
  213.  
  214. People Link:
  215. ID: Blackhawk
  216.  
  217. Delphi:
  218. ID: Blackhawk
  219.  
  220. Bix:
  221. ID: jstivaletta
  222.                                           Joseph M. Stivaletta
  223.                                           P.O. Box 125
  224.                                           Bedford, MA      01730
  225.                                           9 October 1989
  226.