Scope of Variables, Subroutines, and Functions

Scope of Variables , Subroutines, and Functions

The idea of scope deals with the lifetime and visibility of a variable, subroutine, or function in OOo Basic. The scope depends on the location of declaration and the keywords Public, Private, Static, and Global.

Local Variables Defined in a Subroutine or Function

Variables declared inside a subroutine or function are called local variables. It is also commonly said that a variable is local to a routine if the variable is declared inside that routine.

You can declare a variable inside a subroutine or function by using the Dim keyword. Variables defined inside a routine are visible only inside that routine. It is not possible to directly access a variable defined inside a routine from outside the routine. However, it is possible to access a variable defined outside any routine-for example, in a module header-from inside a routine. When a variable or routine name is encountered inside a routine, OOo Basic starts looking for the variable or routine in the following order: current routine, module, library, and other open libraries. In other words, it starts inside and works its way out.

Variables defined in a routine are created and initialized each time the routine is entered. The variables are destroyed every time the routine is exited because the routine is finished. Leaving the routine to call another routine does not cause the variables to be reinitialized.

Use the keyword Static to change a variable's creation and destruction times to the calling macro's start and finish times, respectively. Although the variable is still only visible from within the current routine, it is initialized once when the macro starts running and the values are retained through multiple calls to the same routine. In other words, you start with no macro running. The first time that a subroutine or function that contains a static variable is called, the static variables contain initial values based on their types. The static variables retain their values between calls as long as the macro as a whole did not stop running. The keyword Static uses the same syntax as the keyword Dim and is valid only inside a subroutine or function. Listing 29 calls a routine that uses a static variable. See Figure 8 for variable values.

Figure 8: Static variables maintain their values between calls in Listing 29.

Listing 29: ExampleStatic is found in the Scope module in this chapter's source code files as SC02.sxw.

 Sub ExampleStatic   ExampleStaticWorker()   ExampleStaticWorker() End Sub Sub ExampleStaticWorker   Static iStaticl As Integer   Dim iNonStatic As Integer   iNonStatic = iNonStatic + 1   iStaticl = iStaticl + 1   Msgbox "iNonStatic = " & iNonStatic & CHR$(10) &_          "iStaticl = " & iStaticl End Sub 

 

Variables Defined in a Module

The Dim, Global, Public, or Private statements are used to declare variables in a module header. Global, Public, and Private use the same syntax as the Dim statement but they can't declare variables inside a subroutine or function. Each variable type has a different life cycle, as summarized in Table 10 .

Table 10: Life cycle of a variable defined in a module header.

Keyword	Initialized	Dies	Scope
Global	Compile time	Compile time	All modules and libraries.
Public	Macro start	Macro finish	Declaring library container.
Dim	Macro start	Macro finish	Declaring library container.
Private	Macro start	Macro finish	Declaring module.

Warning  

The included OpenOffice.org help indicates that the keywords Static, Public, Private, and Global may be used as modifiers to the keyword Dim. This is not correct; they are used instead of the keyword Dim.

Although it is sometimes necessary to define a variable in a module header, you should avoid it if possible. Variables defined in the header can be seen in other modules that don't expect them. It's difficult to determine why the compiler claims that a variable is already defined if it is defined in another library or module. Even worse , two working libraries may stop working because of naming conflicts.

Global

Use Global to declare a variable that is available to every module in every library. The library containing the Global variable must be loaded for the variable to be visible.

When a library is loaded, it is automatically compiled and made ready for use; this is when a Global variable is initialized. Changes made to a Global variable are seen by every module and are persisted even after the macro is finished. Global variables are reset when the containing library is compiled. Exiting and restarting OpenOffice.org causes all libraries to be compiled and all Global variables to be initialized. Modifying the module containing the Global definition also forces the module to be recompiled.

 Global iNumberOfTimesRun 

Variables declared Global are similar to variables declared Static, but Static works only for local variables and Global works only for variables declared in the header.

Public and Dim

Use Public or Dim to declare a variable that is visible to all modules in the declaring library container. Outside the declaring library container, the public variables aren't visible. Public variables are initialized every time a macro runs.

Warning  

The included OOo Basic 1.1 help incorrectly states that Dim is equivalent to Private.

An application library is a library that is declared in the "soffice" library container. This is available when OOo is running, is stored in its own directory, and every document can view it. Document-level libraries are stored in OOo documents. The libraries are saved as part of the document and are not visible outside the document.

Public variables declared in an application library are visible in every OOo document-level library. Public variables declared in a library contained in an OOo document are not visible in application-level libraries. Declaring a Public variable in a document library effectively hides a Public variable declared in an application library. Simply stated (see Table 11 ), if you declare a Public variable in a document, it is visible only in the document and it will hide a Public variable with the same name declared outside the document. A Public variable declared in the application is visible everywhere-unless a variable declaration with more local scope takes priority over the declaration with more global scope.

Table 11: The scope of a Public variable depends on where it is declared.

Declaration Location	Scope
Application	Visible everywhere.
Document	Visible only in the declaring document.
Application and Document	Macros in the document are unable to see the application-level variable.

 Public oDialog As Object Dim iCount As Integer 

Although Public and Dim are equivalent, you should use Public because it emphasizes the desired scope. This is especially important because the included OOo Basic 1.1 help incorrectly states that Dim is equivalent to Private.

Private

Use Private to declare a variable in a module that should not be visible in another module. Private variables, like Public variables, are initialized every time a macro runs. A single variable name may be used by two different modules as their own variable if the variable is declared Private.

 Private oDialog As Variant 

Warning  

Some documentation indicates that a Private variable is not visible outside the declaring module. As of OOo 1.1, this is not true. This is scheduled to be fixed in OOo 2.0.

Although some documentation indicates that a Private variable is not visible outside the declaring module, this is not true. To see for yourself, create two modules-Module1 and Module2-in the same library. In Module1, add the declaration "Private priv_var As Integer". Macros in Module2 can use the variable "priv_var". Even if Module2 is located in a different library in the same document, the variable "priv_var" is visible and usable.

In Module1, declare a variable "Private priv_var As Double". A variable of the same name is declared in Module2 but it is an Integer variable. Each module sees its own Private variable. Changing these two variables to have Public scope rather than Private introduces an ugly situation; only one of these is visible and usable, but you don't know which one it is without performing a test. Assign the value 4.7 to the variable and see if it is an Integer or a Double.