# Compaq BASIC for OpenVMS
Alpha and VAX Systems
Reference Manual

Previous | Contents | Index

    DECLARE STRING Z,N,record_string
    INPUT LINE "Type two words", Z$,'Type your name';N$
    INPUT LINE #4%, record_string$

# INSTR

> The INSTR function searches for a substring within a string. It returns the position of the substring's starting character.

## Format

## Syntax Rules

1. Int-exp specifies the character position in the main string at which BASIC starts the search.
2. Str-exp1 specifies the main string.
3. Str-exp2 specifies the substring.

## Remarks

1. The INSTR function searches str-exp1, the main string, for the first occurrence of a substring, str-exp2, and returns the position of the substring's first character.
2. INSTR returns the character position in the main string at which BASIC finds the substring, except in the following situations:
   - If only the substring is null, and if int-exp is less than or equal to zero, INSTR returns a value of 1.
   - If only the substring is null, and if int-exp is equal to or greater than 1 and less than or equal to the length of the main string, INSTR returns the value of int-exp.
   - If only the substring is null, and if int-exp is greater than the length of the main string, INSTR returns the main string's length plus 1.
   - If the substring is not null, and if int-exp is greater than the length of the main string, INSTR returns a value of zero.
   - If only the main string is null, INSTR returns a value of zero.
   - If both the main string and the substring are null, INSTR returns a 1.
3. If BASIC cannot find the substring, INSTR returns a value of zero.
4. If int-exp does not equal 1, BASIC still counts from the beginning of the main string to calculate the starting position of the substring. That is, BASIC counts character positions starting at position 1, regardless of where you specify the start of the search. For example, if you specify 10 as the start of the search and BASIC finds the substring at position 15, INSTR returns the value 15.
5. If int-exp is less than 1, BASIC assumes a starting position of 1.
6. If you specify a floating-point expression for int-exp, BASIC truncates it to an integer of the default size.

## Example

    DECLARE STRING alpha,   &
            INTEGER result
    alpha = "ABCDEF"
    result = INSTR(1,alpha,"DEF")
    PRINT result

Output

     4

# INT

> The INT function returns the floating-point value of the largest whole number less than or equal to a specified expression.

## Format

## Syntax Rules

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

## Remarks

If real-exp is negative, BASIC returns the largest whole number less than or equal to real-exp. For example, INT(-5.3) is -6.

## Examples

Example 1

    DECLARE SINGLE any_num, result
    any_num = 6.667
    result = INT(any_num)
    PRINT result

Output

     6

Example 2

    !This example contrasts the INT and FIX functions
    DECLARE SINGLE test_num
    test_num = -32.7
    PRINT "INT OF -32.7 IS: "; INT(test_num)
    PRINT "FIX OF -32.7 IS: "; FIX(test_num)

Output

    INT OF -32.7 IS: -33
    FIX OF -32.7 IS: -32

# INTEGER

> The INTEGER function converts a numeric expression or numeric string to a specified or default INTEGER data type.

## Format

## Syntax Rules

Exp can be either numeric or string. A string expression can contain the ASCII digits 0 to 9, a plus sign (+), or a minus sign (-).

## Remarks

1. BASIC evaluates exp, then converts it to the specified INTEGER size. If you do not specify a size, BASIC uses the default INTEGER size.
2. If exp is a string, BASIC ignores leading and trailing spaces and tabs.
3. The INTEGER function returns a value of zero when a string argument contains only spaces and tabs, or when it is null.
4. The INTEGER function truncates the decimal portion of REAL and DECIMAL numbers, or rounds if the /ROUND_DECIMAL qualifier is used.

## Example

    INPUT "Enter a floating-point number";F_P
    PRINT INTEGER(F_P, WORD)

Output

    Enter a floating-point number? 76.99
     76

# ITERATE

> The ITERATE statement allows you to explicitly reexecute a loop.

## Format

## Syntax Rules

1. Label is the label of the first statement of a FOR...NEXT, WHILE, or UNTIL loop.
2. Label must conform to the rules for naming variables.

## Remarks

1. ITERATE is equivalent to an unconditional branch to the current loop's NEXT statement. If you supply a label, ITERATE transfers control to the NEXT statement in the specified loop. If you do not supply a label, ITERATE transfers control to the current loop's NEXT statement.
2. The ITERATE statement can be used only within a FOR...NEXT, WHILE, or UNTIL loop.

## Example

    WHEN ERROR IN
    Date_loop:  WHILE 1% = 1%
                      GET #1
                      ITERATE Date_loop IF Day$ <> Today$
                      ITERATE Date_loop IF Month$ <> This_month$
                      ITERATE Date_loop IF Year$ <> This_year$
                      PRINT Item$
                NEXT
    USE
       IF ERR = 11
       THEN
                CONTINUE DONE
       ELSE
                EXIT HANDLER
       END IF
    END WHEN
    Done:  END

# KILL

> The KILL statement deletes a disk file, removes the file's directory entry, and releases the file's storage space.

## Format

## Syntax Rules

File-spec can be a quoted string constant, a string variable, or a string expression. It cannot be an unquoted string constant.

## Remarks

1. The KILL statement marks a file for deletion but does not delete the file until all users have closed it.
2. If you do not specify a complete file specification, BASIC uses the default device and directory. If you do not specify a file version, BASIC deletes the highest version of the file.
3. The file must exist, or BASIC signals an error.
4. You can delete a file in another directory if you have access to that directory and privilege to delete the file.

## Example

    KILL "TEMP.DAT"

# LBOUND

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

## Format

## Syntax Rules

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

## Remarks

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

## Example

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

Output

    1
    2
    3
    4
    5
    6

# LEFT$

> The LEFT$ function extracts a specified substring from a string's left side, leaving the main string unchanged.

## Format

## Syntax Rules

1. Int-exp specifies the number of characters to be extracted from the left side of str-exp.
2. If you specify a floating-point expression for int-exp, BASIC truncates it to an integer of the default size.

## Remarks

1. The LEFT$ function extracts a substring from the left of the specified str-exp and stores it in str-var.
2. If int-exp is less than 1, LEFT$ returns a null string.
3. If int-exp is greater than the length of str-exp, LEFT$ returns the entire string.

## Example

    DECLARE STRING sub_string, main_string
    main_string = "1234567"
    sub_string = LEFT$(main_string, 4)
    PRINT sub_string

Output

    1234

# LEN

> The LEN function returns an integer value equal to the number of characters in a specified string.

## Format

## Syntax Rules

None

## Remarks

1. If str-exp is null, LEN returns a value of zero.
2. The length of str-exp includes leading, trailing, and embedded blanks. Tabs in str-exp are treated as a single space.
3. The value returned by the LEN function is a LONG integer.

## Example

    DECLARE STRING alpha, &
            INTEGER length
    alpha = "ABCDEFG"
    length = LEN(alpha)
    PRINT length

Output

     7

# LET

> The LET statement assigns a value to one or more variables.

## Format

## Syntax Rules

1. Var cannot be a DEF or FUNCTION name unless the LET statement occurs inside that DEF block or in that FUNCTION subprogram.
2. The keyword LET is optional.

## Remarks

1. You cannot assign string data to a numeric variable or unquoted numeric data to a string variable.
2. The value assigned to a numeric variable is converted to the variable's data type. For example, if you assign a floating-point value to an integer variable, BASIC truncates the value to an integer.
3. For dynamic strings, the destination string's length equals the source string's length.
4. When you assign a value to a fixed-length string variable (a variable declared in a COMMON, MAP, or RECORD statement), the value is left-justified and padded with spaces or truncated to match the length of the string variable.

## Example

    DECLARE STRING alpha, &
            INTEGER length
    LET alpha = "ABCDEFG"
    LET length = LEN(alpha)
    PRINT length

Output

     7

# LINPUT

> The LINPUT statement assigns a string value, without line terminators, from a terminal or terminal-format file to a string variable.

## Format

## Syntax Rules

1. Chnl-exp is a numeric expression that specifies a channel number associated with a file. It must be immediately preceded by a number sign (#).
2. Str-var1 and str-var2 cannot be DEF function names unless the LINPUT statement is inside the multiline DEF that defines the function.
3. You can include more than one string constant in a LINPUT statement. Str-const1 is issued for str-var1, str-const2 for str-var2, and so on.
4. The separator (comma or semicolon) that directly follows str-var1 and str-var2 has no formatting effect. BASIC always advances to a new line when you terminate input with a carriage return.
5. The separator character that directly follows str-const1 and str-const2 determines where the question mark (if requested) is displayed and where the cursor is positioned for input.
   - A comma causes BASIC to skip to the next print zone to display the question mark unless a SET NO PROMPT statement has been executed. For example:

         DECLARE STRING your_name
         LINPUT "Name",your_name

     Output

         Name             ?

   - A semicolon causes BASIC to display the question mark next to str-const unless a SET NO PROMPT statement has been executed. For example:

         DECLARE STRING your_name
         LINPUT "What is your name";your_name

     Output

         What is your name?

6. BASIC always advances to a new line when you terminate input with a carriage return.

## Remarks

1. The default chnl-exp is #0 (the controlling terminal). If you specify a channel, the file associated with that channel must have been opened with ACCESS READ or MODIFY.
2. BASIC signals an error if the LINPUT statement has no argument.
3. If input comes from a terminal, BASIC displays the contents of str-const1, if present. If the terminal is open on channel #0, BASIC also displays a question mark (?).
4. You can disable the question mark prompt by using the SET NO PROMPT statement. See the SET PROMPT statement for more information.
5. The LINPUT statement assigns all characters except any line terminators to str-var1 and str-var2. Single and double quotation marks, commas, tabs, leading and trailing spaces, or other special characters in the string are part of the data.
6. If the RETRY, CONTINUE, or RESUME statement transfers control to a LINPUT statement, the LINPUT statement retrieves a new record regardless of any data left in the previous record.
7. After a successful LINPUT statement, the RECOUNT variable contains the number of bytes transferred from the file or terminal to the record buffer.
8. If you terminate input text with Ctrl/Z, BASIC assigns the value to the variable and signals "End of file on device" (ERR=11) when the next terminal input statement executes. If you are in the VAX BASIC Environment and there is no next INPUT, INPUT LINE, or LINPUT statement in the program, the Ctrl/Z is passed to BASIC as a signal to exit the VAX BASIC Environment.

## Example

    DECLARE STRING last_name
    LINPUT "ENTER YOUR LAST NAME";Last_name
    LINPUT #2%, Last_name

# LOC

> The LOC function returns a longword integer specifying the virtual address of a simple or subscripted variable, or the address of an external function. For dynamic strings, the LOC function returns the address of the descriptor rather than the address of the data.

## Format

## Syntax Rules

1. Var can be any local or external, simple or subscripted variable.
2. Var cannot be a virtual array element.
3. Ext-routine can be the name of an external function.

## Remarks

1. The LOC function always returns a LONG value.
2. The LOC function is useful for passing the address of an external function as a parameter to a procedure. When passing a routine address as a parameter, you should usually pass the address by value. For example, OpenVMS system services expect to receive AST procedure entry masks by reference; therefore, the address of the entry mask should be in the argument list on the stack.

## Example

    DECLARE INTEGER A, B
    A = 12
    B = LOC(A)
    PRINT B

Output

     2146799372

# LOG

> The LOG function returns the natural logarithm (base e) of a specified number. The LOG function is the inverse of the EXP function.

## Format

## Syntax Rules

None

## Remarks

1. Real-exp must be greater than zero. An attempt to find the logarithm of zero or a negative number causes BASIC to signal "Illegal argument in LOG" (ERR=53).
2. The LOG function uses the mathematical constant e as a base. VAX BASIC approximates e to be 2.718281828459045 (double precision); Alpha BASIC approximates e to be 2.71828182845905.
3. The LOG function returns the exponent to which e must be raised to equal real-exp.
4. BASIC expects the argument of the LOG 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

    DECLARE SINGLE exponent
    exponent = LOG(98.6)
    PRINT exponent

Output

     4.59107

# LOG10

> The LOG10 function returns the common logarithm (base 10) of a specified number.

## Format

## Syntax Rules

None

## Remarks

1. Real-exp must be larger than zero. An attempt to find the logarithm of zero or a negative number causes BASIC to signal "Illegal argument in LOG" (ERR=53).
2. The LOG10 function returns the exponent to which 10 must be raised to equal real-exp.
3. BASIC expects the argument of the LOG10 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

    DECLARE SINGLE exp_base_10
    exp_base_10 = LOG10(250)
    PRINT exp_base_10

Output

     2.39794

Previous | Next | Contents | Index