home *** CD-ROM | disk | FTP | other *** search
/ Oakland CPM Archive / oakcpm.iso / cpm / cis / protoc.cqs / PROTOC.CIS
Encoding:
Text File  |  1985-02-10  |  14.4 KB  |  365 lines
  1.                    PROTOCOL NOTES: CIS A PROTOCOL
  2.              by Bob Richardson, Carl Raff, and Scott Lowe
  3.                         Copyright (C) 1982
  4.                    Performance Business Machines
  5.  
  6.             A Division of MicroPro International Corporation
  7.                        101 Lucas Valley Road
  8.                        San Rafael, California 94903
  9.  
  10.             Revised by Ken Brassler,  4/2/83
  11.  
  12. Note: this material was not prepared for or by CIS and they have no
  13. responsibility for the accuracy or completeness of the contents. We
  14. gratefully acknowlege their cooperation and the super job they are doing,
  15. and simply wish to help  document the file transfer protocol.
  16.  
  17. INTRODUCTION
  18.  
  19. The information presented here is intended to provide an outline of the
  20. written specifications for the CIS A Protocol. It is designed to be used by
  21. programmers who may need to debug or  write programs to interface with
  22. Compuserve Information  Services (CIS) terminal programs.
  23.  
  24. The PBM 1000 supports a communication subsystem based on the CIS protocol.
  25. One reason is that the CIS protocol is a step in the direction of software
  26. standardization and higher compatibility among different computer systems.
  27. The CIS protocol supports flexible file transfer and is practical for
  28. in-house use on a direct-connect medium speed network. PBM tests show that
  29. the protocol runs effectively at 19.2 KB and can transfer data at a rate
  30. of up to 50 KB.
  31.  
  32. In transferring files from one system to another, one CP/M- based system
  33. (with a copy of any of the CIS executives that supports the A protocol)
  34. acts as a terminal. The other system, referred to as the "host," treats the
  35. "terminal" system both as a console and as the source or target of the file
  36. transfer protocol.
  37.  
  38. The following is a brief description of the CIS A Protocol used by CIS.
  39. Also included is a list of Executives compatible with it, and two new
  40. files which allow anyone with a CP/M remote system to support this
  41. protocol between CP/M systems. Note: CP/M is a registered trademark of
  42. Digital Research.
  43.  
  44. The Executives
  45.  
  46. 1. MNEXEC [Old Executive]
  47.  
  48. An older version of the Executive, MNEXEC supports ASCII transfer only .
  49. This executive is primarily useful for those who wish to buy programs from
  50. Softex, as its ESC I response is the only one that the Softex system
  51. currently recognizes as a file-xfer executive (see ESC I response). This
  52. program does not really support the A protocol, but rather a subset.
  53.  
  54. 2. CSEXEC [The Compuserve Executive]
  55.  
  56. CSEXEC was the first "vanilla" version with binary support. It is a good
  57. executive to start with for those wishing to heavily modify the source
  58. because it  suffers less from "rampant equate-itis" than BUFEXEC (i.e, it
  59. accomplishes tasks in a more general fashion without presenting too many
  60. options to the user). The current version seems to be modified for the
  61. Apple computer.
  62.  
  63. 3. BUFEXEC [Buffered CSEXEC]
  64.  
  65. BUFEXEC adds memory buffered hard copy to CSEXEC, as well as many
  66. customization equates. The Osborne  version is called "BUFEXO.ASM," and is
  67. identical to  BUFEXEC except for modifications for the Osborne I.
  68.  
  69. 4. IOBEXEC [IO/Byte Executive] This executive is identical to BUFEXEC,
  70. except that it  uses IOBYTE dispatch to access the serial port. If  your
  71. system is interrupt driven, you must use IOBEXEC  or modify one of the
  72. other executives. In addition,  IOBEXEC allows use of cursor positioning. 
  73.  
  74. Note: There are a number of customized protocols floating around; most
  75. are based on BUFEXEC and represent adaptation for particular hardware
  76. such as the Osborne, Kaypro, Apple, etc.
  77.  
  78. PROTOCOLS
  79.  
  80. Characteristics of the physical protocol: asynchronous; 8-bit;  8 bits to
  81. the byte; 1 stop bit; no parity.
  82.  
  83. The protocol mode is turned "on" by an SI instruction (shift in) from the
  84. host and the terminal then functions in protocol mode until an SO (shift
  85. out) instruction is received.
  86.  
  87. The ESC "I" Response: Each terminal responds to an ESC "I"  with an ID
  88. string (see diagrams below).
  89.  
  90. The ESC "A" Sequence: This initiates a file transfer.
  91.  
  92. The ESC "L" Sequence: This starts a load sequence.
  93.  
  94. Notes: The "." (period) is used to ACK a message (acknowledge and accept).
  95. The "/" (slash) is used to NAK a message (negative acknowledge; request
  96. retransmission). If Ack or Nak is not sent to CIS in a given period of time,
  97. CIS responds by re-sending ETX a total of 4 times, then aborts. A CTRL U
  98. sent to the host will abort the file transfer.
  99.  
  100. A list of fields enclosed in [ ] marks indicate that 1 of the list will be
  101. transmitted, depending on the conditions at the time.
  102.  
  103. ESC "I" Sequence
  104.  
  105. Host                       Terminal
  106.          "SI" (Protocol on)            
  107. ------------------------------------>
  108.          ESC I (Who are you?)
  109. ------------------------------------>
  110.          ID String (see below)
  111. <-----------------------------------
  112.          "SO"  (Protocol  off)                       
  113. [---------------------------------->]
  114.          error; feature lock; end of function
  115.  
  116.          Continue in Protocol
  117. [----------------------------------->]
  118.  
  119. Action: The terminal sends its ID string to the host. The host checks the
  120. features list, etc.                   
  121.  
  122. ID String: A full sample of the ESC I response for the  IOBEXEC protocol
  123. (assigned by CIS) is as follows:
  124.  
  125. <#> <CPM> <MYSYSTEM>, CC, HC, PA, PL, <CR>  
  126.  
  127. The first character is the protocol ID, followed by the OS  name and the
  128. computer name (optional). The string of four pairs  of characters are a
  129. series of features to be assigned if the  system supports them:
  130.  
  131. CC, HC, PA, and PL  <CR>    
  132. CC = full cursor control
  133. HC = hard copy
  134. PA = "A" protocol
  135. PL = "L" protocol
  136.  
  137. See the comments in any version of the executive for a  more detailed
  138. discussion of these fields.
  139.  
  140. MNEXEC is an older version of the executive, and so  the ID string is
  141. slightly different in format than the one for the CIS Executive. A sample
  142. response follows:
  143.  
  144. <01>,<BF>,<SYSTEM2>,<&CPM>,<D> <CR>
  145.  
  146. The first character is the page address of the lowest available page of
  147. memory in the terminal, followed by the page address of the highest
  148. available page in memory, the computer ID, OS name, and "D" for disk
  149. drives.
  150.  
  151. ESC "L" Sequence
  152.  
  153. Host                       Terminal
  154.          SI
  155. ------------------------------------>
  156.          ESC L
  157. ------------------------------------>
  158. <count-1 byte> <low addr> <hi addr> <data> <CHKSUM>
  159. ------------------------------------>
  160.          "." = ACK (Received; OK)
  161. [<----------------------------------]
  162.          "/" = NAK (Error; request retransmission)
  163. [<----------------------------------]
  164.          ESC L
  165. ------------------------------------>
  166.          Next record
  167. ------------------------------------>
  168.          "." = ACK (Received; OK)
  169. [<-----------------------------------
  170.          "/" = NAK (Error; request retransmission)
  171. [<-----------------------------------
  172.          SO (Done) 
  173. [----------------------------------->
  174.  
  175. Action: The terminal loads <data> into memory starting at  address <low>
  176. <hi> for <count> bytes.
  177.  
  178. ESC "A" Sequence: File Transfer
  179.  
  180. Host                       Terminal
  181.          SI (Protocol on)
  182. ------------------------------------>
  183.          ESC A (Start file transfer)
  184. ------------------------------------>
  185. <1-byte SOH> <1-byte rec #> <U/D> <A/B> <file spec> <CR> <LF> <ETX> <CHKSUM>
  186. ------------------------------------>
  187.          "." ACK (Received; OK)
  188. [<----------------------------------]
  189.          "/" NAK (Retransmit)
  190. [<----------------------------------]
  191.  
  192. Action: The terminal sets up to read or write the file given in <file
  193. spec>.
  194.  
  195. ESC "A" Sequence: File Transfer
  196.  
  197.          Download Subsequence 
  198.  
  199. Host                       Terminal
  200.          <SOH> <R/N> <Text> <ETX> <CHKSUM>
  201. ------------------------------------>
  202.          "."  ACK (Accepted record)
  203. [<----------------------------------]
  204.          "/"  NAK (Rejected; retransmit)                      
  205. [<----------------------------------]
  206.          <SOH> <R/N> <Text> <ETX> <CHKSUM>
  207. ------------------------------------>
  208.          "."  ACK (Accepted record)
  209. [<----------------------------------]
  210.          "/"  NAK (Rejected; retransmit)                      
  211. [<----------------------------------]
  212.          <SOH> <R/N> <Text> <EOT> <ETX> <CHKSUM>
  213. ------------------------------------>
  214.          "." or "/"
  215. <------------------------------------
  216.          SO  (Shift out; protocol off)
  217. [---------------------------------->]
  218.          ESC A  (Next file)
  219. [---------------------------------->]
  220.                     ^
  221.                     |                   
  222.          Note: This is currently unused by CIS.
  223.  
  224. ESC  "A" Sequence: File Transfer
  225.  
  226.          Upload Subsequence 
  227.  
  228. Host                       Terminal
  229.          "."  ACK               
  230. ------------------------------------>
  231.          <SOH> <R/N> <Text> <ETX> <CHKSUM>
  232. <------------------------------------
  233.          "."  ACK  (Record accepted)
  234. [---------------------------------->]
  235.          "/"  NAK  (Record rejected; retransmit)
  236. [---------------------------------->]
  237.          <SOH> <R/N> <Text> <ETX> <CHKSUM>
  238. <------------------------------------
  239.          "."  ACK  (Record accepted)
  240. [---------------------------------->]
  241.          "/"  NAK  (Record rejected; retransmit)
  242. [---------------------------------->]
  243.          <SOH> <R/N> <Text> <EOT> <ETX> <CHKSUM>
  244. <------------------------------------
  245.          "."  ACK  (Record accepted)
  246. [---------------------------------->]
  247.          "/"  NAK  (Record rejected; retransmit)
  248. [---------------------------------->]
  249.          SO  (Shift out; exit protocol)
  250. [---------------------------------->]
  251.          ESC A  (Next file)
  252. [---------------------------------->]
  253.  
  254. Field Definitions
  255.  
  256. SI - Shift in (CTRL O). When received in the communications loop, the
  257. terminal software should jump to protocol mode. SI can be expected to
  258. include a parity bit, so ANI 7FH is necessary. Once in protocol, parity is
  259. disabled.
  260.  
  261. SOH - Start of header (CTRL A). Each record begins with SOH.
  262.  
  263. R/N - An Ascii character, starting with 1, and incremented by one ASCII
  264. number after each previous record is acknowledged (ACK). After 0, the R/N
  265. wraps back to 1.
  266.  
  267. U/D - An Ascii character, the U/D instruction determines the direction of
  268. transfer. U = Upload, transfer to host; D = Download, transfer from host.
  269.  
  270. A/B - An Ascii character, signifying an ascii or binary file. Careful
  271. consideration indicates that this is not necessary, since 8 data bits are
  272. received in either case.
  273.  
  274. FILE SPEC - Standard CP/M file specification, with optional drive
  275. reference. This is a literal echo of what the terminal sends to CIS when a
  276. filename is requested. The terminal software should select the requested
  277. disk, Create the file for a download sequence, or Open the file for an
  278. upload sequence.
  279.  
  280. CR - Carraige return, (CNTRL M). Signifies end of file spec in A Protocol
  281. header.
  282.  
  283. LF - Linefeed, (CNTRL J). Inclusion of this character by the host MAY be
  284. determined by your personal DEFAULT settings. Although not mentioned in
  285. previous protocol definitions, it is transmitted by CIS in my case. (KCB)
  286. After CR is received, looping until ETX will cover either posibility.
  287.  
  288. ETX - End of text, (CNTRL C). ETX ends each packet (a group or string of
  289. related characters), and is followed by CHKSUM.
  290.  
  291. EOT - End of transmission, (CNTRL D). When EOT is encountered in the text
  292. field of a record, it ends the current file. CP/M end of file, 1AH (^Z) is
  293. not transmitted by the host, and should be inserted by the terminal
  294. software whenever EOT is received. A purist may elect to insert it only at
  295. the end of an Ascii file, but it does no harm at the end of a binary file
  296. also. For an upload sequence, EOT should be sent to the host in place of
  297. the 1AH Ascii end of file, or after the last sector in a binary file.
  298.  
  299. Character Masking
  300.  
  301. Data characters in the text field that would normally conflict with control
  302. characters (those less than 20h), are sent 'masked' by adding 40h to their
  303. value and preceeded by a DLE (unmasked).
  304.  
  305. Control characters (those meant for control) are always sent unmasked.
  306.  
  307. CHKSUM - Check sum on record calculated on all characters sent after (and
  308. not including) start of header (SOH) and until (and not including) ETX.
  309. Except that, DLE is not included in the checksum, and the following
  310. 'masked' character is checksumed in it's unmasked state. EOT, however, is
  311. included in the checksum. How other control characters in the text field
  312. are checksummed is unknown, however, these appear to be the only two used.
  313.  
  314. 1. CHKSUM <--- (CHKSUM * 2) mod 256
  315. 2. CHKSUM <--- CHKSUM + character
  316. 3. CHKSUM <--- CHKSUM + carry
  317.  
  318. If the check sum is less than hex '20', it is increased  by hex '40' and
  319. sent masked (preceded by a DLE  character). 
  320.  
  321. APPENDIX
  322.  
  323. Since the heart of the CIS Protocol is the checksum routines, the following
  324. code is included to amplify the verbal description. There are better ways
  325. to do everything, so feel free to hack away. This particular sequence is
  326. for a download.
  327. ;
  328. ;
  329. ;a side effect of docks is that it returns with b=a. since etx is not
  330. ;included in the checksum, the calling program can recognize that etx
  331. ;has been received when a is not equal to b.
  332. ;
  333. CHARCKS: CALL     CHARIN   ;get a char from modem
  334.          CPI      ETX      ;end of packet?
  335.          JZ       CHARETX  ;yes, don't include in checksum
  336.          CPI      DLE      ;is next char masked?
  337.          JZ       UNMASK   ;dle not included in checksum
  338.          CPI      EOT      ;end of xmission?
  339.          JZ       SETEOT   ;yes, set flag, and replace with 1ah
  340.          JMP      DOCKS    ;compute checksum and ret to caller
  341. ;
  342. UNMASK:  CALL     CHARIN   ;get masked char
  343.          SUI      40H      ;unmask before checksum
  344.          JMP      DOCKS    ;compute checksum and ret to caller
  345. ;
  346. SETEOT:  STA      EOTFLG   ;make flag non zero
  347.          CALL     DOCKS    ;include in checksum
  348.          MVI      A,1AH    ;replace with eof
  349.          MOV      B,A      ;set a = b for etx test
  350.          RET               ;to caller
  351. ;
  352. CHARETX: MVI      B,0FFH   ;tell packet etx received
  353.          RET               ;to caller
  354. ;
  355. DOCKS:   MOV      B,A      ;save original char
  356.          LDA      CHKSUM   ;get last check sum
  357.          RLC               ;do math
  358.          ADD      B
  359.          ACI      0
  360.          STA      CHKSUM   ;replace new checksum
  361.          MOV      A,B      ;replace orig char
  362.          RET
  363. ;
  364. ;        end of prtcol.cis
  365.