# Compaq BASIC for OpenVMS
Alpha and VAX Systems
Reference Manual

Previous | Contents | Index

# DIMENSION

> 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)

# ECHO

> 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 !

# EDIT$

> 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

# END

> 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

# ERL

> 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

# ERN$

> 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

# ERR

> 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

# ERT$

> 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

Previous | Next | Contents | Index