HP OpenVMS Systems Documentation

HP BASIC for OpenVMS
Reference Manual

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

• 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%

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

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

The handler statement marks the beginning of a detached handler.

Format

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

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

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

Format

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

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

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$