HP OpenVMS Systems Documentation

HP BASIC for OpenVMS
User Manual

This chapter describes how to compile, link, and run an HP BASIC program.

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

2.1 Compiling an HP BASIC Program

The HP 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.

2.1.1 BASIC Command

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

/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-spec

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 HP BASIC compiler assumes the default file type .BAS.

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

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

2.1.2 BASIC Command Qualifiers

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

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

/[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

• SCA must be installed.

/ARCHITECTURE = GENERIC (default)

All Itanium and Alpha processors implement a core set of instructions and, in some cases, the following extensions: BWX (byte- and word-manipulation instructions) and MAX (multimedia instructions).

OpenVMS Version 7.1 and subsequent releases include an instruction emulator. This capability allows any Itanium or Alpha chip to execute and produce correct results from Itanium or Alpha instructions, respectively, even if some of the instructions are not implemented on the chip. Applications using emulated instructions will run correctly, but might incur significant emulation overhead at run time.

Remarks

• /ARCHITECTURE = GENERIC (default) generates instructions that are appropriate for all Itanium or Alpha processors.
• /ARCHITECTURE = HOST generates instructions for the Itanium or Alpha processor that the compiler is running on (for example, EV56 instructions on an EV56 processor, and EV4 instructions on an EV4 processor).
• /ARCHITECTURE = EV4 generates instructions for the EV4 processor (21064, 21064A, 21066, and 21068 Alpha chips).
  Programs compiled with this option will not incur any emulation overhead on any Alpha processor.
• /ARCHITECTURE = EV5 generates instructions for the EV5 processor (some 21164 Alpha chips).
  Programs compiled with this option will not incur any emulation overhead on any Alpha processor.
• /ARCHITECTURE = EV56 generates instructions for the EV56 processor (some 21164 Alpha chips). This option permits the compiler to generate any EV4 instruction, plus any instructions contained in the BWX extension.
  Programs compiled with this option might incur emulation overhead on EV4 and EV5 processors.
  Note that the EV5 and EV56 processor both have the same chip number: 21164.
• /ARCHITECTURE = PCA56 generates instructions for the PCA56 processor (21164PC Alpha chip). This option permits the compiler to generate any EV4 instruction, plus any instructions contained in the BWX extension. Note that currently HP BASIC does not generate any of the instructions in the MAX extension to the Alpha architecture.
  Programs compiled with this option might incur emulation overhead on EV4 and EV5 processors.
• /ARCHITECTURE = EV6 generates instructions for the EV6 processor (21264 Alpha chip). This option permits the compiler to generate any EV4 instruction, any instructions contained in the BWX and MAX extensions, plus any instructions added for the EV6 chip. These instructions include a floating-point square root instruction (SQRT), integer/floating-point register transfer instructions, and additional instructions to identify extensions and processor groups.
  Programs compiled with this option might incur emulation overhead on EV4, EV5, EV56, and PCA56 processors.
• /ARCHITECTURE = EV67 generates instructions for the EV67 processor (21264A Alpha chip). This option permits the compiler to generate any EV6 instruction, plus bit count instructions (CTLZ, CTPOP, and CTTZ). However, HP BASIC does not generate any of the bit count instructions, so EV67 is essentially identical to EV6.
  Programs compiled with this option might incur emulation overhead on EV4, EV5, EV56, and PCA56 processors.
• /ARCHITECTURE = ITANIUM2 generates instructions for the Itanium 2 processor. This option permits the compiler to generate any Itanium 2 instructions.
• /ARCHITECTURE = MERCED generates instructions for the Merced processor. This option permits the compiler to generate any Merced instructions.

/NOAUDIT (default)

• 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

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

/CHECK = (BOUNDS,OVERFLOW) (default)

Remarks

• In Alpha BASIC, specifying /CHECK = NOBOUNDS causes bounds checking not to be performed on array parameters received by descriptor.
• /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.
• /CHECK = OVERFLOW enables checking for integers and packed decimal numbers.
• /CHECK = NOOVERFLOW disables overflow checking.
• /NOCHECK causes the compiler not to test for arithmetic overflow or for array references outside array boundaries when the program executes.
• /CHECK = ALL is the same as /CHECK = (BOUNDS, OVERFLOW).
• /CHECK = NONE is the same as /NOCHECK.

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

/NOCROSS_REFERENCE (default)

Remarks

• /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.
• The default for /CROSS_REFERENCE is NOKEYWORDS. See Chapter 16 for more information about cross-reference listings.
• /NOCROSS_REFERENCE specifies that no cross-reference listing be produced.

/DEBUG = (TRACEBACK,SYMBOLS) (default)

Remarks

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

/DECIMAL_SIZE = ( d,s )

/DECIMAL_SIZE = (15,2) (default)

/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 HP BASIC for OpenVMS Reference Manual for more information about packed decimal numbers.

/[NO]DEPENDENCY_DATA

/NODEPENDENCY_DATA (default)

Remarks

• 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.
• You must specify this qualifier if you want %INCLUDE %FROM %CDD and %REPORT %DEPENDENCY directives to establish dependency relationships.
• /NODEPENDENCY_DATA causes the compiler not to generate a compiled module entity.

/[NO]DIAGNOSTICS [ = file-spec ]

/NODIAGNOSTICS (default)

Remarks

• The Language-Sensitive Editor (LSE) must be installed.
• If you do not supply a file specification with the /DIAGNOSTICS qualifier, the diagnostics file has the same name as its corresponding source file and the file type .DIA. All other file specification attributes depend on the placement of the qualifier in the command. See the OpenVMS documentation set for more information.
• /NODIAGNOSTICS specifies that no diagnostics file is created.

/FLAG = NODECLINING (default)

Remarks

• /NOFLAG causes the compiler to issue no warnings about declining features.
• /FLAG = ALL is the same as /FLAG = DECLINING.
• /FLAG = NONE is the same as /NOFLAG.

/INTEGER_SIZE = (LONG) (default)

Remarks

• The default integer size (LONG) applies to all integer variables whose data type is not explicitly declared. See the HP BASIC for OpenVMS Reference Manual for more information about integer data types.

/[NO]LINES

/NOLINES (default)

Remarks

• /NOLINES causes line number information to be unavailable for the ERL function and the HP BASIC error reporter. Specifying /NOLINES makes your program run faster and reduces program size. However, specifying /NOLINES causes the following restrictions to be in effect:
  • You cannot use the ERL function.
  • No BASIC line number is given in run-time error messages.

/[NO]LISTING [ = file-spec ]

/LISTING (default in batch mode)

/NOLISTING (default in interactive mode)

Remarks

• /LISTING = file-spec produces a file with an explicit file specification. Omitting the file-spec produces a listing file with the same name as its corresponding source file and a file type of .LIS.
• All other file specification attributes depend on the placement of the qualifier in the command. See the OpenVMS User's Manual for more information.
• /LISTING only controls whether or not the compiler produces a listing file and is the default in batch mode.
• /SHOW controls which parts of the listing are produced.
• /NOLISTING specifies that no source listing file be produced and is the default at a terminal.

/[NO]MACHINE_CODE

/NOMACHINE_CODE (default)

Remarks

• /MACHINE_CODE specifies that the compiler include a listing of the compiler-generated object code in the listing file. If the /LISTING qualifier is not specified as well, /MACHINE is ignored.
• /NOMACHINE_CODE specifies that the listing file not include compiler-generated object code.

/[NO]OBJECT [ = file-spec ]

/OBJECT (default)

• If you specify one source file, BASIC generates one object file.
• If you specify multiple source files separated by plus signs (+), BASIC appends the files and generates one object file.
• If you specify multiple source files separated by commas (,), BASIC compiles and generates a separate object file for each source file.
• You can use both plus signs and commas in the same command line to produce different combinations of appended and separated object files.

Remarks

• /OBJECT = file-spec produces an object file with an explicit file specification. Omitting file-spec causes the compiler to produce an object file having the same name as its corresponding source file and the file type .OBJ. All other file specification attributes depend on the placement of the qualifier in the command. See the OpenVMS User's Manual for more information.
• /NOOBJECT suppresses the creation of an object file. During the early stages of program development, you might find it helpful to suppress the production of object files until your source program compiles without errors.

/[NO]OLD_VERSION [ = CDD_ARRAYS]

/NOOLD_VERSION (default)

The /NOOLD_VERSION qualifier causes the compiler to extract an array from the CDD/Repository with the bounds as specified in the data definition. For example, Array 2:5 in CDD/Repository is translated by the compiler to be an array with a lower bound of 2 and an upper bound of 5.

Remarks

• /OLD_VERSION [ = CDD_ARRAYS] is provided for compatibility with previous versions of BASIC.
• CDD/Repository assumes a default lower bound of 1, if none is specified. Therefore, if no lower bound is specified, the compiler translates the CDD/Repository array to have a lower bound of 1. For example, Array 5 in CDD/Repository is translated by HP BASIC to be an array with a lower bound of 1 and an upper bound of 5.

/OPTIMIZE = LEVEL = 4 (default)

/OPTIMIZE = TUNE = GENERIC (default)

The following list describes the /OPTIMIZE = LEVEL options:

• 0 has the same effect as /NOOPTIMIZE. Most optimizations are turned off.
• 1 has some optimizations (such as instruction scheduling).
• 2 adds more optimizations (such as loop unrolling and split lifetime analysis) to those in level 1.
• 3 adds more optimizations.
• 4 is the default level.
  /OPTIMIZE = LEVEL = 4 is equivalent to /OPTIMIZE or not specifying the qualifier. Level 4 is the maximum optimization level.

The /OPTIMIZE = TUNE qualifier selects processor-specific instruction tuning for a specific implementation of the Itanium or Alpha architecture. Tuning for a specific implementation can provide improvements in run-time performance.

Regardless of the setting of the /OPTIMIZE = TUNE qualifier, the generated code will run correctly on all implementations of the Itanium or Alpha architecture as appropriate. Note that code tuned for a specific target might run more slowly on another target than generically-tuned code.

The following list describes the /OPTIMIZE = TUNE options:

• GENERIC (default) selects instruction tuning that is appropriate for all implementations of the Itanium or Alpha architecture.
• HOST selects instruction tuning that is appropriate for the Itanium or Alpha machine on which the code is being compiled.
• EV4 selects instruction tuning for the 21064, 21064A, 21066, and 21068 implementation of the Alpha architecture.
• EV5 selects instruction tuning for the 21164 implementation of the Alpha architecture.
• EV56 selects instruction tuning for the 21164 implementation of the Alpha architecture.
• PCA56 selects instruction tuning for the 21164PC implementation of the Alpha architecture.
• EV6 selects instruction tuning for the 21264 implementation of the Alpha architecture.
• EV67 selects instruction tuning for the 21264A implementation of the Alpha architecture.
• ITANIUM2 selects instruction tuning for the Itanium 2 implementation of the Itanium architecture.
• MERCED selects instruction tuning for the Merced implementation of the Itanium architecture.

Remarks

• Specify /NOOPTIMIZE if you specify /DEBUG when compiling a program. /NOOPTIMIZE expedites and simplifies the debugging session by putting the machine code in the same order as the lines in the source program. Optimizations can cause unexpected and confusing behavior in a debugging session.
• Specifying /OPTIMIZE, the default, usually makes programs run faster. However, using /OPTIMIZE produces extra instructions to perform the optimization, which might result in larger object modules and longer compile times than the /NOOPTIMIZE qualifier.
• To speed compilations during program development, compile with /NOOBJECT qualifier to check syntax, with /NOOPTIMIZE to check for correct execution, and finally with /OPTIMIZE for the final check.

/REAL_SIZE = SFLOAT (I64 default); SINGLE (Alpha default)

Remarks

• The default floating-point size applies to all floating-point variables whose size is not explicitly declared.

See the HP BASIC for OpenVMS Reference Manual for more information about floating-point data types.

/[NO]ROUND_DECIMAL

/NOROUND_DECIMAL (default)

The /NOROUND_DECIMAL qualifier causes the compiler to truncate packed decimal numbers rather than round them.

The /ROUND_DECIMAL qualifier causes the INTEGER function to round rather than truncate the decimal part.

/SCALE = n

/SCALE = 0 (default)

Remarks

The /SCALE qualifier is provided for compatibility with existing programs and with other implementations of BASIC. It is recommended that you do not use this feature for new program development. Accumulated round-off errors can be better controlled with packed decimal numbers. See the HP BASIC for OpenVMS Reference Manual for more information about packed decimal numbers.

/[NO]SEPARATE_COMPILATION

/NOSEPARATE_COMPILATION (default)

When creating modules for use in an object library, consider using /SEPARATE_COMPILATION to minimize the size of the routines included by the linker as it creates the executable image. /SEPARATE_COMPILATION also reduces the compiler virtual memory requirements when a source contains several compilation units.