# Compaq BASIC for OpenVMS
Alpha and VAX Systems
Reference Manual

Previous | Contents | Index

# STRING$

> The STRING$ function creates a string containing a specified number of identical characters.

## Format

## Syntax Rules

1. Int-exp1 specifies the character string's length.
2. Int-exp2 is the decimal ASCII value of the character that makes up the string. This value is treated modulo 256.

## Remarks

1. BASIC signals the error "String too long" (ERR=227) if int-exp1 is greater than 65535.
2. If int-exp1 is less than or equal to zero, BASIC treats it as zero.
3. BASIC treats int-exp2 as an unsigned 8-bit integer. For example, -1 is treated as 255.
4. If either int-exp1 or int-exp2 is a floating-point expression, BASIC truncates it to an integer.

## Example

    DECLARE STRING output_str
    output_str = STRING$(10%, 50%)  !50 is the ASCII value of the
    PRINT output_str                !character "2"

Output

    2222222222

# SUB

> The SUB statement marks the beginning of a BASIC subprogram and specifies the number and data type of its parameters.

## Format

## Syntax Rules

1. Note that both Alpha BASIC and VAX BASIC are able to pass actual parameters by value, but only Alpha BASIC allows formal parameters to be passed in by value.
2. Sub-name is the name of the separately compiled subprogram.
3. Formal-param specifies the number and type of parameters for the arguments the SUB subprogram expects to receive when invoked.
   - Empty parentheses indicate that the SUB subprogram has no parameters.
   - 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. When you do specify a data type, all following parameters are of that data type until you specify a new data type. Data type keywords and their size, range, and precision are listed in Table 1-2.
4. Sub-name can have 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.
5. Data-type can be any BASIC data type keyword or a data type defined by a RECORD statement.
6. Pass-mech specifies the parameter passing mechanism by which the subprogram receives arguments.
7. A pass-mech clause outside the parentheses applies by default to all SUB parameters. A pass-mech clause in the formal-param list overrides the specified default and applies only to the immediately preceding parameter.

## Remarks

1. The SUB statement must be the first statement in the SUB subprogram.
2. Compiler directives and comment fields created with an exclamation point (!), can precede the SUB statement because they are not BASIC statements. Note that REM is a BASIC statement; therefore, it cannot precede the SUB statement.
3. Every SUB statement must have a corresponding END SUB statement or SUBEND statement.
4. If you do not specify a passing mechanism, the SUB program receives arguments by the default passing mechanisms.
5. Parameters defined in formal-param must agree in number, type, ordinality, and passing mechanism with the arguments specified in the CALL statement of the calling program.
6. You can specify up to 255 parameters.
7. Any BASIC statement except those that refer to other program unit types (FUNCTION, PICTURE or PROGRAM) can appear in a SUB subprogram.
8. All variables, except those named in MAP and COMMON statements are local to that subprogram.
9. BASIC initializes local variables to zero or the null string.
10. SUB subprograms receive parameters by reference, by descriptor, or by value.
    - BY REF specifies that the subprogram receives the argument's address.
    - BY DESC specifies that the subprogram receives the address of a BASIC descriptor. For information about the format of a BASIC descriptor for strings and arrays, see the Compaq BASIC for OpenVMS Alpha and VAX Systems User Manual. For information about other types of descriptors, see the VAX Architecture Handbook.
    - BY VALUE specifies that the subprogram receives a copy of the argument value.
      Note that both Alpha BASIC and VAX BASIC are able to pass actual parameters by value, but only Alpha BASIC allows formal parameters to be passed in by value.
11. By default, BASIC subprograms receive numeric unsubscripted variables by reference, and all other parameters by descriptor. You can override these defaults for strings and arrays with a BY clause:
    - If you specify a string length with the =int-const clause, you must also specify BY REF. If you specify BY REF and do not specify a string length, BASIC uses the default string length of 16.
    - If you specify array bounds, you must also specify BY REF.
12. Subprograms can be called recursively.

## Example

    SUB SUB3 BY REF (DOUBLE A, B,      &
        STRING Emp_nam BY DESC,        &
        wage(20))
       .
       .
       .
    END SUB

# SUBEND

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

## Format

# SUBEXIT

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

## Format

# SUM$

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

## Format

## Syntax Rules

None

## Remarks

1. The SUM$ function does not support E-format notation.
2. Each string expression can contain up to 60 ASCII digits and an optional decimal point and sign.
3. BASIC adds str-exp2 to str-exp1 and stores the result in str-var.
4. If str-exp1 and str-exp2 are integers, str-var takes the precision of the larger string unless trailing zeros generate that precision.
5. 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.
6. SUM$ omits trailing zeros to the right of the decimal point.
7. 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.
8. 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

# SWAP%

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

Note The SWAP% function is supported only for compatibility with BASIC-PLUS-2. It is recommended that you do not use the SWAP% function for new program development.

## Format

## Syntax Rules

None

## Remarks

1. SWAP% is a WORD function. BASIC evaluates int-exp and converts it to the WORD data type, if necessary.
2. 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

# TAB

> 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

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

## Remarks

1. You cannot tab beyond the current MARGIN restriction.
2. The leftmost column position is zero.
3. If int-exp is less than the current cursor position, the TAB function has no effect.
4. The TAB function can move the cursor or print mechanism only from the left to the right.
5. You can use more than one TAB function in the same PRINT statement.
6. Use semicolons to separate multiple TAB functions in a single statement. If you use commas, BASIC moves to the next print zone before executing the TAB function.
7. If you specify a floating-point expression for int-exp, 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

# TAN

> 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

BASIC expects the argument of the TAN function to be a real expression. When the argument is a real expression, BASIC returns a value of the same floating-point size. When the argument is not a real expression, 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

# TIME

> 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

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

Table 4-6 TIME Function Values
Argument Value | 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

# TIME$

> 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 since midnight.

## Remarks

1. If int-exp equals zero, TIME$ returns the current time of day.
2. The value of int-exp must be from 0 to 1440 or BASIC signals an error.
3. 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.
4. If you specify a floating-point expression for int-exp, BASIC truncates it to an integer.

## Example

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

Output

    01:51 PM

# TRM$

> 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

# UBOUND

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

## Format

## Syntax Rules

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

## Remarks

1. If you do not specify a numeric expression, BASIC automatically returns the upper bound of the first dimension.
2. If you specify a numeric expression that is less than or equal to zero, BASIC signals an error message.
3. If you specify a numeric expression that exceeds the number of dimensions, 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

# UNLESS

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

## Format

## Syntax Rules

None

## Remarks

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

## Example

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

# UNLOCK

> 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

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

## Example

    UNLOCK #10%

# UNTIL

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

## Format

## Syntax Rules

None

## Remarks

1. Conditional
   - A NEXT statement must end the UNTIL loop.
   - BASIC evaluates cond-exp before each loop iteration. If the expression is false (value zero), BASIC executes the loop. If the expression is true (value nonzero), control passes to the first executable statement after the NEXT statement.
2. Statement Modifier
   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

Previous | Next | Contents | Index