◄Syntax►  ◄Details►  ◄Example►                 ◄Contents►  ◄Index►  ◄Back►
──────────────────────────────────────────────────────────────────────────────
DIM declares a variable and allocates storage space.
 
DIM [SHARED] variable[(subscripts)] [AS type]
           [,variable[(subscripts)] [AS type]]...
 
    ■ 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.
    ■ If 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          Static
          or CONST statement constants
        ■ 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.