GOSUB

Syntax: GOSUB Address

Function

Store the address of the next instruction after GOSUB, then go to the point in the program specified by Address; with the intention of returning to the stored address.

• Address is a label that specifies where to go.

Quick Facts

* Note: Using GOSUB on the BS1 requires variables B12 and B13 (W6) making them unavailable for general program use.

Explanation

GOSUB is a close relative of GOTO, in fact, its name means, "GO to a SUBroutine". When a PBASIC program reaches a GOSUB, the program executes the code beginning at the specified address label. Unlike GOTO, GOSUB also stores the address of the instruction immediately following itself. When the program encounters a RETURN command, it interprets it to mean, "go to the instruction that follows the most recent GOSUB." In other words, a GOSUB makes the BASIC Stamp do a similar operation as you do when you see a table or figure reference in this manual; 1) you remember where you are, 2) you go to the table or figure and read the information there, and 3) when you've reached the end of it, you "return" to the place you were reading originally.

GOSUB Can Save EEPROM (Program) Space

GOSUB is mainly used to execute the same piece of code from multiple locations. If you have, for example, a block of three lines of code that need to be run from 10 different locations in your entire program you could simple copy and paste those three lines to each of those 10 locations. This would amount to a total of 30 lines of repetitive code (and extra space wasted in the program memory). A better solution is to place those three lines in a separate routine, complete with it's own label and followed by a RETURN command, then just use a GOSUB command at each of the 10 locations to access it. This technique can save a lot of program space.

Try the example below:

Main:
  GOSUB Hello
  DEBUG "How are you?", CR
  END

Hello:
  DEBUG "Hello my friend.", CR
  RETURN

The above code will start out by executing a GOSUB to the section of code beginning with the label Hello. It will print "Hello my friend." on the screen then RETURN to the line after the GOSUB...which prints "How are you?" and ENDs.

Watch Out For Subroutines That Your Program Can "Fall Into"

There's another interesting lesson here; what would happen if we removed the END command from this example? Since the BASIC Stamp reads the code from left to right / top to bottom (like the English language) once it had returned to and run the "How are you?" line, it would naturally "fall into" the Hello routine again. Additionally, at the end of the Hello routine, it would see the RETURN again (although it didn't GOSUB to that routine this time) and because there wasn't a previous place to return to, the BASIC Stamp will start the entire program over again. This would cause an endless loop. The important thing to remember here is to always make sure your program doesn't allow itself to "fall into" a subroutine.

* Note: On the BS1, a RETURN without a GOSUB will return the program to the last GOSUB (or will end the program if no GOSUBwas executed).

GOSUB Limitations

Only a limited number of GOSUBs are allowed per program (as shown in above), and they may be nested only four levels deep. In other words, the subroutine that's the destination of a GOSUB can contain a GOSUB to another subroutine, and so on, to a maximum depth (total number of GOSUBs before the first RETURN) of four. Any deeper, and the program will "forget" its way back to the starting point (the instruction following the very first GOSUB).

When GOSUBs are nested, each RETURN takes the program back to the instruction after the most-recent GOSUB. As is mentioned above, if the BASIC Stamp encounters a RETURN without a previous GOSUB, the entire program starts over from the beginning. Take care to avoid these phenomena.