DECLARE SUB - Revision history

Admin at 20:48, 13 December 2014

2014-12-13T20:48:45Z

Admin: Created page with "= Action = Declares a subroutine. =
2013-02-08T17:28:18Z

Created page with "= Action = Declares a subroutine. = Action =

Declares a subroutine.

 

 

= Syntax =

DECLARE SUB TEST[( [BYREF/BYVAL/BYLABEL] var as type)]

 

 

= Remarks =
<div style="padding: 0px; margin: 0px 0px 0px 4px;">
{| width="573" cellspacing="0" cellpadding="1" border="1" style="border: 2px solid rgb(0, 0, 0); border-spacing: 0px; border-collapse: collapse;"
|- style="vertical-align: top;"
| valign="top" width="14%" style="width: 77px; border: 1px solid rgb(0, 0, 0);" |
test

| valign="top" width="86%" style="width: 487px; border: 1px solid rgb(0, 0, 0);" |
Name of the procedure.

|- style="vertical-align: top;"
| valign="top" width="14%" style="width: 77px; border: 1px solid rgb(0, 0, 0);" |
Var

| valign="top" width="86%" style="width: 487px; border: 1px solid rgb(0, 0, 0);" |
Name of the variable(s).

|- style="vertical-align: top;"
| valign="top" width="14%" style="width: 77px; border: 1px solid rgb(0, 0, 0);" |
Type

| valign="top" width="86%" style="width: 487px; border: 1px solid rgb(0, 0, 0);" |
Type of the variable(s). Byte, Word, Dword,  Integer, Long, Single, Double or String.

|}
</div>
 

= 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(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.

 

 

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. When using the referenced address, you work on the original variable. So a change of the variable inside the sub routine, will change the variable outside the routine as well.

 

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.

 

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|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.

When you for example pass a string like "ABC" to a subroutine or function 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.

 

 

[[File:Notice.jpg|left|Notice.jpg]] 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 with functions or subs.

 

 

= See also =

[[CALL]] , [[SUB]] , [[FUNCTION]] , [[CONFIG SUBMODE|CONFIG SUBMODE]]

 

 

= Example =

 <source lang="bascomavr">
'-----------------------------------------------------------------------------------------
'name : declare.bas
'copyright : (c) 1995-2005, MCS Electronics
'purpose : demonstrate using declare
'micro : Mega48
'suited for demo : yes
'commercial addon needed : no
' Note that the usage of SUBS works different in BASCOM-8051
'-----------------------------------------------------------------------------------------

$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

' First the SUB programs must be declared

'Try a SUB without parameters
Declare Sub Test2

'SUB with variable that can not be changed(A) and
'a variable that can be changed(B1), by the sub program
'When BYVAL is specified, the value is passed to the subprogram
'When BYREF is specified or nothing is specified, the address is passed to
'the subprogram

Declare Sub Test(byval A As Byte , B1 As Byte)
Declare Sub Testarray(byval A As Byte , B1 As Byte)
'All variable types that can be passed
'Notice that BIT variables can not be passed.
'BIT variables are GLOBAL to the application
Declare Sub Testvar(b As Byte , I As Integer , W As Word , L As Long , S As String)

'passing string arrays needs a different syntax because the length of the strings must be passed by the compiler
'the empty () indicated that an array will be passed
Declare Sub Teststr(b As Byte , Dl() As String)

Dim Bb As Byte , I As Integer , W As Word , L As Long , S As String * 10 'dim used variables
Dim Ar(10) As Byte
Dim Sar(10) As String * 8 'strng array

For Bb = 1 To 10
Sar(bb) = Str(bb) 'fill the array
Next
Bb = 1
'now call the sub and notice that we always must pass the first address with index 1
Call Teststr(bb , Sar(1))

Call Test2 'call sub
Test2 'or use without CALL
'Note that when calling a sub without the statement CALL, the enclosing parentheses must be left out
Bb = 1
Call Test(1 , Bb) 'call sub with parameters
Print Bb 'print value that is changed

'now test all the variable types
Call Testvar(bb , I , W , L , S )
Print Bb ; I ; W ; L ; S

'now pass an array
'note that it must be passed by reference
Testarray 2 , Ar(1)
Print "ar(1) = " ; Ar(1)
Print "ar(3) = " ; Ar(3)

$notypecheck ' turn off type checking
Testvar Bb , I , I , I , S
'you can turn off type checking when you want to pass a block of memory
$typecheck 'turn it back on
End

'End your code with the subprograms
'Note that the same variables and names must be used as the declared ones

Sub Test(byval A As Byte , B1 As Byte) 'start sub
Print A ; " " ; B1 'print passed variables
B1 = 3 'change value
'You can change A, but since a copy is passed to the SUB,
'the change will not reflect to the calling variable
End Sub

Sub Test2 'sub without parameters
Print "No parameters"
End Sub

Sub Testvar(b As Byte , I As Integer , W As Word , L As Long , S As String)
Local X As Byte
X = 5 'assign local
B = X
I = -1
W = 40000
L = 20000
S = "test"
End Sub

Sub Testarray(byval A As Byte , B1 As Byte) 'start sub
Print A ; " " ; B1 'print passed variables
B1 = 3 'change value of element with index 1
B1(1) = 3 'specify the index which does the same as the line above
B1(3) = 3 'modify other element of array
'You can change A, but since a copy is passed to the SUB,
'the change will not reflect to the calling variable
End Sub

'notice the empty() to indicate that a string array is passed
Sub Teststr(b As Byte , Dl() As String)
Dl(b) = Dl(b) + "add"
End Sub

Example BYLABEL
$regfile = "m88def.dat"
$hwstack = 40
$swstack = 80
$framesize = 80

Dim B As Byte , W As Word

Declare Sub Somesub(bylabel Mylabel As Word)
Somesub Alabel
End

Sub Somesub(bylabel Mylabel As Word)
W = Mylabel ' this points to the BYTE address of the data
lds _dptrl,{W } ' point to
LDS _dptrh,{W+1}
Read B : Print B
End Sub

Alabel:
Data 1 , 2 , 3
</source> {{Languages}}

[[Category:BASCOM Language Reference]]

@@ Zeile 69: / Zeile 69: @@
 &nbsp;
-<span style="font-style: italic;">Sub TestArray(</span><span style="font-style: italic; font-weight: bold;">ar()</span><span style="font-style: italic;">&nbsp;as byte, b as byte)</span>
+<span class="f_CodeExample" style="font-weight: bold; color: rgb(0, 0, 128);">Sub</span><span class="f_CodeExample">&nbsp;TestArray</span><span class="f_CodeExample" style="color: rgb(255, 0, 0);">(</span><span class="f_CodeExample">ar</span><span class="f_CodeExample" style="color: rgb(255, 0, 0);">()</span><span class="f_CodeExample">&nbsp;as&nbsp;byte</span><span class="f_CodeExample" style="color: rgb(255, 0, 0);">,</span><span class="f_CodeExample">&nbsp;b&nbsp;as&nbsp;byte</span><span class="f_CodeExample" style="color: rgb(255, 0, 0);">)</span>
-<span style="font-style: italic;">&nbsp;print ar(1)</span>
+<span class="f_CodeExample">&nbsp;&nbsp;&nbsp;</span><span class="f_CodeExample" style="font-weight: bold; color: rgb(0, 0, 128);">print</span><span class="f_CodeExample">&nbsp;ar</span><span class="f_CodeExample" style="color: rgb(255, 0, 0);">(</span><span class="f_CodeExample">1</span><span class="f_CodeExample" style="color: rgb(255, 0, 0);">)</span>
-<span style="font-style: italic;">&nbsp;print ar(b)</span>
+<span class="f_CodeExample">&nbsp;&nbsp;&nbsp;</span><span class="f_CodeExample" style="font-weight: bold; color: rgb(0, 0, 128);">print</span><span class="f_CodeExample">&nbsp;ar</span><span class="f_CodeExample" style="color: rgb(255, 0, 0);">(</span><span class="f_CodeExample">b</span><span class="f_CodeExample" style="color: rgb(255, 0, 0);">)</span>
-<span style="font-style: italic;">End Sub</span>
+<span class="f_CodeExample" style="font-weight: bold; color: rgb(0, 0, 128);">End&nbsp;Sub</span>
 <span style="font-style: italic;">&nbsp;</span>
-In older BASCOM versions, it was not required to use (). You only needed to pass the base address. But that is potential unsafe&nbsp;: 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.
+In older BASCOM versions, it was not required to use (). You only needed to pass the base address. But that is potential unsafe&nbsp;: 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.
@@ Zeile 87: / Zeile 87: @@
 <span style="font-family: Arial;">&nbsp;</span>
-When BYREF or BYVAL is not provided, the parameter will be passed by reference.
+= <span class="f_Header">Parameter Passing</span> =
-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 variable outside the routine as well.
+When BYREF | BYVAL | BYREG | BYLABEL or BYSTACK is not provided, the parameter will be passed by reference (BYREF).
 &nbsp;
 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.
@@ Zeile 97: / Zeile 107: @@
 &nbsp;
-Use BYLABEL to pass the address of a label. &nbsp;BYLABEL will pass the word address. It will not work for processors with multiple 64 KB pages.
+&nbsp;
 &nbsp;
@@ Zeile 111: / Zeile 173: @@
 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.
-When you for example pass a string like "ABC" to a subroutine or function BYVAL, the compiler will create a copy with a length of 3. This is sufficient to pass it to the sub routine.
+For example, &nbsp;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.<span style="font-weight: bold;">&nbsp;s as string * 10</span>, will create a string with a size of 10.
+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.&nbsp;s as string * 10, will create a string with a size of 10.&nbsp;
 &nbsp;
 See the&nbsp;[[CALL]]&nbsp;statement for more details.