home *** CD-ROM | disk | FTP | other *** search
/ 8bitfiles.net/archives / archives.tar / archives / canada-remote-systems / c64 / utils / ace15-tm.doc < prev    next >
Encoding:
Text File  |  2019-04-13  |  17.7 KB  |  314 lines
  1. ACEterm Documentation  for version 1.01   [December 17, 1995]
  2. ------------------------------------------------------------------------------
  3. 1. INTRODUCTION
  4.  
  5. This is a simple VT-100 terminal-emulation program.  To start it up, type:
  6.  
  7. term
  8.  
  9. at the command-line prompt.  When it starts, it will bring up a screen with
  10. 24 display lines and a status line.  (You will see slightly different things
  11. depending on the number of display lines that the window you start the
  12. terminal program in; an 27-row VDC screen gives the best results).  The
  13. status line will display the program name and version (the official name is
  14. "ACEterm"), the baud rate, the parity (et al.) setting, the terminal
  15. emulation type, and the capture buffer-size and modification status, the
  16. amount of dynamic memory free, and which key to press for help.
  17.  
  18. The capture buffer, when active, stores every byte received from the serial
  19. port verbatim (including escape sequences, etc.) and can grow to be as large
  20. as the amount of free "dynamic" memory you have available.  My system has
  21. 12.5 Megs of the stuff available, and that is how large my capture buffer
  22. can get.  The size of the capture buffer is reported in bytes on the status
  23. line (as is the amount of dynamic memory free).
  24.  
  25. The capture buffer uses "dynamic memory" exclusively for storing data (it
  26. doesn't use any memory in the program area for this), so you will not have
  27. much luck trying to use this feature on an unexpanded C64, which will only
  28. give you a little bit of dynamic memory to use (more if you disable the
  29. Soft-80 display or decrease the program-area limit).  Also, this feature
  30. will drop lots of characters if your modem doesn't have RTS/CTS hardware
  31. flow control.  If your modem has hardware flow control but you lose
  32. characters anyway, then try fiddling with the "RTS activation delay" field
  33. in the system configuration.  You can check if you are losing characters by
  34. pressing Ctrl-O and checking the overrun count.  The program currently has
  35. only one capture buffer, but the design allows for multiple capture buffers
  36. (if such a thing whould be useful).  The capture buffer is the only real
  37. "feature" of the terminal program, other than the VT-100 emulation.
  38.  
  39. There are three terminal-emulation modes supported: VT-100, GlassTTY, and
  40. Verbatim.  GlassTTY will not interpret any of the escape sequences that it
  41. receives, and Verbatim mode will display every character that it receives
  42. and will not even interpret control characters like carriage return.  In
  43. this mode, the characters will be shown in reverse according to the ASCII
  44. character (printable characters will be translated as normal).
  45.  
  46. All of the important VT-100 escape sequence are supported (including the
  47. Insert-Line and Delete-Line sequences of the VT-102), so you shouldn't have
  48. too many problems.  One thing to note: the scroll-region doesn't work
  49. exactly like it does on a VT-100: if the cursor is moved outside of the
  50. scroll region, then the scroll region will be reset to the entire screen.
  51. (I don't know if this restriction is of any practical consequence; most
  52. full-screen programs just use scroll regions temporarily to insert and
  53. delete lines).  This program has been tested and works perfectly with "vi",
  54. "emacs", "pine", and "lynx".
  55.  
  56. In normal operation, you type characters on the keyboard and they are sent
  57. to the modem, and the characters from the modem are displayed on the
  58. screen.  This is "full echoplex", and the program doesn't support "half
  59. echoplex".  The program also doesn't support menu-oriented auto-dialing/
  60. etc.  features, so you're going to have to send your own "AT" commands to
  61. your modem by hand (which really isn't much of a bother if you have an
  62. intelligent modem and it is set up properly (it doesn't take me very long to
  63. type "atds")).
  64.  
  65. 2. COMMAND KEYS
  66.  
  67. The following hot keys are supported ("Co-" means "Commodore-" and "Ct-"
  68. means "Ctrl-"):
  69.  
  70. Co-A : decrease baud rate
  71. Co-B : increase baud rate
  72. Co-E : exit and save capture buffer if modified
  73. Co-I : help information (also, the HELP key)
  74. Co-N : name the capture buffer
  75. Co-O : show operating status of modem driver
  76. Co-P : change parity: 8N1/7E1
  77. Co-Q : quit (won't work if buffer is modified)-+
  78. Co-S : save the capture buffer                 |
  79. Co-T : set terminal-emulation type             |
  80. Co-Z : pause terminal flow                     v
  81. Co-\ : toggle capture-buffer modification status
  82. Co-_ : compose ISO-8859-1 character
  83. Co + and Co - : enable(+)/disable(-) the capture buffer
  84. Ct-1 : clear the capture buffer
  85. Ct-3 : enter hexadecimal ASCII character code
  86. F1,F3,F5,F7,Ct-@ to Ct-_ : PF1,PF2,PF3,PF4, ASCII Ctrl codes
  87. CLR  : clear screen (nothing sent to modem)
  88. DEL,HOME,BACKARROW : BS,DEL,_(128) / BS,DEL,ESC(64)
  89. RVS,RVSOFF : reverse screen (128 VDC only)
  90. STOP : nothing(128) / send TAB character(64)
  91.  
  92. The capture buffer is named "capturebuf" by default but you can change this
  93. by using Commodore-N.  You will be prompted to enter a filename on the
  94. status line.  This name can be a full pathname if you wish.  If the filename
  95. already exists, then the old file will automatically be overwritten when you
  96. save the capture buffer.
  97.  
  98. If the capture buffer has unsaved characters in it, then an asterisk (*)
  99. will be displayed before the "buf/BUF" field on the status line.  When the
  100. capture buffer is active, the field will be named "BUF" and when it is
  101. inactive, "buf".  The contents of the buffer will be retained between
  102. activations and deactivations.  To clear the capture buffer, use Ctrl-1.
  103. You cannot clear the capture buffer nor exit from the terminal program if
  104. the buffer has unsaved characters in it, so you can use Ctrl-\ (british
  105. pound) to toggle the modification status (or save the buffer with Ctrl-S or
  106. Ctrl-E).
  107.  
  108. The Ctrl-O "operating status" of the modem includes the number of characters
  109. dropped, send, and received.
  110.  
  111. The Ctrl-Z key allows you to stop the flow of the display immediately.  When
  112. this key is pressed, ACEterm will stop pulling characters from the modem
  113. device and will wait for you to press another key.  If the receive buffer
  114. for the modem fills up, then the device driver will assert hardware flow
  115. control.  If you have a hardware-flow-controlled connection all the way back
  116. to your remote host, then no characters will be lost.  For modern remote
  117. hosts, this mechanism will give you much faster response than the
  118. now-pretty-much-useless Ctrl-S / Ctrl-Q (Xoff/Xon) mechanism.
  119.  
  120. The keys DEL, HOME, BACKARROW, and STOP send special characters, depending
  121. on whether you are using a C128 or C64 keyboard (extended or basic
  122. keyboard).  The DEL and HOME keys send BackSpace ($08) and Delete ($7f),
  123. respectively on both keyboards.  The BACKARROW sends an underscore and STOP
  124. is ignored on a C128 while BACKARROW sends an Escape and STOP sends a Tab on
  125. the C64.  To get an underscore on a C64, you can press either
  126. Shift-BACKARROW or Commodore-SPACE.  These keys are not currently
  127. user-definable (except by modifying and re-assembling the terminal
  128. program--it is written for the ACE-assembler and the stuff to change is near
  129. the bottom of the source file), so you'll have to live with these settings
  130. for the time being.
  131.  
  132. 3. CHARACTER COMPOSITION
  133.  
  134. ACEterm has two command keys for composing characters:  Ctrl-3 (with the #
  135. symbol on top) and Commodore-_ (BackArrow).  After pressing the former, you
  136. will be prompted to enter the two-digit hexadecimal number for the ASCII
  137. code that you want to send.  After entering the digits, the code will be
  138. sent just as if you had typed it on the keyboard.  For your convenience, a
  139. table of all of the ASCII codes (including the ISO-8859-1 codes) is included
  140. in Appendix A of this document.
  141.  
  142. Note that in order to display the ISO-8859-1 characters, you have to load
  143. that characterset into the kernel.  You can do this by either typing:
  144.  
  145. chrset acechr-iso8859-1
  146.  
  147. on the command line or by changing the "default character set" field in the
  148. system configuration to be the string "acechr-iso8859-1".  The factory-set
  149. default is to use "acechr-commodore" for hysterical raisins (though I
  150. personally use the ISO set at all times).
  151.  
  152. The Commodore-BackArrow command will prompt you for a special two-character
  153. code that represents the ISO-8859-1 character that you want to send.  For
  154. example, if I wanted to enter Marko Makela's name in the proper way, I would
  155. enter (angle brackets around keystrokes):
  156.  
  157. <M><a><r><k><o>< ><M><Co-_><"><a><k><e><l><Co-_><"><a>
  158.  
  159. The following character-composition sequences are accepted for generating
  160. ISO-8859-1 characters.  This table was derived from the VT-220 character-
  161. composition table, but a few extensions are made because the VT-220 table
  162. didn't include all of the ASCII codes between $A0 and $FF (plus, a couple
  163. of VT characters are in different positions).
  164.  
  165. ASC  SEQUENCE                  ASC  SEQUENCE            ASC  SEQUENCE
  166. ---  ---------------           ---  --------            ---  --------
  167. $a0  <space><space>            $c0  `A                  $e0  `a
  168. $a1  !!                        $c1  'A                  $e1  'a
  169. $a2  C/ or C|                  $c2  ^A                  $e2  ^a
  170. $a3  L- or L=                  $c3  ~A                  $e3  ~a
  171. $a4  XO or X0                  $c4  "A                  $e4  "a
  172. $a5  Y- or Y<space>            $c5  *A                  $e5  *a
  173. $a6  ||                        $c6  AE                  $e6  ae
  174. $a7  SO or S! or S0            $c7  C,                  $e7  c,
  175. $a8  ""                        $c8  `E                  $e8  `e
  176. $a9  CO or C0                  $c9  'E                  $e9  'e
  177. $aa  A_                        $ca  ^E                  $ea  ^e
  178. $ab  <<                        $cb  "E                  $eb  "e
  179. $ac  ~~                        $cc  `I                  $ec  `i
  180. $ad  --                        $cd  'I                  $ed  'i
  181. $ae  RO or R0                  $ce  ^I                  $ee  ^i
  182. $af  __                        $cf  "I                  $ef  "i
  183. $b0  0^                        $d0  D-                  $f0  %o
  184. $b1  +-                        $d1  ~N                  $f1  ~n
  185. $b2  2^                        $d2  `O                  $f2  `o
  186. $b3  3^                        $d3  'O                  $f3  'o
  187. $b4  ''                        $d4  ^O                  $f4  ^o
  188. $b5  /U                        $d5  ~O                  $f5  ~o
  189. $b6  P!                        $d6  "O                  $f6  "o
  190. $b7  .^                        $d7  **                  $f7  //
  191. $b8  ,,                        $d8  O/                  $f8  o/
  192. $b9  1^                        $d9  `U                  $f9  `u
  193. $ba  O_                        $da  'U                  $fa  'u
  194. $bb  >>                        $db  ^U                  $fb  ^u
  195. $bc  14                        $dc  "U                  $fc  "u
  196. $bd  12                        $dd  'Y                  $fd  'y
  197. $be  34                        $de  PP                  $fe  pp
  198. $bf  ??                        $df  ss                  $ff  "y
  199.  
  200. You don't have to worry about typing each of these sequences exactly as-is,
  201. since four transformations are applied in trying to match a two-character
  202. sequence to an ASCII code: (1) try to match as-is; (2) swap the order of the
  203. two characters and try to match; (3) swap the order back and alter the case
  204. of the two characters (letters) and try to match; and (4) swap the altered-
  205. case characters into reverse order again and try to match.  The first match
  206. wins, and if no matches work then an error is displayed and nothing is sent
  207. to the modem.
  208.  
  209. 4. THE FUTURE
  210.  
  211. Future plans for this terminal program include fixing perfecting the
  212. emulation implementing a scrollback viewer for the capture buffer, and
  213. allowing the program to call external programs like the command shell, ZED,
  214. and file-transfer programs.  The intended file-transfer programs are:
  215. Raw-Text transfer, FX, and Z-Modem.
  216.  
  217. The terminal program will be made to accept the following commands in its
  218. configuration file, ".termrc" (currently no support exists):
  219.  
  220. - Implement some kind of user-configuration mechanism into ACEterm.
  221.   Functions: getline, getword, locaseWord, lookupWord.
  222.   - script ".termrc":
  223.   - key del $08
  224.   - key home $7f
  225.   - key backarrow $5f
  226.   - key stop null
  227.   - term vt-100
  228.   - baud 38400
  229.   - parm 8N1
  230.   - string 1 hello there how are you?
  231.   - readbuf 768
  232.   - chrset filename
  233.   - number 1 38400 8N1 886-1234 ccnga
  234.   - hangup ~~~ATH^m~~~
  235.   - dial ATDT
  236.   - call-external yes
  237. - Extra features for ACEterm: send break, drop DTR, force flow control.
  238. - Extend the configuration file to 512+ bytes and add new configuration
  239.   items, including the keymaps, a temporary directory, and a config
  240.   directory list for ".xxxxrc" files (or use exec path?).  Type of C128
  241.   internal memory expansion, type of C64 internal memory expansion, type
  242.   of clock to initially set time from.
  243. ------------------------------------------------------------------------------
  244. APPENDIX A.
  245. ------------------------------------------------------------------------------
  246.                    Craig's Handy ASCII Guide (ISO-8859-1)
  247.  
  248.   0/00 ____NUL____   64/40 _____@_____  128/80 ___________  192/c0 _A`_grave__
  249.   1/01 ____SOH____   65/41 _____A_____  129/81 ___________  193/c1 _A'_acute__
  250.   2/02 ____STX____   66/42 _____B_____  130/82 ___________  194/c2 _A^_circum_
  251.   3/03 ____ETX____   67/43 _____C_____  131/83 ___________  195/c3 _A~_tilde__
  252.   4/04 ____EOT____   68/44 _____D_____  132/84 ___________  196/c4 _A"_dieres_
  253.   5/05 ____ENQ____   69/45 _____E_____  133/85 ___________  197/c5 _A__ring___
  254.   6/06 ____ACK____   70/46 _____F_____  134/86 ___________  198/c6 _AE________
  255.   7/07 ____BEL____   71/47 _____G_____  135/87 ___________  199/c7 _C,cedilla_
  256.   8/08 ____BS_____   72/48 _____H_____  136/88 ___________  200/c8 _E`_grave__
  257.   9/09 ____TAB____   73/49 _____I_____  137/89 ___________  201/c9 _E'_acute__
  258.  10/0a ____LF_____   74/4a _____J_____  138/8a ___________  202/ca _E^_circum_
  259.  11/0b ____VT_____   75/4b _____K_____  139/8b ___________  203/cb _E"_dieres_
  260.  12/0c ____FF_____   76/4c _____L_____  140/8c ___________  204/cc _I`_grave__
  261.  13/0d ____CR_____   77/4d _____M_____  141/8d ___________  205/cd _I'_acute__
  262.  14/0e ____SO_____   78/4e _____N_____  142/8e ___________  206/ce _I^_circum_
  263.  15/0f ____SI_____   79/4f _____O_____  143/8f ___________  207/cf _I"_dieres_
  264.  16/10 ____DLE____   80/50 _____P_____  144/90 ___________  208/d0 _D-_Eth_lr_
  265.  17/11 ____DC1____   81/51 _____Q_____  145/91 ___________  209/d1 _N~_tilde__
  266.  18/12 ____DC2____   82/52 _____R_____  146/92 ___________  210/d2 _O`_grave__
  267.  19/13 ____DC3____   83/53 _____S_____  147/93 ___________  211/d3 _O'_acute__
  268.  20/14 ____DC4____   84/54 _____T_____  148/94 ___________  212/d4 _O^_circum_
  269.  21/15 ____NAK____   85/55 _____U_____  149/95 ___________  213/d5 _O~_tilde__
  270.  22/16 ____SYN____   86/56 _____V_____  150/96 ___________  214/d6 _O"_dieres_
  271.  23/17 ____ETB____   87/57 _____W_____  151/97 ___________  215/d7 __multiply_
  272.  24/18 ____CAN____   88/58 _____X_____  152/98 ___________  216/d8 _O/_slash__
  273.  25/19 ____EM_____   89/59 _____Y_____  153/99 ___________  217/d9 _U`_grave__
  274.  26/1a ____SUB____   90/5a _____Z_____  154/9a ___________  218/da _U'_acute__
  275.  27/1b ____ESC____   91/5b _____[_____  155/9b ___________  219/db _U^_circum_
  276.  28/1c ____FS_____   92/5c _____\_____  156/9c ___________  220/dc _U"_dieres_
  277.  29/1d ____GS_____   93/5d _____]_____  157/9d ___________  221/dd _Y'_acute__
  278.  30/1e ____RS_____   94/5e _____^_____  158/9e ___________  222/de _cap_thorn_
  279.  31/1f ____US_____   95/5f _UNDERLINE_  159/9f ___________  223/df _Es-sed_B__
  280.  32/20 ___SPACE___   96/60 _____`_____  160/a0 _req space_  224/e0 _a`_grave__
  281.  33/21 _____!_____   97/61 _____a_____  161/a1 _!_invertd_  225/e1 _a'_acute__
  282.  34/22 _____"_____   98/62 _____b_____  162/a2 ___cent____  226/e2 _a^_circum_
  283.  35/23 _____#_____   99/63 _____c_____  163/a3 ___pound___  227/e3 _a~_tilde__
  284.  36/24 _____$_____  100/64 _____d_____  164/a4 __currency_  228/e4 _a"_dieres_
  285.  37/25 _____%_____  101/65 _____e_____  165/a5 ____yen____  229/e5 _a__ring___
  286.  38/26 _____&_____  102/66 _____f_____  166/a6 _|_broken__  230/e6 _ae________
  287.  39/27 _____'_____  103/67 _____g_____  167/a7 __section__  231/e7 _c,cedilla_
  288.  40/28 _____(_____  104/68 _____h_____  168/a8 __umulaut__  232/e8 _e`_grave__
  289.  41/29 _____)_____  105/69 _____i_____  169/a9 _copyright_  233/e9 _e'_acute__
  290.  42/2a _____*_____  106/6a _____j_____  170/aa __fem_ord__  234/ea _e^_circum_
  291.  43/2b _____+_____  107/6b _____k_____  171/ab _l_ang_quo_  235/eb _e"_dieres_
  292.  44/2c _____,_____  108/6c _____l_____  172/ac ____not____  236/ec _i`_grave__
  293.  45/2d _____-_____  109/6d _____m_____  173/ad _syl_hyphn_  237/ed _i'_acute__
  294.  46/2e _____._____  110/6e _____n_____  174/ae _registerd_  238/ee _i^_circum_
  295.  47/2f _____/_____  111/6f _____o_____  175/af _overline__  239/ef _i"_dieres_
  296.  48/30 _____0_____  112/70 _____p_____  176/b0 __degrees__  240/f0 _o^x_Eth_s_
  297.  49/31 _____1_____  113/71 _____q_____  177/b1 ____+/-____  241/f1 _n~_tilda__
  298.  50/32 _____2_____  114/72 _____r_____  178/b2 _2_supersc_  242/f2 _o`_grave__
  299.  51/33 _____3_____  115/73 _____s_____  179/b3 _3_supersc_  243/f3 _o'_acute__
  300.  52/34 _____4_____  116/74 _____t_____  180/b4 ___acute___  244/f4 _o^_circum_
  301.  53/35 _____5_____  117/75 _____u_____  181/b5 ____mu_____  245/f5 _o~_tilde__
  302.  54/36 _____6_____  118/76 _____v_____  182/b6 _paragraph_  246/f6 _o"_dieres_
  303.  55/37 _____7_____  119/77 _____w_____  183/b7 __mid_dot__  247/f7 __divide___
  304.  56/38 _____8_____  120/78 _____x_____  184/b8 __cedilla__  248/f8 _o/_slash__
  305.  57/39 _____9_____  121/79 _____y_____  185/b9 _1_supersc_  249/f9 _u`_grave__
  306.  58/3a _____:_____  122/7a _____z_____  186/ba __mas_ord__  250/fa _u'_acute__
  307.  59/3b _____;_____  123/7b _____{_____  187/bb _r_ang_quo_  251/fb _u^_circum_
  308.  60/3c _____<_____  124/7c _____|_____  188/bc ____1/4____  252/fc _u"_dieres_
  309.  61/3d _____=_____  125/7d _____}_____  189/bd ____1/2____  253/fd _y'_acute__
  310.  62/3e _____>_____  126/7e _____~_____  190/be ____3/4____  254/fe _sm_thorn__
  311.  63/3f _____?_____  127/7f ____DEL____  191/bf _?_invertd_  255/ff _y"_dieres_
  312.  
  313. ------------------------------------------------------------------------END---
  314.