====== Sub and Function ======

For subroutines, you can either use Sub or Function. Function can return a value, but subroutines can't.

<code xbasic>
Sub SubName (Param1 As DataType [,ParamX As DataType][,…])
    Statements
    [Exit sub] ' Exit during sub-routine
End Sub

Function FunctionName (Param1 As DataType [,…])[As ReturnDataType]
    Statements
    [Exit Function] ' Exit during sub-routine
End Function
</code>

To return values using ''Function'', simply store the final value as the name of
the function as shown below:

<code xbasic>
Function ADD_VALUE(B As Byte) As Byte
    ADD_VALUE = B + 1 ' Return B+1.
End Function
</code>

{{ :cubloc:sub_and_function:subfinction_demo.png?nolink |}}

===== Global and Local Variables =====

When you declare variables inside a subroutine or a function, it is
considered a "Local" variable. Local variables are created when the
subroutine or function is called, and removed when the subroutine or
function exits. This means that local variables will temporarily allocate data
memory for the duration of the call. Local variables may only be referred to
or used inside the subroutine or function in which they were declared.

On the other hand, global variables may be used anywhere in your
program.

{{ :cubloc:sub_and_function:global_variable.png?nolink |}}

<code xbasic>
Dim A As Integer          ' Declare A as Global Variable

LOOP1:
    A = A + 1
    Debug Dp(A),CR        ' Display A on Debug screen
    DELAYTIME             ' Call Sub DELAYTIME
    GoTo LOOP1
    
End                       ' End of Main Program

Sub DELAYTIME()
    Dim K As Integer      ' Declare K as Local Variable
    For K=0 To 10
    Next
End Sub
</code>

In the program above, A is declared as a global variable and K is declared
as a local variable. A can be used anywhere in the program but K can only
be used inside the subroutine DELAYTIME.

Arrays cannot be declared as local variables. Arrays must be declared as
global variables.

===== Calling Subroutines =====

Once the subroutine is created, they can be used like any other statement.
For a subroutine, you do not need parenthesis around the parameters. Use
commas to separate multiple parameters.

The example below shows how this is done:

<code xbasic>
DELAYTIME 100 ' Call subroutine

End

Sub DELAYTIME(DL As Integer)
    Dim K As Integer ' Declare K as Local Variable
    For K=0 To DL
    Next
End Sub
</code>

For a function, you need parenthesis around the parameters. Parenthesis
are required even when there are no parameters.

<code xbasic>
Dim K As Integer
K = SUMAB(100,200) ' Call subroutine and store return value in K
Debug Dec K,cr

End

Function SUMAB(A AS INTEGER, B AS INTEGER) As Integer
    SUMAB = A + B
End Function
</code>

===== Subroutine Position =====

Subroutines must be created after the main program. To do this, simply put
End at the end of your main program as shown below. End is only required
if you have subroutines

<code xbasic>
Dim A As Integer
LOOP1:
    A = A + 1
    Debug DP(A),CR
    DELAYTIME
    Goto Loop1

    End                   ' End of main program

Sub DELAYTIME()
    Dim K As Integer
    For K=0 To 10
    Next
End Sub
</code>

Subroutines and functions are created after the End statement. Gosub
subroutines must be within the main program like shown below:

{{ :cubloc:sub_and_function:sub_location.png?nolink |}}

The End statement is used to differentiate between the BASIC main
program and the program's subroutines. The END statement in Ladder
Logic is used to indicate the final Ladder Logic rung.

===== Subroutine Parameters and Return Values =====

Functions may use any data type, except arrays, as parameters and return
values:

<code xbasic>
Dim A(10) As Integer

Function ABC(A AS Single) as Single                  ' Return Single value
End Function

Function ABC(A AS long)                 ' Long value as a parameter
End Function                            ' When return value is not declared,Long
                                        ' will be used as return value.
</code>

Please avoid returning a ''String'' data type from a ''Function'', as it can result in undefined behavior. Instead, simply define the return value as a global variable and assign it in a subroutine.

<code xbasic>
Dim ReturnValue As String * 100

Sub Example(var as Integer)
   If var == 0 Then
       ReturnValue = "Zero"
   Else
       ReturnValue = "Non-Zero"
   EndIf
End Sub
</code>
                         
                              
Arrays cannot be used as parameters. The following is not allowed.

<code xbasic>
Function ARRAYUSING(A(10) AS Integer)    ' Arrays may not be used as parameters.
   :
End Function
</code>

But you may use one element of an array as a parameter:

<code xbasic>
Dim b(10) as Integer
K = ARRAYUSING(b(10))            ' Use 10th element of array b as a parameter.

Function ARRAYUSING(A AS Integer) as Integer
   :
End Function
</code>


All subroutine parameters are passed by value, not by reference. If the
parameter value is changed within a subroutine, it will not affect the
variable passed to the subroutine.

<code xbasic>
Dim A As Integer
Dim K As Integer
A = 100
K = ADDATEN(A)
Debug Dec? A, Dec? K,CR ' A is 100 and K is 110

End

Sub ADDATEN(V As Integer)
    V = V + 10 ' A does not change when V is changed.
    ADDATEN = V
End Sub
</code>

In contrast, some languages allow values to be passed by reference in
which the actual memory address is passed to the subroutine. Cubloc
BASIC only supports passing by value.


==== Too many characters in one line? ====

If you run out of room, you can use an underscore character (_) to go to
the next line as shown here:

<code xbasic>
ST = "COMFILE TECHNOLOGY"
ST = "COMFILE _
TECHNOLOGY"
</code>

==== Comments ====

Use an apostrophe/single-quote (') to add comments. Comments are
discarded during at compile time, and will not consume any program memory.

<code xbasic>
ADD_VALUE = B + 1 ' Add 1 to B.(Comment)
</code>

==== Nested Subroutines ====

Nested subroutines are supported in Cubloc.

<code xbasic>
A=Floor(SQR(F)) ' Do Floor() on Sqr(F).
</code>

==== Colons ====

Colons cannot be used to append commands in Cubloc BASIC, as is possible in some other languages.

<code xbasic>
A=1: B=1 : C=1 ' Incorrect.
A=1 ' Correct.
B=1
C=1
</code>

[[cubloc:index:|Go CUBLOC home]]