Procedures and Functions

 < EN | The OpenOffice.org Documentation Project | OpenOffice.org BASIC Programming Guide

BASIC Guide

{{{parttitle}}}

[[{{{PrevPart}}}|← Previous Section ]]

[[{{{NextPart}}}|Next Section →]]

• The Language of OpenOffice.org Basic

• Overview of a Basic Program
• Working With Variables
• Strings
• Numbers
• Boolean Values
• Date and Time
• Arrays
• Scope and Life Span of Variables
• Constants
• Operators
• Branching
• Loops
• Procedures and Functions
• Error Handling
• Other Instructions

• Runtime Library

• Conversion Functions
• Strings
• Date and Time
• Files and Directories
• Message and Input Boxes
• Other Functions

• Introduction to the API

• Universal Network Objects (UNO)
• Properties and Methods
• Modules, Services and Interfaces
• Tools for Working with UNO
• Overview of Central Interfaces

• Working with Documents

• The StarDesktop
• Styles and Templates

• Text Documents

• The Structure of Text Documents
• Editing Text Documents
• More than Just Text

• Spreadsheet Documents

• The Structure of Spreadsheets
  • Rows and Columns
  • Cells and Ranges
  • Formatting Spreadsheet Documents
• Editing Spreadsheet Documents

• Drawings and Presentations

• The Structure of Drawings
• Editing Drawing Objects
• Presentations

• Charts (Diagrams)

• Using Charts in Spreadsheets
• The Structure of Charts
• Chart Types

• Databases

• SQL: a Query Language
• Types of Database Access
• Data Sources
• Database Access

• Dialogs

• Working With Dialogs
• Properties
• Events
• Dialog Control Elements

• Forms

• Working With Forms
• Control Element Forms
• Database Forms

← Previous Page

Next Page →

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.

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.

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 nothing is assigned, 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 return type is not specified (see first example of this page), the function returns a variant.

Terminating Procedures and Functions Prematurely

In OpenOffice.org 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 OpenOffice.org 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

VBA : The method for passing parameters to procedures and functions in OpenOffice.org Basic is virtually identical to that in VBA. By default, the parameters are passed by reference. To pass parameters as values, use the ByVal keyword. In VBA, you can also use the keyword ByRef to force a parameter to be passed by reference. OpenOffice.org Basic recognizes but ignores this keyword, because this is already the default procedure in OpenOffice.org Basic.

Optional Parameters

Functions and procedures can only be called up if all the necessary parameters are passed during the call.

OpenOffice.org Basic lets you define parameters as optional, that is, if the corresponding values are not included in a call, OpenOffice.org 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.

VBA : The ParamArray keyword present in VBA is not supported in OpenOffice.org Basic.

Recursion

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.

The recursion levels are set at different levels based on the software platform. For Windows the recursion level is 5800. For Solaris and Linux, an evaluation of the stacksize is performed and the recursion level is calculated.

Content on this page is licensed under the Public Documentation License (PDL).