home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 8 Other / 08-Other.zip / XFER.ZIP / ESLASYNC.DOC < prev    next >
Text File  |  1991-10-06  |  13KB  |  268 lines
  1. ################################################################################
  2. #                              NOTICE                                          #
  3. #                    PROPRIETARY AND CONFIDENTIAL                              #
  4. #                                                                              #
  5. #                 Copyright (C) 1990  Easel Corporation.                       #
  6. #                         All Rights Reserved.                                 #
  7. #                                                                              #
  8. # This computer program, created in 1990, is and contains trade secret and     #
  9. # confidential and proprietary information of Easel Corporation.  All use,     #
  10. # disclosure, and/or reproduction not specifically authorized in writing       #
  11. # by Easel Corporation is prohibited.  This program may also be protected under#
  12. # the copyright and trade secrets laws of countries other than the U.S.A.      #
  13. #                                                                              #
  14. # EASEL is a registered trademark of Easel Corporation.                        #
  15. ################################################################################
  16.  
  17.   The files on this disk are provided as a free service of Easel
  18.   Corporation but are not supported in any way by the company. 
  19.   Specifically this means the following:  
  20.  
  21. --The code has not been rigorously tested; we make no guarantees of
  22.   how or if it will perform; 
  23.  
  24. --NO technical support is available for this code other than the
  25.   comments in the code, any readme or .doc files, and the sample
  26.   programs (if any) supplied.  
  27.  
  28. --As our products change, we make no guarantees that the code
  29.   herewith will be maintained to reflect those changes.  
  30.  
  31. --No other liabilities or conditions are implied by the distibution
  32.   of this product.  Simply:  if you find this code useful, and we hope
  33.   you will, then everyone is better off!  
  34. ################################################################################
  35.  
  36.  
  37. Overview
  38. --------
  39.  
  40. The ESLASYNC.EXE local application is designed to provide XModem, 1K XModem,
  41. and YModem file transfer protocols for Easel/2 applications.  It is assumed
  42. that you are fairly familiar with file transfer protocols.  Much of the 
  43. interface between ESLASYNC.EXE and Easel/2 is similar to that of the
  44. supported AVT100.EXE local application, which is due to the fact that
  45. ESLASYNC.EXE incorporates much of the same source code that AVT100.EXE uses.
  46. Because of this, and the fact that the AVT100.EXE source code is proprietary,
  47. the source code for ESLASYNC.EXE can not be distributed to customers.
  48.  
  49. Included with ESLASYNC.EXE is a very simple Easel terminal emulation program
  50. which makes a good example of how to use the application.  At the bottom of
  51. this document is a list of every error and status message that can be 
  52. displayed by the application, along with a brief description of each.
  53.  
  54.  
  55. Use
  56. ---
  57.  
  58. ESLASYNC.EXE behaves much like the Easel "start remote" command, in that it
  59. performs absolutely no manipulation on the data that is received from the
  60. communications port.  Once you have started the local application it
  61. behaves much like the AVT100.EXE local application in filter mode (without
  62. the filtering effect).
  63.  
  64.  
  65. Before any text or commands can be sent to the local application it must
  66. be properly started.  The syntax for starting the local application is
  67. identical to the AVT100.EXE local application, except that no mode is 
  68. specified.  Therefore, an appropriate command from Easel/2 would look like:
  69.  
  70.    start local ESLASYNC "ESLASYNC.EXE" "com1: BAUD2400 TANDEM NOPARITY"
  71.  
  72. The default settings for ESLASYNC are 2400 baud, no parity, 8 databits,
  73. 1 stopbit, and flow control is enabled.  Once the application has been
  74. properly started it will respond with the message "READY".  If the local
  75. application has any problems initializing itself, it will display one of
  76. the messages listed at the bottom of this file.
  77.  
  78. Responses to ESLASYNC.EXE can be written using either the "response to char"
  79. or "response to line" format.  When sending characters you would use the
  80. exact same command format as AVT100.EXE.  Any data to be sent must be
  81. preceeded by a "T " and followed by a "\^D".  The following command would
  82. caise the modem to dial a telephone number:
  83.  
  84.    send "T ATDT 868-0524\r\^D" to ESLASYNC
  85.  
  86.  
  87. File Transfers
  88. --------------
  89.  
  90. When performing a file transfer you must first send the appropriate command
  91. to the host to have it initiate it's end of the transfer.  Once this has
  92. been done you send a command to ESLASYNC.EXE telling it what type of 
  93. transfer to perform, and the name of the file.  The file ESLASYNC.INC
  94. contains the following strings, which contain the commands needed to 
  95. initiate a file transfer:
  96.  
  97. string XMODEM_Send    is "UX "  # Upload using the XModem protocol
  98. string XMODEM1K_Send  is "U1 "  # Upload using the 1K XModem protocol
  99. string YMODEM_Send    is "UY "  # Upload using the YModem protocol
  100. string XMODEM_Receive is "DX "  # Download using XModem or 1K XModem protocol
  101. string YMODEM_Receive is "DY "  # Download using the YModem protocol
  102.  
  103. These strings, or the appropriate literals, can be used to initiate a file
  104. transfer from within ESLASYNC.EXE.  Note that there are both XModem and 
  105. 1K Xmodem choices for uploading, but not for downloading.  When downloading,
  106. ESLASYNC.EXE will automatically try to use the 1K method, but will fall back
  107. to the normal XModem protocol if the host doesn't support the 1K method.
  108. For more information on these file transfer protocols see the included file
  109. XYMODEM.DOC.  More information can be found on Compuserve, as well as in 
  110. many manuals on serial communications.
  111.  
  112. The following commands are examples of implementing file transfers:
  113.  
  114.    copy "COMMAND.COM" to FileName
  115.    send XMODEM_Send FileName "\^D" to ESLASYNC
  116.  
  117.    send "U1 AUTOEXEC.BAT\^D" to ESLASYNC
  118.  
  119.    send YMODEM_Receive "DATA.ZIP\^D" to ESLASYNC
  120.  
  121. Note that there are no carriage returns (\r or \n) or spaces between the
  122. end of the filename and the "\^D" character.
  123.  
  124. The included program "EMULATE.EAL" demonstrates the use of this local 
  125. application.  It is a very simple terminal emulator which can perform 
  126. file transfers.  This Easel program may seem slow due to the fact that it
  127. uses only a "response to char" to display data received from ESLASYNC.EXE.
  128.  
  129.    ----------------------------------------------------------------------
  130.  
  131. The following group of messages are displayed only during an XModem or 
  132. YModem file upload.  They are as follows:
  133.  
  134. XY send: Waiting for remote
  135.    This message indicates that the transfer protocol has successfully 
  136.    started (a valid filename was passed to the local, and it was opened).
  137.    At this point the local is waiting for the host to trigger the start
  138.    of the transfer.
  139.  
  140. XY send: i 1024 and j 128 byte packets
  141. XY send: k total packets
  142.    These two messages are displayed after the previous message.  This 
  143.    alerts you to the number of packets that are to be transfered during
  144.    the upload procedure.  Note, k = i + j in the above messages.
  145.  
  146. XY send: Packet i
  147.    At the beginning of each packet transfer this message is displayed.
  148.    It allows you to keep track of the progress of the transfer.  Note
  149.    that when using the YModem protocol the first packet is 0, the XModem
  150.    protocol begins with packet 1.
  151.  
  152. XY send: Attempt i
  153.    Up to ten attempts will be made to transfer each packet of information.
  154.    If the first attempt fails then this message will notify you of the 
  155.    second through tenth attempt.  This only appears if the first attempt
  156.    for transfering the packet was unsuccessful.
  157.  
  158. XY send: Transfer canceled by remote
  159.    This message notifies you if the receiving (host) computer canceled
  160.    the transfer.  This situation is not very common when accessing BBS's,
  161.    mainframes, and networks such as Compuserve.
  162.  
  163.  
  164. XY send: Empty File (YModem only)
  165.    When uploading using the YModem protocol, the receiving computer is
  166.    notified of the end of the file transfers by sending an "empty" or
  167.    non-existant file. This message is displayed when this happens.
  168.   
  169. XY send: Batch transfer complete   (YModem only)
  170. XY send: Transfer complete
  171.    Depending on the type of transfer one of the above two messages will
  172.    appear when the transfer is complete.  The YModem protocol will display
  173.    the Batch message, whereas the XModem and 1K XModem protocols display
  174.    the normal message.
  175.  
  176. XY send: Transfer failed
  177.    If a transfer fails for any reason (ten unsuccessful attemts to transmit
  178.    a packet, a timeout from the host, a cancelation, etc.) then this
  179.    message is displayed.
  180.  
  181. XY send: END
  182.    When the file transfer protocol has entirely finished (successfully or
  183.    unsuccessfully) this message is displayed.  This is provided mainly as
  184.    a means of synchronization between the local application and Easel.
  185.  
  186.    ----------------------------------------------------------------------
  187.  
  188. These messages are encountered during a XModem or YModem download session
  189. only.  They are identical to the upload messages, with the exception of
  190. the "Bad packet" message and the "File" message.  The "Bad packet" message
  191. occurs if the packet received from the host fails its CRC or checksum test, 
  192. and will cause the packet to be retransmitted (up to 10 times).  The "File"
  193. message displays the filename obtained from the first packet of a YModem
  194. file transfer.
  195.  
  196. XY receive: Waiting for remote
  197. XY receive: File <filename>  (YModem only)
  198. XY receive: k total packets  (YModem only)
  199. XY receive: Packet i
  200. XY receive: Bad packet
  201. XY receive: Transfer canceled by remote
  202. XY receive: Transfer complete
  203. XY receive: Batch transfer complete (YModem only)
  204. XY receive: END
  205.  
  206.    ----------------------------------------------------------------------
  207.  
  208. These are a list of error messages that can be encountered when both 
  209. uploading and downloading files.  Most are fairly self-explanitory, and
  210. all of them will currently cause the file transfer to fail.
  211.  
  212.  
  213.          
  214. XYERROR: Unable to open <filename>
  215.          The specified file couldn't be opened.  Make sure that there are
  216.          no control characters (carriage returns, line feeds, etc.) on
  217.          the specified filename.
  218.  
  219. XYERROR: Startup not acknowledged
  220.          The host (remote) computer never acknowledged the file transfer
  221.          protocol.  Check that it was ready to transmit/receive the file.
  222.  
  223. XYERROR: Packet timeout
  224.          Not all the information was received for the current packet, or
  225.          the remote computer didn't acknowledge the receipt of the last
  226.          packet.
  227.  
  228. XYERROR: Error on disk read
  229.          A packet couldn't be read from or written to the file.  Check the
  230.          disk for damage.
  231.  
  232. XYERROR: EOT not acknowledged
  233.          (Upload only)  When a file transfer has completed, an EOT (End of
  234.          Transfer) message is sent.  If the remote computer doesn't 
  235.          acknowledge this message then the transfer is assumed to have
  236.          failed.  When this error occurs it is possible that the file was
  237.          successfully transfered, although not guaranteed.
  238.  
  239. XYERROR: Invalid command line
  240.          If the file transfer command line sent to ESLASYNC.EXE isn't 
  241.          correct you will get this message.
  242.  
  243. XYERROR: Timeout waiting for remote
  244.          (Download only)  This occurs if an entire packet has not been sent
  245.          and the local application hasn't received any data within a 
  246.          specific amount of time.  
  247.  
  248. XYERROR: Unexpected character
  249.          During certian points in the transfer specific characters are 
  250.          expected from the remote computer.  If a character other than one 
  251.          of the expected characters is received then this message is 
  252.          displayed.
  253.  
  254.    ----------------------------------------------------------------------
  255.  
  256. The error messages below have to do with the actual communications between
  257. the local application and the computers com port.  These errors are 
  258. identical to the error messages displayed by the AVT100.EXE local 
  259. application.  For more information on these refer to the Easel/2, Easel/Win,
  260. or Easel/DOS VT100 support manual.
  261.          
  262. ESLASYNC ERROR: Invalid command
  263. ESLASYNC ERROR: illegal serial port name
  264. ESLASYNC ERROR: illegal syntax in port characteristics
  265. ESLASYNC ERROR: failed to open serial port
  266. ESLASYNC ERROR: failed to set port characteristics
  267. ESLASYNC ERROR: failed to write characters to serial port
  268.