UPDATE: I believe I have found the answer, and will share it in an upcoming post. Until then, keep those comments coming. I learn so much from all of you!

This topic has been discussed here years ago, but every time something reminds me about it, I get annoyed. While my annoyance is triggered by how it works in the CoCo’s Extended Color BASIC, past research showed the behavior was the same even in much later Microsoft Visual BASIC. But why?

INSTR is a command to return the index where a target string is found in a search string. From one of the Getting Started with Extended Color BASIC manuals, it is shown as this:

What the manual did not mention is that it can also return 1 when there is no match. See this example:

Looking for “B” in “ABC”? That’s at position 2. Good.

Looking for “X” in “ABC”? It is not there, so it returns 0. Good.

Looking for “A” in “ABC”? That’s at position 1. Good.

Looking for “” in “ABC”? Apparently “” is found at position 1. Don’t tell that to the “A” there.

Callbacks

I ran into this years ago when I was experimenting with various ways to handle key presses. You could have code block until a key was pressed, and then pass the key to INST and then use ON GOTO/GOSUB to get to the routine. Like this:

0 'INSTR.BAS
10 PRINT "A)BORT, R)ETRY, C)ONTINUE:";
20 A$=INKEY$:IF A$="" THEN 20
30 LN=INSTR("ARC",A$)
40 IF LN>0 THEN ON LN GOSUB 1000,2000,3000
50 GOTO 10

1000 ' ABORT
1010 PRINT"ABORT":STOP

2000 ' RETRY
2010 PRINT "RETRY":RETURN

3000 ' CONTINUE
3010 PRINT "CONT":RETURN

This was a great technique when dealing with a long list of menu options.

I had tried to optimize this by eliminating the A$ and embedding it inside the INSTR (someone in the comments may have suggested this to me; not sure if I am clever enough to have thought that up):

ON INSTR("ARC",INKEY$) GOSUB 1000,2000,3000

…but if I put that in my code replacing lines 20-40, running it immediately shows me “ABORT” as if INSTR returned 1.

Because INSTR returned 1.

The workaround suggested to me (again, from smart folks in the comments) was maybe to add a bogus value as the first search string character, and have that routine do nothing.

ON INSTR("*ARC",INKEY$) GOSUB 999,1000,2000,3000

However, for my example where I show the prompt again after it returns, it sticks in a loop printing the prompt over and over again. The code thinks the first option is being selected, then calls that routine (the empty routine that is just a RETURN in line 60) and then prints the prompt again.

0 'INSTR2.BAS
10 PRINT "A)BORT, R)ETRY, C)ONTINUE:";
20 ON INSTR("*ARC",INKEY$) GOSUB 60,1000,2000,3000
50 GOTO 10
60 RETURN

1000 ' ABORT
1010 PRINT"ABORT":STOP

2000 ' RETRY
2010 PRINT "RETRY":RETURN

3000 ' CONTINUE
3010 PRINT "CONT":RETURN

SO … it works, but the logic needs to be updated.

One quick solution is to not use RETURN and let each function decide where to go back to. When you GOSUB, BASIC has to scan forward (possibly starting at the top of the program if the line number is before the current line being parsed) to find the target. RETURN lets it “pop” back to right after the GOSUB, so that part is faster.

Also, GOSUB routines can be called from different places in the main code and they will return back to where they were called.

If these routines are never called from anywhere but the menu code, and the extra speed to GOTO back is not a problem, this this change makes it work. And, as a bonus, the fake first GOTO line can just be back to the ON INSTR again since it doesn’t need to do anything:

0 'INSTR3.BAS
10 PRINT "A)BORT, R)ETRY, C)ONTINUE:";
20 ON INSTR("*ARC",INKEY$) GOTO 20,1000,2000,3000

1000 ' ABORT
1010 PRINT"ABORT":STOP

2000 ' RETRY
2010 PRINT "RETRY":GOTO 10

3000 ' CONTINUE
3010 PRINT "CONT":GOTO 10

I am sure there are many other ways to solve this problem.

But why do we have to?

Why does INSTR behave like this? What is the benefit of not returning 0?

Hmmm, A.I. did not exist when I was first exploring this. Maybe I’ll ask one of the ‘bots and see what it knows.

Until next time…

See Also: part 1 and part 2 (coming soon).

Updates:

• 2026-05-03 – Corrected hex value of 64 (thanks MiaM).

Today I was tagged in a Facebook post by MC-10 (well, and CoCo) programmer, Jim Gerrie. He shared a snipped of code he was trying to get working. The concept was to have stuff on the 32 column text screen get copied into a normal string and then be able to PRINT it back.

Jim’s post (with the code that wasn’t working) with code for the MC-10 was this:

10 CLEAR1200:DIMJ,K,A$,B$:GOSUB100
20 A$=””:K=VARPTR(A$):POKEK,255:POKEK+1,0:POKEK+2,64:B$=A$
50 CLS:PRINTB$;
60 GOTO60
100 CLS1:PRINT”THIS IS LINE ONE”
110 PRINT”THIS IS LINE TWO”
112 PRINT”THIS IS LINE THREE”
113 PRINT”THIS IS LINE FOUR”
114 PRINT”THIS IS LINE FIVE”
115 PRINT”THIS IS LINE SIX”
116 PRINT”THIS IS LINE SEVEN”
117 PRINT”THIS IS LINE EIGHT”:RETURN

Can someone explain why this program doesn’t work on my TRS-80 MC-10?! It should reassign the memory pointer of string variable A$ to the beginning of screen memory (highbyte 64 lowbyte 0) so that I can then just assign A$ to B$, which will allow me to “capture” the first 255 bytes of screen mem.

It works on the TRS-80 MODEL I/III (using its screen start at highbyte 60 lowbyte 0)!

Any help greatly appreciated.

– Jim Gerrie in the Facebook TRS-80 MC-10 Group.

I could immediately see what the program was attempting to do, and it was something that never occurred to me to try. The concept is “simple” now that I see it:

1. Stuff is placed on the screen (CLS, PRINT, etc.)
2. A string (A$) is declared (line 20) and then VARPTR is used to get the memory location of the 5-byte string descriptor for that string. At this point, A$ is zero bytes long, but it will point to somewhere inside the program memory just after the first quote in A=”” because that is where the string begins (even if it is zero bytes long).
3. The string descriptor is modified using POKE to change the length of the string to 255 bytes, then the start location of the string from that location inside program memory to be the start of the text screen. That was the first bug. The location being POKEd was off by one and was not modifying the string start address properly.
4. After this, A$ is copied into a normal string, thus saving the contents of the first string (screen memory) into the new string (in normal reserved string memory). This is where the second bug was.

Before continuing, If you need a refreshed on VARPTR, start with this article. It will show how the five byte string descriptor is used. Here is a refresh:

STRING DESCRIPTOR (5 BYTES)
0 - LENGTH OF STRING
1 - NOT USED FOR STRINGS
2 - MSB OF ADDR OF STRING IN MEMORY
3 - LSB OF ADDR OF STRING IN MEMORY
5 - ALWAYS 0 FOR A STRING

The first POKE at the address returned by VARTPR (K) was fine, setting the length to 255. But the next two pokes were at K+1 and K+2. For Color BASIC, they should have been at K+2 and K+3. Also, the values being poked were 0 and 64, which is backwards. From a quick search, the MC-10s text screen starts at the 16K mark, $4000 (16384). To verify this, I went to the online MC-10 emulator here:

https://mc-10.com

…and then did POKE 16384,42. That indeed placed an inverted “*” in the top left of the text screen.

The MC-10 is a big endian processor, so the memory location should be MSB ($40) then LSB ($00). $40 in decimal is 64 in decimal (no HEX support on the MC-10, I don’t think). So the actual pokes to make a string start at the top left corner of the text screen should have been 64 and 0 rather than 0 and 64. (That is 64*256+0 to make 16384.)

Adjusting those POKEs to be at the proper spot in VARPTR and swapping the values to MSB/LSB was the first fix.

At that point, I still wasn’t getting it working. This was due to the initial string being a “hard coded” string in BASIC. When A$=”” was declared in BASIC, it made a string that pointed into the program space. I have not looked into why, but forcing the string to be in RAM by doing A$=””+”” was all I needed to change to make this work. (NOTE TO SELF: Explore this and understand what was different about the program-space string.)

Jim posted a corrected version for the MC-10:

0 CLEAR1200:DIMC1,M$,I$,AA$,BB$:GOSUB100:GOTO20
8 M$="":C1=VARPTR(M$):POKEC1,255:POKEC1+2,64:POKEC1+3,0:AA$=M$+""
9 M$="":C1=VARPTR(M$):POKEC1,255:POKEC1+2,65:POKEC1+3,0:BB$=M$+"":RETURN
20 GOSUB8:CLS:PRINTAA$" "BB$;
60 GOTO60
100 CLS8:PRINT"THIS IS LINE ONE"
110 PRINT"THIS IS LINE TWO"
112 PRINT"THIS IS LINE THREE"
113 PRINT"THIS IS LINE FOUR"
114 PRINT"THIS IS LINE FIVE"
115 PRINT"THIS IS LINE SIX"
116 PRINT"THIS IS LINE SEVEN"
117 PRINT"THIS IS LINE EIGHT"
118 PRINT"THIS IS LINE NINE"
119 PRINT"THIS IS LINE TEN"
120 PRINT"THIS IS LINE ELEVEN"
121 PRINT"THIS IS LINE TWELVE"
122 PRINT"THIS IS LINE THIRTEEN"
123 PRINT"THIS IS LINE FOURTEEN"
124 PRINT"THIS IS LINE FIFTEEN"
125 PRINT"THIS IS LINE SIXTEEN";:RETURN

Meanwhile, I had come up with a silly program that would create some kind of image on the CoCo screen, then capture it in two strings so it could be quickly restored later. Well, almost the entire screen — a string is limited to 255 bytes so two strings captures 510 bytes of the 32×16 screen. If one were to use this trick, it could be adjusted to capture just the number of lines on the screen needed (like, the first 5 lines, or lines 10-20, etc.).

My example looked like this:

0 'SAVESCR1.BAS
10 CLEAR511:DIMS1$,S2$
11 ' 0 = LEN OF STRING
12 ' 1 = NOT USED FOR STRING
13 ' 2 = MSB OF ADDRESS
14 ' 3 = LSB OF ADDRESS
15 ' 4 = ALWAYS 0
16 ' 1024 = 4*256+0
17 ' 1279 = 4*256+255
20 REM DRAW SCREEN
25 CLS0:C=0:FOR I=0 TO 29 STEP 2
30 SET(I*2,0,C):SET(63-I*2,30,C)
35 SET(0,30-I,C):SET(63,I,C)
40 C=C+1:IF C>7 THEN C=0
50 NEXT
55 PRINT@266,"THIS";CHR$(128)"IS";CHR$(128);"COOL";
60 'SAVE SCREEN
65 GOSUB 1000
70 'WAIT FOR KEY
75 GOSUB 5000
80 'CLEAR SCREEN
85 CLS 5
90 'WAIT FOR KEY
95 GOSUB 5000
100 'RESTORE SCREEN
105 GOSUB 2000
110 GOTO 70

999 GOTO 999

1000 ' SAVE SCREEN
1005 Z$="":K=VARPTR(Z$):POKEK,255:POKEK+2,4:POKEK+3,0:S1$=Z$+""
1010 Z$="":K=VARPTR(Z$):POKEK,255:POKEK+2,4:POKEK+3,255:S2$=Z$+""
1015 RETURN

2000 ' RESTORE SCREEN
2005 PRINT@0,S1$;S2$;:RETURN

5000 ' WAIT FOR KEY
5005 IF INKEY$="" THEN 5005
5010 RETURN

I made a “save screen” subroutine at line 1000. My program starts and makes a simple splash screen (colored pixels set around the screen and a text message in the center), then calls the save screen routine which makes a temporary Z$ then modifies it to point to the start of the text screen (1024 – so values 4*256+0) and be 255 bytes long. It then copies that string to S1$. It repeats the process for the next part of the screen, which begins at 1024+255 (1279, so 4*256+255). That is saved in S2$.

Then the main program waits for a keypress, then does a CLS 5 to erase the screen to white, then after another keypress, it calls the “restore screen” subroutine which just prints the two saved strings starting at position 0 on the top left corner of the screen.

AND IT WORKS!

Now blasting bytes to the screen can be as fast as printing a string. I can think of some interesting uses for this, such as “drawing” various levels slowly during initialization, and capturing them to strings so they can be displayed later very fast.

And that gives me an idea for an old project I was playing with some years ago.

But that will have to wait for the next installment…

Just posting this so I can share the link… This was a planning file from my “ASCII Kong” program I am toying with:

  ----------------------------
12345678901234567890123456789012
         H H            BONUS
         H H             3900
         H HXXXXXXX     
  OO     H H      H
  OO.....H H      H
  XXXXXXXXXXXXXXXXXXXXXXXXXX
                         H        
    XXXXXXXXXXXXXXXXXXXXXXXXXX
       H     H                           
  XXXXXXXXXXXXXXXXXXXXXXXXXX
           H     H       H            
    XXXXXXXXXXXXXXXXXXXXXXXXXX
       H       H
  XXXXXXXXXXXXXXXXXXXXXXXXXX
    U                    H
  XXXXXXXXXXXXXXXXXXXXXXXXXXXX
12345678901234567890123456789012
  ----------------------------
-----
  @ 
 <=> 
 / \
-----
@
/=
 |\
-----
   @
  =\
 /|
-----

.----------|----------|----------
1....XX.... .XX.......
2....XX.... .XX.......
3..XXXXXX.. ..XXX.....
4.X..XX..X. .X.XXX....
5...X..X... X..X.XX...
6..X....X.. ..XX..XX..