# Compaq BASIC for OpenVMS
Alpha and VAX Systems
Reference Manual

Previous | Contents | Index

# SET

> The SET command allows you to specify VAX BASIC defaults for all VAX BASIC qualifiers. Qualifiers control the compilation process and the run-time environment. The defaults you set remain in effect for all subsequent operations until they are reset or until you exit from the compiler.

## Format

## Syntax Rules

1. /Qualifier specifies a qualifier keyword that sets a BASIC default. See the COMPILE command for a list of all BASIC qualifiers and their defaults.
2. VAX BASIC signals the error "Unknown qualifier" if you do not separate multiple qualifiers with commas (,) or slashes (/), or if you mix commas and slashes on the same command line. The same error is signaled if you separate qualifiers with a slash but do not prefix the first qualifier with a slash.

## Remarks

If you do not specify any qualifiers, VAX BASIC resets all defaults to the defaults specified with the DCL command BASIC.

## Examples

Example 1

    SET /DOUBLE/BYTE/LIST

Example 2

    SET DOUBLE,BYTE,LIST

In these examples, the SET command causes VAX BASIC to allocate 64 bits of storage for all floating-point data, and to allocate 8 bits of storage for all integer data. A source listing file is also created.

# SHOW

> The SHOW command displays the current defaults for the VAX BASIC compiler on your terminal.

## Format

## Syntax Rules

None

## Remarks

None

## Example

    SHOW
    VAX BASIC n.n     Current Environment Status    dd-mmm-yyyy hh:mm:ss.cc
    DEFAULT DATA TYPE INFORMATION:           LISTING FILE INFORMATION INCLUDES:
        Data type : REAL                        NO List
        Real size : SINGLE                      NO Cross reference
        Integer size : LONG                        CDD Definitions
        Decimal size : (15,2)                      Environment
        Scale factor : 0                        NO Override of %NOLIST
        NO Round decimal numbers                NO Machine code
                                                   Map
    COMPILATION QUALIFIERS IN EFFECT:              INCLUDE files
           Object file
           Overflow check integers           FLAGGERS:
           Overflow check decimal numbers       NO Declining features
           Bounds checking                      NO BASIC PLUS 2 subset
        NO Syntax checking                      NO Alpha AXP subset
           Line
           Variant : 0                       DEBUG INFORMATION:
           Warnings                                Traceback records
           Informationals                       NO Debug symbol records
           Setup
           Object Libraries : NONE
    Ready

# UNSAVE

> The UNSAVE command deletes a specified file from storage.

## Format

## Syntax Rules

None

## Remarks

1. If you do not supply a file-spec, VAX BASIC deletes a file that has the file name of the program currently in memory and a file type of .BAS.
2. If you do not supply a file-spec and do not have a program in memory, VAX BASIC searches for the default file NONAME.BAS.
3. If you do not specify a complete file name with a file type, VAX BASIC deletes the file with the specified name and the .BAS file type from the default device and directory. Other file types with the same file name are not deleted.

## Example

    UNSAVE DB2:CHECK.DAT

# Chapter 3
Compiler Directives

Compiler directives are instructions that cause BASIC to perform certain operations as it translates the source program. This chapter describes all of the compiler directives supported by BASIC. The directives are listed and discussed alphabetically.

# %ABORT

> The %ABORT directive terminates program compilation and displays a fatal error message that you can supply.

## Format

## Syntax Rules

None

## Remarks

1. Only a line number or a comment field can appear on the same physical line as the %ABORT directive.
2. BASIC stops the compilation and terminates the listing file as soon as it encounters a %ABORT directive. An optional str-lit is displayed on the terminal screen and in the compilation listing, if a listing has been requested.

## Example

    %IF %VARIANT = 2 %THEN
        %ABORT "Cannot compile with variant 2"
    %END %IF

# %CROSS

> The %CROSS directive causes BASIC to begin or resume accumulating cross-reference information for the listing file.

## Format

## Syntax Rules

None

## Remarks

1. Only a line number or a comment field can appear on the same physical line as the %CROSS directive.
2. The %CROSS directive has no effect unless you request both a listing file and a cross-reference. For more information about listing file format, see the Compaq BASIC for OpenVMS Alpha and VAX Systems User Manual.
3. When a cross-reference is requested, the BASIC compiler starts or resumes accumulating cross-reference information immediately after encountering the %CROSS directive.

## Example

    %CROSS

# %DECLARED

> The %DECLARED directive is a built-in lexical function that allows you to determine whether a lexical variable has been defined with the %LET directive. If the lexical variable named in the %DECLARED function is defined in a previous %LET directive, the %DECLARED function returns the value -1. If the lexical variable is not defined in a previous %LET directive, the %DECLARED function returns the value 0.

## Format

## Syntax Rules

1. The %DECLARED function can appear only in a lexical expression.
2. Lex-var is the name of a lexical variable. Lexical variables are always LONG integers.
3. Lex-var must be enclosed in parentheses.

## Remarks

None

## Example

    ! +
    ! Use the following code in %INCLUDE files
    ! which reference constants that may be already ! -
    %IF %DECLARED (%TRUE_FALSE_DEFINED) = 0
    %THEN
        DECLARE LONG CONSTANT True = -1, False = 0
        %LET %TRUE_FALSE_%END %IF

# %DEFINE

> The %DEFINE directive lets you define a user-defined identifier as another identifier or keyword.

## Format

## Syntax Rules

1. Macro-id is a user identifier that follows the rules for BASIC identifiers. It must not be a keyword or a compiler directive.
2. Replacement-token may be an identifier, a keyword, a compiler directive, a literal constant, or an operator.
3. The "&" line continuation character may be used after the macro-id to continue the %DEFINE directive on the next line.
4. The "\" statement separator cannot be used with the %DEFINE directive.
5. "!" comments and line numbers used with the %DEFINE directive behave in the same manner as they do with other compiler directives.

## Remarks

1. The replacement-token is substituted for every subsequent occurrence of the macro identifier in the program text.
2. Macro-identifiers in REM or "!" comments, string literals, or DATA statements are not replaced.
3. A macro-id cannot be used as a line number.
4. A macro definition is in effect from the %DEFINE directive that defines it until either a corresponding %UNDEFINE directive or the end of the source module is encountered. This applies to any included code that occurs after the definition.
5. A previously defined macro identifier may be redefined by using the %DEFINE directive.
6. A previously defined macro may be canceled by using the %UNDEFINE directive.
7. Macros may not be nested. For example, if the replacement-token is an identifier that is defined by itself or some other %DEFINE directive, it is not replaced.
8. Macro-identifiers are not known to the Debugger.
9. The %DEFINE directive can be used within conditionally compiled code.

## Example

            %DEFINE widget LONG
            DECLARE widget X
            X = 3.75
            PRINT "X squared :"; X*X

Output

            X squared : 9

# %IDENT

> The %IDENT directive lets you identify the version of a program module. The identification text is placed in the object module and printed in the listing header.

## Format

## Syntax Rules

Str-lit is the identification text. Str-lit can consist of up to 31 ASCII characters. If it has more than 31 characters, BASIC truncates the extra characters and signals a warning message.

## Remarks

1. Only a line number or a comment field can appear on the same physical line as the %IDENT directive.
2. The BASIC compiler inserts the identification text in the first 31 character positions of the second line on each listing page. BASIC also includes the identification text in the object module, if the compilation produces one, and in the map file created by the OpenVMS Linker.
3. The %IDENT directive should appear at the beginning of your program if you want the identification text to appear on the first page of your listing. If the %IDENT directive appears after the first program statement, the text will appear on the next page of the listing file.
4. You can use the %IDENT directive only once in a module. If you specify more than one %IDENT directive in a module, BASIC signals a warning and uses the identification text specified in the first directive.
5. No default identification text is provided.

## Example

    %IDENT "Version 10"
       .
       .
       .

Output

    TIME$MAIN
    Version 10

         1         10      %IDENT "Version 10"
       .
       .
       .

# %IF-%THEN-%ELSE-%END %IF

> The %IF-%THEN-%ELSE-%END %IF directive lets you conditionally include source code or execute another compiler directive.

## Format

## Syntax Rules

1. Lex-exp is always a LONG integer.
2. Lex-exp can be any of the following:
   - A lexical constant named in a %LET directive.
   - An integer literal, with or without the percent sign suffix.
   - A lexical built-in function.
   - Any combination of the above, separated by valid lexical operators. Lexical operators include logical operators, relational operators, and the arithmetic operators for addition (+), subtraction (-), multiplication (*), and division (/).
3. Code is BASIC program code. It can be any BASIC statement or another compiler directive, including another %IF directive. You can nest %IF directives to eight levels.

## Remarks

1. The %IF directive can appear anywhere in a program where a space is allowed, except within a quoted string. This means that you can use the %IF directive to make a whole statement, part of a statement, or a block of statements conditional.
2. %THEN, %ELSE, and %END %IF do not have to be on the same physical line as %IF.
3. If lex-exp is true, BASIC processes the %THEN clause. If lex-exp is false, BASIC processes the %ELSE clause. If there is no %ELSE clause, BASIC processes the %END %IF clause. The BASIC compiler includes statements in the %THEN or %ELSE clause in the source program and executes directives in order of occurrence.
4. You must include the %END %IF clause. Otherwise, BASIC assumes the remainder of the program is part of the last %THEN or %ELSE clause and signals the error "MISENDIF, missing END IF directive" when compilation ends.

## Example

    %IF (%VARIANT = 2)
    %THEN DECLARE SINGLE hourly_pay(100)
    %ELSE %IF (%VARIANT = 1)
          %THEN DECLARE DOUBLE salary_pay(100)
          %ELSE %ABORT "Can't compile with specified variant"
          %END %IF
    %END %IF
         .
         .
         .
    PRINT %IF (%VARIANT = 2)
          %THEN 'Hourly Wage Chart'
                GOTO Hourly_routine
          %ELSE 'Salaried Wage Chart'
                GOTO Salary_routine
          %END %IF

# %INCLUDE

> The %INCLUDE directive lets you include BASIC source text from another program file in the current program compilation. BASIC also lets you access Oracle CDD/Repository record definitions from the Common Data Dictionary (CDD) and access commonly used routines from text libraries.

## Format

## Syntax Rules

1. Including a File
   Str-lit must be a valid file specification for the file to be included.
2. Including a CDD Definition
   Str-lit specifies a CDD path name enclosed in quotation marks. The path name can be in either DMU or CDO format. This directive lets you extract a RECORD definition from the dictionary.
3. Including a File from a Text Library
   - Str-lit specifies a particular module to be included.
   - The optional str-lit identifies a specific text library in which the included module resides. If the library name is not specified, BASIC uses the logical name BASIC$LIBRARY with a default file specification of BASIC.TLB. If BASIC$LIBRARY is undefined, BASIC uses SYS$LIBRARY:BASIC$STARLET.TLB.

## Remarks

1. Any statement that appears after an END statement inside an included file causes BASIC to signal an error.
2. Only a line number or a comment field can appear on the same physical line as the %INCLUDE directive.
3. The BASIC compiler includes the specified source file in the program compilation at the point of the %INCLUDE directive and prints the included code in the program listing file if the compilation produces one.
4. The included file cannot contain line numbers. If it does, BASIC signals the error "Line number may not appear in %INCLUDE file."
5. All statements in the accessed file are associated with the line number of the program line that contains the %INCLUDE directive. This means that a %INCLUDE directive cannot appear before the first line number in a source program if you are using line numbers.
6. A file accessed by %INCLUDE can itself contain a %INCLUDE directive.
7. All %IF directives in an included file must have a matching %END %IF directive in the file.
8. You can control whether or not included text appears in the compilation listing with the /[NO]SHOW=INCLUDE qualifier. When you specify /SHOW=INCLUDE, the compilation listing file identifies any text obtained from an included file by placing a mnemonic in the first character position of the line on which the text appears. The "n" specifies that the text was either accessed from a source file or from a text library. The "I" tells you that the text was accessed with the %INCLUDE directive and n is a number that tells you the nesting level of the included text. See the Compaq BASIC for OpenVMS Alpha and VAX Systems User Manual for more information about listing mnemonics.
9. Including a File
   If you do not specify a complete file specification, BASIC uses the default device and directory and the file type .BAS.
10. Including a CDD Definition
    - There are two types of CDD path names: full and relative. A full path name begins with CDD$TOP and specifies the complete path to the record definition. A relative path name begins with any string other than CDD$TOP and is appended to the current CDD$DEFAULT.
    - In Oracle CDD/Repository, the path names described previously are known as DMU path names, as distinct from CDO path names. You can specify either a full DMU path name, a full CDO path name, or a relative path name. A full path name consists of a dictionary origin followed by a dictionary path. A full DMU path name has CDD$TOP as its origin. A full CDO path name has an anchor as its origin. See Oracle CDD/Repository documentation for detailed information about path names.
    - If the record definition being accessed is in a CDO-format dictionary, you can create a dependency relationship in the dictionary between a dictionary representation of your program and the record definitions that you include in the program. The dictionary representation of the program is called a compiled module entity.
    - If you specify the /DEPENDENCY_DATA qualifier to the compiler and your CDD$DEFAULT points to a CDO-format dictionary, a compiled module entity is created for each compilation unit at compile time in CDD$DEFAULT. No compiled module entity is created if both conditions are not true.
    - If a compiled module entity exists for the program, an %INCLUDE %FROM %CDD directive specifying a record description in a CDO-format dictionary creates a relationship between the compiled module entity and the CDO-format record definition.
    - If the record description specified in the path name exists, it is copied to the program, whether a compiled module entity can be created or not.
    - When you use the %INCLUDE directive to extract a record definition from the CDD, BASIC translates the CDD definition to the syntax of the BASIC RECORD statement.
    - You can use the /SHOW=CDD_DEFINITIONS qualifier to specify that translated CDD definitions (in RECORD statement syntax) are included in the compilation listing file. BASIC places a "C" in column 1 when the translated RECORD statement appears in the listing file.
    - When you specify /SHOW=NOCDD_DEFINITIONS, BASIC does not include the CDD definition in the listing file. However, BASIC still includes the names, data types, and offsets of the CDD record components in the program listing's allocation map.
    - See the Compaq BASIC for OpenVMS Alpha and VAX Systems User Manual and the Oracle CDD/Repository documentation for more information about dictionary data definitions.
11. Including a File from a Text Library
    - The BASIC compiler searches through the specified text library for the module named and compiles the module upon encountering the %INCLUDE directive.
    - BASIC allows only 16 text libraries to be opened at one time; therefore, you cannot have %INCLUDE directives from a text library nested more than 16 levels deep. If you exceed this maximum, BASIC signals an error message.
    - If you do not specify a directory name and file type, BASIC uses the default device and directory and the file type .TLB.
    - BASIC provides the text library BASIC$STARLET. BASIC$STARLET contains condition codes and other symbols defined in the system object and shareable image libraries. Using the definitions from BASIC$STARLET allows you to reference condition codes and other system-defined symbols as local, rather than global symbols. To create your own text libraries using the OpenVMS Librarian utility, see the OpenVMS Command Definition, Librarian, and Message Manual.

## Examples

Example 1

    !Including a File
    %INCLUDE "YESNO"

Example 2

    !Including a CDD Definition
    %INCLUDE %FROM %CDD "CDD$TOP.EMPLOYEE"

Example 3

    !Including a CDD Definition with a CDO-format path name
    %INCLUDE %FROM %CDD "MYNODE::MY$DISK:[MY_DIR]PERSONNEL.EMPLOYEE"
    !The anchor is MYNODE::MY$DISK:[MY_DIR]

Example 4

    !Including a File from a Text Library
    %INCLUDE "EOF_CHECK" %FROM %LIBRARY "SYS$LIBRARY:BASIC_LIB.TLB"

Previous | Next | Contents | Index