# Compaq BASIC for OpenVMS
Alpha and VAX Systems
User Manual

Previous | Contents | Index

## 2.5.14 LOCK Command

The LOCK command changes default values for COMPILE command qualifiers. It is equivalent to the SET command. The following command specifies that all subsequent compilations use double-precision, floating-point numbers as the default. You can use any valid COMPILE command qualifier as an argument to LOCK.

    LOCK /DOUBLE

    Ready

## 2.5.15 NEW Command

The NEW command clears the memory and assigns a name to a program to be entered. The following command assigns the name PROG1 to the program. You can then enter program lines.

    NEW PROG1

If you do not specify a name, VAX BASIC issues the following prompt:

    New file name--

You should respond with a file name. If you press the Return key in response to the prompt, VAX BASIC assigns the name NONAME.

## 2.5.16 OLD Command

The OLD command brings a previously created VAX BASIC source file into memory. The following command reads PROG1.BAS into memory:

    OLD PROG1

If you do not specify a file name, VAX BASIC issues the prompt:

    Old file name--

You should respond with a file name. If you do not specify a file type, VAX BASIC reads a file with the specified file name and the default file type. If you press the Return key in response to the prompt, VAX BASIC searches for a file with the default file name and default file type: NONAME.BAS.

## 2.5.17 RENAME Command

The RENAME command assigns a new name to the program currently in memory. For example, the following command sequence brings a program named PROG1 into memory and changes its name and directory:

    OLD [KELLY]PROG1

    Ready

    RENAME [MCKAY.BASIC]PROG2

The name of the program is changed to PROG2. If you perform a REPLACE operation, PROG2 is copied to the subdirectory [MCKAY.BASIC] instead of [KELLY]. The remaining portion of the specification is unchanged. If you do not specify a program name, VAX BASIC renames the current program to NONAME.

## 2.5.18 REPLACE Command

The REPLACE command writes a copy of the current program back to disk. It replaces it using the file specification specified in the last OLD command. Part or all of this file specification can be overwritten with the RENAME command; whatever parts are not specifically changed remain the same. RENAME is similar to SAVE except that while SAVE copies the current program to the default directory, REPLACE copies the current program to the location specified in the program's current file specification.

After execution of a REPLACE command, VAX BASIC issues an informational message confirming the file specification.

## 2.5.19 RESEQUENCE Command

The RESEQUENCE command allows you to resequence the line numbers of the program currently in memory. VAX BASIC also changes all references to the old line numbers so they reference the new line numbers. You can specify a starting line number and a value by which to increase each subsequent line number. The following command resequences the line numbers from 10 to 10000, making the first line number 100 and increasing each subsequent line number by 20:

    RESEQUENCE 10-10000 100 STEP 20

The RESEQUENCE command is not allowed on programs without line numbers.

## 2.5.20 RUN and RUNNH Commands

The RUN command executes a program. This program can be any one of the following:

- The current program
- One or more object modules placed in memory with the LOAD command
- A combination of the current and one or more object modules placed in memory with the LOAD command
- A specified VAX BASIC source program

If you do not supply an alternative file specification, VAX BASIC executes the program in memory.

    Ready

    OLD
    Old file name--PROG1
    Ready

    RUN

The RUN command compiles, links, and executes PROG1. It prints a header displaying the program name and the current date and time. To execute a program without displaying this header, enter RUNNH.

The RUN command does not create an object module file or a list file. It uses qualifiers that have been set. The following qualifiers are always in effect for the RUN and RUNNH commands:

> NOCROSS
> NODEBUG
> NOLIST
> NOMACHINE
> NOOBJECT
> SETUP

The RUN command invokes only VAX BASIC procedures and other procedures that reside in shareable image libraries. See Chapter 21 for more information on creating shareable images.

## 2.5.21 SAVE Command

The SAVE command copies a VAX BASIC source program from memory to a file. You can specify a storage device, a file name, and a file type in the SAVE file specification. In the following program, a SAVE command instructs VAX BASIC to arrange the program in ascending line number order and copy it to a file on MTA1: in the current default directory with file name TEST and the default file type of .BAS.

    10 REM THIS IS A TEST
    30 PRINT "THIS IS A TEST"
    SAVE MTA1:TEST

If the program in memory has no name, and you issue the SAVE command with no argument, VAX BASIC copies the program to a file named NONAME with the default file type in your current default device and directory.

## 2.5.22 SCALE Command

The SCALE command overcomes accumulated round-off errors by multiplying double-precision, floating-point values by 10 raised to the specified scale factor before storing them.

## 2.5.23 SCRATCH Command

The SCRATCH command clears memory by doing the following:

- Resetting the program name to NONAME
- Removing any object files previously loaded with the LOAD command
- Removing the source file currently in memory

## 2.5.24 SEQUENCE Command

The SEQUENCE command automatically generates line numbers for input text. After a SEQUENCE command, VAX BASIC prompts with a line number and prompts again after each source line you enter. If you press Ctrl/Z (either in response to the line number prompt or at the end of a program line), VAX BASIC stops prompting, and you can enter source text in the normal way. If you specify a starting line number that already contains a statement, VAX BASIC signals "Attempt to sequence over existing statement" and returns to normal input mode.

Note that the SEQUENCE command is not allowed on programs without line numbers.

## 2.5.25 SET Command

The SET command specifies defaults for compiler command qualifiers. For example:

    SET /SINGLE

    Ready

This command makes /SINGLE the default for the COMPILE or RUN command, thereby making SINGLE the default data type for all untyped values. Entering the SET command with no arguments resets the defaults to their state when you entered the VAX BASIC Environment.

For a full list of options, see the COMPILE command.

## 2.5.26 SHOW Command

The SHOW command displays the current default qualifiers and user libraries. For example:

    SHOW

    VAX BASIC Vn.n Current Environment Status dd-mmm-yyyy 10:12:12.05
    DEFAULT DATA TYPE INFORMATION:           LISTING FILE INFORMATION INCLUDES:
        Data type : REAL                           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:
        NO Overflow check decimal numbers          Declining features
           Bounds checking                      NO BASIC PLUS 2 subset
        NO Syntax checking                      NO Alpha AXP subset
           Line
           Variant : 0                       DEBUG INFORMATION:
        NO Warnings                                Traceback records
        NO Informationals                       NO Debug symbol records
           Setup
           Object Libraries : NONE
    Ready

The DEFAULT DATA TYPE INFORMATION display in the previous example contains the following information:

- The default data type is REAL.
- The default size for floating-point numbers is SINGLE, the default size for integers is LONG, and the default size for packed decimal numbers is (15,2).
- There is no scale factor in effect.
- Packed decimal numbers are truncated rather than rounded.

The LISTING FILE INFORMATION display tells you which parts of the program listing are included if you create a compilation listing:

- The source program is listed.
- No cross-reference information is listed.
- CDD definitions are displayed as RECORD statements.
- The qualifiers in effect when the program was compiled are listed. This means that the program listing contains the equivalent of this SHOW command.
- The %NOLIST compiler directive is not overridden.
- No compiler-generated machine code is listed.
- An allocation map is listed. This contains the sizes and offsets of any variables.
- Files accessed with the %INCLUDE directive are listed.

The COMPILATION QUALIFIERS IN EFFECT display contains the following information:

- An object file is produced.
- Overflow checking for integers is enabled.
- Overflow checking for packed decimal numbers is disabled.
- Bounds checking is enabled.
- Line-by-line syntax checking is disabled.
- Line number information is included in the object file.
- The VARIANT value is zero.
- No warning or informational error messages are displayed.
- VAX BASIC performs normal initialization calls at run time (SETUP).
- No user-supplied object module libraries are searched.

The FLAGGERS display contains the following information:

- Declining features are reported.
- BP2 compatibility issues are not reported.
- Compatibility issues with Alpha BASIC for OpenVMS Alpha are not reported.

The DEBUG INFORMATION section gives you the following information:

- Traceback information is included in the object module.
- No debug records are included in the object module. This means you cannot access program symbols with the OpenVMS Debugger.

See Chapter 21 for more information about user libraries.

## 2.5.27 UNSAVE Command

The UNSAVE command deletes the specified version of a file from disk. If you do not specify a file, UNSAVE deletes the disk file associated with the program currently in memory. If you do not specify a version number, UNSAVE deletes the previous version. For example:

    OLD PROG1

    Ready

    UNSAVE

    Ready

The OLD command copies a program named PROG1.BAS from disk to memory. The UNSAVE command deletes the program from disk.

You can delete a VAX BASIC source program other than the one in memory by specifying the program name. The following command deletes the most recent version of the file PROG2.BAS:

    UNSAVE PROG2

To delete a file other than a source program, specify the file name and file type. The following command deletes the previous version of the object module generated from the compilation of PROG2:

    UNSAVE PROG2.OBJ

# Chapter 3
Developing BASIC Programs at the DCL Command Level

A programmer needs to know how to create, compile, link, and run a program. This chapter describes compiling, linking, and running a BASIC program.

The shortened name Alpha BASIC refers to Compaq BASIC for OpenVMS Alpha, and VAX BASIC refers to Compaq BASIC for OpenVMS VAX.

For information about using a text editor to create and edit files, see the OpenVMS User's Manual.

# 3.1 Compiling a BASIC Program

The BASIC compiler performs the following functions:

- Detects errors in your source program
- Generates any appropriate error messages
- Generates machine language instructions from the source statements
- Groups these language instructions into an object module for the linker

To invoke the compiler, you use the DCL command BASIC. With the BASIC command, you can specify command qualifiers. The next sections discuss the BASIC command in detail as well as the command qualifiers available.

## 3.1.1 BASIC Command

When you compile your source program, use the BASIC command, which has the following format:

`BASIC [/qualifier...][ file specification [/qualifier...]],...`

> ### /qualifier

> Indicates a specific action to be performed by the compiler on all files or specific files listed. When a qualifier appears directly after the BASIC command, it affects all files listed.

> ### file specification

> Indicates the name of the input source file that contains the program or module to be compiled. You are not required to specify a file extension; the BASIC compiler assumes the default file type .BAS.

In VAX BASIC, if you enter the command BASIC without a file specification, you enter the interactive VAX BASIC Environment. Alpha BASIC does not support the Environment. For more information about the Environment, see Chapter 2.

Most of the command qualifiers to the BASIC command affect all files specified in the command line, no matter where the qualifiers are placed; these are called global qualifiers. However, the qualifiers /LISTING, /OBJECT, /DIAGNOSTICS, and /ANALYSIS_DATA are positional qualifiers; that is, depending on their position in the command line, they can affect all or only some of the specified files. The rules for positional qualifiers are as follows:

- If the positional qualifier is located directly following the command name, it affects all the specified files.
- If the file specifications are separated by commas, then any positional qualifier directly following a file specification affects only that file.
- If the file specifications are separated by plus signs, then any positional qualifier directly following a list of file specifications affects only the resulting appended file.
- The rightmost qualifier overrides any conflicting qualifier previously specified in the command line.

The placement of these positional qualifiers causes BASIC to produce or not produce listing files, object files, and diagnostics files. For example:

    $ BASIC/LIST/OBJ PROG1/NOOBJ/DIAG,PROG2+PROG3/NOLIST

This command does the following:

- Compiles PROG1 and produces a listing file called PROG1.LIS
- Produces no object file for PROG1
- Produces a diagnostics file for PROG1 called PROG1.DIA
- Appends PROG2 and PROG3 for compilation, producing a temporary source file called PROG2
- Compiles the new PROG2 and produces an object file called PROG2.OBJ
- Produces no listing file for the new PROG2

VAX BASIC requires that source files using the plus sign (+) to append source files, use line numbers within the files, or an error message is printed.

Alpha BASIC does not require line numbers in either of the source files. The "+" operator is treated as an OpenVMS append operator. Alpha BASIC appends and compiles the separate files as if they were a single source file.

## 3.1.2 BASIC Command Qualifiers

The following list shows the BASIC command qualifiers and their defaults. A description of each qualifier follows the list.

Qualifiers marked by an asterisk (*) are not supported by Alpha BASIC with the following exception: /[NO]FLAG[=(DECLINING)]. Alpha BASIC does support the DECLINING option of the /FLAG qualifier but not the BP2COMPATIBILITY or AXPCOMPATIBILITY options.

The qualifiers that are "declining features" and no longer recommended are separately described in Section 3.1.3.

Qualifiers marked by a double asterisk (**) are not supported by VAX BASIC, with two exceptions: /[NO]OPTIMIZE, which VAX BASIC supports without any level options; and /[NO]WARNINGS, which VAX BASIC supports without the [NO]ALIGNMENT option but with the other options.

Command Qualifier | Default
--- | ---
/[NO]ANALYSIS_DATA [ = file specification ] | /NOANALYSIS_DATA
/[NO]ANSI_STANDARD* | /NOANSI_STANDARD
/[NO]AUDIT [ = text-entry ] | /NOAUDIT
/[NO]CHECK [ = (check-clause,...) ] | /CHECK=(BOUNDS,OVERFLOW)
/[NO]CROSS_REF [ = [NO]KEYWORDS] | /NOCROSS_REF
/[NO]DEBUG [ = (debug-clause,...) ] | /DEBUG=(TRACEBACK,SYMBOLS)
/DECIMAL_SIZE = (d,s) | /DECIMAL_SIZE=(15,2)
/[NO]DEPENDENCY_DATA | /NODEPENDENCY_DATA
/[NO]DESIGN* | /NODESIGN
/[NO]DIAGNOSTICS [ = file specification] | /NODIAGNOSTICS
/[NO]FLAG [ = ( flag-clause,... ) ]* | /FLAG = (NODECLINING,
| NOBP2COMPATIBILITY,
| NOAXPCOMPATIBILITY )
/INTEGER_SIZE = data-type | /INTEGER_SIZE = LONG
/[NO]LINES | /LINES (VAX) /NOLINES (DEC)
/[NO]LISTING [ = file specification ] | /NOLISTING (from terminal) /LISTING (batch)
/[NO]MACHINE_CODE | /NOMACHINE_CODE
/[NO]OBJECT [ = file specification ] | /OBJECT
/[NO]OLD_VERSION[=CDD_ARRAYS] | /NOOLD_VERSION
/[NO]OPTIMIZE[=level=n]** | /OPTIMIZE=level=4
/REAL_SIZE = data-type | /REAL_SIZE = SINGLE
/[NO]ROUND_DECIMAL | /NOROUND_DECIMAL
/SCALE = n | /SCALE = 0
/[NO]SEPARATE_COMPILATION** | /NOSEPARATE_COMPILATION
/[NO]SHOW [ = ( show-item,... ) ] | /SHOW
/[NO]SYNCHRONOUS_EXCEPTIONS** | /NOSYNCHRONOUS_EXCEPTIONS
/[NO]SYNTAX_CHECK* | /NOSYNTAX_CHECK
/TYPE_DEFAULT = default-clause | /TYPE_DEFAULT = REAL
/VARIANT = int-const | /VARIANT = 0
/[NO]WARNINGS [ = ( warn-clause,...) ]** | /WARNINGS = (INFORMATIONALS,
| WARNINGS,
| NOALIGNMENT)

> ### /[NO]ANALYSIS_DATA [ = file specification ]

> ### /NOANALYSIS_DATA (default)

> The /ANALYSIS_DATA qualifier generates a file containing data analysis information. This file has the file type .ANA. The Source Code Analyzer (SCA) library uses these files to display cross-reference information and to analyze source code.

> Remarks

> 1. SCA must be installed.
> 2. /ANALYSIS_DATA cannot be used with /ANSI_STANDARD.

> ### /[NO]ANSI_STANDARD

> ### /NOANSI_STANDARD (default)

> The /ANSI_STANDARD qualifier causes the compiler to allow only valid ANSI Minimal BASIC statements and to compile programs according to the ANSI Minimal BASIC rules. It also allows extensions and implementation-defined features. For more information about ANSI standard BASIC, see the Compaq BASIC for OpenVMS Alpha and VAX Systems Reference Manual.

> Remarks

> 1. Alpha BASIC does not support this qualifier.
> 2. /ANSI_STANDARD cannot be used with /ANALYSIS_DATA.

### /NOAUDIT (default)

The /AUDIT qualifier causes the compiler to include a history entry in CDD/Repository when extracting a CDD/Repository definition. You can specify either a string literal or a file specification with the /AUDIT qualifier. If you specify a string literal, BASIC includes it as part of the history entry. If you specify a file specification, BASIC includes up to the first 64 lines of the specified file. When you specify /AUDIT, BASIC also includes the following information about the CDD/Repository record extraction in the history entry:

- The name of the program module making the extraction
- The time and date of the extraction
- A note that access was made by way of a BASIC program
- A note that the access was an extraction
- The username and UIC of the process accessing CDD/Repository

Remarks

1. /NOAUDIT causes the compiler not to include a history entry in CDD/Repository when extracting a CDD/Repository definition.

### /CHECK=(BOUNDS,OVERFLOW) (default)

The /CHECK qualifier causes the compiler to test for arithmetic overflow and for array references outside array boundaries when the program executes.

Remarks

1. In Alpha BASIC, specifying /CHECK=NOBOUNDS causes bounds checking not to be performed on array parameters received by descriptor.
2. /CHECK=NOBOUNDS should only be used for thoroughly debugged programs and when execution time is critical. The program is smaller and runs faster, but no error is signaled for an array reference outside the array boundaries. The program might get a memory management or access violation error at run time.
3. /CHECK=OVERFLOW enables checking for integers and packed decimal numbers.
4. /CHECK=NOOVERFLOW disables overflow checking.
5. /NOCHECK causes the compiler not to test for arithmetic overflow or for array references outside array boundaries when the program executes.
6. /CHECK=ALL is the same as /CHECK=(BOUNDS, OVERFLOW).
7. /CHECK = NONE is the same as /NOCHECK.

### /[NO]CROSS_REFERENCE [ = [NO]KEYWORDS ]

### /NOCROSS_REFERENCE (default)

The /CROSS_REFERENCE qualifier causes the compiler to generate a cross-reference listing. The cross-reference list shows program symbols, classes, and the program lines in which they are referenced.

Remarks

1. /CROSS_REFERENCE=KEYWORDS specifies that the cross-reference listing includes all references to BASIC keywords. In Alpha BASIC, if the /LIST qualifier is not specified as well, /CROSS_REFERENCE is ignored.
2. The default for /CROSS_REFERENCE is NOKEYWORDS. See Chapter 17 for more information about cross-reference listings.
3. /NOCROSS_REFERENCE specifies that no cross-reference listing be produced.

### /DEBUG = (TRACEBACK,SYMBOLS) (default)

The /DEBUG qualifier causes the compiler to provide information for the OpenVMS Debugger and the system run-time error traceback mechanism. Neither TRACEBACK nor SYMBOLS affects a program's executable code. For more information about debugging, see Chapter 4.

Remarks

1. /NODEBUG causes the compiler to suppress information for the OpenVMS Debugger and the system run-time error traceback mechanism.
2. /DEBUG = ALL is the same as /DEBUG = (TRACEBACK,SYMBOLS).
3. /DEBUG = NONE is the same as /NODEBUG.

### /DECIMAL_SIZE = ( d,s )

### /DECIMAL_SIZE = (15,2) (default)

The /DECIMAL_SIZE qualifier lets you specify the default size for packed decimal data. You specify the total number of digits in the number and the number of digits to the right of the decimal point.

/DECIMAL_SIZE = (15,2) is the default. This default decimal size applies to all decimal variables for which the total number of digits and digits to the right of the decimal point are not explicitly declared. See the Compaq BASIC for OpenVMS Alpha and VAX Systems Reference Manual for more information about packed decimal numbers.

### /[NO]DEPENDENCY_DATA

### /NODEPENDENCY_DATA (default)

The /DEPENDENCY_DATA qualifier generates a compiled module entity in the CDD$DEFAULT for each compilation unit.

Remarks

1. A compiled module entity is generated only if CDD/Plus Version 4.0 or higher or CDD/Repository Version 5.0 or higher is installed on your system and if your current CDD$DEFAULT is a CDO-format dictionary.
2. You must specify this qualifier if you want %INCLUDE %FROM %CDD and %REPORT %DEPENDENCY directives to establish dependency relationships.
3. /NODEPENDENCY_DATA causes the compiler not to generate a compiled module entity.

### /NODESIGN (default)

The /DESIGN qualifier enables Program Design Facility (PDF) processing. Therefore, if you specify the /DESIGN qualifier on the BASIC command line, the BASIC compiler recognizes PDF placeholders and comments as valid program elements.

Previous | Next | Contents | Index