POWER-QWK 2.14 August 1991 (c) Gale Green & Powerline Systems Ltd. This file, and the accompanying programs, form part of the POWER-QWK software package. They can ONLY be distributed as part of the complete POWER-QWK package. Power-Qwk is SHAREWARE. Please register if you find the software of use. Ansi Art and Music ~~~~~~~~~~~~~~~~~~ Introduction ~~~~~~~~~~~~ From release 2.06 onwards, Power-QWK supports messages containing Ansi Music as well as the conventional Ansi colour and cursor movement sequences and the Ansi Art files which were supported at release 2.05. This document describes the Escape Sequences permitted by the ANSI standard, as implemented by console drivers such as ANSI.SYS and its clones, and highlights the differences between standard ANSI files and Ansi Art and Music files. The ANSI standard defines Escape Sequences which may be embedded within Ascii text files to describe various characteristics of that text which are to be applied to it when it is displayed on a video screen. The 'characteristics' describe such things as the colour in which the text is to be displayed, the position on the screen at which the text is to be displayed, whether the text should be standard, intense or flashing, and so on. All this information is read and used by the video driver whenever the file is displayed. As well as providing information to the VIDEO driver about the formatting of subsequent OUTPUT, the Escape Sequences may also contain instructions which the video driver must pass on to the KEYBOARD driver to tell it how it is to interpret subsequent INPUT. A CONSOLE driver, like ANSI.SYS or one of its clones, embodies both a video driver and a keyboard driver so such information is not actually passed anywhere but is merely retained by ANSI.SYS when in video mode for later use when in keyboard mode. An Escape Sequence is a series of characters which always starts with the character pair Esc[. That is, the character Escape, or Ascii 27, followed by a left bracket. An Escape Sequence may be terminated by any one of the characters in the following list: A, B, C, D, H, J, K, R, f, h, l, m, n, p, s, u Each of these terminators defines a particular type of Escape Sequence, thus determining the action to be taken by the video driver and defining what other characters may appear in the Sequence, between the Esc[ and the terminator. With one exception, an Escape Sequence may not contain any of the terminator characters except as its last character, unless the character is embedded within a string which is contained between a matching pair of quote characters. The exception, as we shall see later, is an Ansi Music Sequence. The next three sections describe the standard Ansi Escape Sequences, Ansi Art Escape Sequences and Ansi Music Escape Sequences. Standard Escape Sequences ~~~~~~~~~~~~~~~~~~~~~~~~~ Esc[x;yH These each move the cursor to row x column y. Rows Esc[x;yf are numbered from 1 to 25; columns are numbered from 1 to 80. x and y each default to 1 if omitted. i.e., Esc[H or Esc[f each move the cursor to the Home position (top left hand corner of the screen); Esc[xA Moves the cursor UP x rows (but not beyond top of screen). Cursor column remains unchanged. Esc[xB Moves the cursor DOWN x rows (but not beyond bottom of screen). Cursor column remains unchanged. Esc[xC Moves the cursor RIGHT x columns (but not beyond the right hand edge of the screen). Cursor row remains unchanged. Esc[xD Moves the cursor LEFT x columns (but not beyond the left hand edge of the screen). Cursor row remains unchanged. Esc[s Tells the video driver to remember the current cursor position for later recall by Esc[u. Esc[u Moves the cursor to the last position stored by Esc[s. Esc[2J Clears the screen and moves the cursor to the Home position (top left hand corner of the screen). Esc[K Clears the current row from cursor position to the right hand edge of the screen. Esc[=xh Set Screen to Mode x. mode 0 - 40 by 25 black and white 1 - 40 by 25 colour 2 - 80 by 25 black and white 3 - 80 by 25 colour 4 - 320 by 200 colour 5 - 320 by 200 black and white 6 - 640 by 200 black and white 7 - Set end-of-line wrap ON Esc[=xl Reset screen to Mode x. (N.B., the 'l' is lower case L). This is identical to 'Set Screen Mode', above, except that when x is 7 end-of-line wrap is switched OFF. Esc[?7h Set end-of-line wrap ON. Esc[.....m Set Graphics Rendition Between the Esc[ and the m may appear as many of the numbers in the following list as required, separated by semi-colons. The numbers are processed strictly left to right. 0 - reset to system defaults of White text, Black background, High Intensity (Bold) OFF, Blink OFF. The remaining values only set particular attributes ON. Therefore, whenever you want to alter Intensity or Blink, you are obliged to reset the colours you require at the same time. 1 - Set High Intensity (Bold) ON. 5 - Set Blink ON. 8 - Set Conceal ON (renders the display invisible). 30 - Black foreground ON 31 - Red foreground ON 32 - Green foreground ON 33 - Yellow foreground ON 34 - Blue foreground ON 35 - Magenta foreground ON 36 - Cyan foreground ON 37 - White foreground ON 40 - Black background ON 41 - Red background ON 42 - Green background ON 43 - Yellow background ON 44 - Blue background ON 45 - Magenta background ON 46 - Cyan background ON 47 - White background ON Examples: Esc[45m set Magenta background leaving all other attributes unchanged. Esc[0;1;36m set Light Cyan text on Black background. The following sequence displays the word 'Peacock' in high intensity flashing Blue on a Cyan background, starting at row 10 column 14. As an aid to clarity, the character ` (leftward apostrophe) has been used to represent the Esc character. `[0;1;5;34;46m`[10;14HPeacock Esc[....p Keyboard Reassignment (instructions to be passed to the keyboard driver). Tells the keyboard driver that from now on, until the machine is rebooted or another Reassignment Sequence is encountered, whenever the user types a particular character X, it is to be treated as though the string Y had been typed. X may be specified as a single character between quotes, a single ASCII character code or two ASCII codes (first one zero) separated by a semi-colon. e.g. the character z (lower case Z) may be represented as either "z" or 122 (the ASCII code for lower case Z). The F1 key is represented by the two ASCII codes 0;59. Most of the available ASCII character codes are listed at the end of this document. The entire string between Esc[ and p is treated as an extended ASCII string. The first one or two codes define the character being reassigned and the remainder define the value to be assigned to that character whenever its corresponding key is pressed on the keyboard. Remember, these codes must be OUTPUT in order for them to be interpreted and passed to the keyboard driver to affect INPUT. Therefore, to use any of the keyboard reassignments, you must place the necessary Escape Sequences in a file and then display the file using the DOS TYPE command (and a driver like ANSI.SYS must be loaded at the time). Examples: Esc[0;59;"dir/w";13p causes dir/w to be typed whenever you press F1 Esc["xy"p causes y to be typed whenever you press x. Esc[120;121p causes y to be typed whenever you press x. Esc[120;120p resets character 120 (lower case x) to its normal state. Esc[0;25;"PQ";13p causes PQ to be typed whenever you press Alt/p. The keyboard reassignment sequences are potentially very dangerous because they can be embedded within files to cause 'secret' changes to the keyboard assignments whenever the file is displayed with a console driver in residence. This is how certain Trojan viruses work. Various mechanisms have been adopted to avoid such viruses. For instance, Power-QWK has its own in-built ANSI driver which totally ignores all keyboard reassignments within files and messages. A further precautionary measure has been taken to avoid problems with Ansi Art, as we shall see... Ansi Art Escape Sequences ~~~~~~~~~~~~~~~~~~~~~~~~~ These are exactly as described above for Standard ANSI Escape Sequences except that the Esc character (Ascii 27) is replaced by one of the characters Ascii 249 () Ascii 250 () or Ascii 96 (`). The reason for this change is that it prevents the introduction of Trojan viruses via Ansi keyboard reassignment sequences, if the file is ever displayed using a keyboard driver like ANSI.SYS or any of its clones. Power-QWK automatically ignores keyboard reassignment sequences when displaying received files and messages but this may not be the case with more primitive implementations of the ANSI standard. Ansi Music Escape Sequences ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Ansi Music files and messages may contain all of the Sequences described above for Standard Ansi files, but with the Esc character changed to Ascii 250 or Ascii 96, as described for Ansi Art files. They may also contain Music Escape Sequences in the following format (remember that the notation Esc, here, means Ascii 250 or Ascii 96). Esc[............ i.e., Esc[ as usual, then a series of musical commands terminated by the character Ascii 14. Ascii 14 is the character 'double quaver' (or is it 'double crotchet'), it's a musical note in any case. Many editors and word processors do not allow the use of this character. See the next section 'Placing ANSI Sequences into Files and Messages'. If the program being used to read this document allows the character Ascii 14 then you will see one here: The musical commands are exactly as used by the GW-BASIC PLAY command. There are a total of 85 different notes where note 0 represents silence and notes 1 through 84 are audible. These notes between them cover seven octaves, numbered 0 (deeper notes) to 6 (higher notes). The musical commands are obeyed strictly left to right. The commands available are as follows: On change to Octave n (n range 0 through 6) > if current octave is less than 6 then increase it by 1. < if current octave is greater than 0 then decrease it by 1. Nn play note n (n range 0 to 84 where 0 = rest) See note table at the end of this document. Ln set duration for subsequent notes. 1 = whole note; 2 = half note; 4 = quarter note and so on. Pn pause for duration n. n is as described for Ln. A..G play the note specified (A to G). May be followed by '#' or '+', indicating 'sharp' or '-', indicating 'flat'. Examples: A F B# C- D+ To set a duration for just the current note, over-riding any duration previously set using Ln, write the duration after the note. e.g., L4 A B#2 C plays quarter-length A, followed by half-length B sharp, followed by quarter-length C. One or more dots (.) following a note each indicate that the previously computed duration is to be multiplied by 1.5 Tn set the tempo for subsequent notes. n specifies the number of L4's (quarter notes) that there are in one minute. n must lie in the range 32 to 255. It defaults to 120. MN set 'Music Normal'. Subsequent notes will play for seven eighths of their computed duration. This is the default used by Power-QWK if none of MN, ML or MS has been specified. ML set 'Music Legato'. Subsequent notes will play for the whole of their computed duration. MS set 'Music Staccato'. Subsequent notes will play for three quarters of their computed duration. MF set 'Music Foreground'. Stop all other processing until music has finished. MB set 'Music Background'. Continue other processing while music plays. At least initially, this mode is not supported by Power-QWK. Ansi Music strings may contain MB commands but Power-QWK treats them as MF. Some mail programs insist that music sequences begin with the sequence MB. That is to say, music sequences must have the general form Esc[MB......... Power-QWK is not so fussy - the Esc[ may be followed immediately by any 'M' command - MB, MF, ML, MN or MS. This increases Power-QWK's tolerance of common errors. For the same reason, Power-QWK permits music sequences to be terminated by end-of-line as well as the more usual Ascii 14. When reading Ansi messages with Power-QWK, you will find that more received music will actually play than with ordinary mail readers, simply because Power-QWK is more forgiving of composer errors. Placing Ansi Escape Sequences into Files and Messages ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ There are three main areas of difficulty: 1. Changing Esc characters to Ascii 249, 250 or 96. If you do not have an editor which supports the Esc character, then use the utility ansi2art.exe, supplied with Power-QWK. Just type ansi2art You will be asked whether to replace Esc characters with Ascii 249, 250 or 96 (Power-QWK doesn't mind which you use). If you use one and find that your online service doesn't like it, change to the other. To change a file back to ordinary Esc characters, type art2ansi These utilities are also useful for converting Ansi Art pictures, as output by programs such as TheDraw. If you ask TheDraw to file your picture in Ansi format, it will produce a 'real' Ansi file where all the Escape Sequences start with 'real' Escape characters. This file can be converted to Ansi Art format by typing ansi2art 2. Adding Ascii 14 to the ends of Ansi Music Sequences. If your editor or word processor doesn't support Ascii 14 then use EDLIN. To enter Ascii 14 when using EDLIN, type Ctrl/V followed by the character N. The notation Ctrl/V means 'hold down the Ctrl key; press the V key once and then release both keys'. Pressing Ctrl/Vx (x any character) tells EDLIN that what you really want is Ctrl/x. Ctrl/N is Ascii 14. If you are sending a private message to another Power-QWK user then you may find it useful that Power-QWK, as an extension to the standard, allows you to terminate Ansi Music sequences with the ] character as well as with Ascii 14 (because any editor will allow you to type the ] character). Thus, Power-QWK Music sequences can take the form Esc[Mx..............] Where Esc can be Ascii 27, 249, 250 or 96 and x may be any of the characters which are allowed to follow M - F, B, N, L or S. But remember this is a Power-QWK convention. Other mail readers will not recognise any terminator but Ascii 14 and may expect the first music command to be MB. 3. Entering Esc characters To enter 'ordinary' Escape characters into a file, again use EDLIN if your editor or word processor won't oblige. Remember that Escape is just another name for the character Ctrl/[. Therefore, to enter an Escape character in EDLIN, type Ctrl/V[ To enter the sequence Esc[0;25;"PQ";13p type Ctrl/V[[0;25;"PQ";13p (Note that there are two [ characters - one combines with Ctrl/V to form an Escape character, the other is just a [ character). The Ansi Music Note Table ~~~~~~~~~~~~~~~~~~~~~~~~~ The number suffix on each note below indicates octave. e.g., the notation D#5 indicates the note D sharp in octave 5. No. Note Frequency No. Note Frequency ~~~ ~~~~ ~~~~~~~~~ ~~~ ~~~~ ~~~~~~~~~ 1 C1 65 43 F#4 740 2 C#1 69 44 G4 784 3 D1 73 45 G#4 831 4 D#1 78 46 A4 880 5 E1 82 47 A#4 932 6 F1 87 48 B4 988 7 F#1 93 49 C5 1047 8 G1 98 50 C#5 1109 9 G#1 104 51 D5 1175 10 A1 110 52 D#5 1245 11 A#1 116 53 E5 1319 12 B1 123 54 F5 1397 13 C2 131 55 F#5 1480 14 C#2 139 56 G5 1568 15 D2 147 57 G#5 1661 16 D#2 156 58 A5 1760 17 E2 165 59 A#5 1865 18 F2 175 60 B5 1976 19 F#2 185 61 D#7 2093 20 G2 196 62 E7 2217 21 G#2 208 63 F7 2349 22 A2 220 64 C6 2489 23 A#2 233 65 C#6 2637 24 B2 247 66 D6 2794 25 C3 262 67 D#6 2960 26 C#3 277 68 E6 3136 27 D3 294 69 F6 3322 28 D#3 311 70 F#6 3520 29 E3 330 71 G6 3729 30 F3 349 72 G#6 3951 31 F#3 370 73 A6 4186 32 G3 392 74 A#6 4435 33 G#3 415 75 B6 4699 34 A3 440 76 C7 4978 35 A#3 466 77 C#7 5274 36 B3 494 78 D7 5587 37 C4 523 79 F#7 5919 38 C#4 554 80 G7 6271 39 D4 587 81 G#7 6645 40 D#4 622 82 A7 7040 41 E4 659 83 A#7 7459 42 F4 698 84 B7 7902 Ascii Character Codes ~~~~~~~~~~~~~~~~~~~~~ INPUT Characters Alone Shift Ctrl Alt 1.............49 33 - 0;120 2.............50 64 - 0;121 3.............51 35 - 0;122 4.............52 36 - 0;123 5.............53 37 - 0;124 6.............54 94 - 0;125 7.............55 38 - 0;126 8.............56 42 - 0;127 9.............57 40 - 0;128 0.............48 41 - 0;129 A.............97 65 1 0;30 B.............98 66 2 0;48 C.............99 67 3 0;46 D.............100 68 4 0;32 E.............101 69 5 0;18 F.............102 70 6 0;33 G.............103 71 7 0;34 H.............104 72 8 0;35 I.............105 73 9 0;23 J.............106 74 10 0;36 K.............107 75 11 0;37 L.............108 76 12 0;38 M.............109 77 13 0;50 N.............110 78 14 0;49 O.............111 79 15 0;24 P.............112 80 16 0;25 Q.............113 81 17 0;16 R.............114 82 18 0;19 S.............115 83 19 0;31 T.............116 84 20 0;20 U.............117 85 21 0;22 V.............118 86 22 0;47 W.............119 87 23 0;17 X.............120 88 24 0;45 Y.............121 89 25 0;21 Z.............122 90 26 0;44 F1............0;59 0;84 0;94 0;104 F2............0;60 0;85 0;95 0;105 F3............0;61 0;86 0;96 0;106 F4............0;62 0;87 0;97 0;107 F5............0;63 0;88 0;98 0;108 F6............0;64 0;89 0;99 0;109 F7............0;65 0;90 0;100 0;110 F8............0;66 0;91 0;101 0;111 F9............0;67 0;92 0;102 0;112 F10...........0;68 0;93 0;103 0;113 Alone Shift Ctrl Alt Insert........0;82 48 - - Delete........0;83 46 - - Home..........0;71 55 0;119 - End...........0;79 49 0;117 - PgUp..........0;73 57 0;132 - PgDn..........0;81 51 0;118 - Cursor Up.....0;72 56 - - Cursor Down...0;80 50 - - Cursor Left...0;75 52 0;115 - Cursor Right..0;77 54 0;116 - Print Screen..- - 0;114 - Tab...........9 0;15 - - Return........13 - - - -.............45 95 - 0;130 =.............61 43 - 0;131 The Extended ASCII INPUT Character Set Sorry about the numbering in this section - I'll change it one day. This table I originally used in a different document where this sequence made sense! 1. ^A 32. space 63. ? 94. ^ 2. ^B 33. ! 64. @ 95. _ 3. ^C (Break) 34. " 65. A 96. ` 4. ^D 35. # 66. B 97. a 5. ^E 36. $ 67. C 98. b 6. ^F 37. % 68. D 99. c 7. ^G (Bell) 38. & 69. E 100. d 8. ^H (Backspace) 39. ' 70. F 101. e 9. ^I (Tab) 40. ( 71. G 102. f 10. ^J (Linefeed) 41. ) 72. H 103. g 11. ^K 42. * 73. I 104. h 12. ^L 43. + 74. J 105. i 13. ^M (Return) 44. , 75. K 106. j 14. ^N 45. - 76. L 107. k 15. ^O 46. . 77. M 108. l 16. ^P 47. / 78. N 109. m 17. ^Q 48. 0 (zero) 79. O 110. n 18. ^R 49. 1 80. P 111. o 19. ^S 50. 2 81. Q 112. p 20. ^T 51. 3 82. R 113. q 21. ^U 52. 4 83. S 114. r 22. ^V 53. 5 84. T 115. s 23. ^W 54. 6 85. U 116. t 24. ^X 55. 7 86. V 117. u 25. ^Y 56. 8 87. W 118. v 26. ^Z 57. 9 88. X 119. w 27. Escape (^[) 58. : 89. Y 120. x 28. ^\ 59. ; 90. Z 121. y 29. ^] 60. < 91. [ 122. z 30. ^^ 61. = 92. \ 123. { 31. ^- or ^_ 62. > 93. ] 124. | Next page... 125. } 158. (3) 191. 224. 126. ~ 159. 192. 225. 127. ^backspace 160. 193. 226. 128. 161. 194. 227. 129. 162. 195. 228. 130. 163. 196. 229. 131. 164. 197. 230. 132. 165. 198. 231. 133. 166. 199. 232. 134. 167. 200. 233. 135. 168. 201. 234. 136. 169. 202. 235. 137. 170. 203. 236. 138. 171. 204. 237. 139. 172. 205. 238. 140. 173. 206. 239. 141. 174. 207. 240. 142. 175. 208. 241. 143. 176. 209. 242. 144. 177. 210. 243. 145. 178. 211. 244. 146. 179. 212. 245. 147. 180. 213. 246. 148. 181. 214. 247. 149. 182. 215. 248. 150. 183. 216. 249. 151. 184. 217. 250. 152. 185. 218. 251. 153. 186. 219. 252. 154. 187. 220. 253. 155. 188. 221. 254. 156. 189. 222. 255. Spce 157. 190. 223. This file, and the accompanying programs and Doc files are (c) Gale Green & Powerline Systems Ltd. June 1991