Declaring scalar variables explicitly

Declaring a variable creates an identifier, determines its scope and lifetime, specifies the type of data that can occupy the location in memory to which it refers, and causes LotusScript® to write an initial value to that location. Declaring the variable explicitly is recommended. You declare a scalar variable explicitly with the Dim statement, or one of its variations. The variation you use depends on the application area in which you declare the variable, and on the scope and lifetime you want the variable to have.

Note: You can specify OPTION DECLARE to force LotusScript® to check for implicit declaration. It will generate a compile time error if any variables are not explicitly declared. It is recommended that applications be checked for implicit declaration before being released.

The following diagram summarizes the syntax for declaring a single scalar variable (in this example, a variable of type String):

Single scalar variable syntax

The syntax elements in the declaration of a scalar variable are summarized in the following table:


Element	Description
Dim	Declares a variable with Private scope.
Public, Private	Public declares a variable with Public scope. Private declares a variable with Private scope.
Static	Only applicable to variables declared inside a procedure. Static variables retain their values (rather than going out of existence) between calls to the procedure while the module in which the procedure is defined remains loaded.
varName	The name of the variable. At module level or within a procedure, varName can end in any of the data type suffixes that LotusScript® recognizes. This determines the type of data that the variable can hold. You can append a data type suffix to a variable name when you declare it only if you do not include the As dataType clause in the declaration.
As dataType	Specifies the type of data the variable can hold. If you include this clause, varName cannot end in a data type suffix character. This clause is required in the declaration of a variable within the definition of a user-defined data type or class, but optional in the declaration of a variable at module level or within a procedure.

Initial default values

When you declare a variable explicitly, LotusScript® assigns it an initial default value:


Type of variable	Initial value
Numeric (Boolean, Byte, Integer,Long,Single, Double,Currency)	0
Variable-length String	"" (the empty string)
Fixed-length String	A string of the specified length, filled with Chr(0) (the NULL character)

Note: Because LotusScript® assigns initial values to variables, you can encounter unexpected errors if the initial value is not what you wanted, or if the variable name is later misspelled, in which case it will be treated as a new variable.

Whether or not you append a data type suffix to the name of the variable when you declare it, you can always do so (or not) when referring to an explicitly declared scalar variable.

For example:

Public firstName$
Public lastName As String
Dim age%
Dim money As Currency

firstName$ = "Roman"
lastName$ = "Minsky"
age% = 12
money@ = 150.75
Print firstName & " " & lastName & ", " & age &", $" & money
' Output: Roman Minsky, 12, $150.75
Print firstName$ & " " & lastName$ & ", " & age% &", $" & money
' Output: Roman Minsky, 12, $150.75

String variables

A variable of type String contains a sequence of characters in the Unicode character set. Unicode is a character-encoding system that uses two bytes to represent each character in the set. LotusScript® converts input to Unicode format before compiling an application.

A String variable can be of variable or fixed length. The syntax for declaring a variable-length String variable is shown in the preceding diagram. The syntax for declaring a fixed-length String variable is shown as follows:

Fixed-length string variable syntax

The charNum argument specifies that varName is a fixed-length String variable of charNum characters.

When you assign a string to a fixed-length String variable, LotusScript® truncates the string or pads it to the declared length with trailing spaces if necessary.

For example:

Dim myName$
Dim myTown As String
' myName and myTown are variable-length string variables. 
Dim myState As String * 2
' myState is a 2-character fixed-length String variable.
Dim myZIP As String * 5
' myZIP$ is a 5-character fixed-length String variable.
' If myZIP$ is assigned a value of more than 5 characters,
' that value will be truncated to its first 5 characters.
myName$ = "Mark"
myTown$ = "Centerville"
myState$ = "MA"
myZIP$ = "02100-9999"
Print myName$
' Output: Mark
Print myTown$ & ", " & myState$ & " " & myZIP$
' Output: Centerville, MA 02100

Declaring more than one variable at a time

The Dim statement and its variations allow you to declare more than one variable at a time at module level or within a procedure. At module level, the syntax is

{ Dim|Public| Private}varName1[ As dataType ], varName2 [ As dataType], ...

Within a procedure, the syntax is

{ Dim | Static } varName1 [ As dataType ], varName2 [ As dataType ], ...

It's important to explicitly declare all variables. For example:

DIM X, Y AS INTEGER

results in Y being data-typed as INTEGER but X as Variant. The correct syntax is:

DIM X AS INTEGER, Y AS INTEGER

The conventions for appending a data type suffix character to a variable name in the absence of an As dataType clause (and not appending a data type suffix in the presence of an As dataType clause) are the same as in the declaration of a single scalar variable.

For example:

Dim aString$, anInt%, aDouble As Double, aCurrency@
aString$ = "Hello"
Print TypeName(aString$) & ": " & aString$
' Output: STRING: Hello
anInt% = 123
Print TypeName(anInt%) & ": " & anInt%
' Output: INTEGER: 123
aDouble# = 123.45
Print TypeName(aDouble) & ": " & aDouble#
' Output: DOUBLE: 123.45
aCurrency@ = 456.78
Print TypeName(aCurrency@) & ": " & aCurrency@
' Output: CURRENCY: 456.78

Sub MySub
  Dim aString As String * 2, anotherString$, anInt%
  Static aDouble#, anotherDouble#
    
  aString$ = "Hi"
  Print TypeName(astring$) & ": " & aString$
  anotherString$ = "World"
  Print TypeName(anotherstring$) & ": " & anotherString$
  anInt% = 234
  Print TypeName(anInt%) & ": " & anInt%
  aDouble# = aDouble# + 1
  anotherDouble# = aDouble# * 2
  Print TypeName(anotherDouble#) & ": " & anotherDouble#
End Sub
Call MySub
' Output: 
' STRING: Hi
' STRING: World
' INTEGER: 234
' DOUBLE: 2
Call MySub
' Output:
' STRING: Hi
' STRING: World
' INTEGER: 234
' DOUBLE: 4