The Structured Approach - Using Subroutines and

Functions
Subroutines and functions enable you to divide a program into smaller parts. A
subroutine or function is a named group of statements, constants, variables and other
declarations that perform a particular purpose. A function is identical to a subroutine in
every respect, with the one exception: it can return a single value to the calling program.
Swordfish subroutines and functions are non re-entrant, that is, you cannot make
recursive subroutine or functions calls.

Parameters
The compilers default parameter passing mechanism is by value or ByVal. Passing by
value means that a local copy of the variable is created, and the subroutine or function
operates on a copy. If your subroutine or function statement block changes the
parameter value, it doesn't change the value of the actual variable being passed.
Subroutines and function headings that do not have any formal parameters are written in
the following way,

include "USART.bas"
sub Print()
USART.Write("Hello World", 13, 10)
end sub

// main code block

SetBaudrate(br19200)
Print

The subroutine declaration Print() outputs "Hello World" each time it is called. Note
that although no formal parameters have been declared, start and end round brackets are
still required. A more useful example would enable any string to be output. To do this, a
formal parameter is added,

include "USART.bas"
sub Print(pStr as string)
USART.Write(pStr, 13, 10)
end sub

// main code block

SetBaudrate(br19200)
Print("Hello World")

The Print() subroutine declaration will now output any string value passed to it.

You do not have to explicitly give the size of a formal parameter string when
passing a string argument to a subroutine or function. For example, pStr as
string(20). This is because Swordfish has a powerful mechanism for calculating at
compile time the maximum RAM needed for any string passed by value.

In the previous examples, the string parameter argument was passed to the subroutine
using the compilers default mechanism of by value. This is in contrast to passing a
variable by reference or ByRef. Passing by reference means that a subroutine or
function receiving the variable can modify the contents of the variable being passed.
This is sometimes referred to as a variable parameter. For example,

include "USART.bas"
include "Convert.bas"

sub NoChange(pValue as byte)

pValue = 10
end sub
sub ChangeValue(byref pValue as byte)
pValue = 10
end sub

dim Value as byte

SetBaudrate(br19200)
Value = 0
NoChange(Value)
USART.Write("Value : ", DecToStr(Value), 13, 10)
ChangeValue(Value)
USART.Write("Value : ", DecToStr(Value), 13, 10)

The first subroutine NoChange() has a formal parameter that accepts arguments passed
by value. The second subroutine ChangeValue() has a formal parameter that accepts
arguments passed by reference. When the following lines are executed,

NoChange(Value)
USART.Write("Value : ", DecToStr(Value), 13, 10)

The value output will be 0, because NoChange() has received a copy of the contents of
Value. When the following lines are executed,

ChangeValue(Value)
USART.Write("Value : ", DecToStr(Value), 13, 10)

The value output will now be 10, because ChangeValue() has received the actual RAM
address of Value. Some declaration types, such as arrays, must always be passed by
reference. For example,

sub PassArray(byref pArray() as byte)

end sub

Notice that pArray is followed by open and closing round brackets. This is to inform the
compiler that an array is being passed. Without the brackets, the compiler would just
interpret the parameter argument as a single byte type.

Unlike arrays, structures can be passed by value. However, if your structure has a
large number of variables (or uses arrays and strings) it would be more
computationally efficient to pass by reference, rather than the compiler having to
copy large amounts of data, as would be required if passed by value.
It is important to remember that when a parameter argument is passed by reference, you
can only call a subroutine or function with a single variable type. For example, given
the declaration

sub MySub(byref pValue as word)

end sub

then an error 'cannot be passed by reference' message is generated when any of the
following calls are made,

MySub(10)
MySub(Index * Index)

Remember, passing by reference forces the compiler to pass the RAM address of a
variable, allowing it to be changed from within a subroutine or function. Constants or
expressions do not have RAM addresses associated with them, and so cannot be used if
a parameter argument is expecting pass by reference. If your subroutine or function
parameter declaration is likely to be passed a constant or expression, then you must
always pass by value. When a parameter is passed by value, it is sometimes useful to
initialize the argument with a constant. For example,

sub Print(pStr as string, pTerminator as string = #13 + #10)

USART.Write(pStr, pTerminator)
end sub

The formal parameter pTerminator has a default value of #13#10, which corresponds to
a carriage return, line feed pair. If the subroutine Print() is called without a pTerminator
argument value,

Print("Hello World")

then pTerminator will default to #13#10 when USART.Write() is called. If you wish to
explicitly override the formal parameter default, then call your subroutine with the
required value, like this

Print("Hello World", null)

Here, pTerminator is set to the null terminator when USART.Write() is called. It should
be noted that you can only assign constants if the formal parameter argument is passed
by value. In addition, you can only assign constants to parameters that appear at the end
of the formal parameter list. For example,

sub MySub(pA as byte, pB as byte = 10, pC as byte = 20)

end sub

is correct, but

sub MySub(pA as byte = 10, pB as byte, pC as byte)

end sub

will generate a compilation error.

There is a third parameter passing mechanism, which is primarily used for constant
arrays. On a PIC® microcontroller, constant arrays are stored differently from data
RAM which requires the use of ByRefConst. This ensures that a ROM address is passed
and not a RAM address. For example,

include "USART.bas"
const Names(3) as string = ("David", "Fred", "Peter")

sub DisplayNames(byrefconst pNames() as string)

dim Index as byte
for Index = 0 to bound(pNames)
USART.Write(pNames(Index), 13, 10)
next
end sub

SetBaudrate(br19200)
DisplayNames(Names)

In this example, DisplayNames() will output all the string values contained in the
constant array Names.

Scope
Scope is a common term used to describe the visibility of a particular declaration within
a program. The scope of parameter arguments, constants, structures and variables that
are declared within a subroutine or function are local. That is, they do not exist outside
of the subroutine or function block. For example,

sub MySub(pValue as byte)

dim LocalIndex as byte
end sub

LocalIndex = 10
pValue = 20

Will generate two 'identifier not declared' error messages, because pValue and
LocalIndex can only be seen from inside MySub(). It's useful to understand how the
compiler finds a local declaration. For example, if your subroutine or function
references a variable called Index, it will first look to see if a local variable or parameter
called Index has been declared. If it's not found, then it will then look in the current
module or program to see if the variable has been declared. If it has still not been found,
it will then search all include files to see if any public variable called Index have been
declared. If it still has not been found, an error is generated.

Function Return Types

A function is identical to a subroutine in every respect, with the one exception: it can
return a single value to the calling program. You can use functions in expressions
anywhere you would normally use a constant or variable of the same type. For example,
function Multiply(pValue as byte) as word
Multiply = pValue * pValue
end function

dim Value as word

Value = 100
Value = Multiply(Value) + Multiply(Value * 2) - 50

Alternatively, you can use an implicitly declared variable called result,

function Multiply(pValue as byte) as word

Result = pValue * pValue
end function

You can override the implicit result variable by declaring a variable of the same name,

function Multiply(pValue as byte) as word

dim result as word
result = pValue * pValue
Multiply = result
end function

The function return type can be used on the left and right hand side of an expression.
For example,

function Multiply(pValue as byte) as word

result = pValue
result = result * pValue
end function

You can also use modifiers with the function return type, like you would any other
variable. For example,

function SetUpper(pValue as byte) as word

result.Byte0 = 0
result.Byte1 = pValue
end function

String return types are a special case. They can be declared in a number of ways. The
first uses the same method as a formal parameter declaration. That is, no explicit size is
given

function StrCopy(pStr as string) as string

result = pStr
end function

In this example, the compiler will ensure that result is allocated enough RAM to hold
the return value, which depends on the value of pStr. It may be the case that you don't
explicitly assign a string value to the function result. For example, when using
assembler you will be manipulating the result string directly. The compiler therefore
cannot calculate how much RAM to allocate, so you need to do one of two things.
Firstly, you can give the return string an explicit size

function MyFunc(pStr as string) as string * 32

end function
This will allocate 32 bytes, including the null terminator, for the result. Your return
string must therefore never exceed 31 characters. The second method is to use the auto
keyword, to automatically track the size of a formal parameter,

function MyFunc(pStr as string) as string auto(pStr)

end function

In this example, pStr grows in size during compilation, so will the size of the function
result.

Exit
Calling exit will immediately terminate a currently executing subroutine or function and
return to the next code statement following the subroutine or function call. For example,

include "USART.bas"
include "Convert.bas"

sub DisplayValue(pValue as byte)

if pValue = 5 then
exit
endif
USART.Write("Value = ", DecToStr(pValue), 13, 10)
end sub

dim Index as byte

SetBaudrate(br19200)
for Index = 0 to 10
DisplayValue(Index)
next

In this example, the main program for…next loop will make repeated calls to
DisplayValue() with an Index that ranges from 0 to 10. The if…then statement inside
DisplayValue() will call exit if the value passed is equal to 5, giving an output of 0, 1, 2,
3, 4, 6, 7, 8, 9, and 10. Using exit too often can result in multiple termination points in a
subroutine or function, which can make your program difficult to debug and harder to
read. When possible, it is better programming practice to allow conditional and looping
constructs to control exit conditions. For example, the previous subroutine
DisplayValue() could be written as,

sub DisplayValue(pValue as byte)

if pValue <> 5 then
USART.Write("Value = ", DecToStr(pValue), 13, 10)
endif
end sub

If you must use exit from within a function, it is essential that a return value is assigned
before terminating.
Frame Recycling
A frame describes the area of RAM reserved for use by local variables and parameters.
Variables and parameters that are declared local to a subroutine or function are recycled
by the compiler, whenever possible. For example,

sub MySubA()
dim Array(1000) as byte
dim Index as byte
for Index = 0 to bound(Array)
Array(Index) = 0
next
end sub

sub MySubB()
dim Array(1000) as byte
dim Index as byte
for Index = 0 to bound(Array)
Array(Index) = 0
next
end sub

The subroutine MySubA() allocates just over one thousand RAM bytes for its frame, to
support the Array and Index declarations. MySubB() does exactly the same. However,
when you call both of the subroutines from your program,

MySubA
MySubB

the compiler will just allocate RAM for one frame only (a little over one thousand
bytes). This is because the subroutine calls are not dependent on each other, which
means MySubB() can overlay its frame over the one allocated for MySubA(). Of course,
if MySubB() made call to MySubA(), then twice as much frame RAM is needed. This is
to ensure that the variable and working register state of MySubB() is preserved,
preventing MySubA() from overwriting it.

Frame recycling is a very powerful mechanism for minimizing RAM usage on

microcontrollers with limited resources. If at all possible, declare working variables
inside the scope of a subroutine or function, rather than at the program or module level,
to fully exploit frame recycling.

Inline
When an inline subroutine or function is generated, the computational expense of a call
and return is removed by inserting the subroutine or function statement block at the
point where the original call was made. By default, the compiler will make all
subroutines and functions inline, if they are called only once from your program. For
example, the following Print() subroutine

sub Print()
USART.Write("Hello World", 13, 10)
end sub
SetBaudrate(br19200)
Print
USART.Write("The End", 13, 10)

would be converted to inline, which is the same as writing,

SetBaudrate(br19200)
USART.Write("Hello World", 13, 10)
USART.Write("The End", 13, 10)

You can force the compiler to always inline a subroutine or function by prefixing the
declaration with the inline keyword. For example,

inline sub Print()

USART.Write("Hello World", 13, 10)
end sub

To prevent the compiler from making a subroutine or function inline, simply prefix the
declaration with the noinline keyword. For example,

noinline sub Print()

USART.Write("Hello World", 13, 10)
end sub

Care should be taken when explicitly making a subroutine or function inline. Although
inline routines remove the time overhead associated with making a call, there can be a
very significant cost in terms of code space used. Generally, you should only use inline
for very small routines that need to execute quickly.

Subroutine and Function Aliasing

Subroutines and functions can be aliased, in much the same way as you would alias a
variable. For example,

// standard libraries...
include "USART.bas"
include "LCD.bas"

// rename standard library functions...

dim HSerOut as USART.Write
dim LCDWrite as LCD.Write

// use the alias names

HSerOut("Hello World", 13, 10)
LCDWrite("Hello World")

In this example, the standard library routines for writing have been renamed to match
the naming conventions used by some other PIC® microcontroller BASIC compilers.
Overloading
Overloading enables you to have multiple subroutines and functions in the same scope
that share the same name. The compiler will select the most appropriate routine to call,
based on its signature. A subroutine or function signature is constructed by using the
number of formal parameters and also the type of each parameter. An overloaded
routine must therefore have a unique combination of parameters, so that the compiler
can identify which routine to call during compilation. For example,

function Multiply(pValueA, pValueB as byte) as word

Result = pValueA * pValueB
end function

function Multiply(pValueA, pValueB as byte) as float

Result = pValueA * pValueB
end function

will generate an error because the overloaded function signatures are identical. That is,
they both have two parameters each of type byte. It is important to note that the
compiler does not use function return types as part of the signature, only parameters.
The previous problem can be corrected by overloading the function with a unique
parameter signature, like this,

function Multiply(pValueA, pValueB as byte) as word

Result = pValueA * pValueB
end function

function Multiply(pValueA, pValueB as float) as float

Result = pValueA * pValueB
end function

dim Result as word

Result = Multiply(10,20)

In this example, the first overloaded function is called because the parameter arguments
are of type byte. The compiler will try and invoke the routine whose parameters have
the smallest range that will accommodate the arguments in the call. For example, if the
call to Multiply() is made with the following arguments,

Result = Multiply(-10,20)

then the second function will be called, because the floating point parameter is the only
one that can accommodate a value of -10. If any parameters are assigned a constant in
an overloaded routine, care should be taken to ensure you don't inadvertently create a
situation where a routine cannot be called, for example,

sub MySub(pValueA as byte, pValueB as word = 0)

end sub
sub MySub(pValueA as byte)
end sub

MySub(10)
In this example, the compiler cannot determine if the first overloaded routine should be
called or the second, because the parameter arguments are ambiguous.

Compound Subroutines
A compound subroutine allows you to assign a single identifier that can be used to make
multiple calls to a named subroutine, in one single statement. For example, rather than
writing

WriteByte(10)
WriteByte(100)
WriteByte(5)

you can declare a compound subroutine,

compound sub Write(WriteByte)

and then call it from your main program,

Write(10,100,5)

Each time the compiler encounters the compound subroutine Write(), it takes each
parameter argument in turn and generates a call to WriteByte().

You can have more than one subroutine contained in the compound declaration
parameter list. For example,

compound sub Write(SetAddress, WriteByte)

When declaring a compound subroutine with more than one subroutine parameter, only
the last subroutine in the parameter list will be called multiple times. For example,

Write(100,100,20)

Would be the same as writing

SetAddress(100)
WriteByte(100)
WriteByte(20)

Because a compound subroutine will pass each argument in turn, it is essential that
the subroutine to be called has been declared with exactly one parameter. Failure
to do so will generate a compiler error message.

Compound subroutines are extremely powerful when used in conjunction with

overloaded subroutines. For example,

// overloaded sub to output a string...

sub WriteItem(pValue as string)
end sub
// overloaded sub to output a byte...
sub WriteItem(pValue as byte)
end sub

// create compound subroutine...

compound sub Write(WriteItem)

// make the call...

Write(10,"Hello World", 13, 10)

In this example, the compound subroutine Write() is declared with an overloaded

subroutine parameter called WriteItem(). When Write() is called from the main program,
the compiler will make a call to the overloaded subroutine WriteItem(), based on the
argument type. This allows you to create compound calls which accept arguments of
different types and in any order.