DECLARE SUB

Action

Declares a subroutine.

Syntax

DECLARE SUB TEST[( [BYREF|BYVAL|BYLABEL|BYREG|BYSTACK] var as type)]

Remarks

test

Name of the procedure.

Var

Name of the parameter(s).

Type

Type of the parameter(s) :

Byte, Word, Dword, Integer, Long, Single, Double or String.

When passing a string it is recommended to also pass the maximum length of the string : SomeString As String * 30 would indicate that the string will have a maximum length of 30 characters.

Please notice that you need to specify the string length in both the DECLARE and the actual implementation. Unless you use CONFIG SUBMODE=NEW in which case you only write the implementation.

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.

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

Dim a(10) as byte , q as byte

TestArray a() , 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 knows 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.

Parameter Passing

When BYREF | BYVAL | BYREG | BYLABEL or BYSTACK is not provided, the parameter will be passed by reference (BYREF).

BYREF

Use BYREF to pass a variable by reference with its address. When using the referenced address, you work on the original variable. So a change of the variable inside the sub routine, will change the passed variable outside the routine as well.

BYVAL

Use BYVAL to pass a copy of the variable. Passing a copy of the variable allows to alter the copy in the sub routine while leaving the original variable unaltered. BYVAL will not change the original passed variable but it requires more code since a copy of the parameter must be created.

BYREG

Use BYREG to pass a copy of the variable using a register. The value will be passed to the register(s) you specify. When multiple bytes need to be passed, multiple registers will be used. Registers are named from R0-R31. When you pass a WORD to register R16, you will also use R17 since a word requires 2 bytes.

You can not pass strings. Only numeric variables and constants.

Using BYREG requires some knowledge of the routines you call. The current implementation does not protect already loaded registers. This means that when you pass multiple registers you could destroy some already loaded registers just because a parameter will destroy the register.

Example : declare Sub MySub(byreg R16 as Word, byreg R18 as long, byreg R22 as dword)

mysub 1000, var(J+100), var(j)

In this example, R16 and R17 are loaded, after this the array index of variable var() need to be calculated which uses the ML16 routine which uses R16-R21

Numeric constants and expression do not alter registers but functions might. A future version will track and protect registers.

Why would you want to use BYREG ? Using BYREG is equivalent to using ASM. It is intended to be used with ASM code inside subs. The FT800 include files use BYREG and BYSTACK.

Example from FT800:

Sub Stencilfunc(byreg r18 As Byte , Byreg r17 As Byte , Byreg R16 As Byte)

Cmd32 _stencilfunc(r18 , R17 , r16)

End Sub

BYSTACK

Use BYSTACK to pass a copy of the variable by the soft stack (Y-pointer). BYSTACK will not create a copy of the variable but instead will pass the data directly to the soft stack.

The first parameter is passed first , LSB first. You will find BYSTACK used in the FT800 include files. BYSTACK has the advantage compared to BYREG that no registers are altered. But it has the disadvantage that it requires an optional step to pass the data to the stack.

The SUB/FUNCTION need to clean up the stack. Typically you would use LD reg, y+ to pop data from the stack.

The FT800 uses CMDFTSTACK to pop data from the stack and send it to the FT800.

BYLABEL

Use BYLABEL to pass the address of a label. BYLABEL will pass the word address. It will not work for processors with multiple 64 KB pages.

Using BYLABEL on the EEPROM is possible but the EEPROM image must proceed the call with the label name.

See also READEEPROM, LOADLABEL and Memory usage

If you pass a string you may specify the length of the string. This length will be the maximum length the string may grow. This is important when you pass a string BYVAL.

For example, when you pass a string like "ABC" to a subroutine or function using BYVAL, the compiler will create a copy with a length of 3. This is sufficient to pass it to the sub routine.

But if the sub routine adds data to the string, it will not fit since the string is too short. In such a case you can specify the length. s as string * 10, will create a string with a size of 10.

See the CALL statement for more details.

You must declare each function before writing the function or calling the function. And the declaration must match the function. Optional you can use CONFIG SUBMODE=NEW so DECLARE is not required.

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

See DECLARE FUNCTION paragraph named IMPORTANT