# Compaq BASIC for OpenVMS
Alpha and VAX Systems
Reference Manual

Previous | Contents | Index

       DECLARE LONG rec-num
       MAP (CUSREC) WORD cus_num                                              &
               STRING cus_nam = 20, cus_add = 20, cus_city = 10, cus_zip = 9
       OPEN "CUS_ACCT.DAT" FOR INPUT AS  #1                                   &
             RELATIVE FIXED, ACCESS MODIFY,                                   &
             MAP CUSREC
       INPUT "Which record number would you like to view";rec_num
       GET #1, RECORD REC_NUM, REGARDLESS
       PRINT "The customer's number is ";CUS_NUM
       PRINT "The customer's name is ";cus_nam
       PRINT "The customer's address is ";cus_add
       PRINT "The customer's city is ";cus_city
       PRINT "The customer's zip code is ";cus_zip
       CLOSE #1
       END

# GETRFA

> The GETRFA function returns the record's file address (RFA) of the last record accessed in an RMS file open on a specified channel.

## Format

## Syntax Rules

1. Rfa-var is a variable of the RFA data type.
2. Chnl-exp is the channel number of an open RMS file. You cannot include a number sign in the channel expression.
3. You must access a record in the file with a GET, FIND, or PUT statement before using the GETRFA function, or BASIC signals "No current record" (ERR=131).

## Remarks

1. There must be a file open on the specified chnl-exp or BASIC signals an error.
2. You can use the GETRFA function with RMS sequential, relative, indexed, and block I/O files.
3. The RFA value returned by the GETRFA function can be used only for assignments to and comparisons with other variables of the RFA data type. Comparisons are limited to equal to (=) and not equal to (<>) relational operations.
4. RFA values cannot be printed or used for any arithmetic operations.
5. If you open a file without specifying a file organization (sequential, relative, virtual, or indexed), BASIC defaults to terminal-format. See the Compaq BASIC for OpenVMS Alpha and VAX Systems User Manual for more information.

## Example

    DECLARE RFA R_ARRAY(1 TO 100)
       .
       .
       .
    FOR I% = 1% TO 100%
        PUT #1
        R_ARRAY(I%) = GETRFA(1)
    NEXT I%

# GOSUB

> The GOSUB statement transfers control to a specified line number or label and stores the location of the GOSUB statement for eventual return from the subroutine.

## Format

## Syntax Rules

1. Target must refer to an existing line number or label in the same program unit as the GOSUB statement or BASIC signals an error.
2. Target cannot be inside a block structure such as a FOR...NEXT, WHILE, or UNTIL loop or a multiline function definition unless the GOSUB statement is also within that block or function definition.

## Remarks

1. You can use the GOSUB statement from within protected regions of a WHEN block. GOSUB statements can also contain protected regions themselves.
2. If you fail to handle an exception that occurs while a statement contained 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 statement that invoked the subroutine.

## Example

    GOSUB subroutine_1
       .
       .
       .
    subroutine_1:
       .
       .
       .
    RETURN

# GOTO

> The GOTO statement transfers control to a specified line number or label.

## Format

## Syntax Rules

1. Target must refer to an existing line number or label in the same program unit as the GOTO statement or BASIC signals an error.
2. Target cannot be inside a block structure such as a FOR...NEXT, WHILE, or UNTIL loop or a multiline function definition unless the GOTO statement is also inside that loop or function definition.

## Remarks

1. You can specify the GOTO statement inside a WHEN block if the target is in the same protected region, an outer level protected region, or in a nonprotected region.
2. You cannot specify the GOTO statement inside a WHEN block if the target already resides in another protected region that does not contain the innermost current protected region.

## Example

    IF answer = 0
        THEN GOTO done
    END IF
       .
       .
       .
    done:
         EXIT PROGRAM

# HANDLER

> The handler statement marks the beginning of a detached handler.

## Format

## Syntax Rules

Handler-name must be a valid BASIC identifier and must not be the same as any label, DEF, DEF*, SUB, FUNCTION or PICTURE name.

## Remarks

1. A detached handler must be delimited by a HANDLER statement and an END HANDLER statement.
2. A detached handler can be used only with BASIC's exception-handling mechanism. If you attempt to branch into a detached handler, for example with the GOTO statement, BASIC signals a compile-time error.
3. To exit from a detached handler, you must use either END HANDLER, EXIT HANDLER, RETRY or CONTINUE. See these statements for more information.
4. Within a handler, VAX BASIC allows you to specify user-defined function references and procedure invocations as well as BASIC statements.
5. Within a handler, Alpha BASIC allows you to specify user-defined function references except for DEF* references, as well as procedure invocations and BASIC statements.
6. The following statements are illegal inside a handler:
   - EXIT PROGRAM, FUNCTION, SUB, or PICTURE
   - GOTO to a target outside the handler
   - GOSUB to a target outside the handler

   - ON ERROR
   - RESUME

## Example

    WHEN ERROR USE err_handler
       .
       .
       .
    END WHEN
    HANDLER err_handler
       IF ERR = 50 THEN PRINT "Insufficient data"
           RETRY
           ELSE EXIT HANDLER
       END IF
    END HANDLER

# IF

> The IF statement evaluates a conditional expression and transfers program control depending on the resulting value.

## Format

## Syntax Rules

1. Conditional
   - Cond-exp can be any valid conditional expression.
   - All statements between the THEN keyword and the next ELSE, line number, or END IF are part of the THEN clause. All statements between the keyword ELSE and the next line number or END IF are part of the ELSE clause.
   - BASIC assumes a GOTO statement when the keyword ELSE is followed by a line number. When the target of a GOTO statement is a label, the keyword GOTO is required. The use of this syntax is not recommended for new program development.
   - The END IF statement terminates the most recent unterminated IF statement.
   - A new line number terminates all unterminated IF statements.
2. Statement Modifier
   - IF can modify any executable statement except a block statement such as FOR, WHILE, UNTIL, or SELECT.
   - Cond-exp can be any valid conditional expression.

## Remarks

1. Conditional
   - BASIC evaluates the conditional expression for truth or falsity. If true (nonzero), BASIC executes the THEN clause. If false (zero), BASIC skips the THEN clause and executes the ELSE clause, if present.
   - The keyword NEXT cannot be in a THEN or ELSE clause unless the FOR or WHILE statement associated with the keyword NEXT is also part of the THEN or ELSE clause.
   - If a THEN or ELSE clause contains a block statement such as a FOR, SELECT, UNTIL, or WHILE, then a corresponding block termination statement such as a NEXT or END, must appear in the same THEN or ELSE clause.
   - IF statements can be nested to 12 levels.
   - Any executable statement is valid in the THEN or ELSE clause, including another IF statement. You can include any number of statements in either clause.
   - Execution continues at the statement following the END IF or ELSE clause. If the statement does not contain an ELSE clause, execution continues at the next statement after the THEN clause.
2. Statement Modifier
   - BASIC executes the statement only if the conditional expression is true (nonzero).

## Example

    IF Update_flag = True
    THEN
          Weekly_salary = New_rate * 40.0
          UPDATE #1
          IF Dept <> New_dept
          THEN
                GET #1, KEY #1 EQ New_dept
                Dept_employees = Dept_employees + 1
                UPDATE #1
          END IF
          PRINT "Update complete"
    ELSE
          PRINT "Skipping update for this employee"
    END IF

# INKEY$

> The INKEY$ function reads a single keystroke from a terminal opened on a specified channel and returns the typed character.

## Format

## Syntax Rules

1. Chnl-exp must be the channel number of a terminal.
2. Int-exp represents the timeout value in seconds and must be from 0 to 255. Values beyond this range cause BASIC to signal a compile-time or run-time error.

## Remarks

1. Before using the INKEY$ function, specify the DCL command SET TERMINAL/HOSTSYNC. This command controls whether the system can synchronize the flow of input from the terminal. If you specify SET TERMINAL/HOSTSYNC, the system generates a Ctrl/S or a Ctrl/Q to enable or disable the reception of input. This prevents the typeahead buffer from overflowing. If you do not use this command and the typeahead buffer overflows, BASIC signals the error "Data overflow" (ERR=289).
2. Before using the INKEY$ function on a VT200-series terminal, set your terminal to VT200 mode with 7 bit controls.
3. Before using the INKEY$ function, either your terminal or OpenVMS system, but not both, must enable screen wrapping. To enable terminal screen wrapping, use the Set-Up key on your terminal's keyboard to set the terminal to Auto Wrap. Then disable OpenVMS screen wrapping by entering the DCL SET TERMINAL /NOWRAP command. To enable OpenVMS screen wrapping, enter the DCL SET TERMINAL/WRAP command. Then disable terminal screen wrapping by using the Set-Up key to set the terminal to No Auto Wrap.
4. The INKEY$ function behaves as if the terminal were in APPLICATION_KEYPAD mode. If your terminal is set to NUMERIC_KEYPAD mode, the results may be unpredictable.
5. If the channel is not open, BASIC signals the error "I/O, channel not open" (ERR=9). If a file or a device other than a terminal is open on the channel, BASIC signals the error "Illegal operation" (ERR=141).
6. The optional WAIT clause specifies a timeout interval during which the command will await terminal input. If you specify WAIT int-exp, the timeout period will be the specified number of seconds. If you specify a WAIT clause followed by no timeout value, BASIC waits indefinitely for terminal input.
7. BASIC always examines the typeahead buffer first and retrieves the next keystroke in the buffer if the buffer is not empty. If the typeahead buffer is empty and an optional WAIT clause was specified, BASIC waits for a keystroke to be typed for the specified timeout interval (indefinitely if WAIT was specified with no timeout interval). If the typeahead buffer is empty, and the waiting period is either not specified or expired, BASIC returns the error message "Keyboard wait exhausted" (ERR=15).
8. The escape character (ASCII code 27) is not valid as INKEY$ input. If you enter an escape character, normal program execution resumes when the INKEY$ times out. Without a specified timeout value, the program execution cannot resume without error.
9. BASIC returns the error message "Keyboard wait exhausted" (ERR=15) when any key is pressed after the escape character if no timeout is specified or if the specified timeout has not yet occurred.
10. INKEY$ turns off all line editing. As a result, control of all line-editing characters and the arrow keys is passed back to the user.
11. Nonediting characters normally intercepted by the OpenVMS terminal driver are not returned. These include the Ctrl/C, Ctrl/Y, Ctrl/S, and Ctrl/O characters (unless Ctrl/C trapping is enabled). They are handled by the device driver just as in normal input.
12. All ASCII characters are returned in a 1-byte string.
13. All keystrokes that result in an escape sequence are translated to mnemonic strings based on the following key names:
    - PF1--PF4
    - E1--E6
    - F7--F20
    - LEFT
    - RIGHT
    - UP
    - DOWN
    - KP0 to KP9
    - KP--
    - KP,
    - KP.
    - ENTER

## Example

        PROGRAM Inkey_demo

        DECLARE STRING KEYSTROKE
    Inkey_Loop:
        WHILE 1%
          KEYSTROKE = INKEY$(0%,WAIT)

          SELECT KEYSTROKE
              CASE '26'C
                   PRINT "Ctrl/Z to exit"
                   EXIT Inkey_Loop
              CASE CR,LF,VT,FF
                   PRINT "Line terminator"
              CASE "PF1" TO "PF4"
                   PRINT "P function key"
              CASE "E1" TO "E6", "F7" TO "F9", "F10" TO "F20"
                   PRINT "VT200 function key"
              CASE "KP0" TO "KP9"
                   PRINT "Application keypad key"
              CASE < SP
                   PRINT "Control character"
              CASE '127'C
                   PRINT "<DEL>"
              CASE ELSE
                   PRINT 'Character is "'; KEYSTROKE; '"'
           END SELECT
        NEXT

        END PROGRAM

# INPUT

> The INPUT statement assigns values from your terminal or from a terminal-format file to program variables.

## Format

## Syntax Rules

1. You must supply an argument to the INPUT statement. Otherwise, BASIC signals an error message.
2. Chnl-exp is a numeric expression that specifies a channel number associated with a file. It must be immediately preceded by a number sign (#).
3. You can include more than one string constant in an INPUT statement. Str-const1 is issued for var1, str-const2 for var2, and so on.
4. Var1 and var2 cannot be a DEF function name unless the INPUT statement is inside the multiline DEF that defines the function.
5. The separator (comma or semicolon) that directly follows var1 and var2 has no formatting effect. BASIC always advances to a new line when you terminate input by pressing Return.
6. The separator that directly follows str-const1 and str-const2 determines where the question mark prompt (if requested) is displayed and where the cursor is positioned for input.
   A comma causes BASIC to skip to the next print zone and display the question mark unless a SET NO PROMPT statement has been executed, as follows.

       DECLARE STRING your_name
       INPUT "What is your name",your_name

   Output

       What is your name           ?

   A semicolon causes BASIC to display the question mark next to str-const unless a SET NO PROMPT statement has been executed. For example:

       DECLARE STRING your_name
       INPUT "What is your name";your_name

   Output

       What is your name?

7. BASIC always advances to a new line when you terminate input with a carriage return.

## Remarks

1. If you do not specify a channel, the default chnl-exp is #0 (the controlling terminal). If a chnl-exp is specified, a file must be open on that channel with ACCESS READ or MODIFY before the INPUT statement can execute.
2. If input comes from a terminal, BASIC displays the contents of str-const1, if present. If the terminal is open on channel #0, BASIC also displays a question mark (?).
3. You can disable the question mark prompt by using the SET NO PROMPT statement. See the SET PROMPT statement for more information.
4. When BASIC receives a line terminator or a complete record, it checks each data element for correct data type and range limits, then assigns the values to the corresponding variables.
5. If you specify a string variable to receive the input text, and the user enters an unquoted string in response to the prompt, BASIC ignores the string's leading and trailing spaces and tabs. An unquoted string cannot contain any commas.
6. If there is not enough data in the current record or line to satisfy the variable list, BASIC takes one of the following actions:
   - If the input device is a terminal and you have not specified SET NO PROMPT, BASIC repeats the question mark, but not the str-const, on a new line until sufficient data is entered.
   - If the input device is not a terminal, BASIC signals "Not enough data in record" (ERR=59).
7. If there are more data items than variables in the INPUT response, BASIC ignores the excess.
8. If there is an error while data is being converted or assigned (for example, string data being assigned to a numeric variable), BASIC takes one of the following actions:
   - If there is no error handler in effect and the input device is a terminal, BASIC signals a warning, reexecutes the INPUT statement, and displays str-const and the input prompt.
   - If there is an error handler in effect and the input device is not a terminal, BASIC signals "Illegal number" (ERR=52) or "Data format error" (ERR=50).
9. When a RETRY, CONTINUE, or RESUME statement transfers control to an INPUT statement, the INPUT statement retrieves a new record or line regardless of any data left in the previous record or line.
10. After a successful INPUT statement, the RECOUNT variable contains the number of characters transferred from the file or terminal to the record buffer.
11. If you terminate input text with Ctrl/Z, BASIC assigns the value to the variable and signals "End of file on device" (ERR=11) when the next terminal input statement executes. If you are in the VAX BASIC Environment and there is no subsequent INPUT, INPUT LINE, or LINPUT statement in the program, the Ctrl/Z is passed to BASIC as a signal to exit the VAX BASIC Environment. BASIC signals "Unsaved changes have been made, Ctrl/Z or EXIT to exit" if you have made changes to your program or are running a program that has never been saved. If you have not made changes, BASIC exits from the VAX BASIC Environment and does not signal an error.

## Example

    DECLARE STRING var_1,   &
            INTEGER var_2
    INPUT "The first variable";var_1, "The second variable";var_2

Output

    The first variable? name
    The second variable? 4

# INPUT LINE

> The INPUT LINE statement assigns a string value (including the line terminator in some cases) from a terminal or terminal-format file to a string variable.

## Format

## Syntax Rules

1. Chnl-exp is a numeric expression that specifies a channel number associated with a file. It must be immediately preceded by a number sign (#).
2. Str-var1 or str-var2 cannot be a DEF function name unless the INPUT LINE statement is inside the multiline DEF that defines the function.
3. You can include more than 1 string constant in an INPUT LINE statement. Str-const1 is issued for str-var1, str-const2 for str-var2, and so on.
4. The separator (comma or semicolon) that directly follows str-var1 and str-var2 has no formatting effect. BASIC always advances to a new line when you terminate input with a carriage return.
5. The separator that directly follows str-const1 and str-const2 determines where the question mark (if requested) is displayed and where the cursor is positioned for input. Specifically:
   - A comma causes BASIC to skip to the next print zone and display the question mark unless a SET NO PROMPT statement has been executed. For example:

         DECLARE STRING your_name
         INPUT LINE "Name",your_name

     Output

         Name             ?

   - A semicolon causes BASIC to display the question mark next to str-const unless a SET NO PROMPT statement has been executed. For example:

         DECLARE STRING your_name
         INPUT LINE "Name";your_name

     Output

         Name?

6. BASIC always advances to a new line when you terminate input with a carriage return.

## Remarks

1. The default chnl-exp is #0 (the controlling terminal). If a channel is specified, a file must be open on that channel with ACCESS READ before the INPUT LINE statement can execute.
2. BASIC signals an error if the INPUT LINE statement has no argument.
3. If input comes from a terminal, BASIC displays the contents of str-const1, if present. If the terminal is open on channel #0, BASIC also displays a question mark (?).
4. You can disable the question mark prompt by using the SET NO PROMPT statement. See the SET PROMPT statement for more information.
5. The INPUT LINE statement assigns all input characters to string variables. In addition, the INPUT LINE statement places the following line terminator characters in the assigned string if they are part of the string value:

   Hex code | ASCII char | Character name
   --- | --- | ---
   0A | LF | Line Feed
   0B | VT | Vertical Tab
   0C | FF | Form Feed
   0D | CR | Carriage Return
   0D0A | CRLF | Carriage Return/Line Feed
   1B | ESC | Escape

   Any other line terminator, such as Ctrl/D and Ctrl/F when line editing is turned off, is not included in the assigned string.
6. When a RETRY, CONTINUE, or RESUME statement transfers control to an INPUT LINE statement, the INPUT LINE statement retrieves a new record or line regardless of any data left in the previous record or line.
7. After a successful INPUT LINE statement, the RECOUNT variable contains the number of characters transferred from the file or terminal to the record buffer.
8. If you terminate input text with Ctrl/Z, BASIC assigns the value to the variable and signals "End of file on device" (ERR=11) when the next terminal input statement executes. If you are in the VAX BASIC Environment and there is no next INPUT, INPUT LINE, or LINPUT statement in the program, the Ctrl/Z is passed to BASIC as a signal to exit the VAX BASIC Environment. BASIC signals "Unsaved changes have been made, Ctrl/Z or EXIT to exit" if you have made changes to your program. If you have not made changes, BASIC exits from the VAX BASIC Environment and does not signal an error.

## Example

Previous | Next | Contents | Index