HP OpenVMS Systems Documentation

HP BASIC for OpenVMS
Reference Manual

The SUBEND statement is a synonym for the END SUB statement. See the END statement for more information.

Format

The SUBEXIT statement is a synonym for the EXIT SUB statement. See the EXIT statement for more information.

Format

The SUM$ function returns a string whose value is the sum of two numeric strings.

Format

Syntax Rules

None

Remarks

• The SUM$ function does not support E-format notation.
• Each string expression can contain up to 60 ASCII digits and an optional decimal point and sign.
• HP BASIC adds str-exp2 to str-exp1 and stores the result in str-var.
• If str-exp1 and str-exp2 are integers, str-var takes the precision of the larger string unless trailing zeros generate that precision.
• If str-exp1 and str-exp2 are decimal fractions, str-var takes the precision of the more precise fraction, unless trailing zeros generate that precision.
• SUM$ omits trailing zeros to the right of the decimal point.
• The sum of two fractions takes precision as follows:
  • The sum of the integer parts takes the precision of the larger part.
  • The sum of the decimal fraction part takes the precision of the more precise part.
• SUM$ truncates leading and trailing zeros.

Example

DECLARE STRING A, B, Total A = "45.678" B = "67.89000" total = SUM$ (A,B) PRINT Total

Output

113.568

The SWAP% function transposes a WORD integer's bytes.

Format

Syntax Rules

None

Remarks

• SWAP% is a WORD function. HP BASIC evaluates int-exp and converts it to the WORD data type, if necessary.
• HP BASIC transposes the bytes of int-exp and returns a WORD integer.

Example

DECLARE INTEGER word_int word_int = SWAP%(23) PRINT word_int

Output

5888

When used with the PRINT statement, the TAB function moves the cursor or print mechanism to a specified column.

When used outside the PRINT statement, the TAB function creates a string containing the specified number of spaces.

Format

Syntax Rules

• When used with the PRINT statement, int-exp specifies the column number of the cursor or print mechanism.
• When used outside the PRINT statement, int-exp specifies the number of spaces in the returned string.

Remarks

• You cannot tab beyond the current MARGIN restriction.
• The leftmost column position is zero.
• If int-exp is less than the current cursor position, the TAB function has no effect.
• The TAB function can move the cursor or print mechanism only from the left to the right.
• You can use more than one TAB function in the same PRINT statement.
• Use semicolons to separate multiple TAB functions in a single statement. If you use commas, HP BASIC moves to the next print zone before executing the TAB function.
• If you specify a floating-point expression for int-exp, HP BASIC truncates it to an integer.

Example

PRINT "Number 1"; TAB(15); "Number 2"; TAB(30); "Number 3"

Output

Number 1 Number 2 Number 3

The TAN function returns the tangent of an angle in radians or degrees.

Format

Syntax Rules

Real-exp is an angle specified in radians or degrees, depending on which angle clause you choose with the OPTION statement.

Remarks

HP BASIC expects the argument of the TAN 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.

Example

OPTION ANGLE = DEGREES DECLARE REAL tangent tangent = TAN(45.0) PRINT tangent

Output

1

The TIME function returns the time of day (in seconds) as a floating-point number. The TIME function can also return process CPU time and connect time.

Format

Syntax Rules

None

Remarks

• The value returned by the TIME function depends on the value of int-exp.
• If int-exp equals zero, TIME returns the number of seconds since midnight.
• HP BASIC also accepts values 1 and 2 and returns values as shown in Table 3-6. All other arguments to the TIME function are undefined and cause HP BASIC to signal "Not implemented" (ERR=250).
• The TIME function returns a SINGLE floating-point value.
• If you specify a floating-point expression for int-exp, HP BASIC truncates it to an integer.

Table 3-6 TIME Function Values

Argument Value	HP BASIC Returns
0	The amount of time elapsed since midnight in seconds
1	The CPU time of the current process in tenths of a second
2	The connect time of the current process in minutes

Example

PRINT TIME(0)

Output

49671

The TIME$ function returns a string displaying the time of day in the form hh:mm AM or hh:mm PM.

Format

Syntax Rules

Int-exp specifies the number of minutes before midnight.

Remarks

• If int-exp equals zero, TIME$ returns the current time of day.
• The value of int-exp must be from 0 to 1440 or HP BASIC signals an error.
• The TIME$ function uses a 12-hour, AM/PM clock. Before 12:00 noon, TIME$ returns hh:mm AM; after 12:00 noon, hh:mm PM.
• If you specify a floating-point expression for int-exp, HP BASIC truncates it to an integer.

Example

DECLARE STRING current_time current_time = TIME$(0) PRINT current_time

Output

01:51 PM

The TRM$ function removes all trailing blanks and tabs from a specified string.

Format

Syntax Rules

None

Remarks

The returned str-var is identical to str-exp, except that it has all the trailing blanks and tabs removed.

Example

DECLARE STRING old_string, new_string old_string = "ABCDEFG " new_string = TRM$(old_string) PRINT old_string;"XYZ" PRINT new_string;"XYZ"

Output

ABCDEFG XYZ ABCDEFGXYZ

]The UBOUND function returns the upper bounds of a compile-time or run-time dimensioned array.

Format

Syntax Rules

• Array-name must specify an array that has been previously explicitly or implicitly declared.
• Int-exp specifies the number of the dimension for which you have requested the upper bounds.

Remarks

• If you do not specify a numeric expression, HP BASIC automatically returns the upper bounds of the first dimension.
• If you specify a numeric expression that is less than or equal to zero, HP BASIC signals an error message.
• If you specify a numeric expression that exceeds the number of dimensions, HP BASIC signals an error message.

Example

DECLARE INTEGER CONSTANT B = 5 DIM A(B) account_num = 1 FOR dim_num = 0 TO UBOUND(A) A(dim_num) = account_num account_num = account_num + 1 PRINT A(dim_num) NEXT dim_num

Output

1 2 3 4 5 6

The UNLESS qualifier modifies a statement. HP BASIC executes the modified statement only if a conditional expression is false.

Format

Syntax Rules

None

Remarks

• The UNLESS statement cannot be used on nonexecutable statements or on statements such as SELECT, IF, and DEF that establish a statement block.
• HP BASIC executes the statement only if cond-exp is false (value zero).

Example

PRINT "A DOES NOT EQUAL 3" UNLESS A% = 3%

The UNLOCK statement unlocks the current record or bucket locked by the last FIND or GET statement.

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

• A file must be opened on the specified channel before UNLOCK can execute.
• The UNLOCK statement only applies to files on disk.
• If the current record is not locked by a previous GET or FIND statement, the UNLOCK statement has no effect and HP BASIC does not signal an error.
• The UNLOCK statement does not affect record buffers.
• After HP BASIC executes the UNLOCK statement, you cannot update or delete the current record.
• Once the UNLOCK statement executes, the position of the current record pointer is undefined.

Example

UNLOCK #10%

The UNTIL statement marks the beginning of an UNTIL loop or modifies the execution of another statement.

Format

Conditional
UNTIL cond-exp

[ statement ]...
.
.
. NEXT

Statement Modifier
statement UNTIL cond-exp

Syntax Rules

None

Remarks

• Conditional
  • A NEXT statement must end the UNTIL loop.
  • HP BASIC evaluates cond-exp before each loop iteration. If the expression is false (value zero), HP BASIC executes the loop. If the expression is true (value nonzero), control passes to the first executable statement after the NEXT statement.
• Statement Modifier
  HP BASIC executes the statement repeatedly until cond-exp is true.

Examples

Example 1

!Conditional UNTIL A >= 5 A = A + .01 TOTAL = TOTAL + 1 NEXT

Example 2

!Statement Modifier A = A + 1 UNTIL A >= 200

The UPDATE statement replaces a record in a file with a record in the record buffer. The UPDATE statement is valid on sequential, relative, and indexed files.

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 (#).
• Int-exp specifies the size of the new record.

Remarks

• The file associated with chnl-exp must be a disk file opened with ACCESS MODIFY.
• Each UPDATE statement must be preceded by a successful GET or FIND operation or HP BASIC signals "No current record" (ERR=131). FIND locates but does not retrieve records. Therefore, you must specify a COUNT clause when retrieving variable-length records when the preceding operation was a FIND. Int-exp must exactly match the size of the old record.
• If you are updating a variable-length record, and the record that you want to write out is not the same size as the record you retrieved, you must use a COUNT clause.
• After an UPDATE statement executes, there is no current record pointer. The next record pointer is unchanged.
• The length of the new record must be the same as that of the existing record for all files with fixed-length records and for all sequential files. If you specify a COUNT clause, the int-exp must match the size of the existing record.
• For relative files with variable-length records, the new record can be larger or smaller than the record it replaces.
  • The new record must be smaller than or equal to the maximum record size set with the MAP or RECORDSIZE clause when the file was opened.
  • You must use the COUNT clause to specify the size of the new record if it is different from that of the record last accessed by a GET operation on that channel.
• For indexed files with variable-length records, the new record can be larger or smaller than the record it replaces. When the program does not permit duplicate primary keys, the new record can be no longer than the size specified by the MAP or RECORDSIZE clause when the file was opened. The record must include at least the primary key field.
• An indexed file alternate key for the new record can differ from that of the existing record only if the OPEN statement for that file specified CHANGES for the alternate key.

Example

UPDATE #4%, COUNT 32

The VAL function converts a numeric string to a floating-point value.

Format

Syntax Rules

Str-exp can contain the ASCII digits 0 to 9, uppercase E, a plus sign (+), a minus sign (--), and a period (.).

Remarks

• The VAL function ignores spaces and tabs.
• If str-exp is null, or contains only spaces and tabs, VAL returns a value of zero.
• The value returned by the VAL function is of the default floating-point size.

Example

DECLARE REAL real_num real_num = VAL("990.32") PRINT real_num

Output

990.32

The VAL% function converts a numeric string to an integer.

Format

Syntax Rules

Str-exp can contain the ASCII digits 0 to 9, a plus sign (+), or a minus sign (--).

Remarks

• The VAL% function ignores spaces and tabs.
• If str-exp is null or contains only spaces and tabs, VAL% returns a value of zero.
• The value returned by the VAL% function is an integer of the default size.

Example

DECLARE INTEGER ret_int ret_int = VAL%("789") PRINT ret_int

Output

789

VMSSTATUS returns the underlying OpenVMS condition code when control is transferred to an HP BASIC error handler.

Format

Syntax Rules

None

Remarks

• If ERR contains the value 194, you can specify VMSSTATUS to examine the actual error that was signaled to HP BASIC.
• If an error is raised by an underlying system component such as the Run-Time Library, you can specify VMSSTATUS to determine the underlying error.
• If you are writing a utility routine that may be called from languages other than HP BASIC, you can specify VMSSTATUS in a call to LIB$SIGNAL to signal the underlying error to the caller of the utility routine.
• When there is no error pending, VMSSTATUS remains undefined.
• VMSSTATUS always returns a LONG integer.

Example

PROGRAM WHEN ERROR USE global_handler . . . END WHEN . . . HANDLER global_handler final_status% = VMSSTATUS END HANDLER END PROGRAM final_status%