DPANSA10.HTM (11132B)
1 <HTML><HEAD> 2 <TITLE>DPANS94</TITLE> 3 <link disabled rel="stylesheet" href="mpexc6.css"> 4 <style>@import url(mpexc6.css);</style> 5 </head> 6 7 <BODY> 8 <table width=100%> 9 <tr> 10 <td align=left> 11 <a href=dpansa9.htm><img src=left.gif 12 width=26 height=26 align=ALIGN border=0></a> 13 <a href=dpansa11.htm><img src=right.gif 14 width=26 height=26 align=ALIGN border=0></a> 15 </td> 16 <td align=right> 17 <a href=dpans.htm#toc><img src=up.gif 18 width=26 height=26 align=ALIGN border=0></a> 19 <a name=A.10>Table of Contents</a> 20 </td> 21 </tr> 22 </table> 23 <p> 24 <hr size=4> 25 26 <H2>A.<a href=dpans10.htm>10</a> 27 The optional Facility word set</H2> 28 29 30 <hr> 31 <a name=A.10.6> 32 <H3>A.<a href=dpans10.htm#10.6>10.6</a> 33 Glossary</H3> 34 </a> 35 36 <hr> 37 <a name=A.10.6.1.0742> 38 A.<a href=dpans10.htm#10.6.1.0742>10.6.1.0742</a> 39 AT-XY 40 </a> 41 <P> 42 43 Most implementors supply a method of positioning a cursor on a CRT 44 screen, but there is great variance in names and stack arguments. This 45 version is supported by at least one major vendor. 46 47 <P> 48 49 <hr> 50 <a name=A.10.6.1.1755> 51 A.<a href=dpans10.htm#10.6.1.1755>10.6.1.1755</a> 52 KEY? 53 </a> 54 <P> 55 56 The Technical Committee has gone around several times on the stack 57 effects. Whatever is decided will violate somebody's practice and 58 penalize some machine. This way doesn't interfere with type-ahead on 59 some systems, while requiring the implementation of a single-character 60 buffer on machines where polling the keyboard inevitably results in the 61 destruction of the character. 62 63 <P> 64 65 Use of 66 <a href=dpans6.htm#6.1.1750>KEY</a> 67 or KEY? indicates that the application does not wish to 68 bother with non-character events, so they are discarded, in anticipation 69 of eventually receiving a valid character. Applications wishing to 70 handle non-character events must use 71 <a href=dpans10.htm#10.6.2.1305>EKEY</a> and 72 <a href=dpans10.htm#10.6.2.1307>EKEY?</a>. It is possible to 73 mix uses of KEY? / KEY and EKEY? / EKEY within a single application, but 74 the application must use KEY? and KEY only when it wishes to discard 75 non-character events until a valid character is received. 76 77 <P> 78 79 <hr> 80 <a name=A.10.6.2.1305> 81 A.<a href=dpans10.htm#10.6.2.1305>10.6.2.1305</a> 82 EKEY 83 </a> 84 <P> 85 86 EKEY provides a standard word to access a system-dependent set of 87 <B>raw</B> keyboard events, including events corresponding to members of 88 the standard character set, events corresponding to other members of the 89 implementation-defined character set, and keystrokes that do not 90 correspond to members of the character set. 91 92 <P> 93 94 EKEY assumes no particular numerical correspondence between particular 95 event code values and the values representing standard characters. On 96 some systems, this may allow two separate keys that correspond to the 97 same standard character to be distinguished from one another. 98 99 <P> 100 101 In systems that combine both keyboard and mouse events into a single 102 <B>event stream</B>, the single number returned by EKEY may be 103 inadequate to represent the full range of input possibilities. In such 104 systems, a single <B>event record</B> may include a time stamp, the x,y 105 coordinates of the mouse position, the keyboard state, and the state of 106 the mouse buttons. In such systems, it might be appropriate for EKEY to 107 return the address of an <B>event record</B> from which the other 108 information could be extracted. 109 110 <P> 111 112 Also, consider a hypothetical Forth system running under MS-DOS on a 113 PC-compatible computer. Assume that the implementation-defined 114 character set is the <B>normal</B> 8-bit PC character set. In that 115 character set, the codes from 0 to 127 correspond to ASCII characters. 116 The codes from 128 to 255 represent characters from various non-English 117 languages, mathematical symbols, and some graphical symbols used for 118 line drawing. In addition to those characters, the keyboard can 119 generate various other <B>scan codes</B>, representing such 120 non-character events as arrow keys and function keys. 121 122 <P> 123 124 There may be multiple keys, with different scan codes, corresponding to 125 the same standard character. For example, the character representing 126 the number <B>1</B> often appears both in the row of number keys above 127 the alphabetic keys, and also in the separate numeric keypad. 128 129 <P> 130 131 When a program asks the MS-DOS operating system for a keyboard event, it 132 receives either a single non-zero byte, representing a character, or a 133 zero byte followed by a <B>scan code</B> byte, representing a 134 non-character keyboard event (e.g., a function key). 135 136 <P> 137 138 EKEY represents each keyboard event as a single number, rather than as a 139 sequence of numbers. For the system described above, the following 140 would be a reasonable implementation of EKEY and related words: 141 142 <P> 143 144 The 145 <a href=dpans3.htm#3.2.6>MAX-CHAR</a> 146 environmental query would return 255. 147 148 <P> 149 150 Assume the existence of a word DOS-KEY ( -- char ) which executes the 151 MS-DOS <B>Direct STDIN Input</B> system call (Interrupt 21h, Function 152 07h) and a word DOS-KEY? ( -- flag) which executes the MS-DOS <B>Check 153 STDIN Status</B> system call (Interrupt 21h, Function 0Bh). 154 155 <PRE> 156 : EKEY? ( -- flag ) DOS-KEY? 0<> ; 157 158 : EKEY ( -- u ) DOS-KEY ?DUP 0= IF DOS-KEY 256 + THEN ; 159 160 : EKEY>CHAR ( u -- u false | char true ) 161 DUP 255 > IF ( u ) 162 DUP 259 = IF \ 259 is Ctrl-@ (ASCII NUL) 163 DROP 0 TRUE EXIT \ so replace with character 164 THEN FALSE EXIT \ otherwise extended character 165 THEN TRUE \ normal extended ASCII char. 166 ; 167 168 VARIABLE PENDING-CHAR -1 PENDING-CHAR ! 169 170 : KEY? ( -- flag ) 171 PENDING-CHAR @ 0< IF 172 BEGIN EKEY? WHILE 173 EKEY EKEY>CHAR IF 174 PENDING-CHAR ! TRUE EXIT 175 THEN DROP 176 REPEAT FALSE EXIT 177 THEN TRUE 178 ; 179 180 : KEY ( -- char ) 181 PENDING-CHAR @ 0< IF 182 BEGIN EKEY EKEY>CHAR 0= 183 WHILE 184 DROP 185 REPEAT EXIT 186 THEN PENDING-CHAR @ -1 PENDING-CHAR ! 187 ; 188 </PRE> 189 190 <P> 191 192 This is a full-featured implementation, providing the application 193 program with an easy way to either handle non-character events (with 194 EKEY), or to ignore them and to only consider <B>real</B> characters 195 (with 196 <a href=dpans6.htm#6.1.1750>KEY</a>). 197 198 <P> 199 200 Note that EKEY maps scan codes from 0 to 255 into numbers from 256 to 201 511. EKEY maps the number 259, representing the keyboard combination 202 Ctrl-Shift-@, to the character whose numerical value is 0 (ASCII NUL). 203 Many ASCII keyboards generate ASCII NUL for Ctrl-Shift-@, so we use that 204 key combination for ASCII NUL (which is otherwise unavailable from 205 MS-DOS, because the zero byte signifies that another scan-code byte 206 follows). 207 208 <P> 209 210 One consequence of using the <B>Direct STDIN Input</B> system call 211 (function 7) instead of the <B>STDIN Input</B> system call (function 8) 212 is that the normal DOS <B>Ctrl-C interrupt</B> behavior is disabled when 213 the system is waiting for input (Ctrl-C would still cause an interrupt 214 while characters are being output). On the other hand, if the <B>STDIN 215 Input</B> system call (function 8) were used to implement EKEY, Ctrl-C 216 interrupts would be enabled, but Ctrl-Shift-@ would also cause an 217 interrupt, because the operating system would treat the second byte of 218 the 0,3 sequence as a Ctrl-C, even though the 3 is really a scan code 219 and not a character. One <B>best of both worlds</B> solution is to use 220 function 8 for the first byte received by EKEY, and function 7 for the 221 scan code byte. For example: 222 223 <PRE> 224 : EKEY ( -- u ) 225 DOS-KEY-FUNCTION-8 ?DUP 0= IF 226 DOS-KEY-FUNCTION-7 DUP 3 = IF 227 DROP 0 ELSE 256 + 228 THEN 229 THEN 230 ; 231 </PRE> 232 233 <P> 234 235 Of course, if the Forth implementor chooses to pass Ctrl-C through to 236 the program, without using it for its usual interrupt function, then DOS 237 function 7 is appropriate in both cases (and some additional care must 238 be taken to prevent a typed-ahead Ctrl-C from interrupting the Forth 239 system during output operations). 240 241 <P> 242 243 A Forth system might also choose a simpler implementation of KEY, 244 without implementing EKEY, as follows: 245 246 <PRE> 247 : KEY ( -- char ) DOS-KEY ; 248 249 : KEY? ( -- flag ) DOS-KEY? 0<> ; 250 </PRE> 251 252 <P> 253 254 The disadvantages of the simpler version are: 255 256 <P> 257 258 a) An application program that uses KEY, expecting to receive only valid 259 characters, might receive a sequence of bytes (e.g., a zero byte 260 followed by a byte with the same numerical value as the letter <B>A</B>) 261 that appears to contain a valid character, even though the user pressed 262 a key (e.g., function key 4) that does not correspond to any valid 263 character. 264 265 <P> 266 267 b) An application program that wishes to handle non-character events 268 will have to execute KEY twice if it returns zero the first time. This 269 might appear to be a reasonable and easy thing to do. However, such 270 code is not portable to other systems that do not use a zero byte as an 271 <B>escape</B> code. Using the EKEY approach, the algorithm for handling 272 keyboard events can be the same for all systems; the system dependencies 273 can be reduced to a table or set of constants listing the 274 system-dependent key codes used to access particular application 275 functions. Without EKEY, the algorithm, not just the table, is likely 276 to be system dependent. 277 278 <P> 279 280 Another approach to EKEY on MS-DOS is to use the BIOS <B>Read Keyboard 281 Status</B> function (Interrupt 16h, Function 01h) or the related 282 <B>Check Keyboard</B> function (Interrupt 16h, Function 11h). The 283 advantage of this function is that it allows the program to distinguish 284 between different keys that correspond to the same character (e.g. the 285 two <B>1</B> keys). The disadvantage is that the BIOS keyboard 286 functions read only the keyboard. They cannot be <B>redirected</B> to 287 another <B>standard input</B> source, as can the DOS STDIN Input 288 functions. 289 290 <P> 291 292 293 <hr> 294 <a name=A.10.6.2.1306> 295 A.<a href=dpans10.htm#10.6.2.1306>10.6.2.1306</a> 296 EKEY>CHAR 297 </a> 298 <P> 299 300 EKEY>CHAR translates a keyboard event into the corresponding member of 301 the character set, if such a correspondence exists for that event. 302 303 <P> 304 305 It is possible that several different keyboard events may correspond to 306 the same character, and other keyboard events may correspond to no 307 character. 308 309 <P> 310 311 <hr> 312 <a name=A.10.6.2.1325> 313 A.<a href=dpans10.htm#10.6.2.1325>10.6.2.1325</a> 314 EMIT? 315 </a> 316 <P> 317 318 An indefinite delay is a device related condition, such as printer 319 off-line, that requires operator intervention before the device will 320 accept new data. 321 322 <P> 323 324 <hr> 325 <a name=A.10.6.2.1905> 326 A.<a href=dpans10.htm#10.6.2.1905>10.6.2.1905</a> 327 MS 328 </a> 329 <P> 330 331 Although their frequencies vary, every system has a clock. Since many 332 programs need to time intervals, this word is offered. Use of 333 milliseconds as an internal unit of time is a practical <B>least common 334 denominator</B> external unit. It is assumed implementors will use 335 <B>clock ticks</B> (whatever size they are) as an internal unit and 336 convert as appropriate. 337 338 <P> 339 340 <hr> 341 <a name=A.10.6.2.2292> 342 A.<a href=dpans10.htm#10.6.2.2292>10.6.2.2292</a> 343 TIME&DATE 344 </a> 345 <P> 346 347 Most systems have a real-time clock/calendar. This word gives portable 348 access to it. 349 350 <P> 351 352 <hr> 353 <a href=dpans.htm#toc><IMG src="up.gif" ></A> Table of Contents 354 <BR> 355 <a href=dpansa11.htm><IMG src="right.gif" ></A> 356 Next Section 357 <P> 358 </BODY> 359 </HTML>