Explanation

RETURN is one of two commands (ABORT and RETURN) that terminate a PUB or PRI method's execution. RETURN causes a return from a PUB or PRI method with normal status; meaning it pops the call stack once and returns to the caller of this method, delivering a value in the process.

Every PUB or PRI method has an implied RETURN at its end, but RETURN can also be manually entered in one or more places within the method to create multiple exit points.
When RETURN appears without the optional Value, it returns the current value of the PUB/PRI's built-in RESULT variable. If the Value field was entered, however, the PUB or PRI returns with that Value instead.

About the Call Stack

When methods are called, simply by referring to them from other methods, there must be some mechanism in place to store where to return to once the called method is completed. This mechanism is a called a "stack" but we'll use the term "call stack" here. It is simply RAM memory used to store return addresses, return values, parameters and intermediate results. As more and more methods are called, the call stack logically gets longer. As more and more methods are returned from (via RETURN or by reaching the end of the method) the call stack gets shorter. This is called "pushing" onto the stack and "popping" off of the stack, respectively.

The RETURN command pops the most recent data off the call stack to facilitate returning to the immediate caller; the one who directly called the method that just returned.

Using RETURN

The following example demonstrates two uses of RETURN. Assume that DisplayDivByZeroError is a method defined elsewhere.

PUB Add(Num1, Num2) 
  Result := Num1 + Num2          'Add Num1 + Num2
  return 

PUB Divide(Dividend, Divisor)
  if Divisor == 0                'Check if Divisor = 0
    DisplayDivByZeroError        'If so, display error
    return 0                     'and return with 0
  return Dividend / Divisor      'Otherwise return quotient

The Add method sets its built-in RESULT variable equal to Num1 plus Num2, then executes RETURN. The RETURN causes Add to return the value of RESULT to the caller. Note that this RETURN was not really required because the Propeller Tool Compiler will automatically put it in at the end of any methods that don't have one.

The Divide method checks the Divisor value. If Divisor equals zero, it calls a DisplayDivByZeroError method and then executes return 0, which immediately causes the method to return with the value 0. If, however, the Divisor was not equal to zero, it executes return Dividend / Divisor, which causes the method to return with the result of the division. This is an example where the last RETURN was used to perform the calculation and return the result all in one step rather than separately affecting the built-in RESULT variable beforehand.