HP OpenVMS Systems Documentation

HP BASIC for OpenVMS
User Manual

A function is a single statement or group of statements that perform operations on operands and return the result to your program. HP BASIC has built-in functions that perform numeric and string operations, conversions, and date and time operations. This chapter describes only a selected group of built-in functions. For a complete description of all HP BASIC built-in functions, see the HP BASIC for OpenVMS Reference Manual.

This chapter also describes user-defined functions. HP BASIC lets you define your own functions in two ways:

• With the DEF statement
• As separately compiled subprograms (external functions)

DEF function definitions are local to a program module, while external functions can be accessed by any program module. You create local functions with the DEF statement and optionally declare them with the DECLARE statement. You create external functions with the FUNCTION statement and declare them with the EXTERNAL statement. For more information about creating external functions with the FUNCTION statement, see Chapter 12.

Once you create and declare a function, you can invoke it like a built-in function.

10.1 Built-In Functions

The functions described in this section let you perform sophisticated manipulations of string and numeric data. HP BASIC also provides algebraic, exponential, trigonometric, and randomizing mathematical functions.

10.1.1 Numeric Functions

Numeric functions generally return a result of the same data type as the function's parameter. For example, if you pass a DOUBLE argument to any of the trigonometric functions, they return a DOUBLE result.

If the format of a HP BASIC function specifies an argument of a particular data type, HP BASIC converts the actual argument supplied to the specified data type. For example, if you supply an integer argument to a function that expects a floating-point number, HP BASIC converts the argument to a floating-point number. Floating-point arguments that are passed to integer functions are truncated, not rounded.

The following sections discuss the HP BASIC built-in numeric functions.

10.1.1.1 ABS Function

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

READ A,B
DATA 10,-35.3
NEW_A = ABS(A)
PRINT NEW_A; ABS(B)
END

Output

 10  35.3

The ABS function always returns a number of the default floating-point data type.

10.1.1.2 INT and FIX Functions

The INT function returns the floating-point value of the largest integer less than or equal to a specified expression. The INT function always returns a number of the default floating-point type.

The FIX function truncates the value of a floating-point number at the decimal point. FIX always returns a number of the default floating-point type.

The following example shows the differences between the INT and FIX functions. Note that the value returned by FIX(-45.3) differs from the value returned by INT(-45.3).

PRINT INT(23.553); FIX(23.553)
PRINT INT(3.1); FIX(3.1)
PRINT INT(-45.3); FIX(-45.3)
PRINT INT(-11); FIX(-11)
END

Output

 23  23
 3  3
-46 -45
-11 -11

The SIN, COS, and TAN functions return the sine, cosine, and tangents of an angle in radians or degrees, depending on which angle clause you choose with the OPTION statement. If you supply a floating-point argument to the SIN, COS, and TAN functions, they return a number of the same floating-point type. If you supply an integer argument, they convert the argument to the default floating-point data type and return a floating-point number of that type.

The following example accepts an angle in degrees, converts the angle to radians, and prints the angle's sine, cosine, and tangent:

!CONVERT ANGLE (X) TO RADIANS, AND
!FIND SIN, COS AND TAN
PRINT "DEGREES", "RADIANS", "SINE", "COSINE","TANGENT"
FOR I% = 0% TO 5%
    READ X
    LET Y = X * 2 * PI / 360
    PRINT
    PRINT X ,Y ,SIN(Y) ,COS(Y) ,TAN(Y)
NEXT I%

DATA 0,10,20,30,360,45
END

Output

DEGREES       RADIANS       SINE          COSINE        TANGENT

 0             0             0             1             0

 10            .174533       .173648       .984808       .176327

 20            .349066       .34202        .939693       .36397

 30            .523599       .5            .866025       .57735

 360           6.28319       .174846E-06   1             .174846E-06

 45            .785398       .707107       .707107       1

The SQR function returns the square root of a number. For example:

PRINT SQR (2)

Output

1.41421

A logarithm is the exponent of some number (called a base). Common logarithms use the base 10. The common logarithm of a number n, for example, is the power to which 10 must be raised to equal n. For example, the common logarithm of 100 is 2, because 10 raised to the power 2 equals 100.

The LOG10 function returns a number's common logarithm. The following example calculates the common logarithms of all multiples of 10 from 10 to 100, inclusively:

FOR I% = 10% TO 100% STEP 10%
    PRINT LOG10(I%)
NEXT I%
END

Output

 1
 1.30103
 1.47712
 1.60206
 1.69897
 1.77815
 1.8451
 1.90309
 1.95424
 2

If you supply a floating-point argument to LOG10, the function returns a floating-point number of the same data type. If you supply an integer argument, LOG10 converts it to the default floating-point data type and returns a value of that type.

10.1.1.6 EXP Function

The EXP function returns the value of e raised to a specified power. The following example prints the value of e and e raised to the second power:

READ A,B
DATA 1,2
PRINT 'e RAISED TO THE POWER'; A; " EQUALS"; EXP(A)
PRINT 'e RAISED TO THE POWER'; B; " EQUALS"; EXP(B)
END

Output

e RAISED TO THE POWER 1 EQUALS 2.71828
e RAISED TO THE POWER 2 EQUALS 7.38906

If you supply a floating-point argument to EXP, the function returns a floating-point number of the same data type. If you supply an integer argument, EXP converts it to the default floating-point data type and returns a value of that type.

10.1.1.7 RND Function

The RND function returns a number greater than or equal to zero and less than 1. The RND function always returns a floating-point number of the default floating-point data type. The RND function generates seemingly unrelated numbers. However, given the same starting conditions, a computer always gives the same results. Each time you execute a program with the RND function, you receive the same results.

PRINT RND,RND,RND,RND
END

Output 1

 .76308      .179978      .902878      .88984

Output 2

 .76308      .179978      .902878      .88984

With the RANDOMIZE statement, you can change the RND function's starting condition and generate random numbers. To do this, place a RANDOMIZE statement before the line invoking the RND function. Note that the RANDOMIZE statement should be used only once in a program. With the RANDOMIZE statement, each invocation of RND returns a new and unpredictable number.

RANDOMIZE
PRINT RND,RND,RND,RND
END

Output 1

 .403732       .34971       .15302       .92462

Output 2

 .404165       .272398      .261667      .10209

The RND function can generate a series of random numbers over any open range. To produce random numbers in the open range A to B, use the following formula:

(B-A)*RND + A

The following program produces 10 numbers in the open range 4 to 6:

FOR I% = 1% TO 10%
    PRINT (6%-4%) * RND + 4
NEXT I%
END

Output

 5.52616
 4.35996
 5.80576
 5.77968
 4.77402
 4.95189
 5.76439
 4.37156
 5.2776
 4.53843

HP BASIC provides built-in functions that can perform the following:

• Convert a 1-character string to the character's ASCII value and vice versa
• Translate strings from one data format to another, for example, EBCDIC to ASCII

The following sections describe some of these functions.

10.1.2.1 ASCII Function

The ASCII function returns the numeric ASCII value of a string's first character. The ASCII function returns an integer value from 0 to 255, inclusive. For instance, in the following example, the PRINT statement prints the integer value 66 because this is the ASCII value equivalent of an uppercase B, the first character in the string:

test_string$ = "BAT"
PRINT ASCII(test_string$)
END

Output

 66

Note that the ASCII value of a null string is zero.

10.1.2.2 CHR$ Function

The CHR$ function returns the character whose ASCII value you supply. If the ASCII integer expression that you supply is less than zero or greater than 255, HP BASIC treats it as a modulo 256 value. HP BASIC treats the integer expression as the remainder of the actual supplied integer divided by 256. Therefore, CHR$(325) is equivalent to CHR$(69) and CHR$(-1) is equivalent to CHR$(255).

The following program outputs the character whose ASCII value corresponds to the input value modulo 256:

PRINT "THIS PROGRAM FINDS THE CHARACTER WHOSE"
PRINT "VALUE (MODULO 256) YOU TYPE"
INPUT value%
PRINT CHR$(value%)
END

Output 1

THIS PROGRAM FINDS THE CHARACTER WHOSE
VALUE (MODULO 256) YOU TYPE
 ? 69
E

Output 2

THIS PROGRAM FINDS THE CHARACTER WHOSE
VALUE (MODULO 256) YOU TYPE
 ? 1093
E

Numeric strings are numbers represented by ASCII characters. A numeric string consists of an optional sign, a string of digits, and an optional decimal point. You can use E notation in a numeric string for floating-point constants.

The following sections describe some of the HP BASIC numeric string functions.

10.1.3.1 FORMAT$ Function

The FORMAT$ function converts a numeric value to a string. The output string is formatted according to a string you provide. The expression you give this function can be any string or numeric expression. The format string must contain at least one PRINT USING format field. The formatting rules are the same as those for printing numbers with PRINT USING. See Chapter 14 for more information about the PRINT USING statement and formatting rules.

A = 5
B$ = "##.##"
Z$ = FORMAT$(A, B$)
PRINT Z$
END

Output

 5.00

The NUM$ function evaluates a numeric expression and returns a string of characters formatted as the PRINT statement would format it. The returned numeric string is preceded by one space for positive numbers and by a minus sign (-) for negative numbers. The numeric string is always followed by a space. For example:

PRINT NUM$(7465097802134)
PRINT NUM$(-50)
END

Output

 .74651E+13
-50

The NUM1$ function translates a number into a string of numeric characters. NUM1$ does not return leading or trailing spaces or E format. The following example shows the use of the NUM1$ function:

PRINT NUM1$(PI)
PRINT NUM1$(97.5 * 30456.23 + 30385.1)
PRINT NUM1$(1E-38)
END

Output

3.14159
2999870
.00000000000000000000000000000000000001

NUM1$ returns up to 6 digits of accuracy for SINGLE and SFLOAT real numbers, up to 16 digits of accuracy for DOUBLE numbers, up to 10 digits of accuracy for LONG integers, and up to 19 digits of accuracy for QUAD integers. NUM1$ returns up to 15 digits of accuracy for GFLOAT and TFLOAT numbers and up to 33 digits of accuracy for XFLOAT numbers.

The following example shows the difference between NUM$ and NUM1$:

A$ = NUM$(1000000)
B$ = NUM1$(1000000)
PRINT LEN(A$); "/"; A$; "/"
PRINT LEN(B$); "/"; B$; "/"
END

Output

 8 / .1E+07 /
 7 /1000000/

Note that A$ has a leading and trailing space.

10.1.3.3 VAL% and VAL Functions

The VAL% function returns the integer value of a numeric string. This numeric string expression must be the string representation of an integer. It can contain the ASCII characters 0 to 9, a plus sign (+), or a minus sign (-).

The VAL function returns the floating-point value of a numeric string. The numeric string expression must be the string representation of some number. It can contain the ASCII characters 0 to 9, a plus sign (+), a minus sign (-), or an uppercase E.

The VAL function returns a number of the default floating-point data type. HP BASIC signals "Illegal number" (ERR=52) if the argument is outside the range of the default floating-point data type.

The following is an example of VAL and VAL%:

A = VAL("922")
B$ = "100"
C% = VAL%(B$)
PRINT A
PRINT C%
END

Output

 922
 100

In BASIC, string arithmetic functions process numeric strings as arithmetic operands. This lets you add (SUM$), subtract (DIF$), multiply (PROD$), and divide (QUO$) numeric strings, and express them at a specified level of precision (PLACE$).

String arithmetic offers greater precision than floating-point arithmetic or longword integers and eliminates the need for scaling. However, string arithmetic executes more slowly than the corresponding integer or floating-point operations.

The operands for the functions can be numeric strings representing any integer or floating-point value (E notation is not valid). Table 10-1 shows the string arithmetic functions and their formats, and gives brief descriptions of what they do.

String arithmetic computations permit 56 significant digits. The functions QUO$, PLACE$, and PROD$, however, permit up to 60 significant digits. Table 10-2 shows how HP BASIC determines the precision permitted by each function and if that precision is implicit or explicit.

The SUM$ and DIF$ functions take the precision of the more precise argument in the function unless padded zeros generate that precision. SUM$ and DIF$ omit trailing zeros to the right of the decimal point.

The size and precision of results returned by the SUM$ and DIF$ functions depend on the size and precision of the arguments involved:

• The sum or difference of two integers takes the precision of the larger integer.
• The sum or difference of two decimal fractions takes the precision of the more precise fraction.
• The sum or difference of two real numbers takes precision as follows:
  • The sum or difference of the integer parts takes the precision of the larger part.
  • The sum or difference of the decimal fraction parts takes the precision of the more precise part.
• Trailing zeros are trunctated.

In the QUO$, PLACE$, and PROD$ functions, the value of the integer expression argument explicitly determines numeric precision. That is, the integer expression parameter determines the point at which the number is rounded or truncated.

If the integer expression is between -5000 and 5000, rounding occurs according to the following rules:

• For positive integer expressions, rounding occurs to the right of the decimal point. For example, if the integer expression is 1, rounding occurs one digit to the right of the decimal point (the number is rounded to the nearest tenth). If the integer expression is 2, rounding occurs two digits to the right of the decimal point (the number is rounded to the nearest hundredth), and so on.
• For zero, rounding occurs to the nearest unit.
• For negative integer expressions, rounding occurs to the left of the decimal point. For example, if the integer expression is -1, rounding occurs one place to the left of the decimal point. In this case, HP BASIC moves the decimal point one place to the left, then rounds to units. If the integer expression is -2, rounding occurs two places to the left of the decimal point; HP BASIC moves the decimal point two places to the left, then rounds to units.

Note that when rounding numeric strings, HP BASIC returns only part of the number.

If the integer expression is between 5001 and 15,000, the following rules apply:

• If the integer expression is 10,000, HP BASIC truncates the number at the decimal point.
• If the integer expression is greater than 10,000 (10,000 plus n), HP BASIC truncates the numeric string n places to the right of the decimal point. For example, if the integer expression is 10,001 (10,000 plus 1), HP BASIC truncates the number starting one place to the right of the decimal point. If the integer expression is 10,002 (10,000 plus 2), HP BASIC truncates the number starting two places to the right of the decimal point, and so on.
• If the integer expression is less than 10,000 (10,000 minus n) HP BASIC truncates the numeric string n places to the left of the decimal point. For example, if the integer expression is 9999 (10,000 minus 1), HP BASIC truncates the number starting one place to the left of the decimal point. If the integer expression is 9998 (10,000 minus 2), HP BASIC truncates starting two places to the left of the decimal point, and so on.

The PLACE$ function returns a numeric string, truncated or rounded according to an integer argument you supply.

The following example displays the use of the PLACE$ function with several different integer expression arguments:

number$ = "123456.654321"
FOR I% = -5% TO 5%
    PRINT PLACE$(number$, I%)
NEXT I%
PRINT
FOR I% = 9995 TO 10005
    PRINT PLACE$(number$, I%)
NEXT I%

Output

1
12
123
1235
12346
123457
123456.7
123456.65
123456.654
123456.6543
123456.65432

1
12
123
1234
12345
123456
123456.6
123456.65
123456.654
123456.6543
123456.65432

The PROD$ function returns the product of two numeric strings. The returned string's precision depends on the value you specify for the integer precision expression.

A$ = "-4.333"
B$ = "7.23326"
s_product$ = PROD$(A$, B$, 10005%)
PRINT s_product$
END

Output

-31.34171