Dim statement (LotusScript® Language)

Declares variables.

Syntax

{ Dim | Static | Public | Private } variableDeclaration [ , variableDeclaration ]...

Elements

Dim | Static | Public | Private

Variable declarations begin with one of the words Dim, Static, Private, or Public.

Dim indicates that a variable is nonstatic and private by default.

  • Static indicates that the variable's value is saved between calls to the procedure where the variable is declared.
  • Public indicates that the variable is visible outside the scope (module or class) where the variable is defined, for as long as this module remains loaded.
  • Private indicates that the variable is visible only within the current scope.

You can use the Static keyword in procedure scope, but not in module or class scope. You can use the Public and Private keywords in module or class scope, but not in procedure scope.

variableDeclaration

The declaration has one of the following forms, depending on the kind of variable being declared:

  • Scalar variable: variableName[dtSuffix][ As type ]
  • Object reference variable: variableName As [ New ] type [ argList ]
  • List variable: variableName[dtSuffix] List [ As type ]
  • Array variable: variableName[dtSuffix] ( [ bounds ] ) [ As type ]

You can declare any number of variables in a single statement, separated by commas.

variableName

The name of the variable being declared.

dtSuffix

Optional. A character that specifies the data type of variableName. The data type suffix characters and the data types that they represent are: @ for Currency, # for Double, % for Integer, & for Long, ! for Single, and $ for String.

type

Optional for scalar variables, lists, and arrays. A valid LotusScript® data type, user-defined data type, user-defined class, or product class. This specifies the type of variableName.

If type is the name of a class, variableName is an object reference for that type: its value can only be a reference to an instance of that class or to an instance of a derived class of that class, or the value NOTHING.

New

Optional. Valid only if type is the name of a user-defined or product class. New creates a new object of the class named by type, and assigns a reference to that object in variableName.

Note that in some cases, IBM® products provide other mechanisms for creating product objects in scripts, such as product functions or product object methods. See your IBM® software documentation for details.

argList

Optional. This is valid only if the New keyword is specified.

For user-defined classes, argList is the comma-separated list of arguments required by the class constructor sub New, defined in the class named by type. For product classes, consult the product documentation.

bounds

Optional. bounds is a comma-separated list of bounds for the dimensions of a fixed array. Each bound is specified in the form

[ lowerBound To ] upperBound

where lowerBound is a number designating the minimum subscript allowed for the dimension, and upperBound is a number designating the maximum. If no lowerBound is specified, the lower bound for the array dimension defaults to zero (0), unless the default lower bound has been changed to 1 using the Option Base statement. For example, with a default lower bound of 0, the following statement allocates storage for 4 strings instead of the assumed 3 strings:

		Dim strArray(3) as String

If you don't define any bounds, the array is defined to be a dynamic array.

Usage

The Public keyword cannot be used in a product object script or %Include file in a product object script, except to declare class members. You must put such Public declarations in (Globals).

Explicit declarations and implicit declarations

You can declare a variable name either explicitly or implicitly. The Dim statement declares a name explicitly. A name is declared implicitly if it is used (referred to) when it has not been explicitly declared, or when it is not declared as a Public name in another module being used by the module where the name is referred to. You can prohibit implicit declarations by including the statement Option Declare in your script.

Specifying the data type

Either dtSuffix or As type can be specified in variableDeclaration, but not both. If neither is specified, the data type of variableName is Variant.

The data type suffix character, if it is specified, is not part of the variable name. When the name is used (referred to) in the script, it can be optionally suffixed by the appropriate data type suffix character.

Declaring arrays

For a fixed array, Dim specifies the type of the array, the number of dimensions of the array, and the subscript bounds for each dimension. Dim allocates storage for the array elements and initializes the array elements to the appropriate value for that data type (see "Initializing variables," later in this section).

For a dynamic array, Dim only specifies the type of the array. The number of dimensions of the array and the subscript bounds for each dimension are not defined; and no storage is allocated for the array elements. The declaration of a dynamic array must be completed by a later ReDim statement.

Arrays can have up to 8 dimensions.

Array subscript bounds must fall in the range -32,768 to 32,767, inclusive.

Declaring lists

A list is initially empty when it is declared: it has no elements, and no storage is allocated for it. An element is added to a list when the list name with a particular list tag first appears on the left-hand side of an assignment statement (a Let statement or a Set statement).

If the character set is single byte, Option Compare determines whether list names are case sensitive. For example, if Option Compare Case is in effect, the names "ListA" and "Lista" are different; if Option Compare NoCase is in effect, these names are the same. If the character set is double byte, list names are always case and pitch sensitive.

Declaring object reference variables

If type is the name of a class and the keyword New is not specified, the initial value of the declared object reference variable is NOTHING. To assign another value to an object reference variable, use the Set statement later in the script.

Dim variableName As New className generates executable code. When you save a compiled module, module-level executable code is not saved, so be careful about using such a statement at the module level. Your IBM® software may prohibit you from placing executable statements at the module level.

You may prefer to declare the object reference variable at the module level with Dim variableName As className, which is not executable code, then use a Set statement (which is executable code) in a procedure to bind the object reference variable to an object.

The New keyword is not valid in an array declaration or a list declaration.

Initializing variables

Declaring a variable also initializes it to a default value.

  • Scalar variables are initialized according to their data type:
    • Numeric data types (Boolean, Byte, Integer, Long, Single, Double, Currency): Zero (0)
    • Variants: EMPTY
    • Fixed-length strings: A string filled with the NULL character Chr(0)
    • Variable-length strings: The empty string ("")
  • Object reference variables are initialized to NOTHING, unless New is specified in the variable declaration.
  • Each member of a user-defined data type variable is initialized according to its own data type.
  • Each element of an array variable is initialized according to the array's data type.
  • A list variable has no elements when it is declared, so there is nothing to initialize.

Visibility of declarations

The default visibility for a declaration at the module level is Private, unless Option Public has been specified.

The default visibility for a variable declaration within a class is Private.

Public and Private can only be used to declare variables in module or class scope. Variables declared within a procedure are automatically Private; members of user-defined data types are automatically Public. Once created, these cannot be changed.

Example