# Compaq BASIC for OpenVMS
Alpha and VAX Systems
Reference Manual

Previous | Contents | Index

    MOVE FROM #4%, RUNS%, HITS%, ERRORS%, RBI%, BAT_AVERAGE

    MOVE TO #9%, FILL$ = 10%, A$ = 10%, B$ = 30%, C$ = 2%

# NAME...AS

> The NAME...AS statement renames the specified file.

## Format

## Syntax Rules

1. File-spec1 and file-spec2 must be string expressions.
2. There is no default file type in file-spec1 or file-spec2. If the file to be renamed has a file type, file-spec1 must include both the file name and the file type.
3. If you specify only a file name, BASIC searches for a file with no file type. If you do not specify a file type for file-spec2, BASIC names the file, but does not assign a file type.
4. File-spec2 can include a directory name but not a device name. If you specify a directory name with file-spec2, the file will be placed in the specified directory. If you do not specify a directory name, the default is the current directory.
5. File version numbers are optional. BASIC renames the highest version of file-spec1 if you do not specify a version number.

## Remarks

1. If the file specified by file-spec1 does not exist, BASIC signals "Can't find file or account" (ERR=5).
2. If you use the NAME...AS statement on an open file, BASIC does not rename the file until it is closed.
3. You cannot use the NAME...AS statement to move a file between devices. You can only change the directory, name, type, or version number.

## Example

    $ Directory USER$$DISK:[BASIC_PROG]
    Directory USER$$DISK:[BASIC_PROG]

    FIRST_PROG.BAS;1
    Total of 1 file.
    $ BASIC

    BASIC V3.4
    Ready

    NAME "FIRST_PROG.BAS" AS "SECOND_PROG.BAS"
    Ready

    EXIT

    $ Directory USER$$DISK:[BASIC_PROG]

    Directory USER$$DISK:[BASIC_PROG]

    SECOND_PROG.BAS;1

    Total of 1 file.

# NEXT

> The NEXT statement marks the end of a FOR, UNTIL, or WHILE loop.

## Format

## Syntax Rules

1. Num-unsubs-var is required in a FOR...NEXT loop and must correspond to the num-unsubs-var specified in the FOR statement.
2. Num-unsubs-var is not allowed in an UNTIL or WHILE loop.
3. Num-unsubs-var must be a numeric, unsubscripted variable.

## Remarks

Each NEXT statement must have a corresponding FOR, UNTIL, or WHILE statement or BASIC signals an error.

## Example

    PROGRAM calculating_pay
    DECLARE INTEGER no_hours, &
            SINGLE weekly_pay, minimum_wage
    minimum_wage = 3.65
    no_hours = 40
    WHILE no_hours > 0
      INPUT "Enter the number of hours you intend to work this week";no_hours
      weekly_pay = no_hours * minimum_wage
      PRINT "If you worked";no_hours;"hours, your pay would be";weekly_pay
    NEXT
    END PROGRAM

Output

    Enter the number of hours you intend to work this week? 35
    If you worked 35 hours, your pay would be 127.75
    Enter the number of hours you intend to work this week? 23
    If you worked 23 hours, your pay would be 83.95
    Enter the number of hours you intend to work this week? 0
    If you worked 0 hours your pay would be 0

# NOECHO

> The NOECHO function disables echoing of input on a terminal.

## Format

## Syntax Rules

Chnl-exp must specify a terminal.

## Remarks

1. If you specify NOECHO, BASIC accepts characters typed on the terminal as input, but the characters do not echo on the terminal.
2. The NOECHO function is the complement of the ECHO function; NOECHO disables the effect of ECHO and vice versa.
3. NOECHO always returns a value of zero.

## Example

    DECLARE INTEGER Y,      &
            STRING pass_word
    Y = NOECHO(0)
    INPUT "Enter your password";pass_word
    IF pass_word = "DARLENE" THEN PRINT "Confirmed"
    Y = ECHO(0)

Output

    Enter your password?
    Confirmed

# NOMARGIN

> The NOMARGIN statement removes the right margin limit set with the MARGIN statement for a terminal or a terminal-format file.

## Format

## Syntax Rules

Chnl-exp is a numeric expression that specifies a channel number associated with a file. It must be immediately preceded by a number sign (#).

## Remarks

1. When you specify NOMARGIN, the right margin is set to 132.
2. Chnl-exp, if specified, must be an open terminal-format file or a terminal.
3. If you do not specify a channel, BASIC sets the margin on the controlling terminal to 132.
4. The NOMARGIN statement applies to the specified channel only while the channel is open. If you close the channel and then reopen it, BASIC uses the default margin of 72.

## Example

    OPEN "EMP.DAT" FOR OUTPUT AS #1
    NOMARGIN #1
       .
       .
       .

# NUM

> The NUM function returns the row number of the last data element transferred into an array by a MAT I/O statement.

## Format

## Syntax Rules

None

## Remarks

1. NUM returns a value of zero if it is invoked before BASIC has executed any MAT I/O statements.
2. For a two-dimensional array, NUM returns an integer specifying the row number of the last data element transferred into the array. For a one-dimensional array, NUM returns the number of elements entered.
3. The value returned by the NUM function is an integer of the default size.

## Example

    OPEN "STU_ACCT" FOR INPUT AS #2
    DIM stu_rec$(3,3)
    MAT INPUT #2, stu_rec$
    PRINT "Row count =";NUM
    PRINT "Column number =";NUM2

Output

    Row count = 1
    Column number = 1

# NUM2

> The NUM2 function returns the column number of the last data element transferred into an array by a MAT I/O statement.

## Format

## Syntax Rules

None

## Remarks

1. NUM2 returns a value of zero if it is invoked before BASIC has executed any MAT I/O statements or if the last array element transferred was in a one-dimensional list.
2. The NUM2 function returns an integer specifying the column number of the last data element transferred into an array.
3. The value returned by the NUM2 function is an integer of the default size.

## Example

    OPEN "STU_ACCT" FOR INPUT AS #2
    DIM stu_rec$(3,3)
    MAT INPUT #2, stu_rec$
    PRINT "Row count =";NUM
    PRINT "Column number =";NUM2

Output

    Row count = 1
    Column number = 1

# NUM$

> The NUM$ function evaluates a numeric expression and returns a string of characters in PRINT statement format, with leading and trailing spaces.

## Format

## Syntax Rules

None

## Remarks

1. If num-exp is positive, the first character in the string expression is a space. If num-exp is negative, the first character is a minus sign (-).
2. The NUM$ function does not include trailing zeros in the returned string. If all digits to the right of the decimal point are zeros, NUM$ omits the decimal point as well.
3. When num-exp is a floating-point variable and has an integer portion of 6 decimal digits or less (for example, 1234.567), BASIC rounds the number to 6 digits (1234.57). If num-exp has 7 decimal digits or more, BASIC rounds the number to 6 digits and prints it in E format.
4. When num-exp is from 0.1 to 1 and contains more than 6 digits, BASIC rounds it to 6 digits. When num-exp is smaller than 0.1, BASIC rounds it to 6 digits and prints it in E format.
5. If num-exp is an integer variable, the maximum number of digits in the returned string is as follows, depending on the data type of num-exp:

   Type | Maximum Digits
   --- | ---
   Byte | 3
   Word | 5
   Longword | 10
   Quadword | 19

6. If num-exp is a DECIMAL value, the returned string can have up to 31 digits.
7. The last character in the returned string is a space.

## Example

    DECLARE STRING number
    number = NUM$(34.5500/31.8)
    PRINT number

Output

     1.08648

# NUM1$

> The NUM1$ function changes a numeric expression to a numeric character string without leading and trailing spaces and without rounding.

## Format

## Syntax Rules

None

## Remarks

1. The NUM1$ function returns a string consisting of numeric characters and a decimal point that corresponds to the value of num-exp. Leading and trailing spaces are not included in the returned string.
2. The NUM1$ function returns a maximum of the following number of significant digits:
   - 3 for BYTE integers
   - 5 for WORD integers
   - 6 for SINGLE and SFLOAT floating-point numbers
   - 10 for LONG integers
   - 19 for QUAD integers
   - 16 for DOUBLE floating-point numbers
   - 15 for GFLOAT and TFLOAT floating-point numbers
   - 33 for HFLOAT and XFLOAT floating-point numbers
   - 31 for DECIMAL numbers
     Alpha BASIC does not support HFLOAT. VAX BASIC does not support SFLOAT, TFLOAT, XFLOAT, and QUAD.
3. The returned string does not use E-format notation.

## Example

    DECLARE STRING number
    number = NUM1$(PI/2)
    PRINT number

Output

    1.5708

# ON ERROR GO BACK

> Under certain conditions, an ON ERROR GO BACK statement executed in a subprogram or DEF function transfers control to the calling program.

Note The ON ERROR GO BACK statement is supported for compatibility with other versions of BASIC. For new program development, it is recommended that you use WHEN blocks.

## Format

## Syntax Rules

The ON ERROR GO BACK statement is illegal inside a protected region or within an attached or detached handler. Use the EXIT HANDLER statement instead.

## Remarks

1. If there is no error outstanding, execution of an ON ERROR GO BACK statement causes subsequent errors to return control to the calling program's error handler.
2. If there is an error outstanding, execution of an ON ERROR GO BACK statement immediately transfers control to the calling program's error handler.
3. By default, DEF functions and subprograms resignal errors to the calling program.
4. The ON ERROR GO BACK statement remains in effect until the program unit completes execution, until BASIC executes another ON ERROR statement, or until BASIC enters a protected region.
5. An ON ERROR GO BACK statement executed in the main program is equivalent to an ON ERROR GOTO 0 statement.
6. If a main program calls a subprogram named SUB1, and SUB1 calls the subprogram named SUB2, an ON ERROR GO BACK statement executed in SUB2 transfers control to SUB1's error handler when an error occurs in SUB2. If SUB1 also has executed an ON ERROR GO BACK statement, BASIC transfers control to the main program's error handling routine.
7. For current program development, see the WHEN ERROR statement.
8. It is not recommended that you mix ON ERROR statements with protected regions in the same program unit. For more information, see the Compaq BASIC for OpenVMS Alpha and VAX Systems User Manual.

## Example

    IF ERR = 11
       THEN
            RESUME err_hand
       ELSE
            ON ERROR GO BACK
    END IF

# ON ERROR GOTO

> The ON ERROR GOTO statement transfers program control to a specified line or label in the current program unit when an error occurs under certain conditions.

Note The ON ERROR GOTO statement is supported for compatibility with other versions of BASIC. For new program development, it is recommended that you use WHEN blocks.

## Format

## Syntax Rules

1. You cannot specify an ON ERROR GOTO statement within a protected region or handler.
2. Target must be a valid BASIC line number or label and must exist in the same program unit as the ON ERROR GOTO statement.
3. If an ON ERROR GOTO statement is in a DEF function, target must also be in that function definition.

## Remarks

1. BASIC transfers program control to a specified line number or label under two conditions:
   - If an error occurred outside a protected region of a WHEN block
   - If an error occurred within the protected region of a WHEN block and was propagated by the handler associated with the WHEN block
2. Execution of an ON ERROR GOTO statement causes subsequent errors to transfer control to the specified target.
3. The ON ERROR GOTO statement remains in effect until the program unit completes execution or until BASIC executes another ON ERROR statement.
4. BASIC does not allow recursive error handling. If a second error occurs during execution of an error-handling routine, control passes to the BASIC error handler and the program stops executing.
5. For current program development, see the WHEN ERROR statement.
6. It is not recommended that you mix ON ERROR statements with protected regions within the same program unit. For more information, see the Compaq BASIC for OpenVMS Alpha and VAX Systems User Manual.

## Example

    SUB LIST (STRING A)
    DECLARE STRING B
    ON ERROR GOTO err_block
    OPEN A FOR INPUT AS FILE #1
    Input_loop:
       LINPUT #1, B
       PRINT B
       .
       .
       .
       GOTO Input_loop
    err_block:
       IF (ERR=11%)
       THEN
          CLOSE #1%
          RESUME done
       ELSE
          ON ERROR GOTO 0
       END IF
    done:
    END SUB

# ON ERROR GOTO 0

> The ON ERROR GOTO 0 statement disables ON ERROR error handling and passes control to the BASIC error handler when an error occurs.

Note The ON ERROR GOTO 0 statement is supported for compatibility with other versions of BASIC. For new program development, it is recommended that you use WHEN blocks.

## Format

## Syntax Rules

BASIC does not allow you to specify an ON ERROR GOTO 0 statement within an attached or detached handler or within a protected region.

## Remarks

1. If an error is outstanding, execution of an ON ERROR GOTO 0 statement immediately transfers control to the BASIC error handler. The BASIC error handler will report the error and exit the program.
2. If there is no error outstanding, execution of an ON ERROR GOTO 0 statement causes subsequent errors to transfer control to the BASIC error handler.
3. When an ON ERROR GOTO 0 statement is executed, control is transferred to the BASIC error handler if an error occurred outside a protected region of a WHEN block.
4. If an error occurs within the protected region of a WHEN block and was propagated by the handler associated with the WHEN block, BASIC transfers control to the specified line number or label contained in the subprogram or DEF.
5. For current program development, see the WHEN ERROR statement.
6. It is not recommended that you mix ON ERROR statements with attached or detached handlers within the same program unit. For more information, see the Compaq BASIC for OpenVMS Alpha and VAX Systems User Manual.

## Example

    ON ERROR GOTO err_routine
    FOR I = 1% TO 10%
        PRINT "Please type a number"
        INPUT A
    NEXT I
    err_routine:
    IF ERR = 50
       THEN
          RESUME
       ELSE
          ON ERROR GOTO 0
    END IF

Output

    Please type a number
    ? Ctrl/Z

    %BAS-F-ILLUSADEV, Illegal usage for device
    -BAS-I-ON_CHAFIL, on channel 0 for file SYS$INPUT:[TUTTI]SYSINPUT.DAT;
                                                      at user PC 00000632
    -RMS-F-DEV, error in device name or inappropriate device type for operation
    -BAS-I-FROLINMOD, from line 10 in module BADUSER

# ON...GOSUB

> The ON...GOSUB statement transfers program control to one of several subroutines, depending on the value of a control expression.

## Format

## Syntax Rules

1. Int-exp determines which target BASIC selects as the GOSUB argument. If int-exp equals 1, BASIC selects the first target. If int-exp equals 2, BASIC selects the second target, and so on.
2. Target must be a valid BASIC line number or label and must exist in the current program unit.

## Remarks

1. Control cannot be transferred into a statement block (such as FOR...NEXT, UNTIL...NEXT, WHILE...NEXT, DEF...END DEF, SELECT...END SELECT, WHEN...END WHEN, or HANDLER...END HANDLER).
2. If there is an OTHERWISE clause, and if int-exp is less than 1 or greater than the number of targets in the list, BASIC selects the target of the OTHERWISE clause.
3. If there is no OTHERWISE clause, and if int-exp is less than 1 or greater than the number of targets in the list, BASIC signals "ON statement out of range" (ERR=58).
4. If a target specifies a nonexecutable statement, BASIC transfers control to the first executable statement that lexically follows the target.
5. You can only use the ON...GOSUB statement inside a handler if all the targets are contained within the handler.
6. If you fail to handle an exception that occurs while an ON...GOSUB statement in the body of a subroutine is executing, the exception is handled by the default error handler. The exception is not handled by any WHEN block surrounding the ON...GOSUB statement that invoked the subroutine.
7. You can specify the ON...GOSUB statement inside a WHEN block if the ON...GOSUB target is in the same protected region, an outer protected region, or in a nonprotected region.
8. You cannot specify an ON...GOSUB statement inside a WHEN block if the ON...GOSUB target already resides in another protected region that does not contain the most current protected region.
9. The target cannot be more than 32,767 bytes away from the ON...GOSUB statement.

## Example

    100    INPUT "Please enter 1, 2 or 3"; A%
           ON A% GOSUB 1000, 2000, 3000 OTHERWISE err_routine
           GOTO done

    1000   PRINT "That was a 1"
           RETURN
    2000   PRINT "That was a 2"
           RETURN
    3000   PRINT "That was a 3"
           RETURN

        err_routine:
           PRINT "Out of range:
           RETURN
        done:
           END PROGRAM

Previous | Next | Contents | Index