Syntax [accessModifier] [[Shared] [Shadows] | [Static]] [ReadOnly] _ [Dim ] [WithEvents] name[([subscripts])] _ [As [New] type] [= expression]
accessModifier (optional) Specifies the scope and accessibility of the variable(s). For variables defined within a procedure or code block, no access modifier is permitted; all procedure-level and block-level variables have procedure-level or block-level scope. For all module-level variables, one of the following access levels may be used in place of the Dim keyword: Access level | Description |
|---|
Public | The variable(s) are publicly accessible anywhere, both inside and outside of the project. | Private | The variable(s) are accessible only within the defining type. | Protected | The variable(s) are accessible only to the code in the defining type or to one of its derived types. | Friend | The variable(s) are accessible only within the project that contains the variable definition. | Protected Friend | Combines the access features of Protected and Friend. |
If omitted in a declaration at the module level (and the Dim keyword is used instead), the Public access level is used.
Shared (optional) Indicates that the variables are shared variables instead of instance variables. Shared variables may be accessed without a particular instance of the object. Shared variables are also known as static variables, but they are different from Static variables used within procedures. The Shared keyword is only valid in module-level declarations.
Shadows (optional) Indicates that the variables shadow identically named elements in a base class. The Shadows keyword is only valid in module-level declarations.
Static (optional) Indicates that the variables have a lifetime that lasts for the lifetime of the object that contains the variable, although their scope is limited to the procedure or code block in which they are defined. The Static keyword is only valid in procedure-level or block-level declarations.
ReadOnly (optional) Indicates that the variable(s) are read-only beyond their initial setting through expression; they are functionally equivalent to Const fields. Static variables cannot be ReadOnly.
Dim (optional) The Dim keyword is required unless one of the following keywords is used: Public, Private, Friend, Protected, Protected Friend, or Static. When one of those keywords appears, Dim is always excluded.
WithEvents (optional) Indicates that the object will respond to, and process events through, event handlers. When using the WithEvents keyword, the As clause must appear, and the data type may not be an array. The WithEvents keyword is only valid in module-level declarations.
name (required) The name of the variable.
subscripts (optional) The dimensions of an array variable, with up to 60 comma-delimited dimensions. Each dimension has the format: [[0 To] upper]
which indicates the upper bound of the array dimension. The optional 0 To clause is for clarity only; all array dimensions have a lower bound of zero. All dimensions can be left blank to allow the array to be dimensioned by expression, or later through a ReDim statement. You can indicate the number of dimensions without indicating the range of each dimension by using commas only, without an upper value for each dimension.
New (optional) Creates an instance of an object and assigns it to name.
type (optional unless OptionStrict is On ; any) The data type of name. If omitted, the data type is set to Object. If the New keyword is used, type may be followed by constructor parameters in parentheses.
expression (optional) Any expression that provides the initial value to assign to the variable; cannot be used if an As New clause is used.
Description The Dim statement declares and allocates storage space in memory for variables. The Dim statement is used either at the module level or the procedure level to declare variables of a particular data type. Usage at a Glance If you use WithEvents, the variable cannot be of type Object. If type does not expose any events, the WithEvents keyword generates a compiler error. Reference types have an initial value of Nothing, unless the New keyword is used to assign an initial value, or expression is used to assign an initial value. Multiple variables may be declared with the same Dim statement; each variable is separated from the others by a comma. If one of the variables is not given an explicit type declaration, then its type is that of the next variable with an explicit type declaration. For example, in the line: Dim first As Long, second, third, fourth As Integer
the variables second and third are of type Integer, as is fourth. In VB 6, the variables second and third would have been of type Variant. More than one variable can be assigned a value in a single Dim statement: Dim first As Integer = 6, second As Integer = 9
Variables that are not explicitly initialized by the Dim statement have the following default values: Data type | Initial value |
|---|
All numeric types | 0 | Boolean | False | Date | January 1, 1 AD, 12:00:00 AM | Object | Nothing | String | Nothing |
Local variables can have procedure-level scope or block-level scope. A variable that is declared within a Visual Basic procedure but not within a code block has procedure-level scope: its scope consists of the procedure in which it is declared. If a variable is declared inside a code block (a statement that contains subordinate statements, as with an If or For statement), then the variable has block-level scope: it is visible only within that block. However, block-level variables have a lifetime of the entire procedure. Once set, their value is retained even when the block is exited. There are several ways to declare and assign an initial value to a one-dimensional array: 'Implicit constructor: No initial size and no initialization Dim sampleArray( ) As Integer 'Explicit constructor: No initial size and no initialization Dim sampleArray( ) As Integer = New Integer( ) {} 'Implicit constructor: Initial size but no initialization Dim sampleArray(6) As Integer 'Explicit constructor: Initial size but no initialization Dim sampleArray( ) As Integer = New Integer(6) {} 'Implicit constructor: Initial size implied by initialization Dim sampleArray( ) As Integer = {1, 2, 3, 4, 5, 6, 7} 'Explicit constructor, Initial size and initialization Dim sampleArray( ) As Integer = New Integer(6) {1, 2, 3, 4, 5, 6, 7}
To declare a multidimensional array, use one of the following sample templates: ' Two-dimensional array of unknown size Dim sampleArray(,) As Integer ' Two-dimensional array of unknown size Dim sampleArray(,) As Integer = New Integer(,) {} ' Two-dimensional array of size 3 by 2 Dim sampleArray(3, 2) As Integer ' Two-dimensional array of size 3 by 2 Dim sampleArray(,) As Integer = New Integer(3, 2) {} ' Two-dimensional array of size 3 by 2, initialized Dim sampleArray(,) As Integer = {{1, 4}, {2, 5}, {3, 6}} ' Two-dimensional array of size 3 by 2, initialized Dim sampleArray(,) As Integer = _ New Integer(3, 2) {{1, 4}, {2, 5}, {3, 6}}
There is no limit to the number of object variables that can refer to the same instance using the WithEvents keyword; they will all respond to that object's events. Using Option Explicit On requires that each variable used in your code have a declaration. Enforcing this requirement can greatly reduce potential errors in your code. Static variables retain their value between calls to the procedure in which they are declared, although a Static variable's scope is limited to the procedure in which it is created. A static variable's initial value is set by expression. This initial assignment only occurs when the variable is first created as part of the object instance creation process. A type's constructor is called when you use the New keyword on a declaration. You may include constructor parameters after type. If no parameters are supplied, the default parameterless constructor is used. If you attempt to iterate an array (such as with the For Each...Next statement) that has not yet been dimensioned, an error occurs.
Version Differences There are some syntax and functionality differences between the VB 6 and the .NET versions of the Dim statement. In VB 6, all variables that do not specifying a data type are of type Variant. In .NET, such variables are of type Object. When multiple variables are declared in a single Dim statement in VB 6, variables without a specific data type are cast as Variant. In .NET, such variables are assigned to the data type of the next variable (in the same statement) that has a declared data type. .NET adds the ability to assign an initial value to a variable in the Dim statement. In VB 6, all variables defined within a procedure have procedure-level scope. In .NET, variables defined in code blocks (such as loops) have block-level scope. VB 6 supports fixed-length strings; .NET does not include this feature. In VB 6, arrays could be either fixed-length or dynamic. In .NET, all arrays are dynamic. VB 6 allows you to set the lower bound of an array dimension to a nonzero value. The lower bound of all .NET array dimensions is zero. In VB 6, it was possible to define a procedure as Static; all variables within a Static procedure would be Static. In .NET, the use of the Static keyword with Function or Sub statements is not supported.
See Also Private Keyword, Public Keyword, ReDim Statement, Static Statement, WithEvents Keyword |
