Sometimes, information is not free - you have to work for it!
KEYCODE
GETTER
GETTER
by Bob Hardy
Those of us who enjoy our "power without the price", our "computers for people", or in other words, our 8-bit wonders, hate to admit that there is anything wrong with Atari... but there have been a few moments when it couldn't be helped. There were bugs in Atari BASIC (Revisions A and B) that could lock up the system hopelessly, causing you to lose anything you had in memory at the time.
The Assembler/ Editor cartridge (Rev. A) and its manual were another example... the cartridge got severely confused whenever you tried to trace or step through a binary program and encountered a "CPY #" command. Atari once sent me an errata sheet for the manual -- 11 pages long!
I have discovered another problem area, and it came from a most unexpected source: the venerable Operating System User's Manual!
This often overlooked, almost secret document contains lots of useful information, especially for the advanced programmer. Page 185, in Appendix F, shows a table of keyboard codes for ATASCII characters. This information does not appear in any other publication I know of... not "De Re Atari", nor "Your Atari Computer", nor "Mapping The Atari", nor any other of my Atari bibles. And guess what, campers... it's wrong.
In short, there IS no authoritative place to look up keycodes. I'm not talking about ATASCII codes, or the internal codes used when you poke a character directly into screen ram. I'm talking about the codes that appear in location 764 when a key is pressed. If you PRINT PEEK(764) when no key has been pressed, you get 255, and you can POKE 764, 255 to clear the keypress register. This is fairly well documented, but what about when a key HAS been pressed? According to the Operating System User's Manual, a lower-case "a" keystroke should produce $3F (63), and it does, as does an upper-case "A". But according to that same publication, SHIFT-A should yield the same value... and it doesn't. It also says that CTRL-A yields $3F: it also doesn't.
I could put together a list of all possible values and the keystrokes they represent, but such lists are born to get lost, or to be in the single most unlikely place when you are in the heat of a machine-language programming binge. Instead, I have created Keycode Getter. It runs on any 8-bit Atari with at least 32K or so, from the 400 onward to the 130XE.
How it works is very simple. You do a binary load from DOS with no cartridge present, and press START after reading a little introductory text, and then press a key. What it does is give you the ATASCII character (even "unprintables" like TAB and RETURN), the decimal and hex number for that character in ATASCII, the decimal and hex number for that character in internal code (screen code), and the decimal and hex number for the raw keyboard code, such as can be read from location 764.
Keycode Getter works with combination keystrokes too, or at least, with the combinations that actually produce a character. This excludes SHIFT-CONTROL-A, but includes inverse CTRL-comma, for example. The main purpose of this program is not for such obscurities, however. It is to make the common, ordinary codes accessible, the ones that you might very easily want to use in programming. You may want to see the codes for lower-case or inverse characters anyway. If so, you must press the Inverse key or the CAPS key for each letter, as the program resets the K: device for all capitals, noninverse, after each completed character. Just for your reference, some keys that WON'T return anything are:
SHIFT-CTRL-A
SHIFT-CTRL-B
SHIFT-CTRL-C
SHIFT-CTRL-J
SHIFT-CTRL-K
SHIFT-CTRL-L
SHIFT-CTRL-V
SHIFT-CTRL-X
SHIFT-CTRL-Z
SHIFT-CTRL-;
SHIFT-CTRL-+
SHIFT-CTRL-*
CTRL-1
CTRL-4 through -9
CTRL-0
BREAK
SHIFT, CTRL, CAPS or the Inverse
(Atari) key when with no other key
There is no doubt about the accuracy of the numbers the program gives you, since all but the keyboard codes can be checked in a number of other places, and the keyboard codes themselves are taken directly from the OS register known as CH1. It would be beyond my means to fully explain the significance of CH1 here, but it is discussed in Mapping The Atari... let's just say that it contains the keyboard code of the last key accepted as input by the K: device.
So when you want your program to accept keyboard input, like for a menu selection, and you don't want to use an error-trapped "get a key" IOCB routine... or maybe you want to redefine keys somehow without having to mess with the character tables, especially since they aren't all in the same places between the 400 and 800 operating system and the 1200XL, 600XL, 800XL, 65XE and 130XE operating systems... you can just leave the K: device open, and look at location 764 for ANY particular keycode you might want. (Don't forget to promptly replace it with a 255, if you want it all to end there!)
I am making the source code available for those who are interested in machine language programming. It is written with MAC/65, but with only a little conversion it can be used with SynAssembler or the Assembler/ Editor. There are a few points of interest: the decimal and hex routines could be adapted for almost any kind of number display printout, and there are three separate screenprint routines, each one using a different method!
Feel free to pass Keycode Getter around. In my opinion, most people who write software are users who got unusually frustrated when they couldn't find software written the way they wanted it! I am no exception. I'm anxious to see the software YOU'LL write using Keycode Getter, too!
KEYCODE3.M65