HP OpenVMS Systems Documentation

HP BASIC for OpenVMS
Reference Manual

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

rfa-var = GETRFA (chnl-exp)

Syntax Rules

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

Remarks

There must be a file open on the specified chnl-exp or HP BASIC signals an error.
You can use the GETRFA function with RMS sequential, relative, indexed, and block I/O files.
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.
RFA values cannot be printed or used for any arithmetic operations.
If you open a file without specifying a file organization (sequential, relative, virtual, or indexed), HP BASIC defaults to terminal-format. See the HP BASIC for OpenVMS 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

Target must refer to an existing line number or label in the same program unit as the GOSUB statement or HP BASIC signals an error.
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

You can use the GOSUB statement from within protected regions of a WHEN block. GOSUB statements can also contain protected regions themselves.
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

Target must refer to an existing line number or label in the same program unit as the GOTO statement or HP BASIC signals an error.
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

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

HANDLER handler-name

Syntax Rules

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

Remarks

A detached handler must be delimited by a HANDLER statement and an END HANDLER statement.
A detached handler can be used only with HP BASIC's exception-handling mechanism. If you attempt to branch into a detached handler, for example with the GOTO statement, HP BASIC signals a compile-time error.
To exit from a detached handler, you must use either END HANDLER, EXIT HANDLER, RETRY or CONTINUE. See these statements for more information.
Within a handler, HP BASIC allows you to specify user-defined function references except for DEF* references, as well as procedure invocations and BASIC statements.
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

Conditional
IF cond-exp THEN statement... [ ELSE statement...] END IF

Statement Modifier
statement IF cond-exp

Syntax Rules

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.
HP 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.

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

Conditional

HP BASIC evaluates the conditional expression for truth or falsity. If true (nonzero), HP BASIC executes the THEN clause. If false (zero), HP 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.

Statement Modifier

HP 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

string-var = INKEY$ (chnl-exp [ ,WAIT [ int-exp ] ] )

Syntax Rules

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

Remarks

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, HP BASIC signals the error "Data overflow" (ERR=289).
Before using the INKEY$ function on a VT200-series terminal, set your terminal to VT200 mode with 7 bit controls.
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.
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.
If the channel is not open, HP 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, HP BASIC signals the error "Illegal operation" (ERR=141).
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, HP BASIC waits indefinitely for terminal input.
HP 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, HP 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, HP BASIC returns the error message "Keyboard wait exhausted" (ERR=15).
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.
HP 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.
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.
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.
All ASCII characters are returned in a 1-byte string.
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

You must supply an argument to the INPUT statement. Otherwise, HP BASIC signals an error message.
Chnl-exp is a numeric expression that specifies a channel number associated with a file. It must be immediately preceded by a number sign (#).
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.
Var1 and var2 cannot be a DEF function name unless the INPUT statement is inside the multiline DEF that defines the function.
The separator (comma or semicolon) that directly follows var1 and var2 has no formatting effect. HP BASIC always advances to a new line when you terminate input by pressing Return.
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 HP 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 HP 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?
HP BASIC always advances to a new line when you terminate input with a carriage return.

Remarks

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.
If input comes from a terminal, HP BASIC displays the contents of str-const1, if present. If the terminal is open on channel #0, HP BASIC also displays a question mark (?).
You can disable the question mark prompt by using the SET NO PROMPT statement. See the SET PROMPT statement for more information.
When HP 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.
If you specify a string variable to receive the input text, and you enter an unquoted string in response to the prompt, HP BASIC ignores the string's leading and trailing spaces and tabs. An unquoted string cannot contain any commas.
If there is not enough data in the current record or line to satisfy the variable list, HP BASIC takes one of the following actions:

If the input device is a terminal and you have not specified SET NO PROMPT, HP 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, HP BASIC signals "Not enough data in record" (ERR=59).

If there are more data items than variables in the INPUT response, HP BASIC ignores the excess.
If there is an error while data is being converted or assigned (for example, string data being assigned to a numeric variable), HP BASIC takes one of the following actions:

If there is no error handler in effect and the input device is a terminal, HP 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, HP BASIC signals "Illegal number" (ERR=52) or "Data format error" (ERR=50).

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.
After a successful INPUT statement, the RECOUNT variable contains the number of characters transferred from the file or terminal to the record buffer.
If you terminate input text with Ctrl/Z, HP BASIC assigns the value to the variable and signals "End of file on device" (ERR=11) when the next terminal input statement executes.

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

Chnl-exp is a numeric expression that specifies a channel number associated with a file. It must be immediately preceded by a number sign (#).
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.
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.
The separator (comma or semicolon) that directly follows str-var1 and str-var2 has no formatting effect. HP BASIC always advances to a new line when you terminate input with a carriage return.
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 HP 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 HP 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?
HP BASIC always advances to a new line when you terminate input with a carriage return.

Remarks

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.
HP BASIC signals an error if the INPUT LINE statement has no argument.
If input comes from a terminal, HP BASIC displays the contents of str-const1, if present. If the terminal is open on channel #0, HP BASIC also displays a question mark (?).
You can disable the question mark prompt by using the SET NO PROMPT statement. See the SET PROMPT statement for more information.
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.
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.
After a successful INPUT LINE statement, the RECOUNT variable contains the number of characters transferred from the file or terminal to the record buffer.
If you terminate input text with Ctrl/Z, HP BASIC assigns the value to the variable and signals "End of file on device" (ERR=11) when the next terminal input statement executes.

Example

DECLARE STRING Z,N,record_string
INPUT LINE "Type two words", Z$,'Type your name';N$
INPUT LINE #4%, record_string$

Contents

Index

HP OpenVMS Systems Documentation

HP BASIC for OpenVMSReference Manual

GETRFA

Format

Syntax Rules

Remarks

Example

GOSUB

Format

Syntax Rules

Remarks

Example

GOTO

Format

Syntax Rules

Remarks

Example

HANDLER

Format

Syntax Rules

Remarks

Example

IF

Format

Syntax Rules

Remarks

Example

INKEY$

Format

Syntax Rules

Remarks

Example

INPUT

Format

Syntax Rules

Remarks

Example

INPUT LINE

Format

Syntax Rules

Remarks

Example

HP BASIC for OpenVMS
Reference Manual