home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 2 BBS / 02-BBS.zip / FSC.ZIP / FSC-0025.TXT < prev    next >
Text File  |  1988-08-23  |  14KB  |  363 lines
  1. /*   FSC-0025
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.                                                         Pittsburgh, PA
  11.                                                         23 August 1988
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.                              A V A T A R
  23.  
  24.       Advanced Video Attribute Terminal Assembler and Recreator
  25.  
  26.                           George A. Stanislav
  27.  
  28.                                  129/39
  29.  
  30.  
  31.  
  32.                           Historical Overview
  33.  
  34.  
  35. Wynn Wagner III, the author of Opus-CBCS, developed a method of storing
  36. video control codes in a file sent to the Opus caller which was meant as
  37. a replacement of ANSI escape codes. Its main advantages were:
  38.  
  39.         o  The codes are smaller than ANSI, thus needing less disk
  40.            storage space.
  41.  
  42.         o  The codes are in the binary form easily interpreted by the
  43.            computer (ANSI sequences use ASCII).
  44.  
  45.         o  The same file can be sent to callers who do or do not have
  46.            the ability of interpreting ANSI codes - in the former case
  47.            the codes are first translated to ANSI, in the latter they
  48.            are ignored.
  49.  
  50. Because of lack of an appropriate name, Wynn temporarily named the codes
  51. oANSI with the understanding that a better name was needed.
  52.  
  53. When I started working on my TinyTerm communications program, I had the
  54. idea that if Opus-CBCS could send the "oANSI" codes directly over the phone
  55. lines, it would speed up the communications considerably. A typical ANSI
  56. sequence contains 4 times as many bytes as the codes developed by Wynn
  57. Wagner.
  58.  
  59. A phone call to Wynn resulted in two things: 
  60.  
  61.         o  TinyTerm can interpret the "oANSI" codes and translate
  62.            them to ANSI, then send them to stdout where they are
  63.            converted to colors by ANSI.SYS.
  64.  
  65.         o  Opus-CBCS, starting with gamma version 1.10.iii, will
  66.            send the codes without converting them to ANSI sequences.
  67.            (It will still send ANSI codes to users without the proper
  68.            terminal software.)
  69.  
  70. I took over the coding of the part of Opus handling the video codes. I
  71. realized the codes were offering us much more power than just translating
  72. them to ANSI escape sequences. I proposed to call the codes AVATAR, the
  73. Advanced Video Attribute Terminal Assembler and Recreator. Wynn readily
  74. accepted the new name.
  75.  
  76.  
  77.  
  78.                      The Two Levels of Avatar
  79.  
  80. Avatar is more than a video attribute controller. It is a protocol which,
  81. if need be, can totally eliminate the interference of line noise. However,
  82. this document is not concerned with the advanced topics of Avatar (which
  83. no program is using as of this writing).
  84.  
  85. A full Avatar session with all its advanced features starts by exchanging
  86. the AVINIT packets. The caller sends a packet which describes the video
  87. capabilities of his/her system. It also contains the caller's name, password
  88. and some other optional information. It also tells the BBS if the user is
  89. calling in person or just emulating a BBS session with an Avatar terminal
  90. program.
  91.  
  92. The called system (the BBS) replies to the AVINIT packet with a packet that
  93. informs the user of his current status, e.g. you can stay till 16:30 GMT,
  94. or you are denied access, or I am processing mail now but you can call back
  95. at 10:43 GMT, etc.
  96.  
  97. Until such AVINIT packets are exchanged, only the Avatar commands that were
  98. part of the original oANSI codes can be sent from the BBS to the caller.
  99. The caller's term program should send no Avatar commands, with the exception
  100. of function key codes, before the AVINIT packets are exchanged. This assures
  101. that a BBS program which does not support full Avatar can still take
  102. advantage of the faster transfer of video codes using Avatar as opposed to
  103. ANSI escape sequences. It also permits the caller whose term program does
  104. not support full Avatar but can interpret the basic codes to take advantage
  105. of the term program's abilities.
  106.  
  107. The two levels of Avatar then are: a full session and a basic session. This
  108. document is concerned with the BASIC Avatar session only. The full session
  109. will be defined in a separate document.
  110.  
  111.  
  112.  
  113.  
  114.                        Basic Avatar Commands
  115.  
  116.  
  117. Before the AVINIT packets are exchanged, the BBS can send the basic Avatar
  118. commands if so permitted by the user's choice, typically recorded in the
  119. user datafile (e.g. USER.BBS). Because Avatar is window oriented, in a
  120. basic session the full screen is considered the default window. Further,
  121. the default color of the window is assumed to be 3 (cyan text on a black
  122. background). All bytes are taken at their face value without escaping.
  123. However, save for one exception described below, no basic Avatar code will
  124. have the high bit set. Therefore, the term program should reset the high
  125. bit of all bytes except as described below.
  126.  
  127. The basic commands are:
  128.  
  129.         <^L>    -       clear the current window and set current attribute
  130.                         to default. In the basic session this means:
  131.                         Clear the screen and set its attribute to 3.
  132.  
  133.         <^Y>    -       Read two bytes from the modem. Send the first one
  134.                         to the screen as many times as the binary value
  135.                         of the second one. This is the exception where
  136.                         the two bytes may have their high bit set. Do
  137.                         not reset it here!
  138.  
  139.         <^V> <^A> <attr> - Set the color attribute to <attr>. The default
  140.                         attribute remains unchanged. However, all text
  141.                         will be displayed in <attr> until the next ^V^A,
  142.                         ^V^B, or ^L.
  143.  
  144.         <^V> <^B>   -   Turn the high bit of current attribute on. In
  145.                         other words, turn blink on.
  146.  
  147.         <^V> <^C>   -   Move the cursor one line up. Do nothing, if you
  148.                         already are at the top line of the current
  149.                         window.
  150.  
  151.         <^V> <^D>   -   Move the cursor one line down. Do nothing if you
  152.                         already are at the bottom line of the current
  153.                         window.
  154.  
  155.         <^V> <^E>   -   Move the cursor one column to the left. Do nothing
  156.                         if you already are at the leftmost column of the
  157.                         current window.
  158.  
  159.         <^V> <^F>   -   Move the cursor one column to the right. Do nothing
  160.                         if you already are at the rightmost column of the
  161.                         current window.
  162.  
  163.         <^V> <^G>   -   Clear the rest of the line in the current window
  164.  
  165.  
  166.                         using the current attribute (not to be confused
  167.                         with the default attribute).
  168.  
  169.         <^V> <^H> <row> <col>   -   Move the cursor to the <row> <col>
  170.                         position within the current window.
  171.  
  172.  
  173. Comments:
  174.  
  175. Current attribute and default atribute are not necessarily the same.
  176. Whenever the window is cleared by the <^L> command, the current attribute
  177. is made equal to the default attribute. There is also another command to
  178. make the current attribute equal to the default attribute. However, this
  179. command is not a part of the basic Avatar command set and therefore cannot
  180. be used before the AVINIT packets are exchanged.
  181.  
  182. Whatever characters are sent to the screen, they should be displayed using
  183. the CURRENT attribute. There is an exception to this, but only after the
  184. AVINIT packets have been exchanged.
  185.  
  186. The attribute byte is an eight-bit value. As basic Avatar can only transfer
  187. 7-bit commands, the high bit of the attribute byte can be set only by the
  188. <^V> <^B> command. The <attr> byte of the <^V> <^A> <attr> command should
  189. be AND-ed with 7F (hexadecimal). The colors set by the attribute byte are
  190. the same as are the colors of the text mode of an IMB color graphics adapter.
  191.  
  192. That means the bits of the attribute byte have the following meaning:
  193.  
  194.      bit:         7   6   5   4   3   2   1   0
  195.                   -   -   -   -   -   -   -   -
  196.                   |   |       |   |           |
  197.                   |   |       |   |           |
  198.                   |   +---+---+   +-----+-----+
  199.                   |       |             |
  200.                   |       |             |
  201.                   |       |
  202.                   |       |         text color
  203.                   |       |
  204.                   |
  205.                   |    background color
  206.                   |
  207.  
  208.                 blink
  209.  
  210. If the blink bit is set, the text is blinking, else it is not blinking.
  211.  
  212. The bits of background color can have values 0 - 7, the bits of the text
  213. color can have values 0 - 15. The value indicates the following colors:
  214.  
  215.                  0      black
  216.                  1      blue
  217.                  2      green
  218.                  3      cyan
  219.  
  220.  
  221.                  4      red
  222.                  5      magenta
  223.                  6      brown
  224.                  7      gray  (i.e. non-itense white)
  225.                  8      dark gray
  226.                  9      light blue
  227.                 10      light green
  228.                 11      light cyan
  229.                 12      light red
  230.                 13      light magenta
  231.                 14      yellow
  232.                 15      white (intense)
  233.  
  234. Colors 8 - 15 are the same as 0 - 7 but with high intensity.
  235.  
  236. Please note that these values are different from the numbers used by ANSI
  237. escape codes.
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.                      The Function Key Codes
  245.  
  246.  
  247.  
  248. An Avatar capable BBS can accept function keys from the remote caller.
  249. This feature is optional (for the term program) but highly recommended.
  250.  
  251. On an IBM (compatible) computer this means that if a caller hits a function
  252. key (e.g., left arrow, page up, F7, insert, alt-H, etc.), the term program
  253. should send two bytes to the Avatar capable BBS: A binary zero followed by
  254. the keyboard scancode. Please note that control keys (^A, ^B, etc.) are not
  255. function keys but have an ASCII value which is the only byte that should be
  256. transfered.
  257.  
  258. There are two keys on the IBM keyboard that do have an ASCII value but also
  259. offer a separate scan code. These are the gray-plus and the gray-minus. If
  260. one of these keys is hit, treat it as a function key - send the binary zero
  261. followed by the scan code. This way if the BBS treats them differently from a
  262. regular plus and minus keys, the caller can take advantage of the keys.
  263. On the other hand, BBS writers who do not want to assign the gray keys
  264. a special value, should watch for their codes and treat them as a regular
  265. plus and minus.
  266.  
  267. Systems that use a different keyboard layout (and scan codes) than IBM can
  268. emulate IBM by declaring which keys are considered the arrows, f-keys, etc.
  269. If you have the arrow keys, for example, but their scan codes are different,
  270. still send the binary zero and the scan code that an IBM keyboard would
  271. assign to that particular key. This should be transparent to the user.
  272.  
  273.  
  274.  
  275. There is an obvious problem here. All terminal programs I have seen use
  276. function keys internally. A switch is needed so the user can decide whether
  277. a function key is meant for the internal use of the term program or it
  278. should be transfered to the BBS. Most but not all IBM clones have a scroll
  279. lock key, some even have an LED indicator on it. The IBM programs could use
  280. that as a switch to know what the user means by hitting a function key.
  281. Since some compatibles do not have a scroll lock key (e.g. Tandy 1000), the
  282. Avatar capable BBS should never expect the <shift> <F1> combination to be
  283. transfered. That way the term program can use <shift> <F1> to switch between
  284. the local and remote use of function keys if the scroll lock key is not
  285. available.
  286.  
  287.  
  288.  
  289.  
  290.                               Conclusion
  291.  
  292.  
  293. This should about summarize the basic Avatar commands. I have written this
  294. document one day before leaving for Fidocon '88 realizing it would be nice
  295. to give the software developers (both of BBS's and term programs) something
  296. before releasing the specs of the full Avatar implementation.
  297.  
  298. Here is also some sample C code. It assumes you have some low level
  299. communications functions of your own. For the screen output it uses Turbo C
  300. library, but you can use anything you want. */
  301.  
  302.  
  303. #include <conio.h>
  304.  
  305. int def_attr = 3;
  306. int cur_attr = 3;
  307. int lastline = 25;
  308. int lastrow  = 80;
  309.  
  310. /* WARNING: This code has not been tested. It is just meant as an example  */
  311.  
  312. void pascal avatar()
  313. {
  314.  int c,i,j;
  315.  
  316.  switch (mgetchar())            /* Read a char from the modem */
  317.   {
  318.         case 12 :       textattr(cur_attr = def_attr);  /* ^L */
  319.                         clrscr();
  320.                         break;
  321.  
  322.         case 25 :       c = mgetchar();                 /* ^Y */
  323.                         j = mgetchar();
  324.                         for (i = 0; i < j; i++)
  325.                                 cprintf("%c",c);        /* print in color */
  326.                         break;
  327.  
  328.         case 22 :       switch(mgetchar())              /* ^V */
  329.                         {
  330.                          case 1 : cur_attr = mgetchar() & 0x7f;
  331.                                   textattr(cur_attr);
  332.                                   break;
  333.  
  334.                          case 2 : cur_attr |= 0x80;
  335.                                   textattr(cur_attr);
  336.                                   break;
  337.  
  338.                          case 3 : if ((i = wherey()) > 1)
  339.                                         gotoxy(wherex(),i - 1);
  340.                                   break;
  341.  
  342.                          case 4 : if ((i = wherey()) < lastline)
  343.                                         gotoxy(wherex(), i + 1);
  344.                                   break;
  345.  
  346.                          case 5 : if ((i = wherex()) > 1)
  347.                                         gotoxy(i - 1,wherey());
  348.                                   break;
  349.  
  350.                          case 6 : if ((i = wherex()) < lastrow)
  351.                                         gotoxy(i + 1,wherey());
  352.                                   break;
  353.  
  354.                          case 7 : cleol();
  355.                                   break;
  356.  
  357.                          case 8 : i = mgetchar();
  358.                                   gotoxy(mgetchar(),i);
  359.                         }
  360.   }
  361. }
  362.  
  363.