Special Behavior of Apache OpenOffice Basic

From Apache OpenOffice Wiki
Jump to: navigation, search

Threading and rescheduling of Apache OpenOffice Basic differs from other languages which must be taken into consideration.


Apache OpenOffice Basic does not support threads:

  • In situations it may be necessary to create new threads to access UNO components in a special way. This is not possible in Apache OpenOffice Basic.
  • Apache OpenOffice Basic is unable to control threads. If two threads use the Basic runtime system simultaneously, the result will be undefined results or even a crash. Please take precautions.


The Apache OpenOffice Basic runtime system reschedules regularly. It allows system messages to be dispatched continuously that have been sent to the Apache OpenOffice process during the runtime of a Basic module. This is necessary to allow repainting operations, and access to controls and menus during the runtime of a Basic script as Basic runs in the Apache OpenOffice main thread. Otherwise, it would not be possible to stop a running Basic script by clicking the corresponding button on the toolbar.

This behavior has an important consequence. Any system message, for example, clicking a push button control, can result in a callback into Basic if an corresponding event is specified. The Basic programmer must be aware of the fact that this can take place at any point of time when a script is running.

The following example shows how this effects the state of the Basic runtime system:

  Dim EndLoop As Boolean
  Dim AllowBreak As Boolean
  ' Main sub, the execution starts here
      Sub Main
      ' Initialize flags
      EndLoop = FALSE
      AllowBreak = FALSE
      Macro1' calls sub Macro1
  End Sub
  ' Sub called by main
  Sub Macro1
      Dim a
      While Not EndLoop
          ' Toggle flags permanently
          AllowBreak = TRUE
          AllowBreak = FALSE
      Print "Ready!"
  End Sub
  ' Sub assigned to a push button in a writer document
  Sub Break
  If AllowBreak = TRUE Then
      EndLoop = TRUE
  End Sub

When Sub Main in this Basic module is executed, the two Boolean variables EndLoop and AllowBreak are initialized. Then Sub Macro1 is called where the execution runs into a loop. The loop is executed until the EndLoop flag is set to TRUE. This is done in Sub Break that is assigned to a push button in a writer document, but the EndLoop flag can only be set to TRUE if the AllowBreak flag is also TRUE. This flag is permanently toggled in the loop in Sub Macro1.

The program execution may or may not be stopped if the push button is clicked. It depends on the point of time the push button is clicked. If the Basic runtime system has just executed the AllowBreak = TRUE statement, the execution is stopped because the If condition in Sub Break is TRUE and the EndLoop flag can be set to TRUE. If the push button is clicked when the AllowBreak variable is FALSE, the execution is not stopped. The Basic runtime system reschedules permanently, therefore it is unpredictable. This is an example to show what problems may result from the Basic rescheduling mechanism.

Callbacks to Basic that result from rescheduling have the same effect as if the Sub specified in the event had been called directly from the position in the Basic code that is executed in the moment the rescheduling action leading to the callback takes place. In this example, the Basic call stack looks like this, if a breakpoint is placed in the Sub Break:

 Basic         Native code
 0: Break  <---  Callback due to push button event
 1: Macro1 --->  Reschedule()
 2: Main

With the call to the native Reschedule method, the Basic runtime system is left and reentered when the push button events in a Callback to Basic. On the Basic stack this looks like a direct call from Sub Macro1 to Sub Break.

A similar situation occurs when a program raises a dialog using the execute method of the dialog object returned by CreateUnoDialog(). See Programming Dialogs and Dialog Controls. In this case, the Basic runtime system does not reschedule, but messages are processed by the dialog's message loop that also result in callbacks to Basic. When the Basic runtime system is called back due to an event at a dialog control, the resulting Basic stack looks analogous. For example:

  Sub Main
      Dim oDialog
      oDialog = CreateUnoDialog( ... )
  End Sub
  Sub DoIt
  End Sub

If Sub DoIt is specified to be executed if an event occurs for one of the dialog controls, the Basic call stack looks like this if a breakpoint is placed in Sub DoIt:

 Basic        Native code
 0: DoIt <--- Callback due to control event
 1: Main ---> execute() ---> Reschedule()

There is also a difference to the rescheduling done directly by the Basic runtime system. The rescheduling done by the dialog's message loop can not result in unpredictable behavior, because the Basic runtime system has called the dialog's execute method and waits for its return. It is in a well-defined state.

Content on this page is licensed under the Public Documentation License (PDL).
Personal tools
In other languages