dim statement

	<< Index >>	FutureBasic 5
dim		statement

Syntax:
dim as userType declaration1 [,declaration2...]
dim as predefinedType declaration1 [,declaration2...]
dim varName as userType
dim varName as predefinedType

Description:
dim is a non-executable statement that allows the compiler to determine how much storage space should be allocated for the declared variables, arrays and record fields, and identifies their data types. dim can also be used to affect the relative storage locations of the declared variables, arrays and fields. The basic syntax is the same for dims within a record and outside a record. There are some exceptions such as arrays inside records, see help for begin record.
A declaration can have any of the following forms:
Simple variables:

   {varName | [maxLen] stringVar$}

   untypedVar as predefinedType

   untypedVar as userType

Records:

   untypedVar as recordType

   untypedVar.constant2

Arrays:

   varName | [maxLen] stringVar$}(maxSub1[,maxSub2...])

   untypedVar (maxSub1 [,maxSub2...]) as predefinedType 

   untypedVar (maxSub1 [,maxSub2...]) as userType

   untypedVar.constant2 (maxSub1 [,maxSub2...])

Pointers:
   untypedVar as {pointer to|^|@|.}{predefinedType|recordType}
Handles
   untypedVar as {Handle to|^^|@@|..}{predefinedType|recordType}
Memory alignment declarations:
  {%|&|&&|&&&|.constant}

maxLen, maxSub1, maxSub2 and statExpr are (non-negative) static integer expressions.
constant is a (non-negative) literal integer or a symbolic constant; but if a symbolic constant is used, its initial underscore character is omitted.
stringVar$ is a variable name that ends with a "$" type-identifier suffix.
varName is a variable name that may optionally end with a type-identifier suffix.
untypedVar is a variable name that does not end with a type-identifier suffix.
userType is a type name defined in a previous begin record statement or #define statement.
recordType is a type name defined in a previous begin record statement.
predefinedType is one of the following: char, [unsigned] byte, [unsigned] word, [unsigned] short, [unsigned] int, UInt16, SInt16, [unsigned] long, UInt32, SInt32, UInt64, SInt64, Rect, Handle, RgnHandle, Str255, Str63, Str31, Str15, double, single.

If a dim statement appears within a begin globals...end globals block, then the scope of the declared variables and arrays is global. If it appears within the scope of a local function (but not within a begin globals...end globals block), then the scope of the declared variables and arrays is local to that function or procedure block. If dim appears outside of all local functions and procedure blocks (and outside of any begin globals...end globals block), then the scope of the declared variables and arrays is local to "main."

Your program can use as many dim statements as you like. The following statement:
dim a, b&, c$, d#
is equivalent to this pair of statements:

dim a, b&

dim c$, d#

Certain structures must always be declared in a dim statement, which must appear somewhere above the first line where the structure is used. These structures include:

Arrays (unless declared in an xref or xref@ statement)
Record variables
Variables of user-defined types
Pointer variables and Handle variables

Storage space for FutureBasic's built-in types is allocated as follows:

byte integers (`, ``), `byte`, `char`, `Boolean`	1 byte
short integers (`%`, %`), `short`, `int`, `SInt16`, `UInt16`	2 bytes
long integers (`&`, &`), `long`, `SInt32`, `UInt32`	4 bytes
long long integers `SInt64, UInt64`	8 bytes
`Point`	4 bytes
single precision (`!`), `single`	4 bytes
double precision (`#`), `double`	8 bytes
`Rect`	8 bytes
`Str255`	256 bytes
`pointer`	4 bytes
`Handle`	4 bytes

(Note: the storage space for variables can vary between CPU devices. When in doubt, use the sizeof function to make a definite determination of the size of the variable.)
The storage space allocated for a string variable depends on the value of the maxLen parameter (which cannot exceed 255). If maxLen is omitted, then the most recent maxLen specified in the same dim statement is used. String variables declared using the as Str255 clause always have a maxLen value of 255.
Once maxLen has been determined for a given string variable, the actual number of bytes allocated for the variable is:

maxLen + 1 bytes, if maxLen is odd;
maxLen + 2 bytes, if maxLen is even;

Your program should not assign a string longer than maxLen characters to a string variable. The storage space for a record variable equals the sum of the lengths of the record's fields, or the value of constant2 (in bytes).

Storage space for an array is calculated as follows: If elSize is the size in bytes of a single array element, then the space allocated for the entire array is given by the following expression:
array size = elSize * (maxSub1 + 1) * (maxSub2 + 1) * ...
All the elements in an array are stored in contiguous locations in memory. If the array is multi-demensional, then the rightmost dimensions change most rapidly as you step through the elements' locations in memory. For example, if you declare an array as follows:
dim p%(3, 2)
Then the elements of p%() are stored in this order in memory:

p%(0,0)

p%(0,1)

p%(0,2)

p%(1,0)
p%(1,1)
p%(1,2)
p%(2,0)
p%(2,1)
p%(2,2)
p%(3,0)
p%(3,1)
p%(3,2)

Aliased variables
Aliased variables are no longer supported. For example, the following syntax cannot be used:
dim as int;0, hi as byte, lo as byte

See Also:
begin globals...end globals; dim record; begin record...end record