GS 7: Utilities File

BAD CHARACTERS?

How can we ensure the user enters only hex characters if that's what the  program or sub requires?  Enter the "getByte" and "kpChecker" utilities.

"getByte" calls "kpChecker" but let's start with the latter.

DOCUMENTATION

Before we go on you may have noticed that the variables and addresses used in a sub are always listed as comments at the very start of the "sub". We have found it a lot easier to configure the OshonSoft 6502 simulator for variables to be watched if we have that info at the ready instead of always going back to the Variables and Indexes files. We're just saying it's a good habit to get into... it's too bad we didn't follow our own advice when we wrote this adjacent utility sub.

If the calling application requires user input to be in hexadecimal, we would have to enter the data with two keystrokes instead of one. As an example, the number "1" is represented as the hex value "$31" in ASCII so the user would have to type "3" on the keyboard followed by "1". The ACIA will see $33 followed by $31 from your PC.

ARE YOU VALID, HEXY?

What are the valid hexadecimal characters?  0 to 9, A to F and a to f. In hex they are $30 to $39, $41 to $46 and $61 to $66.
But what if I wanted to send a "G"?  Then you may have to convert it to ASCII which would be byte "$47". But this letter is not part of the hexadecimal set - it's an ASCII character - so it would have to be handled differently if the required input needed to be hex.

Search for "kpChecker:" which is located in your Math_Menu_v1.0.asm code just after the "getByte:" sub.

kpChecker

The first thing this utility does is perform a "kpRead" from the keyboard. The comments under the "KPCHECKER" blocked title name indicate "kpRead" processes the user keypress and then performs a "kpWrite" to write it to the display.

In line 609 in the adjacent screenshot we see the user keypress from "kpRead" being pushed onto the 6502 Stack with "pha", PusH register A. Adding in this "insurance" ensures we won't lose it if some other routine needs register A which virtually every one will.

Before we determine if the keypress is valid hex, we need to accommodate the special keys like <Enter>, <Delete>, etc.

Using the adjacent screenshot let's examine the code starting at line 612. If the user presses the <ENTER> key, then "$0D" will be sent to the SBC30. In line 613 register A subtracts the keypress value from "$0D" and if the result is zero, then the branch occurs. The branch is to label "goodKP", meaning "good keypress" down in line 642. At that label we see a "pla" instruction indicating the value pushed onto the Stack will now be PuLled back into register A. The "jsr kpWrite" that follows will display it on the user screen. This instruction is followed with an "rts" which is known as "return from subroutine": the program will return to the line following the original "jsr kpChecker".

But <Enter> is just one of several special key examinations starting in line 612. Note that all of them have branch commands to the label "goodKP".

OtherKeys

When 6502 commands occur the addressing method for each has to be defined within the command. In the "cmp  #$67" command of line 623, the "#" indicates Immediate Mode so we will process $67 as a value and not as an address. If we had left off the "#" symbol, the CPU would know it has to look up the value stored at address "$67" - that's not what we had in mind - we wanted it to process the number "$67"!

Branch if Carry Set (BCS)

See page 21 of w65c02s.pdf

If the keypress value was "$66" however, subtracting $67 from $66 in register A would force the Carry bit from 1 to 0 so it would no longer remain "set" to "1". The "bcs badKP" (branch if Carry set) command would fall through to the next command. In the adjacent screenshot if you work through lines 623 to 639, you can see the Carry Bit is tested for each permutation.

Learning the branch commands is not the easiest part of coding. In the next section we're going to modify our Math_Menu_v1.0.asm file to become Math_Menu_v1.0_SIM.asm. Then we'll load it into the OshonSoft 6502 Simulator and watch the actual bits change as each instruction is executed. It really helps in understanding BCS, etc.

What is $67 as an ASCII value?  It's the letter "g". But valid hex characters only go up to $66 for the letter "f". So what does the command "BCS badKP" do?

If the user presses a non-hex character like the lowercase letter "j", the value for it is "$6A" and it will be put on the wire. Register A would now contain "$6A", the keypress, and when we subtract "$67" the value would be a positive number. That means if the Carry Bit was preset to "1" then it should stay at "1". Thus "BCS badKP" would pass (Branch If Carry Set) and the program would continue at label "badKP" because the keypress was not hex-valid.

What does "badKP" do? First it pulls the keypress off the Stack to clear it, loads the hex value "$7F" and sends it to kpWrite for display. "$7F" is the <delete> character so we expect the value typed by the user to be deleted quickly, prob'ly quicker than we can see.

FALLING THROUGH

If the keypress value was $66 for the valid hex letter "f" however, subtracting "$67" from "$66" in register A will force the "N" or Negative Number bit to 1 and the Carry bit to "0" so it would no longer remain set to "1". The "bcs badKP" command would "fall through" to the next command.

Examine the comments for lines 623 to 641. They try to briefly explain what is occurring.

JSRs: kpRead, getByte & kpChecker