HP OpenVMS Systems Documentation
HP BASIC for OpenVMS
The %TITLE directive lets you specify a title for the program listing file.
Str-lit can contain up to 31 characters.
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
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.
Macro-id is a user identifier that follows the rules for a BASIC identifier.
- 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.
G = 6% PRINT "G ="; G %DEFINE G "anything" PRINT "G = "; G %UNDEFINE G PRINT "G ="; G
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.
%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:
|Definition||A description of what the statement does.|
|Format||The required syntax for the statement.|
|Syntax Rules||Any rules governing the use of parameters, separators, or other syntax items.|
|Remarks||Explanatory remarks concerning the effect of the statement on program execution and any restrictions governing its use.|
|Example||One or more examples of the statement in a BASIC program. Where appropriate, sample output is also shown.|
The ABS function returns a floating-point number that equals the absolute value of a specified floating-point expression.
- 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.
G = 5.1273 A = ABS(-100 * G) B = -39 PRINT ABS(B), A
The ABS% function returns an integer that equals the absolute value of a specified integer expression.
- 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.
G% = 5.1273 A = ABS%(-100% * G%) B = -39 PRINT ABS%(B), A
The ASCII function returns the ASCII value in decimal of a string's first character.
- The ASCII value of a null string is zero.
- The ASCII function returns an integer value of the default size from 0 to 255.
DECLARE STRING time_out time_out = "Friday" PRINT ASCII(time_out)
The ATN function returns the arctangent (that is, angular value) of a specified tangent in radians or degrees.
- 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.
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"
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.
- Chnl-exp is a numeric expression that specifies a channel number.
- The value assigned to int-var is a LONG integer.
- If the specified channel is closed, BUFSIZ returns a value of zero.
- BUFSIZ of channel #0 always returns the value 132.
DECLARE LONG buffer_size buffer_size = BUFSIZ(0) PRINT "Buffer size equals";buffer_size
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.
- 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.
- 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.
EXTERNAL SUB LIB$PUT_OUTPUT (string) DECLARE STRING msg_str msg_str = "Successful call to LIB$PUT_OUTPUT!" CALL LIB$PUT_OUTPUT (msg_str)
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.
Err-num should be a valid HP BASIC run-time error number.
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).
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.
Chnl-exp must specify an open file or terminal.
- 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.
DECLARE LONG curs_pos PRINT "Hello"; curs_pos = CCPOS (0) PRINT curs_pos
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.
The CHAIN statement is not recommended for new program development. It is recommended that you use subprograms and external functions for program segmentation.
- 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.
DECLARE STRING time_out time_out = "Friday" PRINT ASCII(time_out) CHAIN "CCPOS"
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.
String Variable to Array
CHANGE str-exp TO num-array-name
Array to String Variable
CHANGE num-array-name TO str-var
- 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.
- 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.
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
4 65 66 67 68 ABCD