Swordfish Compiler

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.