Psub - Learn To Code - PlayBASIC Documentation

Psub

Psub <.PsubName.>[(ParamList)] ... [Return] ... EndPsub

Parameters: NONE

Returns: NONE

Psubs (protected sub-routines) are really a variation of the classic Gosub / Return pairings also known as a sub routines that can be found in traditional BASIC's, with one major exception, they're required to be defined within Psub / EndPsub blocks. So Psubs look more like functions than sub routines do. (See Functions for more in depth info about functions)

To define a psub, we first need to give the sub routine a Name and optionally a list of parameters that would be passed to the sub routine when it's called. The following shows a sample Psub template of a routine called "Test" which has no parameters.

; Define the TEST routine with no input parameters

Psub TEST()

;  empty routine, with no code in it, just the closing EndPsub

EndPsub

      The above code just declares the entry and exit points of the PSUB named TEST. Apart from that, if you executed this in PlayBASIC, the program wouldn't seem to do anything. That's because, we need to call the psub in order for the code inside it to be executed.

      To call any psub, we use the subs name, followed by it's list of input parameters enclosed within brackets. Now since this example doesn't have any input parameters, to call this sub would simply be Test(). So when PlayBASIC executes this statement in your program, execution control is changed from the current place to that of the sub routine. When the PlayBASIC reaches the end of the sub routine, control reverts back to after the calling statement.

      Here's a version of previous example, but this time we've fleshed it out some more with a call to the sub routine and we've added some code to display (print) a message when the call is executed.

; Call the Test() sub routine,
  Test()

;
; Define the TEST routine with no input parameters

Psub TEST()
;  Display a message, so we can see when
; this routine was called.
  Print "Hello World, This is the code inside TEST"
EndPsub

PSUBS handle input and return parameters the same way that functions do. So rather than go over that again, we recommend you read the page on functions, which covers this in greater detail.

The following example, shows a psub with a pair of integer input parmeters and a single integer return, with calling example.

; Call the AddIntegers sub routine,  with params
; this calls the psub and returns the result back to
; the print statements
  Print AddIntegers(100,200)


;      refresh the screen and wait for a key press
  Sync
  WaitKey



; The ADD Integer psub, with two integer input parameters

Psub AddIntegers(Value1 ,  Value2)

; The Value1 and Value2 are assigned the input params
; that are passed in during the calling process

; Add value 1 and 2 together and store the answer
; in the REsult variable
  Result = Value1 + Value2

;  Result is returned back to calling location
; of of where this psub was called.
EndPsub Result

FACTS:

      * PSUBS are similar to Functions. The primary difference is that all variables inside the psub are static. That is to say, between each call all variable retain their existing information. You can declare variables as Static and do the same thing in a function.

      * PSUBS generally execute faster than Functions. So if you don't need local variables (and many functions don't) then you get an easy bit of performance gain just by using Psubs.

      * For an overview of function and psub parameter passing, please see the Functions&PSub tutorial.

      * Protected Subroutine declaration keywords (Psub & EndPsub) can not be indented.

      * Variables & Arrays defined within a Psub are ALL static by default.

      * You can return multiple values from a Psub.

Mini Tutorial:

; A Psub that does Not Return a value
Psub NoReturnValue()
  Print "This Psub doesn't return anything"
EndPsub

; A Psub that conditionally exits
Psub ExitEarly(AValue)
  If AValue = 5
     Print "I exit with Return"
     Return
  EndIf
  Print "I exit with EndPsub"
EndPsub

; A Psub that returns three values
Psub MoreReturnValues()
  Life = 42
  Name$ = "Deep Thought"
EndPsub Life, Name$, 4.321



; Call the Psubs
  NoReturnValue()
  ExitEarly(1)
  ExitEarly(5)
  MyLife, MyName$, MyFloatValue# = MoreReturnValues()

  Print MyLife
  Print MyName$
  Print MyFloatValue#

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

This example would output.

  This Psub doesn't Return anything
  I Exit with EndPsub
  I Exit with Return
  42
  Deep Thought
  4.321


Related Info:	CallFunction \| EndPsub \| Function \| Functions&Psub \| Gosub \| Goto \| Return :