Gosub - Learn To Code - PlayBASIC Documentation

Gosub

Gosub <.label.>

Parameters: NONE

Returns: NONE

      Gosub is an unconditional change of control with return mechanism. So Gosub allows us to jump from the current position in our program to another section, performing some task, then Return back to point after the gosub call and continue on. These tasks are often called "Sub Routines" and allow us to take a repeatable fragment of code and reuse then.

      To create a Sub Routine we need two things, we need a entry point (a label to jump to) and our closing return (exit point) statement.

      (1) The Label is the start of the section of code we wish to call / reuse (The entry point)

      (2) A RETURN statement at the end of the gosub. (The exit point)

Gosub / Return Sample:

Here's some sample code that shows how a simple sub routine can be called using Gosub with Return continue on from the call point.

; Call our sub routine
  Gosub Example

; display a message when it returns from the 'Example'
; sub routine
  Print "Continues On From Here"

; show the screen and wait for a key press
  Sync
  WaitKey
  End

; Label defines where our routine starts
Example:
  Print "Hello World"

; return statement will jump back to where it was
; called from
  Return

Gosub Related Programming Errors

      It's important to note that while using sub-routines can allow us a very free form style of programming, compared to Functions() and Psubs(). This freedom comes at a cost. It's not possible for PlayBASIC to detect errors in your logic when building, calling or returning from subroutines during the compilation of your program . So If you've made a boo-boo then it'll probably only raise it's ugly head during testing.

      The two most common issues with Gosub's are Stack Under and Over Flows. To understand them, we need to dig a bit deeper into how Gosub actually works behind the scenes.

      When a Gosub command is executed, PlayBASIC pushes the current Address ( the position in memory of the gosub call ) onto the STACK (an area in memory where temporary information is stored in a big heap). After the push, control is then changed to the sub routine. In other words, It first remembers where it should return to, then jumps to the subroutine code.

      When PlayBASIC reaches a RETURN command, it does the opposite. So this time, it Pops the top value off the stack. If you think about, This value should be location (address) of the original Gosub call. Now once it has the address, it restores execution to the next command after the original gosub call.

      This is where the problems lie. If you call a subroutine and never return. Then the stack is slowly or rapidly filling up with data (return addresses) which are never being removed. Sooner or later the stack will overflow (fill up). Producing the "Stack Overflow" runtime error.

      Alternatively, if you attempt to Return from a sub-routine without ever gosub-ing into it in the first place, then you'll get a stack underflow error. Which means the stack was empty when Return tried to remove the top item from it.

      So when using gosubs, we have to be careful that our program is jumping and returning correctly. I'd recommend trying to structure your sub-routines so that they a top-down flow about them. Preferable with one entry point and one exit point. The more entry points and exit points you have in your sub-routines, the harder they can be to keep the program flow logical. Often many of above stack problem occurs due to program logic being faulty. Which is something to be aware of.

Sub-Routine Labels:

      While Labels can be placed virtually anywhere through your program, there are some limitations you should be aware of!

Which are,

      1) Labels can not be indented.

      2) Goto/Gosub can only jump to labels within the same scope. So you can't call a label inside a function/psub if you've outside of it and vice versa.

These have been put in place to help prevent some unsafe programming practices.

FACTS:

      * Gosub expects the labels you give it, to be within the current scope.

      * Opposed to Psubs and Functions calls you can't pass parameters

      * When using Gosub, make sure the Label you are calling is NOT indented.

      * Gosub is fall back command from old school editions of the BASIC langauge. Today, it's recommended that you use Function's or Psub's to create reusable sections of code. See Functions&Psub for a tutorial.

      * Labels are declared with a name followed by a : character (See ProgramLayout)

Example #1

; use Gosub to call a sub routine called "MySubRoutine"
  Gosub MySubRoutine

; use Gosub to call a sub routine called "MySubRoutine"
  Gosub MySubRoutine

; Refresh the screen and wait for a Key to be pressed
  Sync
  WaitKey

; End the Program here.  Otherwise PB will fall through
; past our label and attempt to execute our SubRoutine code.
; Which result in a Stack InderFlow error.
  End




; Define the Entry Point with a LABEL
MySubRoutine:

; Display this Message to the screen
  Print "My First Sub  Routine"


; Use The RETURN command to restore execution back to the
; point after the Gosub call
  Return

This program would output.

  My First Sub  Routine
  My First Sub  Routine

Example #2

The differences of Gosub and Goto

  Goto Label2

; labels are declared with a name followed by a :
Label1:
  Print "Hello this is the code of Label1"
  Print "... and good-bye"
  Return

  Print "This code will NEVER be executed"

; labels are declared with a name followed by a :
Label2:
  Print "This is the beginning."
  Print "Now we use Gosub Label1..."
  Gosub Label1
  Print "We returned from the code section 'Label1'"
  Print "And this ends our program"


; Display the Screen and wait for the user to press a key
  Sync
  WaitKey

This example would output.

  This is the beginning.
  Now we use Gosub Label1...
  Hello this is the code of Label1
  ... And good-bye
  We returned from the code section 'Label1'
  And this ends our program


Related Info:	Function \| Functions&Psub \| Goto \| ProgramLayout \| Psub \| Return :