home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 459.lha / XPRGate_v1.0 / XPRGate.Doc < prev    next >
Text File  |  1990-12-06  |  11KB  |  277 lines
  1.                             XPRGate v1.0
  2.                             ------------
  3.  
  4.                 Copyright © 1990 by Timothy J. Aston.
  5.  
  6.                        All Rights Reserved.
  7.  
  8.  
  9. ******************************** IMPORTANT *********************************
  10.  
  11. XPRGate is freely distributable provided the following conditions are met:
  12.  
  13.   1) No profit is realized from it
  14.   
  15.   2) All files included with this distribution are distributed with it.
  16.  
  17. If you wish to include XPRGate with a commercial or shareware product,
  18. please contact the author me to make arrangements.
  19.  
  20. I make no guarantees as to the performance of the included files.  The user
  21. takes all responsability for any damages or losses incurred do to the direct
  22. or indirect use or misuse of these files.
  23.  
  24. I hereby give permission to Fred Fish to include the full contents of this
  25. archive in his public domain software library.
  26.  
  27. ****************************************************************************
  28.  
  29.  
  30. * What is XPRGate?:
  31.  
  32.   XPRGate is a programme used for transfering files over the modem using the
  33. XPR standard for external file transfer libraries.  It provides the frontend
  34. and all the necessary I/O routines to use the XPR libraries.  XPRGate is
  35. intended primarily for use with TransAmiga BBS, but maybe of interest to
  36. other people too.
  37.  
  38.  
  39. * What are XPR Libraries?:
  40.  
  41.   The XPR specification provides a standard for writing file transfer
  42. protocols in Amiga shared libraries, which can then be used by any
  43. communications programme supporting the specification.  The communication
  44. need have no protocol specific code, so new protocols can be easily added as
  45. they become available without a need to upgrade the communications programme.
  46.  
  47.  
  48. * Using XPRGate:
  49.  
  50.   XPRGate must be run from the CLI, it cannot be run from the Workbench.  The
  51. command line arguments for it are:
  52.  
  53.     XPRGate <device> <unit> <baud> <xpr library> <init string> <R|S> <files>
  54.     
  55.   Where:
  56.   
  57.   <device> is the serial device for XPRGate to use.  Usually this will be
  58. "serial.device" as long as you're using the internal Amiga serial port.
  59. Users of Supra 2400ZI internal modems would use "modem0.device".  Multi-port
  60. serial cards will have their own serial device, so consult the manual if you
  61. have one of these.  It must be in lower-case.
  62.  
  63.   <unit> is the unit number to use.  If you're using the serial.device for
  64. the internal serial port, the unit number is 0.  For others, it depends,
  65. consult your serial card's user manual.
  66.  
  67.   <baud> is the baud rate at which to do the transfer.  Valid rates range
  68. from 110 to 19200 baud.
  69.  
  70.   <xpr library> is the name of the XPR external file transfer library to use
  71. for the transfer.  This file must resided in your LIBS: directory.  The
  72. .library suffix must be entered, and it must be in all lower-case.
  73.  
  74.   <init string> is the initialization string to send to the library.  This
  75. depends entirely on the XPR library being used.  Each will have its own
  76. paramaters that it accepts here, so consult the XPR's documentation for more
  77. info.
  78.  
  79.   <R|S> tells XPRGate whether you are [R]eceiving (downloading) or [S]ending
  80. (uploading) a file.
  81.  
  82.   <files> is a listing of up to 20 files to send or receive.  This also
  83. depends slightly on the individual protocol and whether it can handle batch
  84. transfers or not.
  85.  
  86. XPRGate will create a file called t:Xfers.Temp.  It will append the name of
  87. any file received to this file, followed by a carriage return.  This is so
  88. that you can easily tell what files have been received during a batch
  89. receive (using non-batch protocols it is quite useless to you).
  90.  
  91. Included in this archive are the xprxmodem.library and the
  92. xprzmodem.library which you should put in your Libs: directory.  I have not
  93. included the docs, so to find out more about those libraries, get ahold of
  94. the complete archives.  There is also an xprascii.library, but that was
  95. merely intended as a model for XPR programmers.  I have heard there also
  96. exists an xprkermit.library and an XPR for Compuserve's B+ protocol.
  97. Since I do not have access to any system which uses either protocol, I
  98. wouldn't be able to test them out even if I could get my hands on them.
  99.  
  100.  
  101. * Examples of Using XPRGate:
  102.  
  103.   To send the file df0:File.Lzh using Xmodem-CRC at 1200 baud, you would
  104. enter the following:
  105.  
  106.    XPRGate serial.device 0 1200 xprxmodem.library T0,C0,K0 s df0:File.Lzh
  107.  
  108. To do a Zmodem send of three files at 2400 baud, you might enter:
  109.  
  110.    XPRGate serial.device 0 % xprzmodem.library T?,OY,B1,AN,DN,SN s
  111.       df0:File1.Lzh ram:File2.Lzh df1:File3.lzh    [all one line]
  112.  
  113. To do a Zmodem batch receive to a floppy drive, you could use:
  114.  
  115.    XPRGate serial.device 0 % xprzmodem.library r
  116.      T?,OY,B8,F8192,AN,DN,KN,SN,RN,Pdf1: r ram:    [all one line]
  117.  
  118. The above Zmodem example is kind of special.  First of all, the buffer size
  119. is set to only 8k (B8) and it is set to require an ACK every time the
  120. buffer needs to be written (that is, every 8k).  This is because on floppy
  121. drives, the time it takes to write the buffer to disk seems to cause
  122. XPRGate to crash (there is no such problem with hard drives or RAM drives).
  123. The second thing to note is that the receive filename (ram:) is actually
  124. ignored by the xprzmodem.library, it uses the P parameter to set the path
  125. recieved files should go in (in the above example, df1:).
  126.  
  127.  
  128. * Using XPRGate With TransAmiga:
  129.  
  130.   The primary reason for developping XPRGate was so that TransAmiga BBS (a
  131. FidoNet capable BBS written by ME!) could use XPR protocol libraries for its
  132. file transfers.  TransAmiga runs external programmes to take care of file
  133. transfers.  In the beginning, I was hoping to rely on Rz and Sz for this, but
  134. it quickly became evident that this would not do at all, so I started work on
  135. XPRGate.
  136.  
  137.   To setup TransAmiga to use XPRGate, start up TransConfig and select the
  138. option to edit your file area settings.  Using the currently available
  139. xprzmodem.library and xprxmodem.library, you will be able to implement
  140. Xmodem-Checksum, Xmodem-CRC, Xmodem-1k, and Zmodem batch.  You can implement
  141. as many of those as you like, but since all the Xmodem derivatives use the
  142. same library, you might as well use them all since it will requires no extra
  143. memory or disk space.  So here are the send and receive commands that you
  144. could use for each of these protocols:
  145.  
  146.   Xmodem-Checkum
  147.    send command: XPRGate serial.device 0 % xprxmodem.library T0,C0,K0 s $
  148.    receive command: XPRGate serial.device 0 % xprxmodem.library T0,C0,K0 r $
  149.   Xmodem-CRC
  150.    send command: XPRGate serial.device 0 % xprxmodem.library T0,C1,K0 s $
  151.    receive command: XPRGate serial.device 0 % xprxmodem.library T0,C1,K0 r $
  152.   Xmodem-1k
  153.    send command: XPRGate serial.device 0 % xprxmodem.library T0,C1,K1 s $
  154.    receive command: XPRGate serial.device 0 % xprxmodem.library T0,C1,K1 r $
  155.   Zmodem *
  156.    send command: XPRGate serial.device 0 % xprzmodem.library
  157.       T?,OR,B1,AN,DN,SN s $                        [all one line]
  158.    receive command: XPRGate serial.device 0 % xprzmodem.library  r
  159.       T?,OR,B1,AN,DN,KN,SN,RN,P$ r ram:            [all one line]
  160.    floppy receive: XPRGate serial.device 0 % xprzmodem.library  r
  161.       T?,OR,B8,F8192,AN,DN,KN,SN,RN,P$ r ram:      [all one line]
  162.  
  163. Note the asterisk after Zmodem to indicate to TransAmiga that it is a batch
  164. protocol, and that the Zmodem commands should not be split over two lines.
  165.  
  166.   These are just suggestions, consult the documentation for each library to
  167. find more out about their options.
  168.  
  169.  
  170. * Compatability:
  171.  
  172.   XPRGate does not currently support all of the call-back routines as defined
  173. in the XPR 2.0 spec.  The call-backs that are implemented are:
  174.  
  175.     xpr_fopen()
  176.     xpr_fclose()
  177.     xpr_fread()
  178.     xpr_fwrite()
  179.     xpr_sflush()
  180.     xpr_sread()
  181.     xpr_swrite()
  182.     xpr_update()
  183.     xpr_chkabort()
  184.     xpr_chkmisc()   [1]
  185.     xpr_gets()      [2]
  186.     xpr_ffirst()
  187.     xpr_fnext()
  188.     xpr_finfo()
  189.     xpr_fseek()
  190.     xpr_unlink()
  191.     xpr_squery()
  192.  
  193.   [1] In XPRGate, xpr_chkmisc() doesn't actually do anything.
  194.   [2] xpr_gets() returns 0 always.  This shouldn't normally be called since
  195.       XPRgate will always supply an init string.  The function had to be
  196.       included because most XPRs won't work al all without it being
  197.       present.
  198.  
  199.   The call-backs not supported by XPRGate are:       
  200.  
  201.     xpr_setserial()
  202.     xpr_options()
  203.     xpr_getptr()
  204.  
  205.   XPRGate provides all the necessary call-backs to make sufficient use the
  206. xprxmodem.library and xprzmodem.library.  As protocols become developped that
  207. require some of the non-implemented call-backs, I will try to add them to
  208. XPRGate so it can use all available XPR protocols.
  209.  
  210.  
  211. * Acknowledgements:
  212.  
  213.   I can't take all that much credit for XPRGate, because a good part of it
  214. uses source that other people wrote.  I just adjusted it a bit and glued all
  215. the parts together.  Specifically, I used:
  216.  
  217.    - xprfuncs.c and vltface.asm by Willie Langeveld as distributed with the
  218.   XPR 2.0 spec.
  219.  
  220.    - protsupp.c by Kenneth Osterberg as distributed with the source to his
  221.   Amiga Jmodem implementation.
  222.  
  223. I'd also like to thank:
  224.  
  225.    - Rick Huebner for his XPR Zmodem implementation and Marc Boucher for
  226.   his XPR Xmodem implementation.
  227.  
  228.   Keep 'em coming!
  229.  
  230.  
  231. * An Editorial About XPRs:
  232.  
  233.   If you are writing any kind of telecommunications programme that is to do
  234. file transfers, I strongly reccommend that you look into implementing
  235. support for the XPR libraries.  The specification is very powerful and
  236. flexible, and is also very easy to implement.  The benefits of using
  237. external protocols are obvious, it cuts down on code size, allows the user
  238. to only keep around the protocols he/she wants to use, and allows new
  239. protocols to be instantaneously added as they become available.  Looking at
  240. the various alternatives, I think that Amiga shared libraries is the best
  241. way to do this.  It's very clean, requires minimal memory, and yields the
  242. greatest flexibility.
  243.  
  244.   Source is readily available for various XPRs, to help you out with your
  245. protocol.  You've got a full range, from the simple ASCII protocol, to the
  246. more advanced Xmodem, all the way up to state-of-the-art Zmodem.
  247.  
  248.   Remember, there are still many file transfer protocols that have not yet
  249. been implemented as XPRs.  I'd like to see a Ymodem XPR, and Jmodem XPR,
  250. and perhaps even a bi-directional XPR (so Amiga could users could FINALLY
  251. have a standard bi-directional protocol).  The potential of XPRs is
  252. tremendous.
  253.  
  254.   If you have written an XPR library, I would greatly appreciate it if you
  255. would let me know, and preferably send me a copy of it on disk.  If your
  256. library requires any of the call-backs that XPRGate does not yet support, I
  257. will certainly look into adding them.
  258.  
  259.  
  260. * Contacting Me:
  261.  
  262.   If you have any questions, suggestions, or whatever, I can be reached as
  263. Tim Aston, 1:247/102.4 @ FidoNet, and:
  264.  
  265.     Tim Aston
  266.     128 Riverview Blvd.
  267.     St. Catharines, Ont.
  268.     CANADA
  269.     L2T 3M2
  270.  
  271. I also frequent several FidoNet echoes such AMIGA, AMIGA_PROG, AMY_POINT and
  272. AMIGA_NET_DEV.  I'm always good for a chat.
  273.  
  274.  
  275. -Tim
  276.  
  277.