Commodore‎ > ‎BASIC‎ > ‎Keywords‎ > ‎

GOSUB

Keyword Abbreviation Token (hex) Version(s) Classification
GOSUB GO{Shift+S} 8D 1.0 to 7.0 Command and Statement

 
Syntax  
[ ON selector ] GOSUB lineNumber [ , lineNumber ] ...
  
Parameters Type Legal Value(s) Default Value Note(s)
selector Unsigned Byte 0 ~ 255 1
lineNumber Unsigned Integer 0 ~ 63999 If choosen, it must exist.  Must be a literal number.
 
 
 
Purpose  
Program flow control; call a subroutine.

 
 
Remarks  
GOSUB does two thing in the following order:
  1. It saves the location of the next BASIC statement (the one following GOSUB) on an internal stack.
  2. It "jumps" to the first statement on the selected program line (in other words, it performs GOTO lineNumber).
A set of statements begininng at the lineNumber is called a subroutine.  The subroutine should conclude with RETURN, which will recover the location of the next statement that was saved on the stack by GOSUB.  Failure to do this will eventually result in OUT OF MEMORY ERROR (a.k.a., a memory leak).
 
GOSUB is normally used to perform a set of statements (the subroutine) multiple times.  Unlike FOR/NEXT and DO/LOOP, which perform their statements repeatedly at a certain point in the program (and often never again), GOSUB executes the statements just once when used, but is generally used multiple times at various points in the program.  So FOR/NEXT and DO/LOOP are like sequential access (or bulk repetition) while GOSUB is like random access (or single repetition).  All three techiniques are usefull to reduce the program size (may also increase speed) and also make maintaining the software easier (duplicating code is error prone).
 
One subroutine may use GOSUB to call another subroutine.  This is known as nesting.  The depth of nesting is machine-dependant, but all CBM BASICs use 5 bytes of stack space (in theory) for each GOSUB level.  Although it is possible, care must be taken when a subroutine calls itself.  This is known as recursion.  Some sort of "flag" must be used to prevent infinite recursion.  An OUT OF MEMORY ERROR will occur if the stack space is exhausted.
 
In BASIC versions 3.5 and 7.0, a software stack holds the 5 bytes saved by GOSUB.  Other versions use the CPU stack.  In all versions, two (more) bytes are added to the CPU stack because BASIC (for some reason silly reason) performs JSR GOTO instead of JMP GOTO (thats just some assembly language, you don't need to understand it).
 
Although the main (trailing) argument to GOSUB, the lineNumber, is simply a number, CBM BASIC does not allow the number to be contained in a variable or calculated from an expression (it must be a literal value).  Why, why, why?  It seems to make a RENUMBER routine more complex, but the original version(s) of CBM BASIC did not have RENUMBER so the answer must be something else...  You might need to ask Bill Gates!
 
Anyway, a kludgy method around the "no variables, no expressions" restriction is the use of the ON preposition.  When this is present, the selector is evaluated.  If the result is less than 0 (or greater than 255), then an ILLEGAL QUANTITY ERROR is generated.  Otherwise the selector's value (call it N) is used to select the Nth lineNumber in the list.  The default N is 1 (i.e., when no ON preposition exists).  Not all N possibilities need to be entered.  If N is greater than the number of lineNumbers following GOSUB, then the GOSUB is completely ignored and the statment following it (whether on the same line or the next line) will be executed instead.  If N is less/equal to the count of lineNumbers listed, then Nth one is used.  Not all N values need to have a corresponding lineNumber, but for any N that is actually choosen, its corresponding line number must exist in the program or an UNDEF'D STATEMENT ERROR occurs.  If the Nth lineNumber is "empty" (no number) and is selected, then instead a SYNTAX ERROR message will be generated (all other cases work as described above).  If the Nth lineNumber is "garbage" then everything will run fine when N is > 0 and N < "garbage" entry, but when N = 0 or N >= the "garbage" entry, you will also get SYNTAX ERROR.
 
Sorry if that seems complex!  Now you know why I call it a kludge.  Some examples are below.  Also it should be noted that ON/GOSUB is very similar (and more compact) than the SELECT/CASE of VisualBASIC or SWITCH/CASE of C.  Anyway, it is cleaner and faster than a long chain of IF/THEN/ELSE statements, which would otherwise be needed.
 
If GOSUB is executed in direct mode, the BASIC interpreter will change its internal state from from "direct mode" to "run mode" before calling the subroutine.  While the concept may seem obvious, the details are not well-documented!  See this topic for details.  It will also update a secret variable (set it to 128).  It is secret because BASIC provides no way to read the value (except for machine-specific PEEK).
 
Example 1:
NEW

READY.
10 GOSUB 10 : REM infinite recursion
RUN

?OUT OF MEMORY ERROR IN 10
READY.
 
Example 2:
NEW

READY.
10 W$="": GOSUB 100: U$ = N$        : REM get user's name
20 PRINT "HELLO "; U$
30 W$=" PET'S" : GOSUB 100: P$ = N$ : REM get pet's name
40 PRINT "IS " P$ " A DOG"; : INPUT N$
50 IF LEFT$(N$,1) = "Y" THEN PRINT "I LIKE DOGS!"
60 END
100 N$="" : PRINT "WHAT'S YOUR"; W$; " NAME";
110 INPUT N$: IF LEN(N$)<1 OR LEN(N$) > 20 THEN GOTO 100
120 RETURN
RUN
WHAT'S YOUR NAME? HYDRO (user input)
HELLO HYDRO
WHAT'S YOUR PET'S NAME? NONE (user input)
IS NONE A DOG? NO (user input)

READY.
 
Example 3:
NEW

READY.
10 GOSUB 100: REM start-up message
20 PRINT "1. RESTART
30 PRINT "2. CALCULATE
40 PRINT "3. END
50 INPUT "CHOICE"; N
60 ON N GOSUB 100, 200, 300
70 PRINT : GOTO 20
100 PRINT "DEMO SYSTEM V1.0" : RETURN
200 PRINT 2*TI : RETURN
300 END
RUN
DEMO SYSTEM V1.0
1. RESTART
2. CACLULATE
3. END
CHOICE? 2 (user input)
 26544

1. RESTART
2. CACLULATE
3. END
CHOICE? 5 (user input)

1. RESTART
2. CACLULATE
3. END
CHOICE? 0 (user input)

1. RESTART
2. CACLULATE
3. END
CHOICE? -1 (user input)

?ILLGAL QUANTITY ERROR IN 60
READY.
RUN
DEMO SYSTEM V1.0
1. RESTART
2. CACLULATE
3. END
CHOICE? 1 (user input)
DEMO SYSTEM V1.0

1. RESTART
2. CACLULATE
3. END
CHOICE? 3 (user input)

READY.
 
 
 
Compare With  
 
 
Contrast With  
 
See Also  

© H2Obsession, 2014
Comments