The DIMENSION statement creates and names a static, dynamic, or virtual array. The array subscripts determine the dimensions and the size of the array. You can specify the data type of the array and associate the array with an I/O channel.

Format

Syntax Rules

1. An array name in a DIM statement cannot also appear in a COMMON, MAP, or DECLARE statement.
2. Data-type can be any BASIC data type keyword or a data type defined in a RECORD statement. Data type keywords, size, range, and precision are listed in Table 1-2.
3. If you do specify a data type and the array name ends in a percent sign (%) or dollar sign ($) suffix character, the variable must be a string or integer data type.
4. If you do not specify a data type, the array name determines the type of data the array holds. If the array name ends in a percent sign, the array stores integer data of the default integer size. If the array name ends in a dollar sign, the array stores string data. Otherwise, the array stores data of the default type and size.
5. An array can have up to 32 dimensions. Nonvirtual array sizes are limited by the virtual memory limits of your system.
6. When you declare a nonvirtual array, BASIC allows you to specify both lower and upper bounds. The upper bound is required; the lower bound is optional.
   • Int-const1 or int-var1 specifies the lower bounds of the array.
   • Int-const2 or int-var2 specifies the upper bounds of the array and, when accompanied by int-const1 or int-var1, must be preceded by the keyword TO.
   • Int-const1 must be less than or equal to int-const2. Int-var1 must be less than or equal to int-var2.
   • If you do not specify int-const1 or int-var1, BASIC uses zero as the default lower bound.
   • Array dimensions can have either positive or negative values.
7. Nonvirtual, Nonexecutable
   • When all the dimension specifications are integer constants, as in DIM A(15,10,20), the DIM statement is nonexecutable and the array size is static. A static array cannot appear in another DIM statement because BASIC determines storage requirements at compilation time.
   • A nonexecutable DIM statement must lexically precede any reference to the array it dimensions. That is, you must dimension a static array before you can reference array elements.
8. Virtual
   • The virtual array must be dimensioned and the file must be open before you can reference the array.
   • When the data type is STRING, the =int-const clause specifies the length of each array element. The default string length is 16 characters. Virtual string array lengths are rounded to the next higher power of 2. Therefore, specifying an element length of 12 results in an actual length of 16. For example:

     DIM #1, STRING vir_array(100) = 12 OPEN "STATS.BAS" FOR OUTPUT as #1, VIRTUAL

     
     Output

     %BASIC-W-STRLENINC, virtual array string VIR_ARRAY length increased from 12 to 16

9. Executable
   When any of the dimension specifications are integer variables as in DIM A(10%,20%,Y%), the DIM statement is executable and the array is dynamic. A dynamic array can be redimensioned with a DIM statement any number of times because BASIC allocates storage at run time when each DIM statement is executed.

Remarks

1. You can create an array implicitly by referencing an array element without using a DIM statement. This causes BASIC to create an array with dimensions of (10), (10,10), (10,10,10), and so on, depending on the number of bounds specifications in the referenced array element. You cannot create virtual or executable arrays implicitly.
2. BASIC allocates storage for arrays by row, from right to left.
3. Nonvirtual, Nonexecutable
   • You can declare arrays with the COMMON, MAP, and DECLARE statements. Arrays so declared cannot be redimensioned with the DIM statement. Furthermore, string arrays declared with a COMMON or MAP statement are always fixed-length arrays.
   • If you reference an array element declared in an array whose subscripts are smaller than the lower bound or larger than the upper bound specified in the DIM statement, BASIC signals the error "Subscript out of range" (ERR=55).
4. Virtual
   • For new development, using virtual arrays is not recommended.
   • When the rightmost subscript varies faster than the subscripts to the left, fewer disk accesses are necessary to access array elements in virtual arrays.
   • Using the same DIM statement for multiple virtual arrays allocates all arrays in a single disk file. The arrays are stored in the order they were declared.
   • Any program or subprogram can access a virtual array by declaring it in a virtual DIMENSION statement. For example:

     DIM #1, A(10) DIM #1, B(10)

     
     In this example, array B overlays array A. You must specify the same channel number, data types, and limits in the same order as they occur in the DIM statement that created the virtual array.

   • BASIC stores a string in a virtual array by padding it with trailing nulls to the length of the array element. It removes these nulls when it retrieves the string from the virtual array. Remember that string array element sizes are always rounded to the next power of 2.
   • The OPEN statement for a virtual array must include the ORGANIZATION VIRTUAL clause for the channel specified in the DIMENSION statement.
   • BASIC does not initialize virtual arrays and treats them as statically allocated arrays. You cannot redimension virtual arrays.
   • See the Compaq BASIC for OpenVMS Alpha and VAX Systems User Manual for more information about virtual arrays.
5. Executable
   • You create an executable, dynamic array by using integer variables for array bounds, as in DIM A(Y%,X%). This eliminates the need to dimension an array to its largest possible size. Array bounds in an executable DIM statement can be constants or variables, but not expressions. At least one bound must be a variable.
   • You cannot reference an array named in an executable DIM statement until after the DIM statement executes.
   • You can redimension a dynamic array to make the bounds of each dimension larger or smaller, but you cannot change the number of dimensions. For example, you cannot redimension a four-dimensional array to be a five-dimensional array.
   • The executable DIM statement cannot be used to dimension virtual arrays, arrays received as formal parameters, or arrays declared in COMMON, MAP, or nonexecutable DIM statements.
   • An executable DIM statement always reinitializes the array to zero (for numeric arrays) or to the null string if string.
   • If you reference an array element declared in an executable DIM statement whose subscripts are not within the bounds specified in the last execution of the DIM, BASIC signals the error "Subscript out of range" (ERR=55).

Examples

Example 1

!Nonvirtual, Nonexecutable DIM STRING name_list(20 TO 100), BYTE age(100)

Example 2

!Virtual DIM #1%, STRING name_list(500), REAL amount(10,10)

Example 3

!Executable DIM DOUBLE inventory(base,markup) . . . DIM DOUBLE inventory (new_base,new_markup)

The ECHO function causes characters to be echoed at a terminal that is opened on a specified channel.

Format

Syntax Rules

Chnl-exp must specify a terminal.

Remarks

1. The ECHO function is the complement of the NOECHO function; each function disables the effect of the other.
2. The ECHO function has no effect on an unopened channel.
3. The ECHO function always returns a value of zero.

Example

DECLARE INTEGER Y, & STRING pass_word Y = NOECHO(0%) SET NO PROMPT INPUT "Enter your password: ";pass_word Y = ECHO(0%) IF pass_word = "Darlene" THEN PRINT CR+LF+"YOU ARE CORRECT !" END IF

Output

Enter your password? YOU ARE CORRECT !

The EDIT$ function performs one or more string editing functions, depending on the value of its integer argument.

Format

Syntax Rules

None

Remarks

1. BASIC edits str-exp to produce str-var.
2. The editing that BASIC performs depends on the value of int-exp. Table 4-2 describes EDIT$ values and functions.
3. All values are additive; for example, you can perform the editing functions of values 8, 16, and 32 by specifying a value of 56.
4. If you specify a floating-point expression for int-exp, BASIC truncates it to an integer of the default size.

Table 4-2 EDIT$ Values

Value	Edit Performed
1	Discards each character's parity bit (bit 7)
2	Discards all spaces and tabs
4	Discards all carriage returns <CR>, line feeds <LF>, form feeds <FF>, deletes <DEL>, escapes <ESC>, and nulls <NUL>
8	Discards leading spaces and tabs
16	Converts multiple spaces and tabs to a single space
32	Converts lowercase letters to uppercase letters
64	Converts left bracket ([) to left parenthesis [(] and right bracket (]) to right parenthesis [)]
128	Discards trailing spaces and tabs (same as TRM$ function)
256	Suppresses all editing for characters within quotation marks; if the string has only one quotation mark, BASIC suppresses all editing for the characters following the quotation mark

Example

DECLARE STRING old_string, new_string old_string = "a value of 32 converts lowercase letters to uppercase" new_string = EDIT$(old_string,32) PRINT new_string

Output

A VALUE OF 32 CONVERTS LOWERCASE LETTERS TO UPPERCASE

The END statement marks the physical and logical end of a main program, a program module, or a block of statements.

Format

Syntax Rules

None

Remarks

1. The END statement with no block keyword marks the end of a main program. The END or END PROGRAM statement must be the last statement on the last lexical line of the main program.
2. The END statement followed by a block keyword marks the end of a program, a BASIC SUB, FUNCTION, or PICTURE subprogram, a DEF, an IF, a HANDLER, a PROGRAM, a SELECT statement block or a WHEN block.
3. END RECORD, END GROUP, and END VARIANT mark the end of a RECORD statement, or a GROUP component or VARIANT component of a RECORD statement.
4. END DEF and END FUNCTION
   • When BASIC executes an END DEF or an END FUNCTION statement, it returns the function value to the statement that invoked the function and releases all storage associated with the DEF or FUNCTION.
   • If you specify an optional expression with the END DEF or END FUNCTION statement, the expression must be compatible with the DEF or FUNCTION data type. The expression is the function result unless an EXIT DEF or EXIT FUNCTION statement is executed. This expression supersedes all function assignments.
   • The END DEF statement restores the error handler in effect when the DEF was invoked (this is not true of the DEF* statement).
   • The END FUNCTION statement does not affect I/O operations or files.
5. END HANDLER
   The END HANDLER statement causes BASIC to transfer control to the statement following the WHEN block with the exception cleared.
6. END PROGRAM
   • The END PROGRAM statement allows you to end a program module.
   • An optional integer expression specifies the exit status of the program that is reported to DCL. This status is overridden by a status expression in an EXIT PROGRAM statement.
   • You can specify an END PROGRAM statement without a matching PROGRAM statement.
7. END WHEN
   • The END WHEN statement ends a WHEN block and transfers control to the statement following the WHEN block.
   • If the END WHEN statement ends an attached handler, control is transferred to the statement following the WHEN block with the exception cleared.
8. END SUB
   • The END SUB statement does not affect I/O operations or files.
   • The END SUB statement releases the storage allocated to local variables and returns control to the calling program.
   • The END SUB statement cannot be executed in an error handler unless the END SUB is in a subprogram called by the error handler of another routine.
9. When an END or END PROGRAM statement marking the end of a main program executes, BASIC closes all files and releases all program storage.
10. If you use ON ERROR error handling, you must clear any errors with the RESUME statement before executing an END PROGRAM, END SUB, END FUNCTION, or END PICTURE statement.
11. Except for the END PROGRAM statement, BASIC signals an error when a program contains an END block statement with no corresponding and preceding block keyword.

Example

10 INPUT "Guess a number";A% IF A% = 24 THEN PRINT, "YOU GUESSED IT!" END IF IF A% < 24 THEN PRINT, "BIGGER IS BETTER!" GOTO 10 END IF IF A% > 24 THEN PRINT, "SMALLER IS BETTER!" GOTO 10 END IF END PROGRAM

The ERL function returns the number of the BASIC line where the last error occurred.

Format

Syntax Rules

The value of int-var returned by the ERL function is a LONG integer.

Remarks

1. If the ERL function is used before an error occurs or after an error is handled, the results are undefined.
2. The ERL function overrides the /NOLINE qualifier for VAX BASIC.

Example

10 DECLARE LONG int_exp WHEN ERROR USE error_routine 20 INPUT "Enter an integer expression";int_exp 30 PRINT DATE$(int_exp) END WHEN HANDLER error_routine IF ERL = 20 THEN PRINT "Invalid input...try again" RETRY ELSE PRINT "UNEXPECTED ERROR" EXIT HANDLER END IF END HANDLER END PROGRAM

Output

Enter an integer expression? ABCD Error occurred on line 20 Enter an integer expression? 0 07-Feb-00

The ERN$ function returns the name of the main program, subprogram, or DEF function that was executing when the last error occurred.

Format

Syntax Rules

None

Remarks

1. If the ERN$ function executes before an error occurs or after an error is handled, ERN$ returns a null string.
2. If you call a subprogram or function compiled with /NOSETUP or containing an OPTION INACTIVE=SETUP statement, the ERN$ function will not have a valid value if an exception occurs in the called procedure.

Example

10 DECLARE LONG int_exp !This module's name is DATE WHEN ERROR IN INPUT "Enter an number";int_exp USE PRINT "Error in module ";ERN$ RETRY END WHEN PRINT Date$(int_exp) END

Output

Enter a number? ABCD Error in module DATE Enter a number? 0 07-Feb-00

The ERR function returns the error number of the current run-time error.

Format

Syntax Rules

The value of int-var returned by the ERR function is always a LONG integer.

Remarks

If the ERR function is used before an error occurs or after an error is handled, the results are undefined.

Example

10 DECLARE LONG int_exp WHEN ERROR USE error_routine 20 INPUT "Enter an integer expression";int_exp PRINT DATE$(int_exp) END WHEN HANDLER error_routine: PRINT "Error number";ERR IF ERR = 50 THEN PRINT "DATA FORMAT ERROR" ELSE PRINT "UNEXPECTED ERROR" END IF RETRY END HANDLER END

Output

Enter an integer expression? ABCD Error number 50 DATA FORMAT ERROR Enter an integer expression? 0 07-Feb-00

The ERT$ function returns explanatory text associated with an error number.

Format

Syntax Rules

Int-exp is a BASIC error number. The error number should be a valid BASIC error number.

Remarks

1. The ERT$ function can be used at any time to return the text associated with a specified error number.
2. If you specify a floating-point expression for int-exp, BASIC truncates it to an integer of the default size.
3. Any error outside the range of valid BASIC RTL errors results in the following error message: "NOTBASIC, Not a BASIC error" (ERR=194).

Example

10 DECLARE LONG int_exp WHEN ERROR USE error_routine 20 INPUT "Enter an integer expression";int_exp PRINT DATE$(int_exp) END WHEN HANDLER error_routine PRINT "Error number";ERR PRINT ERT$(ERR) RETRY END HANDLER END

Output

Enter an integer expression? ABCD Error number 50 %Data format error Enter an integer expression? 0 07-Feb-00