Q(uick)BASIC Statement: GOSUB

Quick View

GOSUB...RETURN

A control flow statement that branches to, and returns from, a subroutine

Worth knowing

Useful and cross-version information about the programming environments of QBasic and QuickBasic.

Syntax

GOSUB line1
⋮
RETURN [line2]

Description/Parameter(s)

line1	The label or line number of the first line of the subroutine.
line2	The label or line number where the subroutine returns.

If you don't supply a label or line number for RETURN, the program continues execution at the statement following the GOSUB (for subroutine calls) or where an event occurred (for event handling). See the ⮜ ON ⮞ keyword for information about event-handling statements.
SUB and CALL statements provide a better alternative to GOSUB subroutines.

Example

FOR i% = 1 TO 20
    GOSUB Square
NEXT i%
END

Square:
PRINT i%, i% * i%
RETURN

Syntax

GOSUB {linelabel1 | linenumber1}
[statements]
RETURN [linelabel2 | linenumber2]

Description/Parameter(s)

Argument	Description
linelabel1, linenumber1	The line number or line label that is the first line of the subroutine.
linelabel2, linenumber2	The line label or line number where the subroutine returns.

Note:

BASIC's SUB and FUNCTION procedures provide a more well-structured alternative to GOSUB...RETURN subroutines.

In addition to RETURN with no argument, BASIC supports RETURN with a line label or line number allowing a return from a subroutine to the statement having the specified line number or label, instead of returning to the statement after the GOSUB statement. Use this line-specific type of return with care.

You may call a subroutine any number of times in a program. You may also call a subroutine from within another subroutine. How deeply you can nest subroutines is limited only by the available stack space (you may increase the stack space with the CLEAR statement). Subroutines that call themselves (recursive subroutines) can easily run out of stack space. RETURN with a line label or line number can only return control to a statement in the module-level code not procedure-level code. See the example program below.

A subroutine may contain more than one RETURN statement. Simple RETURN statements (without the linelabel2, linenumber2 option) in a subroutine make BASIC branch back to the statement following the most recent GOSUB statement.

Subroutines may appear anywhere in the program, but it is good programming practice to make them readily distinguishable from the main program. To prevent inadvertent entry into a subroutine, precede it with a STOP, END, or GOTO statement that directs program control around the subroutine.

Important

The preceding discussion of subroutines applies only to the targets of GOSUB statements, not subprograms delimited by SUB statements. Entering and exiting SUB blocks with GOSUB...RETURN statements is not supported.

Example

This example shows the correct use of RETURN linelabel statements.

CLS                              ' Clear screen
PRINT "in module-level code"
GOSUB Sub1
PRINT "this line in main routine should be skipped"
Label1:
   PRINT "back in module-level code"
   END

Sub1:
   PRINT "in subroutine one"
   GOSUB Sub2
   PRINT "this line in subroutine one should be skipped"
Label2:
   PRINT "back in subroutine one"
   RETURN Label1

Sub2:
   PRINT "in subroutine two"
   RETURN Label2   'Cannot return from here to main
                   'program - only to SUB1.

Sample Output:

in module-level code in subroutine one in subroutine two back in subroutine one back in module-level code

Syntax

GOSUB {linelabel1 | linenumber1}
⋮
RETURN [{linelabel2 | linenumber2}]

Description/Parameter(s)

Usage Notes

BASIC's SUB and FUNCTION procedures provide a better-structured alternative to GOSUB...RETURN subroutines.
In addition to RETURN with no argument, BASIC supports RETURN with a line label or line number. This allows a return from a subroutine to the statement having the specified line number or label, instead of returning to the statement after the GOSUB statement. Use this line-specific type of return with care.
You can call a subroutine any number of times in a program. You also can call a subroutine from within another subroutine. How deeply you can nest subroutines is limited only by the available stack space (you can increase the stack space with the CLEAR statement). Subroutines that call themselves (recursive subroutines) can easily run out of stack space.
RETURN with a line label or line number can return control to a statement only in the module-level code (not procedure-level code). See the Example below.
A subroutine can contain more than one RETURN statement. A simple RETURN statement (without the linelabel2, linenumber2 option) in a subroutine makes BASIC branch back to the statement following the most recent GOSUB statement.
Subroutines can appear anywhere in the program, but it is good programming practice to make them readily distinguishable from the main program. To prevent inadvertent entry into a subroutine, precede it with a STOP, END, or GOTO statement that directs program control around the subroutine.

Important

The preceding discussion of subroutines applies only to the targets of GOSUB statements, not SUB procedures delimited by SUB statements. For information on entering and exiting subroutines, see ⮜ CALL Statement (BASIC Procedures) ⮞.

Example

This example uses the GOSUB and RETURN statements to branch to and return from a subroutine with and without using linelabel statements.

CLS
GOSUB PrintMessage
PRINT "This message is in module-level code"
GOSUB Sub1
PRINT "This line in module-level code should be skipped."
Label1:
PRINT "This message is back in module-level code"
END
 
PrintMessage:
    PRINT "This program illustrates use of the GOSUB and RETURN statements."
    PRINT
    RETURN
 
Sub1:
   PRINT "This message is in Sub1."
   GOSUB Sub2
   PRINT "This line in Sub1 should be skipped."
Label2:
   PRINT "This message is back in Sub1."
   RETURN Label1
 
Sub2:
   PRINT "This message is in Sub2."
   RETURN Label2   'Cannot return from here to main program - only to SUB1.