Q(uick)BASIC Statement: DIM

Quick View

DIM

A declaration statement that names one or more variables and allocates storage space for them

Worth knowing

Useful and cross-version information about the programming environments of QBasic and QuickBasic.

Syntax
  • DIM [SHARED] variable[(subscripts)] [AS type] [,variable[(subscripts)] [AS type]]…
  • REDIM [SHARED] variable(subscripts) [AS type] [,variable(subscripts) [AS type]]…
Description/Parameter(s)
SHARED Specifies that variables are shared with all SUB or FUNCTION procedures in the module.
variable The name of an array or variable.
subscripts Dimensions of the array, expressed as follows:
[lower TO] upper [,[lower TO] upper]…
lowerThe lower bound of the array's subscripts. The default lower bound is zero.
upperThe upper bound.
AS type Declares the data type of the array or variable (INTEGER, LONG, SINGLE, DOUBLE, STRING, or a user-defined data type).
  • DIM declares either static or dynamic arrays. Unless array storage has been determined by $STATIC, $DYNAMIC, or COMMON, arrays dimensioned with numbers are static and arrays dimensioned with variables are dynamic. REDIM always declares dynamic arrays.
  • Static array storage is allocated when you start a program and remains fixed. Dynamic array storage is allocated while a program runs.
Example
' $DYNAMIC DIM A(49, 49) REDIM A(19, 14)

See also:

Syntax
  • DIM [SHARED] variable[(subscripts)][AS type] [,variable[(subscripts)][AS type]…
Description/Parameter(s)
Argument Description
SHARED The optional SHARED attribute allows all procedures in a module to share arrays and simple variables. This differs from the SHARED statement, which affects only variables within a single SUB or FUNCTION.
variable A BASIC variable name.
subscripts The dimensions of the array. Multiple dimensions can be declared. The subscript syntax is described below.
AS type Declares variable to be an elementary or user-defined type. The elementary types are INTEGER, LONG, SINGLE, DOUBLE, and STRING (variable or fixed).

Subscripts in DIM statements have the following form:

  • [lower TO] upper [,[lower TO] upper]…

The TO keyword provides a way to indicate both the lower and the upper bounds of an array's subscripts. The following statements are equivalent (if there is no OPTION BASE statement):

  • DIM A(8,3)
  • DIM A(0 TO 8, 0 TO 3)
  • DIM A(8,0 TO 3)

With the TO keyword, you are no longer restricted to positive subscripts. You can use TO to specify any range of subscripts from -32,768 to 32,767:

  • DIM A(-4 TO 10)
  • DIM B(-99 TO -5,-3 TO 0)

If you use an array in your program without including the array in a DIM statement, the maximum value of each subscript of the array is 10. If you use a subscript that is greater than the specified maximum, an error message appears that says "Subscript out of range."

The DIM statement initializes all elements of numeric arrays to zero and all the elements of string arrays to null strings. The fields of record variables are initialized to zero, including fixed-string fields. The maximum number of dimensions allowed in a DIM statement is 60.

If you try to dimension an array variable with a DIM statement after you have referred to the array, an error message results that reads "Array already dimensioned." It is good programming practice to put the required DIM statements at the beginning of a program, outside of any loops.

Static and Dynamic ArraysHow you declare an array also determines whether it is $STATIC (allocated when the program is translated) or $DYNAMIC (allocated when the program is run).

  • An array declared first in a COMMON statement is $DYNAMIC.
  • Implicitly dimensioned arrays are $STATIC.
  • Arrays dimensioned with numeric constants or CONST statement constants are $STATIC.
  • Arrays dimensioned with variables as subscripts are $DYNAMIC.

The following list shows the different combinations and results:

Statement Result
DIM A(0 TO 9) The array A is allocated as a $STATIC array if $DYNAMIC is not in effect.
DIM A(MAXDIM) If MAXDIM is defined in a CONST statement A is a $STATIC array. If MAXDIM is a variable, then the array is a $DYNAMIC array and is only allocated when the program reaches the DIM statement.
Note: If the array size exceeds 64K, if the array is not dynamic, and if the /AH option was not used, you may get an error message that reads "Subscript out of range" or one that reads "Array too big." Reduce the size of the array or make the array dynamic and use the /AH command-line option.

Type DeclarationsIn addition to declaring the dimensions of an array, the DIM statement may also be used to declare the type of a variable. For example, the following statement declares the variable to be an integer, even though there is no type declaration character or DEFINT statement:

  • DIM NumberOfBytes AS INTEGER

The DIM statement provides a mechanism for declaring specific variables to be records. In the following example, the variable TopCard is declared as a record variable:

  • TYPE Card
  •   Suit AS STRING * 9
  •   Value AS INTEGER
  • END TYPE
  • DIM TopCard AS Card

You may also declare arrays of records:

  • TYPE Card
  •   Suit AS STRING * 9
  •   Value AS INTEGER
  • END TYPE
  • DIM Deck(1 TO 52) AS Card

Differences from BASICA

  • BASICA executes a DIM statement when it encounters the statement in the program. The array is only allocated when the statement is executed, so all arrays in BASICA are dynamic.
Example

The following example finds and prints the maximum and minimum of a set of values:

' Find the maximum and minimum of up to 20 values. ' ' Dimension an array to hold the values. CONST MAXDIM=20 DIM A(1 TO MAXDIM) ' Use DIM to set up two integer variables. ' All other variables are SINGLE. DIM NumValues AS INTEGER, I AS INTEGER ' Get the values. NumValues=0 PRINT "Enter values one per line. Type END to end." DO INPUT A$ IF UCASE$(A$)="END" OR NumValues>=MAXDIM THEN EXIT DO NumValues=NumValues+1 A(NumValues)=VAL(A$) LOOP ' Find the maximum and minimum values. IF NumValues>0 THEN Max=A(1) Min=A(1) FOR I=1 TO NumValues IF A(I)>Max THEN Max=A(I) IF A(I)<Min THEN Min=A(I) NEXT I PRINT "The maximum is ";Max;" The minimum is ";Min ELSE PRINT "Too few values." END IF

Sample Output:

Enter values one per line. Type END to end. ? 23.2 ? 11.3 ? 1.6 ? end The maximum is 23.2 The minimum is 1.6

See also:

Syntax
  • DIM [SHARED] variable[(subscripts)] [AS type] [,variable[(subscripts)] [AS type]]…
Description/Parameter(s)
  • SHARED differs from the SHARED statement, which affects only variables within a single SUB or FUNCTION procedure.
  • The subscripts are the dimensions of the array. Multiple dimensions can be declared. The subscript syntax is:

  • [lower TO] upper [,[lower TO] upper]…
lower TO upper Indicates the lower and the upper bounds of an array's subscripts.
  • The following statements are equivalent (if there is no OPTION BASE statement):

  • DIM A(8, 3)
  • DIM A(0 TO 8, 0 TO 3)
  • DIM A(8, 0 TO 3)

  • Subscripts can be negative. TO can be used to specify any range of subscripts from -32,768 to 32,767:

  • DIM A(-4 TO 10)
  • DIM B(-99 TO -5, -3 TO 0)

  • If you use an implicitly dimensioned array in your program (that is, an array that has not been declared with a DIM or COMMON statement), the maximum value of each subscript of the array is 10. If you use a subscript that is greater than the specified maximum and if run-time error checking is in effect, BASIC generates the error message, "Subscript out of range." Run-time error checking is in effect, when:
    • You run a program from the QBX environment.
    • You have created an .EXE file from the QBX environment and selected the Run-Time Error Checking option in the Make EXE File dialog box.
    • You have compiled your program with BC using the /D switch to select run-time error checking.
  • AS type declares the type of the variable. The type may be INTEGER, LONG, SINGLE, DOUBLE, STRING (for variable-length strings), STRING * length (for fixed-length strings), CURRENCY, or a user- defined type.

Usage Notes

  • The DIM statement initializes all elements of numeric arrays to zero and all the elements of string arrays to null strings. The fields of record variables are initialized to zero, including fixed-string fields. The maximum number of dimensions allowed in a DIM statement is 60.
  • f you try to declare a dimension for an array variable with a DIM statement after you have referred to the array, BASIC generates the error message, "Array already dimensioned." It is good programming practice to put the required DIM statements at the beginning of a program, outside of any loops.

Static and Dynamic Arrays

  • How you declare an array also determines whether it is static (allocated when the program is translated) or dynamic (allocated when the program is run):
How array is declared Allocation
Declared first in a COMMON statement Dynamic
Implicitly dimensioned arrays Static
Dimensioned with numeric constants or CONST statement constants Static
Dimensioned with variables as subscripts Dynamic
  • Examples of different DIM statements and results:
Statement Result
DIM A(0 TO 9) Array A is allocated as a static array if $DYNAMIC is not in effect.
DIM A(MAXDIM) If MAXDIM is defined in a CONST statement, array A is a static array. If MAXDIM is a variable, then the array is a dynamic array and is only allocated when the program reaches the DIM statement.
  • If the array size exceeds 64K, if the array is not dynamic, and if the /AH option was not used, BASIC may generate the error message, "Subscript out of range" or "Array too big." Reduce the size of the array or make the array dynamic and use the /AH command-line option.

TYPE Declarations

  • The DIM statement also can be used to declare the type of a variable. For example, the following statement declares the variable to be an integer, even though there is no-type declaration character or DEFINT Statement:

  • DIM NumberOfBytes AS INTEGER

  • The DIM statement provides a way to declare specific variables to be records. In the following example, the variable TopCard is declared as a record variable:

  • TYPE Card
  •   Suit AS STRING * 9
  •   Value AS INTEGER
  • END TYPE
  • DIM TopCard AS Card

  • You also can declare arrays of records:

  • TYPE Card
  •   Suit AS STRING * 9
  •   Value AS INTEGER
  • END TYPE
  • DIM Deck(1 TO 52) AS Card

Difference from BASICA

  • BASICA executes a DIM statement when it encounters the statement in the program. The array is allocated only when the statement is executed, so all arrays in BASICA are dynamic.
Example

This example uses the DIM statement to set the dimensions for an array. The program finds and prints the maximum and minimum of a set of values.

'Dimension an array to hold the values. CONST MAXDIM = 20 DIM A(1 TO MAXDIM) 'Use DIM to set up two integer variables. 'All other variables are single-precision. DIM NumValues AS INTEGER, I AS INTEGER 'Get the values. NumValues = 0 PRINT "Enter values one per line. Type END to end." DO INPUT A$ IF UCASE$(A$) = "END" OR NumValues >= MAXDIM THEN EXIT DO NumValues = NumValues + 1 A(NumValues) = VAL(A$) LOOP 'Find the maximum and minimum values. IF NumValues > 0 THEN Max = A(1) Min = A(1) FOR I = 1 TO NumValues IF A(I) > Max THEN Max = A(I) IF A(I) < Min THEN Min = A(I) NEXT I PRINT "The maximum is "; Max; " The minimum is "; Min ELSE PRINT "Too few values." END IF

Sample Output:

Enter values one per line. Type END to end. ? 23.2 ? 11.3 ? 1.6 ? end The maximum is 23.2 The minimum is 1.6

See also: