home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 642b.lha / xprbplus_v1.0 / xprbplus.doc.pp / xprbplus.doc
Text File  |  1992-06-01  |  9KB  |  265 lines
  1.                 Documentation for XPRBPlus.library
  2.                 ==================================
  3.  
  4.                      Version 1.0 - 24 May 1992
  5.                      =========================
  6.  
  7.               by Terence (Terry) Finney [100021,2621]
  8.               =======================================
  9.  
  10.  
  11. 1. Introduction
  12. ===============
  13.  
  14. XPRBPlus.library is an Amiga shared library for use with Terminal
  15. programs which support the XPR standard, such as Term, VLT and
  16. Backtalk.
  17.  
  18. Its purpose is to provide the improved facilities allowed by the
  19. Compuserve B Plus Protocol. For this first release I have
  20. implemented the 'File Information' facility which enables file
  21. sizes and hence estimated download times to be displayed during
  22. downloads.
  23.  
  24. In a future version I hope to be able to implement the 'Download
  25. Resume' facility which enables partial file transfers to be
  26. completed after an abort.
  27.  
  28.  
  29. 2. Disclaimer
  30. =============
  31.  
  32. This is my first serious programming effort, so I stress that the
  33. usual disclaimers apply. I am not a programmer by profession. My
  34. intention in producing this library was to give myself a challenge
  35. and hopefully end up with something offering the enhancements of
  36. other XPR libraries such as XPRZmodem. If after attempting to
  37. download a 200k file at 300 Baud you find that an error has
  38. occurred rendering the file useless, please hold your breath, count
  39. to ten, read this section again and see the Section 11 at the end
  40. of this document for details of how to report bugs.
  41.  
  42.  
  43. 3. Credits
  44. ==========
  45.  
  46. The protocol support code for this library was supplied by
  47. Compuserve in the bpcsrc.arc archive and is by various authors.
  48. This archive also contains essential information on implementing
  49. the protocol. Other information was obtained from 'The Compuserve B
  50. Plus Protocol' by Russ Ranshaw (available as bplus.arc) and
  51. 'B/Quick B Protocol Information' by Steve Sneed (available as
  52. proto.nfo).
  53.  
  54. This exercise would have been impossible without reference to the
  55. source code for XPRZmodem.library originally written by Rick
  56. Huebner and revised by William M. Perkins, to XPRQuickb.library
  57. from The Software Distillery, and to the example XPRAscii.library
  58. by Willy Langeveld.
  59.  
  60. Further credit is of course due to Willy Langeveld for creating the
  61. XPR specification in the first place.
  62.  
  63. The library was written in Lattice (SAS) C.
  64.  
  65. Last but not least, special thanks are due to Vic Reeves, whose 'I
  66. Will Cure You' album was echoing around the room the first time a
  67. download was achieved successfully. Definitely the best debugging
  68. tool ever invented.
  69.  
  70.  
  71. 4. Installation
  72. ===============
  73.  
  74. First, copy the XPRBPlus.library to LIBS: Then enter your XPR
  75. supporting terminal program and choose the option to select an XPR
  76. library. This usually takes place through a file requester. Direct
  77. this to LIBS: (if it isn't there already) and select the
  78. XPRBPlus.library. That should be it. If you have any problems,
  79. please read your comms program documentation on selecting an
  80. external protocol.
  81.  
  82.  
  83. 5. Options
  84. ==========
  85.  
  86. Once the library is installed there are a number of configurable
  87. options. Select the comms program command for changing transfers
  88. options and a number of gadgets should appear showing the
  89. following:
  90.             Text conversion             (Default N)
  91.             Overwrite Mode              (Default N)
  92.             Buffer size                 (Default 16)
  93.             Auto initiate               (Default Y)
  94.             Delete after send           (Default N)
  95.             Keep partial files          (Default Y)
  96.  
  97. The actual format of the display will change from one comm program
  98. to another, with YES/NO, or ON/OFF being displayed.
  99.  
  100. Text conversion
  101. ---------------
  102.  
  103. If this is set to YES, and the file to be uploaded or downloaded is
  104. an ASCII file, the library will carry out end of line CR/LF
  105. conversion. If it is set to OFF, no conversion will be carried out.
  106. Please note that this option only works on ASCII files and cannot
  107. be enabled for binary files.
  108.  
  109. Overwrite mode
  110. --------------
  111.  
  112. This can be O, N, or S and only affects downloads where a file with
  113. the same name already exists. If set to O the original file will be
  114. overwritten. If set to N, the new file will be downloaded with the
  115. file name appended with .dup or .dupNN, where NN is a number up to
  116. 99. If 99 is reached, .dup99 will be overwritten. If set to S, the
  117. transfer will be aborted.
  118.  
  119. Buffer size
  120. -----------
  121.  
  122. This sets the buffer size for disk read/writes and is in multiples
  123. of 1K. If set to zero, no buffering is used.
  124.  
  125. Auto initiate
  126. -------------
  127.  
  128. This setting affects whether transfers can be initiated by the
  129. Compuserve Host alone or whether they need to be initiated by the
  130. user through the XProtocolSend and XProtocolReceive functions. If
  131. set to OFF, the comms program "Receive" and "Send" commands must be
  132. used.
  133. Delete after sending
  134. --------------------
  135.  
  136. If enabled, after a successful upload the local copy of the file
  137. will be deleted. If disabled, the file will be retained.
  138.  
  139. Keep partial files
  140. ------------------
  141.  
  142. If a partial file is transmitted and this option is enabled, the
  143. file will be retained. It will then be possible to attempt to
  144. resume the transfer later. If is is disabled the partial file will
  145. be deleted.
  146.  
  147. Important
  148. ---------
  149.  
  150. The "Delete after sending" and "Keep partial files" options require
  151. that the comms program implements the xpr_unlink function. Without
  152. this the library cannot delete files.
  153.  
  154.  
  155. 6. Serial Port Settings
  156. =======================
  157.  
  158. I know a lot of grief has been caused by the fact that the
  159. Compuserve documentation states that serial settings of 7 Bits,
  160. Even Parity should be used except for the Apple Mac. When I tried
  161. this originally everything appeared to work OK until I attempted to
  162. transfer files. All the transfers failed, no matter what program I
  163. was using. Only when 8 Bits, No Parity was set did the transfers
  164. work. With most comms programs this means that the "Strip 8th bit"
  165. option has to be set in order to prevent garbage appearing on the
  166. screen. I am sorry to say that with this library it's still the
  167. case that 8N should be set. Although the library does attempt to
  168. set the serial device properly during transfers itself, either my
  169. code does not work or the comms programs I have tested it with do
  170. not support the function properly. If you have problems, please
  171. make sure that the settings are 8 Bits, No Parity. If you do get
  172. the library to work with 7 Bits, Even Parity, please let me know
  173. which program you are using!
  174.  
  175.  
  176. 7. Receiving Files
  177. ==================
  178.  
  179. Since all file transfers are initiated by the Host (ie. Compuserve)
  180. the appropriate command e.g. DOW or DOWNLOAD will need to be sent.
  181. This can be done at the appropriate Compuserve menu prompt. After
  182. the file name has been entered the Host should then initiate the
  183. transfer and the file transfer window will appear. The library
  184. recognises abort requests if your comms program supports them. As a
  185. short cut the library can send the download command itself if the
  186. comms program uses the XProtocolReceive function. This is usually
  187. called by selecting the "Receive" menu option of the comms program.
  188. This will cause the comms program to ask for a filename and once
  189. this has been entered the library to send the string "dow/proto:b+"
  190. followed by the filename to the Host. If 'Auto initiate is set to
  191. off this is the only way to initiate a download. Provided it is
  192. appropriate to the context the download should now be activated.
  193.  
  194.  
  195. 8. Sending Files
  196. ================
  197.  
  198.  
  199. This is very similar to receiving files, except that the Compuserve
  200. menu command is different! You should use UPLOAD or UPL, or
  201. activate the XProtocolSend function (usually through a menu "Send"
  202. command) if your comms program supports it which will cause a
  203. filename requester to appear before sending the command sequence.
  204. Once the Host has initiated the transfer the file transfer window
  205. will again appear.
  206.  
  207.  
  208. 9. Performance
  209. ==============
  210.  
  211. The library runs roughly 3% slower than xprquickb. At present I am
  212. afraid that is the price of the file size display. The bulk of this
  213. difference is during the first 10 to 15 seconds of the transfer and
  214. I will be looking into it to see if improvements can be made.
  215.  
  216.  
  217. 10. The Future
  218. ==============
  219.  
  220. My first task will be to see if the performance of the library can
  221. be improved and if the problems detailed in Section 11 can be
  222. ironed out. I will add options to allow the user to control aspects
  223. of the transfer such as the number of Send Ahead buffers and the
  224. Quoting Level. I will also look further into the serial setting
  225. functions. Finally I hope to be able implement the Download Resume
  226. facility successfully.
  227.  
  228.  
  229. 11. Bugs
  230. ========
  231.  
  232. The library has been tested with Term 2.1 by Olaf Barthel, VLT
  233. version 5.517 by Willy Langeveld and Backtalk by 1.51 by Steve
  234. Ahlstrom and Don Curtis. The only problems I have experienced so
  235. far are that the command sent by XProtocolReceive is not always
  236. successful and aborts during file transfers are not always
  237. acknowledged. I will be looking further at these as well.
  238.  
  239. As this is my first upload I have not had chance to test the
  240. XProtocolSend function to any extent. I would be interested to hear
  241. how successful it is.
  242.  
  243. In case of bugs, please read Section 2 again and then report them
  244. to me on:
  245.  
  246.             Compuserve      ID 100021,2621
  247.             CIX (UK)        ID tfinney
  248.  
  249. If you have any comments, please let me know.
  250.  
  251.  
  252. 12. And Finally.....
  253. ====================
  254.  
  255. ....I hope you find the library useful!
  256.  
  257.  
  258.  
  259.  
  260.  
  261.  
  262.  
  263.  
  264.  
  265.