Call Box
Bit Masking
Written by: William Stephens - Sept 28,1990

This tech note describes how to set and unset bits within a byte, or any number of any length from Applesoft BASIC.

---

Bit Masking is a boolean math process which Applesoft BASIC does not support directly. This does not mean that it can not be done from Applesoft, it's just that it is a little more difficult and obscure to accomplish. The value of bit masking becomes apparent when setting soft switches in the Apple IIgs.

When dealing with soft switches it is important to set or un-set the bit(s) you want and not change the others in the byte or word where they reside. You can find lots of soft switches in the $00C000 thru $00C7FF range of the Apple IIgs ... this is the I/O (Input Output).

In Applesoft, we will use an algorithm which subtracts a decreasing multiple of 2 from the target number and bit mask number to create the current boolean place values. If the subtraction results in a value less than 0 the bit is not set, otherwise it is set. On each iteration a result number will be built by adding itself to the boolean place value if the bit should be set. If you want the bits to be un-set then a zero is used for the boolean place value. The subroutine will iterate until the number of requested bits has been processed.

This may sound like mumbo jumbo but this added complexity allows the algorithm (subroutine) to handle soft switch fields much larger than a byte (8-bits). You need to supply the number to be masked (R1), the mask pattern (R2), the number of bits to be masked (R3) and whether you want the bits in the number to be masked to be set or un-set according to the mask pattern bits (R4). The resultant masked value will be returned in (R5).

Enter the bit masker subroutine as follows:
(See C.B.P.A. #3 disk TEMPLATES/BITMSKTMPLT)

35000  REM Bit Masker 
35010  RO = 1 : R5 = 0 : FOR R8 = 2 TO R3 : RO = RO * 2 : NEXT : FOR R8 = 1 
       TO R3 : R6 = INT (R1 / RO) : R7 = INT (R2 / RO)
35020  R1 = R1 - RO : IF R1 < 0 THEN R1 = R1 + RO
35030  R2 = R2 - RO : IF R2 < 0 THEN R2 = R2 + RO
35040  IF R7 = 1 THEN R6 = R4 
35050  R5 = (R6 * RO) + R5:RO = RO / 2 : NEXT : RETURN 

You can use this subroutine with POKE's and PEEK's for 8 bit values that are located in bank zero like soft switches. Let's enable the super hi-res screen by masking in the 7th bit of the NEW VIDEO soft switch located at $001C029. The address is 49193 (decimal) and the mask for the 7th bit is 128 (decimal).

First let's set a few variables like the bit mask (128), the number of bits to process (8) and the flag which indicates that you want to SET the bit (1).

100    R2 = 128 : R3 = 8 : R4 = 1 

and now fetch, process and replace the byte using POKE and PEEK.

110    R1 = PEEK(49193) : GOSUB 35000 : POKE 49193,R5 

Before we run this test let's put in some code which will wait for a keypress and then un-set the super hi-res soft switch so that when you are done running the test the text screen is visible again.

120    GET K$ : R2 = 128 : R4 = 0 : R1 = PEEK(49193) : GOSUB 35000 : POKE 
       49193,A5 : END 

This little test program performs the exact same functions as the Call Box BASIC commands CALL SC,0 and CALL SC,1 but without Call Box active. When Call Box BASIC is active however you can utilize the Big Peek and Big Poke commands to mask bytes, words, and longs anywhere in the Apple IIgs memory range. To mask a word (16 bits ... 2 bytes) change R3 to 16 and for longs (32 bits ... 4 bytes) change R3 to 32.

The application of properly setting and un-setting bits is vital for glitch free operation of programs which use the computers I/O. Bit masking can be of great value in the direct manipulation of super hi-res bibbles (2 bits) and nibbles (4 bits). A comprehensive reference for soft switches and things you handle by the bit are in the Apple IIgs Hardware and Firmware Reference Manuals.

---

Further Reference
Apple IIgs Hardware Reference Manual Apple IIgs Fmnware Reference Manual
Apple IIgs Toolbox Reference Manuals Vol's 1,2 and 3


Call Box - So What Software 10221 Slater Ave. Suite 103 Fountain Valley, CA. 92708