# Compaq BASIC for OpenVMS
Alpha and VAX Systems
Reference Manual

Previous | Contents | Index

Example 3

    MAP (OWNERKEYS) STRING owner_id = 6, dog_reg_no = 7,    &
             last_name = 25, first_name = 20

    OPEN "OWNERS.IND" FOR OUTPUT AS FILE #1,                &
             ORGANIZATION INDEXED,                          &
             PRIMARY KEY (owner_id),                        &
             ALTERNATE KEY (last_name) DUPLICATES CHANGES,  &
             ALTERNATE (dog_reg_no) DESCENDING,             &
             MAP OWNERKEYS

The MAP statement describes the three string variables used as index keys in the file OWNERS.IND. The OPEN statement declares an indexed file with two alternate keys in addition to the primary key. The alternate key dog_reg_no is a DESCENDING key; the other keys are ASCENDING by default.

# OPTION

> The OPTION statement allows you to set compilation qualifiers such as default data type, size, and scale factor. You can also set compilation conditions such as severity of run-time errors to handle, constant type checking, subscript checking, overflow checking, decimal rounding, and setup in a source program. The options you set affect only the program module in which the OPTION statement occurs.

## Format

## Syntax Rules

None

## Remarks

1. Option-clause specifies the compilation qualifiers to be in effect for the program module.
2. Angle-clause specifies whether angles are to be evaluated in radians or in degrees. If you do not specify an angle-clause, BASIC uses radians as the default.
3. Handle-clause specifies the severity level of the errors that are to be handled by an error handler.
   - If you do not specify an OPTION HANDLE statement, BASIC uses OPTION HANDLE = BASIC as the default. Only those errors that can be trapped and that map onto a BASIC ERR value will transfer control to the current error handler. See the Compaq BASIC for OpenVMS Alpha and VAX Systems User Manual for a list of BASIC run-time errors.
   - If you specify a severity level, all errors of the specified severity or less, whether or not they can be trapped, transfer control to the current error handler. This includes non BASIC errors. For example, OPTION HANDLE = ERROR implies ERROR, WARNING, and INFORMATIONAL errors but not SEVERE errors.
   - If you specify OPTION HANDLE = SEVERE, you can handle fatal errors. However, in most cases, a fatal error indicates that the program environment is badly corrupted and you should not continue program execution.
4. Const-type-clause specifies the data type for all constants that do not end in a data type suffix or are not in explicit literal notation with a data type supplied.
5. Type-clause sets the default data type for variables that have not been explicitly declared and for constants if no constant type clause is specified. You can specify only one type-clause in a program module.
6. Size-clause sets the default data subtypes for floating-point, integer, and packed decimal data. Size-item specifies the data subtype you want to set. You can specify an INTEGER, REAL or DECIMAL size-item, or a combination. Multiple size-items in an OPTION statement must be enclosed in parentheses and separated by commas.
7. SCALE controls the scaling of double precision floating-point variables. Int-const specifies the power of 10 you want as the scaling factor. It must be an integer from 0 to 6 or BASIC signals an error. See the description of the SCALE command in Chapter 2 for more information about scaling.
8. OLD VERSION = CDD is provided for compatibility with previous versions of BASIC. When bounds are specified in the CDD array, BASIC changes the lower bound to zero and adjusts the upper bound of the array. By default, if you do not specify OLD VERSION = CDD, BASIC compiles the program with the bounds specified in the CDD data definition.
9. Active-clause specifies the decimal rounding, integer and decimal overflow checking, setup, and subscript checking conditions you want in effect for the program module. Active-item specifies the conditions you want to set. Multiple active-items in an OPTION statement must be enclosed in parentheses and separated by commas.
   ACTIVE specifies the conditions that are to be in effect for a particular program module. INACTIVE specifies the conditions that are not to be in effect for a particular program module. If a condition does not appear in an active-clause, BASIC uses the current environment default for the condition.
   See the description of the COMPILE command in Chapter 2 and the Compaq BASIC for OpenVMS Alpha and VAX Systems User Manual for more information about the INTEGER_OVERFLOW, DECIMAL_OVERFLOW, SETUP, DECIMAL_ROUNDING, and SUBSCRIPT_CHECKING compilation qualifiers. These qualifiers correspond to active-clause conditions (INTEGER OVERFLOW, DECIMAL OVERFLOW, SETUP, DECIMAL ROUNDING, and SUBSCRIPT CHECKING).
10. You can have more than one option in an OPTION statement, or you can use multiple OPTION statements in a program module. However, each OPTION statement must lexically precede all other source code in the program module, with the exception of comment fields, REM, PICTURE, PROGRAM, SUB, FUNCTION, and OPTION statements.
11. OPTION statement specifications apply only to the program module in which the statement appears and affect all variables in the module, including SUB and FUNCTION parameters.
12. BASIC signals an error in the case of conflicting options. For example, you cannot specify more than one type-clause or SCALE factor in the same program unit.
13. If you do not specify a type-clause or a subtype-clause, BASIC uses the current environment default data types.
14. If you do not specify a scale factor, BASIC uses the current environment default scale factor.

## Example

    FUNCTION REAL DOUBLE monthly_payment,                   &
            (DOUBLE interest_rate,                          &
              LONG   no_of_payments,                        &
              DOUBLE principle)
    OPTION TYPE = REAL,                                     &
           SIZE = (REAL DOUBLE, INTEGER LONG),              &
           SCALE = 4

# PLACE$

> The PLACE$ function explicitly changes the precision of a numeric string. PLACE$ returns a numeric string, truncated or rounded, according to the value of an integer argument you supply.

## Format

## Syntax Rules

1. Str-exp specifies the numeric string you want to process. It can contain an optional minus sign (-), ASCII digits, and an optional decimal point.
2. Int-exp specifies the numeric precision of str-exp. Table 4-4 shows examples of rounding and truncation and the values of int-exp that produce them.

## Remarks

1. The PLACE$ function does not support E-format notation.
2. If str-exp has more than 60 characters, BASIC signals the error "Illegal number" (ERR=52).
3. Str-exp is rounded or truncated, or both, according to the value of int-exp.
4. If int-exp is from -60 to 60, rounding and truncation occur as follows:
   - For positive integer expressions, rounding occurs to the right of the decimal place. For example, if int-exp is 1, rounding occurs one digit to the right of the decimal place (the number is rounded to the nearest tenth). If int-exp is 2, rounding occurs two digits to the right of the decimal place (the number is rounded to the nearest hundredth), and so on.
   - If int-exp is zero, BASIC rounds to the nearest unit.
   - For negative integer expressions, rounding occurs to the left of the decimal point. If int-exp is -1, for example, BASIC moves the decimal point one place to the left, then rounds to units. If int-exp is -2, rounding occurs two places to the left of the decimal point; BASIC moves the decimal point two places to the left, then rounds to tens.
5. If int-exp is from 9940 to 10,060, truncation occurs as follows:
   - If int-exp is 10,000, BASIC truncates the number at the decimal point.
   - If int-exp is greater than 10,000 (10,000 plus n), BASIC truncates the numeric string n places to the right of the decimal point. For example, if int-exp is 10,001 (10,000 plus 1), BASIC truncates the number starting one place to the right of the decimal point. If int-exp is 10,002 (10,000 plus 2), BASIC truncates the number starting two places to the right of the decimal point, and so on.
   - If int-exp is less than 10,000 (10,000 minus n), BASIC truncates the numeric string n places to the left of the decimal point. For example, if int-exp is 9999 (10,000 minus 1), BASIC truncates the number starting one place to the left of the decimal point. If int-exp is 9998 (10,000 minus 2), BASIC truncates starting two places to the left of the decimal point, and so on.
6. If int-exp is not from -60 to 60 or 9940 to 10,060, BASIC returns a value of zero.
7. If you specify a floating-point expression for int-exp, BASIC truncates it to an integer of the default size.
8. Table 4-4 shows examples of rounding and truncation and the values of int-exp that produce them. The number used is 123456.654321.

Table 4-4 Rounding and Truncation of 123456.654321
Int-exp | Effect | Value Returned
--- | --- | ---
-5 | Rounded to 100,000s and truncated | 1
-4 | Rounded to 10,000s and truncated | 12
-3 | Rounded to 1000s and truncated | 123
-2 | Rounded to 100s and truncated | 1235
-1 | Rounded to 10s and truncated | 12346
0 | Rounded to units and truncated | 123457
1 | Rounded to tenths and truncated | 123456.7
2 | Rounded to hundredths and truncated | 123456.65
3 | Rounded to thousandths and truncated | 123456.654
4 | Rounded to ten-thousandths and truncated | 123456.6543
5 | Rounded to hundred-thousandths and truncated | 123456.65432
9,995 | Truncated to 100,000s | 1
9,996 | Truncated to 10,000s | 12
9,997 | Truncated to 1000s | 123
9,998 | Truncated to 100s | 1234
9,999 | Truncated to 10s | 12345
10,000 | Truncated to units | 123456
10,001 | Truncated to tenths | 12345.6
10,002 | Truncated to hundredths | 123456.65
10,003 | Truncated to thousandths | 123456.654
10,004 | Truncated to ten-thousandths | 123456.6543
10,005 | Truncated to hundred-thousandths | 123456.65432

## Example

    DECLARE STRING str_exp, str_var
    str_exp = "9999.9999"
    str_var = PLACE$(str_exp,3)
    PRINT str_var

Output

    10000

# POS

> The POS function searches for a substring within a string and returns the substring's starting character position.

## Format

## Syntax Rules

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

## Remarks

1. The POS function searches str-exp1, the main string, for the first occurrence of str-exp2, the substring, and returns the position of the substring's first character.
2. If int-exp is greater than the length of the main string, POS returns a value of zero.
3. POS always returns the character position in the main string at which BASIC finds the substring, with the following exceptions:
   - If only the substring is null, and if int-exp is less than or equal to zero, POS 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, POS 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, POS returns the main string's length plus 1.
   - If only the main string is null, POS returns a value of zero.
   - If both the main string and the substring are null, POS returns 1.
4. If BASIC cannot find the substring, POS returns a value of zero.
5. If int-exp is less than 1, BASIC assumes a starting position of 1.
6. If int-exp does not equal 1, BASIC still counts from the string's beginning 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, POS returns the value 15.
7. If you know that the substring is not near the beginning of the string, specifying a starting position greater than 1 speeds program execution by reducing the number of characters BASIC must search.
8. If you specify a floating-point expression for int-exp, BASIC truncates it to an integer of the default size.

## Example

    DECLARE STRING main_str,   &
                   sub_str
    DECLARE INTEGER  first_char
    main_str = "ABCDEFG"
    sub_str = "DEF"
    first_char = POS(main_str, sub_str, 1)
    PRINT first_char

Output

     4

# PRINT

> The PRINT statement transfers program data to a terminal or a terminal-format file.

## 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 (#). If you do not specify a channel, BASIC prints to the controlling terminal.
2. Output-list specifies the expressions to be printed and the print format to be used.
3. Exp can be any valid expression.
4. A separator character (comma or semicolon) must separate each exp. Separator characters control the print format as follows:
   - A comma (,) causes BASIC to skip to the next print zone before printing the expression.
   - A semicolon (;) causes BASIC to print the expression immediately after the previous expression.

## Remarks

1. A terminal or terminal-format file must be open on the specified channel. (Your current terminal is always open on channel #0.)
2. A PRINT line has an integral number of print zones. Note, however, that the number of print zones in a line differs from terminal to terminal.
3. The right margin setting, if set by the MARGIN statement, controls the width of the PRINT line. The default right margin is 72.
4. The PRINT statement prints string constants and variables exactly as they appear, with no leading or trailing spaces.
5. BASIC prints quoted string literals exactly as they appear. Therefore, you can print quotation marks, commas, and other characters by enclosing them in quotation marks.
6. A PRINT statement with no output-list prints a blank line.
7. An expression in the output-list can be followed by more than one separator character. That is, you can omit an expression and specify where the next expression is to be printed by the use of multiple separator characters. For example:

       PRINT "Name",,"Address and ";"City"

   Output

       Name                       Address and City

   In this example, the double commas after "Name" cause BASIC to skip two print zones before printing "Address and ". The semicolon causes the next expression, "City", to be printed immediately after the preceding expression. Multiple semicolons have the same effect as a single semicolon.
8. When printing numeric fields, BASIC precedes each number with a space or minus sign (-) and follows it with a space.
9. BASIC does not print trailing zeros to the right of the decimal point. If all digits to the right of the decimal point are zeros, BASIC omits the decimal point as well.
10. For REAL numbers (SINGLE, DOUBLE, GFLOAT, SFLOAT, TFLOAT, XFLOAT, and HFLOAT), BASIC does not print more than 6 digits in explicit notation. If a number requires more than 6 digits, BASIC uses E format and precedes positive exponents with a plus sign (+). BASIC rounds a floating-point number with a magnitude from 0.1 to 1.0 to 6 digits. For magnitudes smaller than 0.1, BASIC rounds the number to 6 digits and prints it in E format.
11. The PRINT statement can print up to:
    - Three digits of precision for BYTE integers
    - Five digits of precision for WORD integers
    - Ten digits of precision for LONG integers
    - Nineteen digits of precision for QUAD integers
    - Thirty-one digits of precision for DECIMAL numbers
    - The string length for STRING values
    BASIC prints both INTEGER and DECIMAL values according to the previous rules. However, for REAL values, BASIC displays a maximum of 6 digits.
12. If there is a comma or semicolon following the last item in output-list, BASIC does the following:
    - When printing to a terminal, BASIC does not generate a line terminator after printing the last item. The next item printed with a PRINT statement is printed at the position specified by the separator character following the last item in the first PRINT statement.
    - When printing to a terminal-format file, BASIC does not write out the record until a PRINT statement without trailing punctuation executes.
13. If no punctuation follows the last item in the output-list, BASIC does the following:
    - When printing to a terminal, BASIC generates a line terminator after printing the last item.
    - When printing to a terminal-format file, BASIC writes out the record after printing the last item.
14. If a string field does not fit on the current line, BASIC does the following:
    - When printing string elements to a terminal, BASIC prints as much as will fit on the current line and prints the remainder on the next line.
    - When printing string elements to a terminal-format file, BASIC prints the entire element on the next line.
15. If a numeric field is the first field in a line, and the numeric field spans more than one line, BASIC prints part of the number on one line and the remainder on the next; otherwise, numeric fields are never split across lines. If the entire field cannot be printed at the end of one line, the number is printed on the next line.
16. When a number's trailing space does not fit in the last print zone, the number is printed without the trailing space.

## Example

    PRINT "name "; "age", "height "; "weight"

Output

    name age       height weight

Previous | Next | Contents | Index