HP OpenVMS Systems Documentation

HP BASIC for OpenVMS
Reference Manual

The %TITLE directive lets you specify a title for the program listing file.

Format

Syntax Rules

Str-lit can contain up to 31 characters.

Remarks

• HP BASIC truncates extra characters from str-lit and does not signal a warning or error. Str-lit is truncated at 31 characters.
• Only a line number or a comment field can appear on the same physical line as the %TITLE directive.
• The specified title appears on the first line of every page of the listing file until HP BASIC encounters another %TITLE directive in the program.
• The %TITLE directive should appear on the first line of your program, before the first statement, if you want the specified title to appear on the first page of your listing.
• If you want the specified title to appear on the page that contains the %TITLE directive, the %TITLE directive should immediately follow a %PAGE directive.
• Because HP BASIC associates a subtitle with a title, a new %TITLE directive sets the current subtitle to the null string.
• The %TITLE directive has no effect unless you request a listing file.

Example

100     %TITLE "Learning to Program in HP BASIC"
        REM THIS PROGRAM IS A SIMPLE TEST
200     DATA 1, 2, 3, 4
   .
   .
   .
        NEXT I%
300     END

Output

TEST$MAIN                      Learning to Program in HP BASIC

     1         100     %TITLE "Learning to Program in HP BASIC"
     2                 %SBTTL "Using FOR-NEXT Loops"
     3                 REM THIS PROGRAM IS A SIMPLE TEST
     4         200     DATA 1, 2, 3, 4
   .
   .
   .

    10                 NEXT I%
    11         300     END

The %UNDEFINE directive causes HP BASIC to undefine an identifier that was previously defined with the %DEFINE directive.

Format

Syntax Rules

Macro-id is a user identifier that follows the rules for a BASIC identifier.

Remarks

• The %UNDEFINE directive cancels a previous definition of macro-id by a %DEFINE.
• The %UNDEFINE directive may appear with included code and will cancel the definition of an identifier that was previously defined.

Example

 G = 6%
 PRINT "G ="; G
 %DEFINE G "anything"
 PRINT "G = "; G
 %UNDEFINE G
 PRINT "G ="; G

Output

 G = 6
 G = anything
 G = 6

The %VARIANT directive is a built-in lexical function that allows you to conditionally control program compilation. %VARIANT returns an integer value when you reference it in a lexical expression. You set the variant value with the /VARIANT qualifier when you compile the program or with the SET VARIANT command. If the /VARIANT qualifier or the SET VARIANT command is not used, the value of %VARIANT is 0.

Format

Syntax Rules

None

Remarks

• The %VARIANT function can appear only in a lexical expression.
• The %VARIANT function returns the integer value specified either with the COMPILE /VARIANT command, the SET /VARIANT command, or the BASIC DCL command. The returned integer always has a data type of LONG.

Example

%LET %VMS = 0
%LET %RSX = 1
%LET %RSTS = 2

%IF %VARIANT = %VMS
    %THEN
       .
       .
       .

%ELSE %IF %VARIANT = %RSX OR %VARIANT = %RSTS
    %THEN
       .
       .
       .

    %ELSE %ABORT "Illegal compilation variant"
    %END %IF

%END %IF

This chapter provides reference material on all of the HP BASIC statements and functions.

The statements and functions are listed in alphabetical order and each description contains the following format:

The ABS function returns a floating-point number that equals the absolute value of a specified floating-point expression.

Format

Syntax Rules

None

Remarks

• The argument of the ABS function must 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.
• The returned floating-point value is always greater than or equal to zero. The absolute value of 0 is zero. The absolute value of a positive number equals that number. The absolute value of a negative number equals that number multiplied by --1.

Example

G = 5.1273 A = ABS(-100 * G) B = -39 PRINT ABS(B), A

Output

39 512.73

The ABS% function returns an integer that equals the absolute value of a specified integer expression.

Format

Syntax Rules

None

Remarks

• If you specify a floating-point expression for int-exp, HP BASIC truncates it to an integer.
• The returned value is always greater than or equal to zero. The absolute value of 0 is zero. The absolute value of a positive number equals that number. The absolute value of a negative number equals that number multiplied by --1.

Example

G% = 5.1273 A = ABS%(-100% * G%) B = -39 PRINT ABS%(B), A

Output

39 500

The ASCII function returns the ASCII value in decimal of a string's first character.

Format

Syntax Rules

None

Remarks

• The ASCII value of a null string is zero.
• The ASCII function returns an integer value of the default size from 0 to 255.

Example

DECLARE STRING time_out time_out = "Friday" PRINT ASCII(time_out)

Output

70

The ATN function returns the arctangent (that is, angular value) of a specified tangent in radians or degrees.

Format

Syntax Rules

None

Remarks

• The returned angle is expressed in radians or degrees, depending on which angle clause you choose with the OPTION statement.
• ATN returns a value from --PI/2 to PI/2 when you request the result in radians via the OPTION statement. It returns a value from --90 to 90 when you request the result in degrees.
• The argument of the ATN function must 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 = RADIANS DECLARE SINGLE angle_rad, angle_deg, T INPUT "Tangent value";T angle_rad = ATN(T) PRINT "The smallest angle with that tangent is" ;angle_rad; "radians" angle_deg = angle_rad/(PI/180) PRINT "and"; angle_deg; "degrees"

Output

Tangent value? 2 The smallest angle with that tangent is 1.10715 radians and 63.435 degrees

The BUFSIZ function returns the record buffer size, in bytes, of a specified channel.

Format

Syntax Rules

• Chnl-exp is a numeric expression that specifies a channel number.
• The value assigned to int-var is a LONG integer.

Remarks

• If the specified channel is closed, BUFSIZ returns a value of zero.
• BUFSIZ of channel #0 always returns the value 132.

Example

DECLARE LONG buffer_size buffer_size = BUFSIZ(0) PRINT "Buffer size equals";buffer_size

Output

Buffer size equals 132

The CALL statement transfers control to a subprogram, external function, or other callable routine. You can pass arguments to the routine and can optionally specify passing mechanisms. When the called routine finishes executing, control returns to the calling program.

Format

Syntax Rules

• Routine is the name of a SUB subprogram or any other callable procedure, such as a system service or an RTL routine you want to call. It cannot be a variable name. See the HP BASIC for OpenVMS User Manual for more information about using system services, RTL routines, and other procedures.
• You should use parameter-passing mechanisms only when calling non BASIC routines or when a subprogram expects to receive a string or entire array by reference.
  For more information about parameter-passing mechanisms, see the HP BASIC for OpenVMS User Manual.
• When pass-mech appears before the parameter list, it applies to all arguments passed to the called routine. You can override this passing mechanism by specifying a pass-mech for individual arguments in the actual-param list.
• Actual-param lists the arguments to be passed to the called routine.
• You can pass expressions or entire arrays. Optional commas in parentheses after the array name specify the dimensions of the array. The number of commas is equal to the number of dimensions --1. Thus, no comma specifies a one-dimensional array, one comma specifies a two-dimensional array, two commas specify a three-dimensional array, and so on.
• You cannot pass entire virtual arrays.
• The name of the routine can be from 1 to 31 characters and must conform to the following rules:
  • The first character of an unquoted name must be an alphabetic character (A to Z). The remaining characters, if present, can be any combination of letters, digits (0 to 9), dollar signs ($), periods (.), or underscores (_).
  • A quoted name can consist of any combination of printable ASCII characters.
• HP BASIC allows you to pass up to 255 parameters.

Remarks

• You can specify a null argument as an actual-param for non BASIC routines by omitting the argument and the pass-mech, but not the commas or parentheses. This forces HP BASIC to pass a null argument and allows you to access system routines from HP BASIC.
• Arguments in the actual-param list must agree in data type and number with the formal parameters specified in the subprogram.
• An argument is modifiable when changes to it are evident in the calling program. Changing a modifiable parameter in a subprogram means the parameter is changed for the calling program as well. Variables and entire arrays passed by descriptor or by reference are modifiable.
• An argument is nonmodifiable when changes to it are not evident in the calling program. Changing a nonmodifiable argument in a subprogram does not affect the value of that argument in the calling program. Arguments passed by value, constants, and expressions are nonmodifiable. Passing an argument as an expression (by placing it in parentheses) changes it from a modifiable to a nonmodifiable argument. Virtual array elements passed as parameters are nonmodifiable.

• HP BASIC will automatically convert numeric actual parameters to match the declared data type. If the actual parameter is a variable, HP BASIC signals the informational message "Mode for parameter <n> of routine <name> changed to match declaration" and passes the argument by local copy. This prevents the called routine from modifying the contents of the variable.
• For expressions and virtual array elements passed by reference, HP BASIC makes a local copy of the value, and passes the address of this local copy. For dynamic string arrays, HP BASIC passes a descriptor of the array of string descriptors. The compiler passes the address of the argument's actual value for all other arguments passed by reference.
• You can pass BYTE, WORD, LONG, QUAD, DOUBLE, GFLOAT, SINGLE, SFLOAT, and TFLOAT values by value.
• If you attempt to call an external function, HP BASIC treats the function as if it were invoked normally and validates all parameters. Note that you cannot call a STRING, HFLOAT, or RFA function. See the EXTERNAL statement for more information about how to invoke functions.

Example

EXTERNAL SUB LIB$PUT_OUTPUT (string) DECLARE STRING msg_str msg_str = "Successful call to LIB$PUT_OUTPUT!" CALL LIB$PUT_OUTPUT (msg_str)

Output

Successful call to LIB$PUT_OUTPUT!

The CAUSE ERROR statement allows you to artificially generate an HP BASIC run-time error and transfer program control to an HP BASIC error handler.

Format

Syntax Rules

Err-num should be a valid HP BASIC run-time error number.

Remarks

All error numbers are listed in the HP BASIC for OpenVMS User Manual. Any error outside the valid range of BASIC Run-Time Library errors results in the following error message: "NOTBASIC, Not a BASIC error" (ERR=194).

Example

WHEN ERROR IN . . . CAUSE ERROR 11% . . . USE SELECT ERR CASE = 11 PRINT "End of file" CONTINUE CASE ELSE EXIT HANDLER END SELECT END WHEN

The CCPOS function returns the current character or cursor position of the output record on a specified channel.

Format

Syntax Rules

Chnl-exp must specify an open file or terminal.

Remarks

• If chnl-exp is zero, CCPOS returns the current character position of the controlling terminal.
• The int-var returned by the CCPOS function is of the default integer size.
• The CCPOS function counts only characters. If you use cursor addressing sequences such as escape sequences, the value returned will not be the cursor position.
• The first character position on a line is zero.

Example

DECLARE LONG curs_pos PRINT "Hello"; curs_pos = CCPOS (0) PRINT curs_pos

Output

Hello 5

The CHAIN statement transfers control from the current program to another executable image. CHAIN closes all files, then requests that the new program begin execution. Control does not return to the original program when the new image finishes executing.

Format

Syntax Rules

Str-exp represents the file specification of the program to which control is passed.

Remarks

• Str-exp must refer to an executable image or HP BASIC signals an error.
• If you do not specify a file type, HP BASIC searches for an .EXE file type.
• You cannot chain to a program on another node.
• Execution starts at the beginning of the specified program.
• Before chaining takes place, all active output buffers are written, all open files are closed, and all storage is released.

• Because a CHAIN statement passes control from the executing image, the values of any program variables are lost. This means that you can pass parameters to a chained program only by using files or a system-specific feature such as LIB$GET_COMMON and LIB$PUT_COMMON.

Example

DECLARE STRING time_out time_out = "Friday" PRINT ASCII(time_out) CHAIN "CCPOS"

Output

70 The current cursor position is 0

In this example, the executing image ASCII.EXE passes control to the chained program, CCPOS.EXE. The value that results from ASCII.EXE is 70. The second line of output reflects the value that results from CCPOS.EXE.

The CHANGE statement either converts a string of characters to their ASCII integer values or converts a list of numbers to a string of ASCII characters.

Format

String Variable to Array
CHANGE str-exp TO num-array-name

Array to String Variable
CHANGE num-array-name TO str-var

Syntax Rules

• Str-exp is a string expression.
• Num-array-name should be a one-dimensional array. If you specify a two-dimensional array, HP BASIC converts only the first row of that array. HP BASIC does not support conversion to or from arrays of more than two dimensions.
• Str-var is a string variable.

Remarks

• HP BASIC does not support RECORD elements as a destination string or as a source or destination array for the CHANGE statement.
• String Variable to Array
  • This format converts each character in the string to its ASCII value.
  • HP BASIC assigns the value of the string's length to element zero (0) of the array.
  • HP BASIC assigns the ASCII value of the first character in the string to element one, (1) or (0,1), of the array, the ASCII value of the second character to element two, (2) or (0,2), and so on.
  • If the string is longer than the bounds of the array, HP BASIC does not translate the excess characters, and signals the error "Subscript out of range" (ERR=55). The first element of array still contains the length of the string.
• Array to String Variable
  • This format converts the elements of the array to a string of characters.
  • The length of the string is determined by the value in element zero, (0) or (0,0), of the array. If the value of element zero is greater than the array bounds, HP BASIC signals the error "Subscript out of range" (ERR=55).
  • HP BASIC changes element one, (1) or (0,1), of array to its ASCII character equivalent, element two, (2) or (0,2), to its ASCII equivalent, and so on. The length of the returned string is determined by the value in element zero of the array. For example, if the array is dimensioned as (10), but the zero element (0) contains the value 5, HP BASIC changes only elements (1), (2), (3), (4), and (5) to string characters.
  • HP BASIC truncates floating-point values to integers before converting them to characters.
  • Values in array elements are treated as modulo 256.

Example

DECLARE STRING ABCD, A DIM INTEGER array_changes(6) ABCD = "ABCD" CHANGE ABCD TO array_changes FOR I% = 0 TO 4 PRINT array_changes(I%) NEXT I% CHANGE array_changes TO A PRINT A

Output

4 65 66 67 68 ABCD