Part 1 provides an overview of BASIC and describes how to develop and debug BASIC programs. It shows you how to get started on the OpenVMS system and how to develop programs both at DCL command level and within the VAX BASIC Environment.

This brief overview highlights features of Compaq BASIC for OpenVMS Alpha (referred to as Alpha BASIC) and Compaq BASIC for OpenVMS VAX (referred to as VAX BASIC). (The term Compaq BASIC applies to both implementations.) The features are described fully in subsequent chapters.

BASIC was originally developed for students with little or no programming experience. Since then, BASIC has become one of the most widely used programming languages and is available on almost every computer system. The OpenVMS implementations of BASIC have evolved beyond the original design but still support all of the traditional features of the original language in addition to more recent programming techniques. Compaq BASIC has become much more than a teaching tool and is used in a wide variety of sophisticated applications.

Compaq BASIC is a powerful structured programming language designed for novice and application programmers alike. The language provides both a highly interactive programming environment (VAX BASIC only) and a high-performance development language. Compaq BASIC supports the following language constructs:

• Code without line numbers (traditional line numbers are optional)
• Control structures, such as SELECT CASE
• Explicit variable declarations
• Capabilities for handling dynamic strings
• Adaptable file-handling capabilities for terminal-format files, and the full range of RMS facilities
• Global and local run-time error handling with WHEN ERROR blocks
• Compile-time directives
• A variety of data types, including packed-decimal, user-defined records, and (for Alpha BASIC) three IEEE floating-point data types: SFLOAT, TFLOAT, and XFLOAT.

• Extensive error checking with meaningful error messages
• Thirty-one character names for variables, labels, functions, and subprograms

Compaq BASIC uses the OpenVMS operating system to its full advantage and is integrated with many other Compaq products. In particular, Compaq BASIC supports:

• The OpenVMS systems standard calling procedures
• Record definitions included from the OpenVMS Common Data Dictionary
• Code analysis with the Performance and Coverage Analyzer (PCA)
• Creation of code with the Language-Sensitive Editor (LSE)
• Extensive online language help
• Interactive graphics (VAX BASIC only)¹
• Exchange of data with other systems using DECnet

Compaq BASIC supports features of other versions of BASIC, including PDP-11 BASIC-PLUS-2. Compaq BASIC is a functional superset of BASIC-PLUS-2. Compatibility flags for BASIC-PLUS-2 and ANSI Minimal BASIC allow you to check whether the programs will run on other systems.

When you write programs in VAX BASIC, you can choose between two program development methods: developing programs at DCL command level or developing programs from within the VAX BASIC Environment ². When you develop programs at DCL level, you write your source program with a text editor, then compile, link, and run the program with commands to the OpenVMS operating system. Alternatively, when you develop programs within the VAX BASIC Environment, you type the DCL command BASIC to enter the environment, enter your program, then execute it with the BASIC command RUN.

The VAX BASIC Environment provides for interactive VAX BASIC program development. This chapter describes how to work within the VAX BASIC Environment.

The information in this chapter is specific to Compaq BASIC for OpenVMS VAX (VAX BASIC). The VAX BASIC Environment is not supported by Compaq BASIC for OpenVMS Alpha (Alpha BASIC). (For more information about the differences between Alpha BASIC and VAX BASIC, see the Compaq BASIC for OpenVMS Alpha and VAX Systems Reference Manual, Appendix C.)

2.1 Entering the Environment

To enter the VAX BASIC Environment, type the DCL command BASIC and press Return. An identification line and the Ready prompt appear.

$ BASIC VAX BASIC Vn.n Ready

In the VAX BASIC Environment, you can interact directly with the compiler. In this mode of operation, you can enter any of the following:

• BASIC program lines
• Immediate mode statements
• Compiler commands and qualifiers

When you enter program statements, VAX BASIC stores them in ascending line number sequence as part of the current program in memory. If you enter a program line with the same line number as an existing program line, the new line replaces the old line.

When you create a program in the Environment, the first line of the program must have a line number. If you enter a subsequent program line without a line number, you must precede it with a space or a tab. Inside the Environment, only those program lines that begin with line numbers can start in the first character position on a line.

If a program line is too long for one text line, you can continue it by typing an ampersand (&) and pressing Return. (Note that only spaces and tabs are valid between the ampersand and the carriage return.)

See Section 2.3 for more information about immediate mode statements and Section 2.5 for more information about BASIC compiler commands.

2.2 Creating and Running Programs

Within the VAX BASIC Environment, there are two ways to create and edit a program. You can create and edit the program directly using line mode, or you can use the compiler command EDIT to invoke a text editor when you are in the Environment.

The EDIT command invokes the default text editor for your system. After entering the VAX BASIC Environment, you can enter the EDIT command, create a program using a text editor, and then exit from the editor back to the Environment. At this point, the program you created is the current program in memory, and you can type RUN or RUNNH to compile, link, and execute your program. (RUNNH suppresses header information such as the name of the program and the time of day.)

You can also create a program using a text editor accessed from DCL. After creating the program, you can either use the OLD command from within the VAX BASIC Environment to read your program into memory, or compile your program from DCL. Chapter 3 discusses how to compile programs from DCL.

The following example shows a simple program that accepts three numbers entered at the terminal, averages them, and displays the result:

$ BASIC VAX BASIC Vn.n Ready NEW FIRSTTRY Ready 10 PRINT "Please enter three numbers" INPUT A, B, C PRINT "Their average is"; ( A + B + C ) / 3 END RUNNH

Output

Please enter three numbers ? 5 ? 10.3 ? 4.7 Their average is 6.66667 Ready

In the previous example, the DCL command BASIC places you in the VAX BASIC Environment. The Environment command NEW informs VAX BASIC that you want to create a new program and assigns the program a name. Here the program is named FIRSTTRY. If you do not enter a program name with the NEW command, VAX BASIC assigns the name NONAME by default. The default file type is .BAS.

The RUNNH command compiles, links, and executes the program you create. To save this program, enter the SAVE command at the Ready prompt.

You can execute multiple-module programs while in the VAX BASIC Environment. To execute multiple-module programs, follow these steps:

1. Compile all subprograms to generate object modules.
2. Use the OLD command to read the main program into memory.
3. Use the LOAD command to read the subprogram object modules into memory.
4. Enter the RUN command.

Figure 2-1 shows how to execute multiple-module programs.

Figure 2-1 Running Multiple-Module Programs

The following example program contains multiple units:

10 REM This program calls SUBPROGRAM SB1 20 PRINT "NOW IN MAIN PROGRAM" 30 CALL SB1 40 PRINT "BACK IN MAIN PROGRAM" 50 END 10 SUB SB1 20 PRINT "NOW IN SUBPROGRAM" 30 SUBEND

To execute this program in the VAX BASIC Environment, enter the following commands:

Ready OLD SB1 Ready COMPILE Ready OLD MAIN Ready LOAD SB1 Ready RUN

Output

NOW IN MAIN PROGRAM NOW IN SUBPROGRAM BACK IN MAIN PROGRAM Ready

If a STOP statement or Ctrl/C is encountered in a module other than the currently compiled module, VAX BASIC signals "Compiled procedure is currently not active." At this point, you cannot use immediate mode statements.

When you run multiple-module programs in the VAX BASIC Environment, only one module is currently compiled. Normally, the currently compiled program is the one you read into memory with the OLD command. However, if a source file contains more than one program module, the last one (the one closest to the end of the source file) is the currently compiled module. In the previous example, MAIN is the currently compiled module.

For more information about loading multiple object modules, see Section 2.4.

2.3 Immediate Mode

You do not have to write a complete program in VAX BASIC. Many statements are executable in immediate mode.

Immediate mode statements are BASIC statements that are executed immediately after you press the Return key. Immediate mode statements cannot be preceded by a line number, space, or tab and can be used only if you are working directly in the Environment.

In the following example, VAX BASIC interprets the first line as a comment because it begins with an exclamation point (!). VAX BASIC interprets the second line as part of a larger program because it begins with a line number. This line does not execute until a RUN command is specified. The third line does not begin with a line number, a space, or an exclamation point. Therefore, VAX BASIC treats the line as an immediate mode statement and immediately displays the specified text.

!In the Environment, this is a comment[Return] 10 PRINT 'This is an executable BASIC statement'[Return] PRINT 'THIS IS AN IMMEDIATE MODE STATEMENT'[Return]

Output

THIS IS AN IMMEDIATE MODE STATEMENT Ready

The Ready prompt indicates that VAX BASIC is ready to receive compiler commands, immediate mode statements, or new program lines.

You can precede each executable statement with a backslash (\). You can also have more than one BASIC statement on a line if you separate the statements with a backslash character as in the following example:

Ready A = (54.37 / 1.25 ) \ B = ( 328.15^2) \ PRINT ( B / A ) 2475.69

Unless a STOP statement is executed, VAX BASIC compiles and executes each immediate mode statement as if it were a self-contained program. For example:

Ready PRINT PI * 67.3 211.429

Even if the current program executes a STOP statement, you can perform independent calculations. However, after a stop, any immediate mode statement referencing program variables uses the values assigned in the program. Note that you cannot create new program variables after a STOP statement has been executed.

If the current program does not execute a STOP statement, each immediate mode line exists by itself, and any variables used by the statements on that line are temporary. For example:

Ready A = 2^5 \ PRINT A 32 READY PRINT A 0

The second PRINT statement instructs VAX BASIC to display zero because the compiler treats A as a new variable and initializes it to zero.

You can use the IF, WHILE, UNTIL, UNLESS, and FOR statement modifiers in immediate mode statements. The following example shows how you can generate a table of square roots by using the immediate mode statement:

Ready PRINT I, SQR (I) FOR I = 1 TO 10 1 1 2 1.41421 3 1.73205 4 2 5 2.23607 6 2.44949 7 2.64575 8 2.82843 9 3 10 3.16228 Ready

Certain statements are invalid in immediate mode. In general, statements are invalid that require the allocation of new storage, or statements that do not make sense in the context of a single line. If you try to execute such a statement, VAX BASIC signals the error "Illegal in immediate mode."

2.4 Debugging in Immediate Mode

To debug in immediate mode, you insert STOP statements in your program at the points where you wish to examine the values of variables. When VAX BASIC encounters a STOP statement, program execution is interrupted. You can use immediate mode statements to display the values of variables or to assign them new values. After changing or examining data, you can use the CONTINUE command to resume program execution.

The following restrictions apply when you are debugging in immediate mode:

• You cannot continue execution if you change any program code; for example, you cannot create new variables after VAX BASIC encounters a STOP statement.
• You can debug only one module at a time. You can examine and change variables only in the current module (the most recently compiled module) of a multiple-module program.

When you are debugging multiple program units in the Environment, follow these guidelines:

• Use the OLD command to read in the source file for the module you want to debug. This source file becomes the current module---the one available for immediate mode debugging.
• Use the LOAD command to read in the object files for the remaining program modules.

An object module is the file that results from compiling a source file; its format is an intermediate step between a source file and an executable image. The LOAD command removes any previously loaded object modules, whether or not the command specifies any object module files. Therefore, you must use a single LOAD command to specify all the object files you need. In addition, you must separate multiple object modules with a plus sign (+).

The object files are not linked with the current program or executed until you issue the RUN command. Therefore, run-time errors in the loaded modules are not detected until you execute the program.

When you want to run a program, you can load all the object modules for that program and then execute the program with the RUN command. If you want to debug a program, use the OLD command for the module you want to debug and then load the remaining program modules. The module to be debugged can be either a main program or a subprogram because, when you enter the RUN command, VAX BASIC transfers control to the main program, whether it is in object-module format or source-program format.

For information about using the OpenVMS Debugger, see Chapter 4.

2.5 Compiler Commands

Compiling is the process of translating a source program to an object module. An object module is an intermediate step between source code and an executable image. It contains information that the linker uses to create an image.

VAX BASIC has certain defaults that are in effect each time you enter the VAX BASIC Environment. Unless you explicitly override these defaults, they remain in effect until you leave the Environment. You can see a listing of these defaults by entering the SHOW command when in the VAX BASIC Environment. The following example displays the standard VAX BASIC Environment defaults:

Ready 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 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

You can override any of these defaults with qualifiers to the COMPILE or SET commands, or with the OPTION statement in your program. Table 2-1 lists and describes all the VAX BASIC compiler commands. The sections that follow describe the commands in detail, including the qualifiers to the COMPILE, SET, and RUN commands. For more information about the OPTION statement, see the Compaq BASIC for OpenVMS Alpha and VAX Systems Reference Manual.

Table 2-1 VAX BASIC Compiler Commands

Command	Description
! comment	Identifies a comment.
$ command	Starts a subprocess to execute the specified DCL command.
APPEND	Merges the specified program with the program currently in memory.
ASSIGN	Assigns a logical name to a complete file specification (the equivalence name).
COMPILE	Generates an object module (file type .OBJ) from a VAX BASIC source program.
CONTINUE	Resumes execution after a STOP statement or Ctrl/C.
DELETE	Erases the specified line or lines from the program currently in memory.
EDIT	Changes source text or calls a text editor.
EXIT	Returns to DCL command level.
HELP	Displays HELP text.
IDENTIFY	Causes VAX BASIC to print an identification header on the terminal.
LIST	Displays the current source program on the terminal.
LISTNH	Displays the current source program without header information.
LOAD	Loads an object module into memory.
LOCK	Specifies default values for compiler command qualifiers (identical to the SET command).
NEW	Clears memory for the creation of a new program and assigns a new program name.
OLD	Reads a specified VAX BASIC source program into memory.
RENAME	Changes the name of the program currently in memory.
REPLACE	Writes the program currently in memory to a file, using the file specification in the OLD or RENAME command.
RESEQUENCE	Supplies new line numbers for the program currently in memory.
RUN	Executes the program currently in memory, or a specified VAX BASIC source program. The program in memory can be any of the following: A VAX BASIC source program placed in memory with the OLD command One or more object modules placed in memory with the LOAD command A combination of the first two
RUNNH	Similar to RUN but does not display header information.
SAVE	Copies the current source program to a file.
SCALE	Controls accumulated round-off errors for numeric operations.
SCRATCH	Erases the current program and any loaded object modules.
SEQUENCE	Generates line numbers for input text.
SET	Specifies default values for compiler command qualifiers.
SHOW	Displays the current default compiler qualifiers.
UNSAVE	Deletes a specified file.

The following sections describe these commands. For more detailed information, see the Compaq BASIC for OpenVMS Alpha and VAX Systems Reference Manual.