DECLARE FUNCTION

DECLARE FUNCTION

Top  Previous  Next

Action

Declares a user function.

 

 

Syntax

DECLARE FUNCTION TEST[( [BYREF/BYVAL] var as type)] As type

 

 

Remarks

test

Name of the function.

Var

Name of the variable(s).

Type

Type of the variable(s) and of the result. Byte,Word, Dword, Integer, Long, Single, Double or String. Bits are not supported.

 

When BYREF or BYVAL is not provided, the parameter will be passed by reference.

Use BYREF to pass a variable by reference with its address.

Use BYVAL to pass a copy of the variable.

Use BYLABEL to pass the address of a label.

 

See the CALL and DECLARE SUB statements for more details.

See also Memory usage

 

 

ARRAYS

Arrays can be passed by reference only. You need to add  empty parenthesis() after the variable to indicate that you pass an array.

Inside the sub/function you also need to use () when accessing the variable.

Let's have a look at an example which calls a SUB but is similar for FUNCTIONS.

 

Declare Sub TestArray(ar() as byte, b as byte)

Dim a(10) as byte , q as byte

TestArray a(1) , q

 

As you can see, we add () after the variable to indicate that it is an array we pass.

When we call the sub program, we pass the first address or the base address of the array. That is a(1) in this case.

Inside the sub module, we also refer to the variable using ().

 

Sub TestArray(ar() as byte, b as byte)

   print ar(1)

   print ar(b)

End Sub

 

In older BASCOM versions, it was not required to use (). You only needed to pass the base address. But that is potential unsafe : if you reference a variable as an array while it is actually a single variable, then you can write to the wrong address. When using (), the compiler known when an array is expected and can inform you about a possible error.

If you have old code you can use CONFIG ERROR=IGNORE,380=IGNORE to ignore errors as a result of the updated syntax.

 

 

notice You must declare each function before writing the function or calling the function. And the declaration must match the function.

Bits are global and can not be passed to functions or subs.

 

When you want to pass a string, you pass it with it's name : string. So the size is not important. For example :

Declare function Test(s as string, byval z as string) as byte

You may however specify an optional maximum length.

 

 

noticeWhen you set the function result, you need to take care that no other code is executed after this.

So a good way to set the result would be this :

 

Function Myfunc(b as byte) as Byte

   local bDummy as byte

   'some code here

   Myfunc=3 ' assign result

   ' no other code is executed

End Function 

 

Also good would be:

 

Function Myfunc(b as byte) as Byte

   local bDummy as byte

   'some code here

   Myfunc=1 ' assign default result

   Print "this is a test " ; b

   Myfunc=4 ' now again the result is the last code

   ' no other code is executed

End Function 

 

If you execute other code after you assigned the function result, registers will be trashed. This is no problem if you assigned the function result to a variable. But when you use a function without assigning it to a variable, some temporarily registers are used which might be trashed.

 

 

Thus this special attention is only needed when you use the function like :

If Myfunc()=3 then  'myfunc is not assigned to a variable but the result is needed for the test

 

When you use :

myvar=Myfunc() 

Then you will not trash the registers. So in such a case there is no problem to run code after the function assignment.

 

To keep it safe, assign the result just before you exit the function.

 

 

See also

CALL, SUB , CONFIG SUBMODE

 

 

Example

'-----------------------------------------------------------------------------------------

'name                     : function.bas

'copyright                : (c) 1995-2016, MCS Electronics

'purpose                  : demonstration of user function

'micro                    : Mega48

'suited for demo          : yes

'commercial addon needed  : no

'-----------------------------------------------------------------------------------------

 

$regfile = "m48def.dat"                                   ' specify the used micro

$crystal = 4000000                                         ' used crystal frequency

$baud = 19200                                               ' use baud rate

$hwstack = 32                                               ' default use 32 for the hardware stack

$swstack = 10                                               ' default use 10 for the SW stack

$framesize = 40                                             ' default use 40 for the frame space

 

'A user function must be declare before it can be used.

'A function must return a type

Declare Function Myfunction(byval I As Integer , S As String) As Integer

'The byval paramter will pass the parameter by value so the original value

'will not be changed by the function

 

Dim K As Integer

Dim Z As String * 10

Dim T As Integer

'assign the values

K = 5

Z = "123"

 

T = Myfunction(k , Z)

Print T

End

 

 

Function Myfunction(byval I As Integer , S As String) As Integer

'you can use local variables in subs and functions

Local P As Integer

P = I

'because I is passed by value, altering will not change the original

'variable named k

I = 10

 

P = Val(s) + I

 

'finally assign result

'Note that the same data type must be used !

'So when declared as an Integer function, the result can only be

'assigned with an Integer in this case.

Myfunction = P

End Function