HP OpenVMS Systems Documentation

HP BASIC for OpenVMS
Reference Manual

Contents

Index

EDIT$

The EDIT$ function performs one or more string editing functions, depending on the value of its integer argument.

Format

str-var = EDIT$ (str-exp, int-exp)

Syntax Rules

None

Remarks

HP BASIC edits str-exp to produce str-var.
The editing that HP BASIC performs depends on the value of int-exp. Table 3-2 describes EDIT$ values and functions.
All values are additive; for example, you can perform the editing functions of values 8, 16, and 32 by specifying a value of 56.
If you specify a floating-point expression for int-exp, HP BASIC truncates it to an integer of the default size.

**Table 3-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, HP 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

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.
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.
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.
END DEF and END FUNCTION

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

END HANDLER
The END HANDLER statement causes HP BASIC to transfer control to the statement following the WHEN block with the exception cleared.
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.

END WHEN

The END WHEN statement ends a WHEN block.
If the END WHEN statement ends an attached handler, and the handler does not process an error with an EXIT HANDLER, RETRY, or CONTINUE statement, then control is transferred to the statement following the WHEN block with the exception cleared.

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.

When an END or END PROGRAM statement marking the end of a main program executes, HP BASIC closes all files and releases all program storage.
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.
Except for the END PROGRAM statement, HP 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

int-var = ERL

Syntax Rules

The value of int-var returned by the ERL function is a LONG integer.

Remarks

If the ERL 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
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

str-var = ERN$

Syntax Rules

None

Remarks

If the ERN$ function executes before an error occurs or after an error is handled, ERN$ returns a null string.
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

int-var = ERR

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

str-var = ERT$ (int-exp)

Syntax Rules

Int-exp is an HP BASIC error number. The error number should be a valid BASIC error number.

Remarks

The ERT$ function can be used at any time to return the text associated with a specified error number.
If you specify a floating-point expression for int-exp, HP BASIC truncates it to an integer of the default size.
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

EXIT

The EXIT statement lets you exit from a main program, a SUB, FUNCTION, or PICTURE subprogram, a multiline DEF, a statement block, or a handler.

Format

Syntax Rules

The DEF, FUNCTION, SUB, HANDLER, and PROGRAM keywords specify the type of subprogram, multiline DEF, or handler from which HP BASIC is to exit.
If you specify an optional expression with the EXIT DEF statement or with the EXIT FUNCTION statement, the expression becomes the function result and supersedes any function assignment. It also overrides any expression specified on the END DEF or END FUNCTION statement. Note that the expression must be compatible with the FUNCTION or DEF data type.
Label specifies a statement label for an IF, SELECT, FOR, WHILE, or UNTIL statement block.

Remarks

An EXIT SUB, EXIT FUNCTION, EXIT PROGRAM, EXIT DEF, or EXIT PICTURE statement is equivalent to an unconditional branch to an equivalent END statement. Control then passes to the statement that invoked the DEF or to the statement following the statement that called the subprogram.
The EXIT HANDLER statement causes HP BASIC to transfer control to a specified area.
- If the current WHEN block is nested, control transfers to the handler associated with the next outer protected region.
- If an ON ERROR statement is in effect and the current WHEN block is not nested, control transfers to the target of the ON ERROR statement.
- If neither of the previous conditions is true, an EXIT HANDLER statement transfers control to the calling program or DCL. This action is the equivalent of the ON ERROR GO BACK statement.
The EXIT PROGRAM statement causes HP BASIC to exit from a main program module.
- An optional integer expression on an EXIT PROGRAM statement specifies the exit status of the program that is reported to DCL.
- The expression specified by an EXIT PROGRAM statement overrides any integer expression specified by an END PROGRAM statement.
- HP BASIC allows you to specify an EXIT PROGRAM statement without a matching PROGRAM statement.
The EXIT label statement is equivalent to an unconditional branch to the first statement following the end of the IF, SELECT, FOR, WHILE, or UNTIL statement labeled by the specified label.
An EXIT FUNCTION, EXIT SUB or EXIT PROGRAM statement cannot be used within a multiline DEF function.
When the EXIT FUNCTION, EXIT SUB or EXIT PROGRAM statement executes, HP BASIC releases all storage allocated to local variables and returns control to the calling program.

Example

DEF emp.bonus(A)
IF A > 10
THEN
    PRINT "OUT OF RANGE"
    EXIT DEF 0
ELSE
    emp.bonus = A * 4
END IF
END DEF
INPUT A
PRINT emp.bonus(A)
END

Output

? 11
OUT OF RANGE
 0

EXP

The EXP function returns the value of the mathematical constant e raised to a specified power.

Format

real-var = EXP (real-exp)

Syntax Rules

None

Remarks

The EXP function returns the value of e raised to the power of real-exp.
HP BASIC expects the argument of the EXP function to be a real expression. When the argument is a real expression, HP BASIC returns a value of the same floating-point size. When the argument is not a real expression, HP BASIC converts the argument to the default floating-point size and returns a value of the default floating-point size.
When the default REAL size is SINGLE, DOUBLE, or SFLOAT, EXP allows arguments from --88 to 88. If the default REAL size is GFLOAT or TFLOAT, EXP allows arguments from -709 to 709. If the default REAL size is HFLOAT or XFLOAT, the arguments can be in the range --11356 to 11355. When the argument exceeds the upper limit of a range, HP BASIC signals an error. When the argument is beyond the lower limit of a range, the EXP function returns a zero and HP BASIC does not signal an error.

Example

DECLARE SINGLE num_val
num_val = EXP(4.6)
PRINT num_val

Output

 99.4843

EXTERNAL

The EXTERNAL statement declares constants, variables, functions, and subroutines external to your program. You can describe parameters for external functions and subroutines.

Format

Syntax Rules

For external constants, data-type can be BYTE, WORD, LONG, INTEGER (if default is not QUAD), SINGLE, SFLOAT, or REAL (if default is SINGLE or SFLOAT).
For external variables, the data type can be any valid numeric data type.
For external functions and subroutines, the data type can be BYTE, WORD, LONG, QUAD, SINGLE, DOUBLE, GFLOAT, HFLOAT, SFLOAT, TFLOAT, XFLOAT, DECIMAL, STRING, INTEGER, REAL, RFA, or a data type defined with the RECORD statement. See Table 1-2 for more information about data type size, range, and precision.
The name of an external constant, variable, function, or subroutine can be from 1 to 31 characters.
For all external routine declarations, the name must be a valid HP BASIC identifier and must not be the same as any other SUB, FUNCTION, PICTURE, or PROGRAM name.
For more information about external pictures, see Programming with VAX BASIC Graphics.
Param-data-type specifies the data type of a parameter. If you do not specify a data type, parameters are of the default data type and size.
Param-list is identical to external-param except that no OPTIONAL parameter is allowed.
Parameters in the param-list must agree in number and data type with the parameters in the invocation. Param-data-type includes ANY, BYTE, WORD, LONG, QUAD, INTEGER, SINGLE, DOUBLE, GFLOAT, HFLOAT, SFLOAT, TFLOAT, XFLOAT, READ, a user-defined RECORD type, STRING, or RFA.
A maximum of 255 parameters may be passed.
External Functions and Subroutines
- The data type that precedes the keyword FUNCTION defines the data type of the function result.
- Pass-mech specifies how parameters are to be passed to the function or subroutine.
  - A pass-mech clause outside the parentheses applies to all parameters.
  - A pass-mech clause inside the parentheses overrides the previous pass-mech and applies only to the specific parameter.
- External-param defines the form of the arguments passed to the external function or subprogram. Empty parentheses indicate that the subprogram expects zero parameters. Missing parentheses indicate that the EXTERNAL statement does not define parameters.
Using ANY as a BASIC Data Type
- The ANY data type should only be used for calling non-BASIC procedures. Therefore, the ANY data type is illegal in a PICTURE declaration.
- If you specify ANY, HP BASIC does not perform data type checking or conversions. If no passing mechanism is specified, HP BASIC uses the default passing mechanism for the data type passed in a given invocation.
- When you specify a data type, all following parameters that are not specifically declared default to the last specified data type. Similarly, when you specify ANY, all following unspecified parameters default to the data type ANY until a new declaration is provided. For example:
  EXTERNAL SUB allocate (LONG,ANY, )
Passing Optional Parameters
- The OPTIONAL keyword should be used only for calling non BASIC procedures.
- If you specify the keyword OPTIONAL, HP BASIC treats all following parameters as optional. In the following example, the last three parameters are optional:
  EXTERNAL SUB queue(STRING, OPTIONAL STRING, LONG, ANY)
- HP BASIC still performs type checking and conversion on optional parameters.
- If you want to omit an optional parameter that appears in the middle of a parameter list, HP BASIC requires you to insert a comma placeholder. However, if you want to omit an optional parameter that appears at the end of a parameter list, you can omit that parameter without inserting any placeholder.
- You can specify the keyword OPTIONAL only once in any one parameter list.
Declaring Array Dimensions
The DIM keyword indicates that the parameter is an array. Commas specify array dimensions. The number of dimensions is equal to the number of commas plus 1. For example:
EXTERNAL STRING FUNCTION new (DOUBLE, STRING DIM(,), DIM( ))
This statement declares a function named new that has three parameters. The first is a double-precision floating-point value, the second is a two-dimensional string array, and the third is a one-dimensional string array. The function returns a string result.

Remarks

The EXTERNAL statement must precede any program reference to the constant, variable, function, subroutine or picture declared in the statement.
The EXTERNAL statement is not executable.
A name declared in an EXTERNAL CONSTANT statement can be used in any nondeclarative statement as if it were a constant.
A name declared in an EXTERNAL FUNCTION statement can be used as a function invocation in an expression. In addition, you can invoke a function with the CALL statement unless the function data type is DECIMAL, HFLOAT, or STRING.
A name declared in an EXTERNAL SUB statement can be used in a CALL statement.
The optional pass-mech clauses in the EXTERNAL FUNCTION and EXTERNAL SUB statements tell HP BASIC how to pass arguments to a non BASIC function or subprogram.
- BY VALUE specifies that HP BASIC passes the argument's value.
- BY REF specifies that HP BASIC passes the argument's address. This is the default for all arguments except strings and entire arrays. If you know the size of string parameters and the dimensions of array parameters, you can improve run-time performance by passing strings and arrays by reference.
- BY DESC specifies that HP BASIC passes the address of a BASIC descriptor. For information about the format of a BASIC descriptor for strings and arrays, see Appendix A.
If you do not specify the data type ANY or declare parameters as optional, the arguments passed to external functions and subroutines should match the external parameters declared in the EXTERNAL FUNCTION or EXTERNAL SUB statement in number, type, and passing mechanism. HP BASIC forces arguments to be compatible with declared parameters. If they are not compatible, HP BASIC signals an error.

Examples

Example 1

!External Constant
EXTERNAL LONG CONSTANT SS$_NORMAL

Example 2

!External Variable
EXTERNAL WORD SYSNUM

Example 3

!External Function
EXTERNAL DOUBLE FUNCTION USR$2(WORD,LONG,ANY)

Example 4

!External Subroutine
EXTERNAL SUB calc BY DESC (STRING DIM(,),  BYTE BY REF)

Contents

Index

HP OpenVMS Systems Documentation

HP BASIC for OpenVMSReference Manual

EDIT$

Format

Syntax Rules

Remarks

Example

END

Format

Syntax Rules

Remarks

Example

ERL

Format

Syntax Rules

Remarks

Example

ERN$

Format

Syntax Rules

Remarks

Example

ERR

Format

Syntax Rules

Remarks

Example

ERT$

Format

Syntax Rules

Remarks

Example

EXIT

Format

Syntax Rules

Remarks

Example

EXP

Format

Syntax Rules

Remarks

Example

EXTERNAL

Format

Syntax Rules

Remarks

Examples

HP BASIC for OpenVMS
Reference Manual