Difference between revisions of "Documentation/BASIC Guide/Procedures and Functions"
Line 14: | Line 14: | ||
A '''procedure''' executes an action without providing an explicit value. Its syntax is | A '''procedure''' executes an action without providing an explicit value. Its syntax is | ||
− | + | <source lang="oobas"> | |
− | + | Sub Test | |
− | + | ' ... here is the actual code of the procedure | |
+ | End Sub | ||
+ | </source> | ||
The example defines a procedure called <tt>Test</tt> that contains code that can be accessed from any point in the program. The call is made by entering the procedure name at the relevant point of the program: | The example defines a procedure called <tt>Test</tt> that contains code that can be accessed from any point in the program. The call is made by entering the procedure name at the relevant point of the program: | ||
Line 26: | Line 28: | ||
A '''function''', just like a procedure, combines a block of programs to be executed into one logical unit. However, unlike a procedure, a function provides a return value. | A '''function''', just like a procedure, combines a block of programs to be executed into one logical unit. However, unlike a procedure, a function provides a return value. | ||
− | + | <source lang="oobas"> | |
− | + | Function Test | |
− | + | ' ... here is the actual code of the function | |
− | + | Test = 123 | |
+ | End Function | ||
+ | </source> | ||
The return value is assigned using simple assignment. The assignment does not need to be placed at the end of the function, but can be made anywhere in the function. | The return value is assigned using simple assignment. The assignment does not need to be placed at the end of the function, but can be made anywhere in the function. | ||
Line 35: | Line 39: | ||
The preceding function can be called within a program as follows: | The preceding function can be called within a program as follows: | ||
− | + | <source lang="oobas"> | |
− | + | Dim A | |
+ | A = Test | ||
+ | </source> | ||
The code defines a variable <tt>A</tt> and assigns the result of the <tt>Test</tt> function to it. | The code defines a variable <tt>A</tt> and assigns the result of the <tt>Test</tt> function to it. | ||
Line 42: | Line 48: | ||
The return value can be overwritten several times within the function. As with classic variable assignment, the function in this example returns the value that was last assigned to it. | The return value can be overwritten several times within the function. As with classic variable assignment, the function in this example returns the value that was last assigned to it. | ||
− | + | <source lang="oobas"> | |
− | + | Function Test | |
− | + | Test = 12 | |
− | + | ' ... | |
− | + | Test = 123 | |
+ | End Function | ||
+ | </source> | ||
In this example, the return value of the function is 123. | In this example, the return value of the function is 123. | ||
Line 54: | Line 62: | ||
The return value of a function can be any type. The type is declared in the same way as a variable declaration: | The return value of a function can be any type. The type is declared in the same way as a variable declaration: | ||
− | + | <source lang="oobas"> | |
− | + | Function Test As Integer | |
− | + | ' ... here is the actual code of the function | |
+ | End Function | ||
+ | </source> | ||
If the specification of an explicit value is stopped, the type of the return value is assigned as variant. | If the specification of an explicit value is stopped, the type of the return value is assigned as variant. | ||
Line 66: | Line 76: | ||
The following example shows a procedure which terminates implementation when the <tt>ErrorOccured</tt> variable has the value <tt>True</tt>. | The following example shows a procedure which terminates implementation when the <tt>ErrorOccured</tt> variable has the value <tt>True</tt>. | ||
− | + | <source lang="oobas"> | |
− | + | Sub Test | |
− | + | Dim ErrorOccured As Boolean | |
− | + | ' ... | |
− | + | If ErrorOccured Then | |
− | + | Exit Sub | |
− | + | End If | |
− | + | ' ... | |
+ | End Sub | ||
+ | </source> | ||
== Passing Parameters == | == Passing Parameters == | ||
Line 79: | Line 91: | ||
Functions and procedures can receive one or more parameters. Essential parameters must be enclosed in parentheses after the function or procedure names. The following example defines a procedure that expects an integer value <tt>A</tt> and a string <tt>B</tt> as parameters. | Functions and procedures can receive one or more parameters. Essential parameters must be enclosed in parentheses after the function or procedure names. The following example defines a procedure that expects an integer value <tt>A</tt> and a string <tt>B</tt> as parameters. | ||
− | + | <source lang="oobas"> | |
− | + | Sub Test (A As Integer, B As String) | |
− | + | ' ... | |
+ | End Sub | ||
+ | </source> | ||
Parameters are normally [http://en.wikipedia.org/wiki/Pass_by_reference#Call_by_reference passed by '''Reference'''] in {{OOo}} Basic. Changes made to the variables are retained when the procedure or function is exited: | Parameters are normally [http://en.wikipedia.org/wiki/Pass_by_reference#Call_by_reference passed by '''Reference'''] in {{OOo}} Basic. Changes made to the variables are retained when the procedure or function is exited: | ||
− | + | <source lang="oobas"> | |
− | + | Sub Test | |
− | + | Dim A As Integer | |
− | + | A = 10 | |
− | + | ChangeValue(A) | |
− | + | ' The parameter A now has the value 20 | |
− | + | End Sub | |
− | + | ||
− | + | Sub ChangeValue(TheValue As Integer) | |
− | + | TheValue = 20 | |
+ | End Sub | ||
+ | </source> | ||
In this example, the value <tt>A</tt> that is defined in the <tt>Test</tt> function is passed as a parameter to the <tt>ChangeValue</tt> function. The value is then changed to 20 and passed to <tt>TheValue</tt>, which is retained when the function is exited. | In this example, the value <tt>A</tt> that is defined in the <tt>Test</tt> function is passed as a parameter to the <tt>ChangeValue</tt> function. The value is then changed to 20 and passed to <tt>TheValue</tt>, which is retained when the function is exited. | ||
Line 102: | Line 118: | ||
In the preceding example, if we replace the <tt>ChangeValue</tt> function then the superordinate variable A remains unaffected by this change. After the call for the <tt>ChangeValue</tt> function, variable <tt>A</tt> retains the value 10. | In the preceding example, if we replace the <tt>ChangeValue</tt> function then the superordinate variable A remains unaffected by this change. After the call for the <tt>ChangeValue</tt> function, variable <tt>A</tt> retains the value 10. | ||
− | + | <source lang="oobas"> | |
− | + | Sub ChangeValue(ByVal TheValue As Integer) | |
− | + | TheValue = 20 | |
+ | End Sub | ||
+ | </source> | ||
{{Documentation/Note|The method for passing parameters to procedures and functions in {{OOo}} Basic is virtually identical to that in VBA. By default, the parameters are passed by reference. To pass parameters as values, use the <tt>ByVal</tt> keyword. In VBA, you can also use the keyword <tt>ByRef</tt> to force a parameter to be passed by reference. {{OOo}} Basic recognizes but ignores this keyword, because this is already the default procedure in {{OOo}} Basic.}} | {{Documentation/Note|The method for passing parameters to procedures and functions in {{OOo}} Basic is virtually identical to that in VBA. By default, the parameters are passed by reference. To pass parameters as values, use the <tt>ByVal</tt> keyword. In VBA, you can also use the keyword <tt>ByRef</tt> to force a parameter to be passed by reference. {{OOo}} Basic recognizes but ignores this keyword, because this is already the default procedure in {{OOo}} Basic.}} | ||
Line 114: | Line 132: | ||
{{OOo}} Basic lets you define parameters as '''optional''' , that is, if the corresponding values are not included in a call, {{OOo}} Basic passes an empty parameter. In the following example the <tt>A</tt> parameter is obligatory, whereas the <tt>B</tt> parameter is optional. | {{OOo}} Basic lets you define parameters as '''optional''' , that is, if the corresponding values are not included in a call, {{OOo}} Basic passes an empty parameter. In the following example the <tt>A</tt> parameter is obligatory, whereas the <tt>B</tt> parameter is optional. | ||
− | + | <source lang="oobas"> | |
− | + | Sub Test(A As Integer, Optional B As Integer) | |
− | + | ' ... | |
+ | End Sub | ||
+ | </source> | ||
The <tt>IsMissing</tt> function checks whether a parameter has been passed or is left out. | The <tt>IsMissing</tt> function checks whether a parameter has been passed or is left out. | ||
− | + | <source lang="oobas"> | |
− | + | Sub Test(A As Integer, Optional B As Integer) | |
− | + | Dim B_Local As Integer | |
− | + | ' Check whether B parameter is actually present | |
− | + | If Not IsMissing (B) Then | |
− | + | B_Local = B ' B parameter present | |
− | + | Else | |
− | + | B_Local = 0 ' B parameter missing -> default value 0 | |
− | + | End If | |
− | + | ' ... Start the actual function | |
+ | End Sub | ||
+ | </source> | ||
The example first tests whether the <tt>B</tt> parameter has been passed and, if necessary, passes the same parameter to the internal <tt>B_Local</tt> variable. If the corresponding parameter is not present, then a default value (in this instance, the value 0) is passed to <tt>B_ Local</tt> rather than the passed parameter. | The example first tests whether the <tt>B</tt> parameter has been passed and, if necessary, passes the same parameter to the internal <tt>B_Local</tt> variable. If the corresponding parameter is not present, then a default value (in this instance, the value 0) is passed to <tt>B_ Local</tt> rather than the passed parameter. | ||
Line 141: | Line 163: | ||
The following example uses a recursive function to calculate the factorial of the numbers <tt>42</tt>, <tt>-42</tt>, and <tt>3.14</tt>: | The following example uses a recursive function to calculate the factorial of the numbers <tt>42</tt>, <tt>-42</tt>, and <tt>3.14</tt>: | ||
− | + | <source lang="oobas"> | |
− | + | Sub Main | |
− | + | Msgbox CalculateFactorial( 42 ) ' Displays 1,40500611775288E+51 | |
− | + | Msgbox CalculateFactorial( -42 ) ' Displays "Invalid number for factorial!" | |
− | + | Msgbox CalculateFactorial( 3.14 ) ' Displays "Invalid number for factorial!" | |
− | + | End Sub | |
− | + | ||
− | + | Function CalculateFactorial( Number ) | |
− | + | If Number < 0 Or Number <> Int( Number ) Then | |
− | + | CalculateFactorial = "Invalid number for factorial!" | |
− | + | ElseIf Number = 0 Then | |
− | + | CalculateFactorial = 1 | |
− | + | Else | |
− | + | ' This is the recursive call: | |
− | + | CalculateFactorial = Number * CalculateFactorial( Number - 1 ) | |
− | + | Endif | |
+ | End Function | ||
+ | </source> | ||
The example returns the factorial of the number <tt>42</tt> by recursively calling the <tt>CalculateFactorial</tt> function until it reaches the base condition of <tt>0! = 1</tt>. | The example returns the factorial of the number <tt>42</tt> by recursively calling the <tt>CalculateFactorial</tt> function until it reaches the base condition of <tt>0! = 1</tt>. |
Revision as of 13:18, 2 April 2008
Procedures and functions form pivotal points in the structure of a program. They provide the framework for dividing a complex problem into various sub-tasks.
Contents
Procedures
A procedure executes an action without providing an explicit value. Its syntax is
Sub Test ' ... here is the actual code of the procedure End Sub
The example defines a procedure called Test that contains code that can be accessed from any point in the program. The call is made by entering the procedure name at the relevant point of the program:
Test
Functions
A function, just like a procedure, combines a block of programs to be executed into one logical unit. However, unlike a procedure, a function provides a return value.
Function Test ' ... here is the actual code of the function Test = 123 End Function
The return value is assigned using simple assignment. The assignment does not need to be placed at the end of the function, but can be made anywhere in the function.
The preceding function can be called within a program as follows:
Dim A A = Test
The code defines a variable A and assigns the result of the Test function to it.
The return value can be overwritten several times within the function. As with classic variable assignment, the function in this example returns the value that was last assigned to it.
Function Test Test = 12 ' ... Test = 123 End Function
In this example, the return value of the function is 123.
If an assignment is stopped, the function returns a zero value (number 0 for numerical values and a blank for strings).
The return value of a function can be any type. The type is declared in the same way as a variable declaration:
Function Test As Integer ' ... here is the actual code of the function End Function
If the specification of an explicit value is stopped, the type of the return value is assigned as variant.
Terminating Procedures and Functions Prematurely
In Apache OpenOffice Basic, you can use the Exit Sub and Exit Function commands to terminate a procedure or function prematurely, for example, for error handling. These commands stop the procedure or function and return the program to the point at which the procedure or function was called up.
The following example shows a procedure which terminates implementation when the ErrorOccured variable has the value True.
Sub Test Dim ErrorOccured As Boolean ' ... If ErrorOccured Then Exit Sub End If ' ... End Sub
Passing Parameters
Functions and procedures can receive one or more parameters. Essential parameters must be enclosed in parentheses after the function or procedure names. The following example defines a procedure that expects an integer value A and a string B as parameters.
Sub Test (A As Integer, B As String) ' ... End Sub
Parameters are normally passed by Reference in Apache OpenOffice Basic. Changes made to the variables are retained when the procedure or function is exited:
Sub Test Dim A As Integer A = 10 ChangeValue(A) ' The parameter A now has the value 20 End Sub Sub ChangeValue(TheValue As Integer) TheValue = 20 End Sub
In this example, the value A that is defined in the Test function is passed as a parameter to the ChangeValue function. The value is then changed to 20 and passed to TheValue, which is retained when the function is exited.
You can also pass a parameter as a value if you do not want subsequent changes to the parameter to affect the value that is originally passed. To specify that a parameter is to be passed as a value, ensure that the ByVal keyword precedes the variable declaration in the function header.
In the preceding example, if we replace the ChangeValue function then the superordinate variable A remains unaffected by this change. After the call for the ChangeValue function, variable A retains the value 10.
Sub ChangeValue(ByVal TheValue As Integer) TheValue = 20 End Sub
Optional Parameters
Functions and procedures can only be called up if all the necessary parameters are passed during the call.
Apache OpenOffice Basic lets you define parameters as optional , that is, if the corresponding values are not included in a call, Apache OpenOffice Basic passes an empty parameter. In the following example the A parameter is obligatory, whereas the B parameter is optional.
Sub Test(A As Integer, Optional B As Integer) ' ... End Sub
The IsMissing function checks whether a parameter has been passed or is left out.
Sub Test(A As Integer, Optional B As Integer) Dim B_Local As Integer ' Check whether B parameter is actually present If Not IsMissing (B) Then B_Local = B ' B parameter present Else B_Local = 0 ' B parameter missing -> default value 0 End If ' ... Start the actual function End Sub
The example first tests whether the B parameter has been passed and, if necessary, passes the same parameter to the internal B_Local variable. If the corresponding parameter is not present, then a default value (in this instance, the value 0) is passed to B_ Local rather than the passed parameter.
Recursion
Recursion is now possible in Apache OpenOffice Basic. A recursive procedure or function is one that has the ability to call itself until it detects that some base condition has been satisfied. When the function is called with the base condition, a result is returned.
The following example uses a recursive function to calculate the factorial of the numbers 42, -42, and 3.14:
Sub Main Msgbox CalculateFactorial( 42 ) ' Displays 1,40500611775288E+51 Msgbox CalculateFactorial( -42 ) ' Displays "Invalid number for factorial!" Msgbox CalculateFactorial( 3.14 ) ' Displays "Invalid number for factorial!" End Sub Function CalculateFactorial( Number ) If Number < 0 Or Number <> Int( Number ) Then CalculateFactorial = "Invalid number for factorial!" ElseIf Number = 0 Then CalculateFactorial = 1 Else ' This is the recursive call: CalculateFactorial = Number * CalculateFactorial( Number - 1 ) Endif End Function
The example returns the factorial of the number 42 by recursively calling the CalculateFactorial function until it reaches the base condition of 0! = 1.
Content on this page is licensed under the Public Documentation License (PDL). |