home *** CD-ROM | disk | FTP | other *** search
/ ftp.whtech.com / ftp.whtech.com.tar / ftp.whtech.com / club100 / tel / xmodem.doc < prev    next >
Text File  |  2006-10-19  |  13KB  |  395 lines
  1. Club 100 Library - 415/939-1246 BBS,    937-5039 NEWSLETTER, 932-8856 VOICE
  2.  
  3. Documentation for XMODEM, for TRS-80 Model 100
  4.  
  5. Version of 1/23/85  by  Rick Perry
  6.  
  7.  
  8.    This program performs auto-dial-redial, auto-logon, terminal
  9. emulation, and buffered text file transfers (.DO) using either regular
  10. ASCII Xon/Xoff protocol or the Xmodem Christensen checksum protocol.
  11. Communication parameters are 8N1D during Xmodem file transfers and 7I1E
  12. for terminal emulation and Xon/Xoff transfers. The program will operate
  13. using the 300 baud internal modem or an external modem (Novation
  14. Smart-Cat or equivalent) at 300 or 1200 baud. Files may be Up/Down
  15. loaded directly from/to RAM, disk or cassette.
  16.  
  17.  
  18. AUTO-DIAL/LOGON:
  19.  
  20.    The program starts with a "Find:" prompt and will attempt to retrieve
  21. a phone number and auto-logon sequence from the ADRS.DO file and logon
  22. to a host computer.
  23.  
  24.    When using the internal modem, if no carrier is detected within 20
  25. seconds after dialing, or if you press any key, the program will hang up
  26. the phone. After waiting 20 seconds more, it will retry the number
  27. unless you press any key.
  28.  
  29.    If the carrier is detected, it will BEEP and proceed through the
  30. auto-logon sequence as specified in the ADRS line, then jump to the
  31. terminal emulation mode of the program.
  32.  
  33.    At the "Find:" prompt, enter a string to search for in the ADRS file
  34. or press F8 (or enter "Menu") to return to the Menu. When the string is
  35. found press "M" to begin auto-dial using the internal modem, or press
  36. "S" to dial through an external Novation Smart-Cat modem at 1200 baud,
  37. or press "3" to use Novation at 300 baud, or press ESC to return to the
  38. "Find:" prompt, or press any other key (like ENTER) to continue
  39. searching.
  40.  
  41.    If you wish to manually dial a telephone number, enter "Dial" at the
  42. "Find:" prompt. After dialing and hearing the carrier tone, press "M",
  43. "S", or "3" to allow the program to Connect, or press any other key to
  44. return to the "Find:" prompt.
  45.  
  46.    For a Novation Smart-Cat modem, "3" actually sets the modem baud rate
  47. to 300, "S" sets it to 1200, and the modem command character is set to
  48. CTRL/V in both cases.  The modem is also set for 8-bit data format and
  49. "unlisten" mode to allow Xmodem transfers.  Note: modem baud rates, cmd
  50. char, etc. are not affected when using "DIAL" option at Find: prompt.
  51.  
  52.    The control sequences used with the Novation modem appear around the
  53. last twelve lines of the program. This code may be modified to work
  54. properly with other smart modems. When dialing through an external
  55. modem, code around the last eight lines of the program allow you to
  56. directly enter commands to the modem and optionally press CTRL/R to
  57. restart the program or CTRL/E to exit to the Menu.
  58.  
  59.  
  60. TERMINAL EMULATION:
  61.  
  62.    Once in terminal emulation mode, the program is transparent to all
  63. control characters entered from the keyboard (except CTRL/G as noted
  64. below) and these characters (like CTRL/C/S/Q) will be sent to the host.
  65. But Function key F5 (Brk) may be used to STOP the program if needed.
  66.  
  67.    F4 (Term) is used to jump directly to TELCOM's Term mode while
  68. remaining connected to the host. Once in TELCOM you cannot return to the
  69. program without logging off and disconnecting from the host unless you
  70. are connected through an external modem.
  71.  
  72.    F6 (Free) provides a display of how many bytes of RAM are currently
  73. available.
  74.  
  75.    F7 (Dir) lists the RAM file directory in the same way as the BASIC
  76. FILES command.
  77.  
  78.    F8 (Bye) is used to exit the program and return to the Model 100's
  79. Main Menu.
  80.  
  81.    F2 (Down) will initiate a file download transfer and F3 (Up) will
  82. initiate uploading.
  83.  
  84.    F1 (Prev) will display the previous screen, same as in TELCOM.
  85.  
  86.  
  87. FILE TRANSFERS:
  88.  
  89.    After pressing F2 or F3 and entering file name, program prompts
  90. "Append?" if downloading.  Then it prompts "Use XMODEM protocol?" --
  91. press "Y" or "N".  Responding with "N" means that buffered Xon/Xoff
  92. protocol will be used.
  93.  
  94.    For uploading using Xon/Xoff protocol answer "Width?" prompt by
  95. pressing ENTER if no wrapping is desired, otherwise enter desired width
  96. for word wrapping.
  97.  
  98.    During Xon/Xoff download, F3 is blanked and F2=@@@@.  Press F2 to end
  99. download.  During upload, use F8 to abort.
  100.  
  101.  
  102. DOWNLOADING WITH XMODEM PROTOCOL:
  103.  
  104.    The host should be ready to send the file before entering this mode.
  105. While downloading, the received file is not displayed on the screen.
  106. When a NAK (negative acknowledge) is sent, the program prints an "X".
  107. When ACK (acknowledge) is sent, the program prints ".".
  108.  
  109.    You can abort the download at any time by pressing F8 (Abrt). The
  110. program itself will automatically abort the download only if one of the
  111. following circumstances occur:
  112.  
  113.  - The host sends a CANcel.
  114.  
  115.  - The received block number is neither the current block number nor the
  116. previous block number.
  117.  
  118.  - An error trap occurs in the program (this could be caused by an "Out
  119. of Memory" condition on the Model 100).
  120.  
  121.  
  122. UPLOADING WITH XMODEM PROTOCOL:
  123.  
  124.    The host should be ready to receive the file before entering this
  125. mode. While uploading, the transmitted file is not displayed on the
  126. screen. When a NAK is received, the program prints an "X". When ACK is
  127. received, the program prints ".". If nothing is received after waiting
  128. 10 seconds, or if anything other than NAK, ACK or CAN is received, the
  129. program prints a "?".
  130.  
  131.    You can abort the upload at any time by pressing F8 (Abrt). The
  132. program itself will automatically abort the upload only if the host
  133. sends a CANcel or if an error trap occurs (e.g. due to an IO Error when
  134. uploading from cassette).
  135.  
  136.  
  137. ALTERNATE CHARACTER SET:
  138.  
  139.    When in terminal mode, press CTRL/G to switch between the regular
  140. character set and an alternate set (pseudo APL). This character
  141. translation is defined in an array, T(*), which is loaded from the last
  142. data statement.  This only affects characters printing on the screen,
  143. not file transfers.
  144.  
  145.  
  146. PROGRAM NOTES:
  147.  
  148.    The program itself does not count the number of NAK's sent or
  149. received per block and will not automatically abort if an excessive
  150. number of NAK's occur. It is up to you to use F8 (Abrt) to cancel the
  151. file transfer if you feel that too many NAK's are occuring.
  152.  
  153.    When aborting a file transfer the program sends a single CANcel
  154. character (CTRL/X) to the host and returns to its terminal emulation
  155. mode. If you then notice that the host has not responded to the CANcel,
  156. you may send additional CAN's by pressing CTRL/X. Some hosts expect to
  157. receive three CTRL/C chars in a row to signal an abort; that's dumb, but
  158. anyway, if CTRL/X doesn't work, try that.  Most hosts will automatically
  159. abort an Xmodem transfer if no chars are received for 1 or 2 minutes.
  160.  
  161.    MAXFILES is set to 3 at the beginning and reset to 2 upon normal exit
  162. to the Menu.
  163.  
  164.    Function key definitions are restored to their previous user-defined
  165. values upon exit from the program to the Menu.
  166.  
  167.  
  168. The following ROM calls and POKEs are used:
  169.  
  170.  6118 - set serial interface parameters and activate modem.
  171. 16969 - turn cursor on.
  172. 17061 - set and display temporary function key strings.
  173. 17875 - fill previous screen with blanks.
  174. 21172 - keep phone off hook.
  175. 21179 - hang up phone.
  176. 21264 - 2 second delay.
  177. 21274 - 1/2 second delay.
  178. 21293 - dial a phone number.
  179. 21392 - execute auto-logon sequence.
  180. 21608 - jump to TELCOM's Term mode.
  181. 21795 - display previous screen.
  182. 27804 - restore function key definitions.
  183.  
  184. POKE 63056,64 - enable scrolling into previous screen area and also
  185. disables Break and ON KEY and makes F1...F8 return chars 248...255.
  186.  
  187. POKE -86,0 - purge keyboard buffer.
  188.  
  189.  
  190. PERSONAL NOTE:
  191.  
  192.    This program is customized for my own use, so some of its features
  193. may not be useful to you.  In particular, note that it performs CLEAR
  194. 500, MAXRAM and leaves MAXFILES=2.  Feel free to revise the program to
  195. your own liking and share it here and/or elsewhere.
  196.  
  197.  
  198. MACHINE LANGUAGE SUBROUTINES:
  199.  
  200.    The integer array M(0)..M(60) is used to hold six position
  201. independent machine language subroutines. Entry points are at M(0),
  202. M(3), M(16), M(21), M(24) & M(59). The assembly source listing follows:
  203.  
  204.  
  205. ; ENTRY M(0) - check MDM: for carrier detect.
  206. ;  calling sequence: CALL VARPTR(M(0)),0,VARPTR(X)
  207. ;  where X is an integer variable.
  208.  
  209. M(0)    call    6EEF    ; check for carrier detect
  210.     mov    m,a    ; X=0 if carrier detected,
  211.     ret        ; FF if no carrier
  212.     nop
  213.  
  214.  
  215. ; ENTRY M(3) - convert string to uppercase.
  216. ;  calling sequence: CALL VARPTR(M(3)),0,VARPTR(A$)
  217. ;  where A$ is a string variable.
  218.  
  219. M(3)    mov    a,m    ; check length of string
  220.     ora    a    ; if zero
  221.     rz        ;  then return
  222.  
  223.     mov    c,a    ; save length in counter C
  224.     inx    h    ; get string address
  225.     mov    a,m    ; that's the low byte
  226.     inx    h
  227.     mov    h,m    ; that's the high byte
  228.     mov    l,a    ; HL --> string
  229.  
  230.     lxi    d,2    ; here comes the tricky part
  231.     call    31E9    ; in ROM there is XTHL, PCHL
  232. $PC1    dad    d    ; now HL = loop
  233.     pop    d    ; and DE --> string
  234.  
  235. loop    ldax    d    ; A = char from string
  236.     call    0FE9    ; let ROM convert to uppercase
  237.     stax    d    ; restore converted char
  238.     inx    d    ; point to next char
  239.     dcr    c    ; decrement counter
  240.     rz        ; done when counter = 0
  241.     pchl        ; otherwise jump to loop
  242.  
  243.  
  244. ; ENTRY M(16) - check MDM: or COM: queue for received chars.
  245. ;  calling sequence: CALL VARPTR(M(16)),0,VARPTR(X(0))
  246. ;  where X(0)..X(1) is an integer array.
  247.  
  248. M(16)    mvi    m,0    ; set flag, X(0)=0, for no char
  249.     call    6D6D    ; check queue for chars
  250.     rz        ; return if no chars available
  251.  
  252.     inr    m    ; set flag, X(0)=1, for char received
  253.     inx    h
  254.     inx    h    ; HL --> received char buffer, X(1)
  255.     nop
  256.  
  257.  
  258. ; ENTRY M(21) - retrieve char from MDM: or COM: queue.
  259. ;  if entry was made at M(16) and the queue contained a char
  260. ;  then the code will fall through to this point and the
  261. ;  received char will be placed in X(1).
  262. ;  M(21) may also be called independently of M(16) to receive
  263. ;  a char if it's already known that one is there (due to an
  264. ;  ON MDM GOSUB.. interrupt for example).
  265. ;  calling sequence: CALL VARPTR(M(21)),0,VARPTR(X)
  266. ;  where X is an integer variable.
  267.  
  268. M(21)    call    6D7E    ; get char from queue
  269.     mov    m,a    ; store it
  270.     ret
  271.     nop
  272.  
  273.  
  274. ; ENTRY M(24) - timed read of 131 chars from MDM: or COM: queue.
  275. ;  calling sequence: CALL VARPTR(M(24)),0,VARPTR(Z(0))
  276. ;  where Z(0)..Z(131) is an integer array.
  277. ;  Z(0) is used as a flag.
  278. ;  Upon return, if Z(0)=0 then a timeout occurred.
  279. ;  Z(0)=1 implies successful return and in this case
  280. ;  Z(1)..Z(131) will contain the 131 received characters.
  281.  
  282. x1    equ    39.    ; get_ch - $PC2
  283. x2    equ    7.    ; ck_que - $PC2
  284. x3    equ    4.    ;  init  - $PC2
  285.  
  286. M(24)    mvi    m,0    ; set flag for failure
  287.     mov    d,h
  288.     mov    e,l    ; DE = HL --> flag
  289.  
  290.     call    31E9    ; xthl, pchl
  291. $PC2    mvi    b,131.    ; char counter
  292.     push    b
  293.     push    h
  294.  
  295. ; stack now contains:
  296. ;
  297. ;        address of flag
  298. ;        char counter
  299. ;    sp  -->    $PC2
  300.  
  301. init    lxi    h,7282.    ; HL = 1 second timeout counter
  302.  
  303. ck_que    call    6D6D    ; check queue
  304.  
  305.     pop    b
  306.     push    b
  307.     push    b    ; extra $PC2 on stack
  308.     xthl        ; counter on stack, HL = $PC2
  309.  
  310.     lxi    b,x1    ; offset to get_ch
  311.     dad    b
  312.     xthl
  313.     rnz        ; jnz    get_ch
  314.  
  315.     pop    b    ; clear stack
  316.     dcx    h    ; decrement timeout counter
  317.     mov    a,h
  318.     ora    l
  319.  
  320.     pop    b
  321.     push    b
  322.     push    b    ; extra $PC2 on stack
  323.     xthl        ; counter on stack, HL = $PC2
  324.  
  325.     lxi    b,x2    ; offset to ck_que
  326.     dad    b
  327.     xthl
  328.     rnz        ; jnz    ck_que
  329.  
  330.     pop    b
  331.     pop    b
  332.     pop    b
  333.     pop    b
  334.     ret        ; timeout exit
  335.  
  336. get_ch    call    6D7E    ; get char from queue
  337.     inx    d
  338.     inx    d
  339.     stax    d    ; store it in buffer
  340.  
  341.     pop    h
  342.     pop    b
  343.     dcr    b    ; decrement char counter
  344.     push    b
  345.     push    h    ; HL = $PC2
  346.  
  347.     lxi    b,x3    ; offset to init
  348.     dad    b
  349.     push    h
  350.     rnz        ; jnz    init
  351.  
  352.     pop    h
  353.     pop    h
  354.     pop    h
  355.     pop    h
  356.     inr    m    ; set flag for success !
  357.     ret
  358.  
  359.  
  360. ; ENTRY M(59) - delay A*2 milliseconds
  361. ;  calling sequence:  CALL VARPTR(M(59),A
  362. ;  where A is an integer from 0 to 127.
  363.  
  364. M(59)    mov    c,a
  365.     jmp    531C
  366.  
  367.  
  368. TIMING COMPARISONS:
  369.  
  370.    Up/down-loading tests were performed using a 3422 byte text file and
  371. a VAX-11/780 host.  The following table shows the relative time required
  372. for the file transfers normalized to the TELCOM download time at 300
  373. baud (which was 114 secs.).  Alternate character set was not used, nor
  374. was word wrapping, and CAS: times include overhead of opening the file:
  375.  
  376.               -------XMODEM PROGRAM-------
  377.                 Xon/Xoff        Xmodem
  378. baud  direction  TELCOM       RAM      CAS:      RAM     CAS:
  379. 300    down      1.00       1.25      1.89      1.02     2.16
  380. 300     up      1.25       2.28      2.98      1.52     2.14
  381. 1200    down      0.46       1.27      1.89      0.76     1.38
  382. 1200     up      0.58       2.25      2.93      0.75     1.41
  383.  
  384.  
  385. CONCLUSIONS:
  386.  
  387.  - In TELCOM, uploads take about 25% longer than downloads.
  388.  
  389.  - 1200 baud transfers take at best only half as long as 300 baud,
  390. partly due to the slow speed of LCD scrolling.  Using Xmodem program
  391. Xon/Xoff protocol, transfer times are independent of baud rate.
  392.  
  393.  - Transfer times for Xmodem protocol using RAM file are slightly longer
  394. than TELCOM times.  Using CAS: file doubles the time in some cases.
  395.