XAND — Bitwise AND for Atari BASIC

Type
Utility
Category
Machine-language USR function (programming tutorial)
Author
XL Freak
Published in
AtariAge forums, "Remembering the magazines... Coding bitwise AND for Basic" thread, Lesson 1 (May 2024)
Year
2024
Language
Atari BASIC (with 6502 machine language)
Requirements
Any 8-bit Atari with Atari BASIC; MAC/65 or another assembler only if you want to rebuild the routine

About the program

Atari BASIC's AND and OR are logical operators. They answer 1 or 0, so you can't use them to test or mask individual bits the way C's & or Turbo BASIC XL's & can. In 2024 the AtariAge member XL Freak wrote a tutorial "in memory and honor of those 'Learn it by typing it in' days", laid out the way he might once have submitted it to Compute! or Byte. It's a commented MAC/65 assembly routine for a bitwise AND, plus this BASIC loader and demo. A second lesson in the same thread wraps AND, OR and EOR into one generator program.

Typing it in

Plain ASCII. The machine code is in hexadecimal DATA (lines 2010–2050), and lines 3000–3210 convert each two-digit hex string to a number. Watch out for one neat trick: the first DATA item, 25, is itself hex for 37, the length of the routine. If you mistype a hex pair, line 3210 deliberately forces an error by calling VAL on it, so you'll see which DATA item was bad instead of getting a silent crash.

How to use it

RUN it, and the demo prints a random number ANDed with 15, which is its low four bits. In your own code:

100 RESULT=USR(XAND,VALUE,BITS)
110 IF USR(XAND,FLAGS,4) THEN ? "BIT 2 IS SET"
120 FLAGS=USR(XAND,FLAGS,65535-4):REM CLEAR BIT 2

Values are 16-bit unsigned (0–65535), because that's how USR passes its arguments.

How it works

USR(address, a, b) pushes each argument onto the 6502 stack as a two-byte integer, followed by a one-byte count. The routine:

  1. pulls the count. If it's 0 it returns at once, and if it isn't 2 it pulls and discards every argument (so the stack stays balanced) before returning;
  2. pulls the first argument into FR0 ($D4/$D5), the floating-point register BASIC reads the result from;
  3. pulls the second argument a byte at a time, ANDs it with FR0 and stores it back;
  4. returns with RTS, and BASIC converts FR0 back into a number.

Replacing the two AND opcodes ($25) with ORA ($05) or EOR ($45) gives XOR and XEOR. That's exactly what Lesson 2 in the thread does.

One discrepancy to know about: in the assembly listing, the error/no-argument exit loads 0 (LDA #0), but the hex DATA has A9,FF, which is LDA #$FF. So the BASIC version returns 65535 when it's called with the wrong number of arguments. Change FF to 00 in line 2050 if you want it to match the source.

The author's tutorial also shows how to make the program print the routine as a ready-made string-literal line (XAND$="…"), so you can drop the loader entirely. It also warns that ADR(XAND$) changes whenever you edit the program, which is why XAND is recalculated each run.

The assembly source (MAC/65)

1000 ;SAVE #D:XAND.ASM
1010 FR0 =   $D4     ;FP REG 0
1020     PLA         ;GET # OF ARGS
1030     BEQ ZERO    ;RETURN 0 IF NONE
1040     CMP #2      ;IF NOT 2 ARGS...
1050     BNE ERR     ; FIX & RETURN 0
1060     PLA         ;GET ARG1 HI
1070     STA FR0+1   ; SAVE IN FP REG0
1080     PLA         ;GET ARG1 LO
1090     STA FR0
1100     PLA         ;GET ARG2 HI
1110     AND FR0+1   ;BITWISE AND W/ARG
1120     STA FR0+1   ;SAVE IN FR0 HI
1130     PLA         ;GET ARG2 LO
1140     AND FR0     ;BITWISE AND W/ARG
1150     STA FR0     ;SAVE IN FR0 LO
1160     RTS         ;RETURN VALUE
1170 ERR ;           IF ERR, PULL OFF
1180     TAX         ; ALL ARGS X=#ARGS
1190 ER1
1200     PLA         ;GET UNUSED ARG HI
1210     PLA         ;GET UNUSED ARG LO
1220     DEX         ;COUNT DOWN BY 1
1230     BNE ER1     ;DO AGAIN IF MORE
1240 ZERO
1250     LDA #0      ;CLEAR FR0 TO
1260     STA FR0     ; RETURN ZERO
1270     STA FR0+1
1280     RTS

Changes from the published listing

One fix in the short usage example. As posted, line 100 assigned to a variable called NEWVALUE. Atari BASIC reads any statement that starts with NEW as the NEW command, so that line is rejected when typed. The variable is renamed RESULT.

Line As posted Now
100 NEWVALUE=USR(XAND,VALUE,BITS) RESULT=USR(XAND,VALUE,BITS)

Listing

1 REM SAVE "D:XAND.BAS
1000 DIM A$(2)
1010 RESTORE 2000:READ A$:GOSUB 3000
1020 IX=A:DIM XAND$(IX):XAND=ADR(XAND$)
1030 FOR I=1 TO IX:READ A$:GOSUB 3000
1040 XAND$(I,I)=CHR$(A)
1050 NEXT I
1100 REM DEMO
1110 R=INT(RND(0)*65536)
1120 ? "DEMO: ";R;"&15 = ";
1130 ? USR(XAND,R,15)
1900 STOP
2000 REM XAND ML DATA
2010 DATA 25
2020 DATA 68,F0,14,C9,02,D0,11,68,85,D5
2030 DATA 68,85,D4,68,25,D5,85,D5,68,25
2040 DATA D4,85,D4,60,AA,68,68,CA,D0,FB
2050 DATA A9,FF,85,D4,85,D5,60
3000 REM HEX TO DEC CONVERTOR
3010 REM ASSUMES 2 HEX DIGITS IN A$
3020 HI=ASC(A$(1,1))-48
3030 IF HI<0 OR HI>22 THEN 3200
3040 IF HI>9 AND HI<17 THEN 3200
3050 IF HI>9 THEN HI=HI-7
3060 LO=ASC(A$(2,2))-48
3070 IF LO<0 OR LO>22 THEN 3200
3080 IF LO>9 AND LO<17 THEN 3200
3090 IF LO>9 THEN LO=LO-7
3100 A=LO+HI*16:RETURN
3200 REM FORCE INVALID VALUE ERROR
3210 A=VAL(A$):RETURN

Credits