Programmer's Minefield
    Those of us who enjoy our "power without the price", our "computers for people", or in other words, our 8-bit wonders, are occasionally forced to admit that Atari Corporation did a few nasty things to us before they finally gave us the boot in 1992. Those of us who were heavily into serious programming occupied the front lines when it came to discovering the minefields Atari laid for us. The infamous Atari BASIC bugs claimed many early casualties. There are bugs in Atari BASIC (Revisions A and B) that could lock up your system hopelessly, causing you to lose anything you had in memory at the time.
    [Editor's Note. Unless you've upgraded your machine to BASIC REV C, your 400/800, XL, and some XE machines probably have one of these "buggy" BASICS, which continue to wreak havoc on the unwary even today. To find out which version you have, do a PRINT PEEK (43234). The number returned indicates which version your machine has: 162 = REVA; 96 = REV B; 234 = REV C. REV C is available from major distributors such as American Techna-Vision, B&C ComputerVisions, etc. - BLP]
    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 discovered yet 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 doesn't 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.

Keycode Follies
    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 (per Tom Andrews' "Speedy Text Buffer Display" elsewhere in this issue). 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 swallowed up in a black hole somewhere just when you're in the heat of a machine-language programming binge. Instead, I created Keycode Getter. It runs on any 8-bit Atari with at least 32K or so, from the 400 up to the 130XE. The binary file is called KEYCODE3.COM.

Running KEYCODE3.COM
    How it works is very simple. Just do a binary load of the KEYCODE3.COM file from DOS with no cartridge present, and press START after reading a little introductory text, and then press a key. Keycode Getter will 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 lowercase 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 (keyboard) for all capitals, non-inverse, 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

Take It To The Bank!
    There's 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's beyond the scope of this article to fully explain the significance of CH1 here, but Ian Chadwick discusses it in "Mapping The Atari". Let's just say CH1 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-just leave the K: device open, and look at location 764 for any particular keyoode you might want. Or maybe you'd like 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/800 operating system and the XL/XE operating systems); again, just leave the K: device open and look at location 764. (Don't forget to promptly replace it with a 255, if you want it all to end there!)

Sourcecode Goodies
    I'm making the source code available for those interested in machine language programming. I wrote it 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 screen-print routines, each one using a different method!
    Feel free to pass Keycode Getter around. I have a feeling that most people who write software are users who got unusually frustrated when they couldn't find software written the way they wanted it, and I'm no exception. I'm anxious to see the software you'll write using Keycode Getter, too!
    [Editor's Note: In addition to the binary file KEYCODE3. COM, the sourcecode listings in in both listable and MAC/65 (files KEYCODE3.LIS and KEYCODE3.M65) form are included on AC's Feb. 1993 software disk. We also will post these files to major telecom network libraries (GEnie and CompuServe) where they should be available for downloading by the time you receive this magazine.]