DIM(stmt)

NAME

dim - specify maximum subscript values for arrays

SYNOPSIS

dim [shared] Var(NumExpr[, NumExpr]. . .)

[, Var(NumExpr[, NumExpr]. . .)]. . .

DESCRIPTION

Dim sets the number of dimensions and the maximum subscript values for each dimension of an array or list of arrays. Var is the name of the array. NumExpr is the maximum subscript value. The varieties of arrays are two: static and dynamic. The maximum subscript values of dynamic arrays may be changed while the program is running. Those of static arrays may not. In neither case, however, may values within an array be preserved while the maximum subscript values are being changed. Nor may the number of dimensions be changed while the program is running. When a dim statement appears (when the program is being compiled), the variety of the array (static or dynamic) is determined. An array is dynamic if the $dynamic metacommand is in effect or any NumExpr for the array is not a constant expression. The $dynamic metacommand is in effect if a $dynamic metacommand has appeared more recently than any $static metacommands (see $dynamic and $static). A constant expression is any numeric expression consisting entirely of constants and operators except for function calls and exponentiation. The details of the behavior of the dim statement differ for static and dynamic arrays.

If the array is determined to be static, its number of dimensions and maximum subscript values are fixed and may not be changed. Space for the array is allocated.

If the array is determined to be dynamic, only its number of dimensions is fixed and may not be changed. The dim statement is an executable statement: when the statement is executed while the program is running, the maximum subscript expressions are evaluated, the maximum subscript values are fixed and space for the array is allocated. A dynamic array may be dimensioned more than once provided it is erased in the interim (see erase). The elements of a dynamic array may not be used before the initial dim statement is executed and while it is erased. An array which is a formal parameter to a subprogram may not be dimensioned.

In the absence of an explicit dim statement for an array, the array is assumed to be static with as many dimensions as there are subscripts in its first reference and with 10 as the maximum value for each subscript.

The minimum subscript value for all arrays in a program is specified by the option base statement and may be either zero or one. The default minimum value is zero.

By default, an array that appears within a subprogram is different from an array with the same name and type outside that subprogram. That is, the scope of the array does not include the subprogram. If the word shared is used in the dim statement, the scope of an array so declared includes the subprograms of the module. Nevertheless, within any particular subprogram, this declaration of the array may be nullified and the default restored by a static declaration (see static) or by a declaration as a formal parameter. This version of the dim statement may not be used within a user defined function or subprogram.

EXAMPLE

The program

	dim n(12 + 1), a$(3, 3)
	data 13.2, 24, 2, 63, 70, 6.3, 50
	data 3, 42, 70, 42, 3, 89
	for i = 0 to 12
		read n(i)
	next i
	data JONES, JOHN, PAUL
	data "AKRON, OHIO", CANTON, TOLEDO
	data CLEVELAND, COLUMBUS, CINCINNATI
	for i = 0 to 2 : for j = 0 to 2
		read a$(i, j)
	next j, i
	print n(3); a$(2, 0)

produces

	 63 CLEVELAND

This example dimensions two arrays: a one-dimensional numeric array named n with 13 elements, n(0) through n(12), and a two-dimensional string array named a$, with three rows and three columns.

The following program fragment reads from a file the length of a list which is used to allocate a dynamic array. The list of coordinate pairs is read from the file and stored in the array.

	open "coordinates" for input as #1
	input #1, n
	dim xy(n, 2)
	for i = 1 to n
		input #1, xy(n, 1), xy(n, 2)
	next i
	close #1

DIAGNOSTICS

If an attempt is made to dimension a dynamic array that is already dimensioned, an "Illegal function call" error occurs.

If the value of a subscript is greater than the maximum allowed or less than the minimum allowed, a "Subscript out of range" error occurs.

USAGE NOTES

Subscript range checking can be disabled by compiling with the "-C" option.