Compaq BASIC for OpenVMS
Alpha and VAX Systems
User Manual


Previous Contents Index

3.1.4 Compiler Listings

A compiler listing provides information that can help you debug your BASIC program. To generate a listing file, specify the /LISTING qualifier when you compile your BASIC program interactively. For example:


$ BASIC/LISTING prog-name

If the program is compiled as a batch job, the listing file is created by default; specify the /NOLISTING qualifier to suppress creation of the listing file. By default, the name of the listing file is the name of the source program followed by the file type .LIS. You can include a file specification with the /LISTING qualifier to override this default.

A compiler listing generated by the /LISTING qualifier has the following major sections:

3.2 Linking a BASIC Program

On OpenVMS systems, the OpenVMS Linker (linker) simplifies the job of each language compiler because the logic needed to resolve symbolic references need not be duplicated. The main advantage to a system that has a linker, however, is that individual program modules can be separately written and compiled, and then linked together. This includes object modules produced by different language compilers.

The linker performs the following functions:

When you link a program in development, in order to enable debugging, use the /DEBUG qualifier with the LINK command. The /DEBUG qualifier appends to the image all the symbol and line number information appended to the object modules plus information about global symbols, and forces the image to run under debugger control when you execute it (unless you then specify /NODEBUG).

The LINK command produces an executable image by default; however, you can also use the LINK command to obtain shareable images and system images. The /SHAREABLE qualifier directs the linker to produce a shareable image; the /SYSTEM qualifier directs the linker to produce a system image. See Section 3.2.2 for a complete description of these and other LINK command qualifiers.

For a complete discussion of the OpenVMS Linker, see the OpenVMS Linker Utility Manual.

3.2.1 LINK Command

Once you have compiled your source program or module, you link it by using the DCL command LINK. The LINK command combines your object modules into one executable image, which can then be executed by the OpenVMS system. A source program or module cannot run on the OpenVMS system until it is linked. The format of the LINK command is as follows:

LINK[ /command-qualifier]... {file specification [/file-qualifier...]},...

/command-qualifier

Specifies one or more output file options.

file specification

Specifies the input file or files to be linked.

/file-qualifier

Specifies one or more input file options.

If you specify more than one input file, you must separate the input file specifications with plus signs (+) or commas (,). By default, the linker creates an output file with the name of the first input file specified and the file type .EXE. When you link more than one file, list the file containing the main program first. This way, the name of your output file will have the same name as that of your main program module.

The following command line links the object files DANCE.OBJ, CHACHA.OBJ, and SWING.OBJ to produce one executable image called DANCE.EXE:


$ LINK DANCE.OBJ, CHACHA.OBJ, SWING.OBJ

3.2.2 LINK Command Qualifiers

The LINK command qualifiers can be used to modify linker output, as well as to invoke the debugging and traceback facilities. Linker output consists of an image file and an optional map file. Image file qualifiers, map file qualifiers, and debugging and traceback qualifiers are described in this section.

This section summarizes some of the most commonly used LINK command qualifiers. For a complete list and description of LINK qualifiers, see the OpenVMS Linker Utility Manual.

/BRIEF

The /BRIEF qualifier causes the linker to produce a summary of the image's characteristics and a list of contributing modules. This qualifier is used with /MAP.

/[NO]CROSS_REFERENCE

/NOCROSS_REFERENCE (default)

The /CROSS_REFERENCE qualifier causes the linker to produce cross-reference information for global symbols; the /NOCROSS_REFERENCE qualifier causes the linker to suppress cross-reference information.

/[NO]DEBUG

/NODEBUG (default)

The /DEBUG qualifier causes the linker to include the OpenVMS Debugger information in the executable image and generates a symbol table; the /NODEBUG qualifier causes the linker to prevent debugger control of the program. The default is /NODEBUG.

/[NO]EXECUTABLE [= file-spec]

/EXECUTABLE (default)

The /EXECUTABLE qualifier causes the linker to produce an executable image; the /NOEXECUTABLE qualifier suppresses production of an image file. If a file-spec is given, the resulting image is given the name of the file-spec.

/FULL

The /FULL qualifier causes the linker to produce a summary of the image's characteristics, a list of contributing modules, listings of global symbols by name and by value, and a summary of characteristics of image sections in the linked image. This qualifier is used with /MAP.

/[NO]MAP [= file-spec]

/NOMAP (default interactive mode)

/MAP (default batch mode)

The /MAP qualifier causes the linker to generate a map file; the /NOMAP qualifier suppresses the map. If a file-spec is given, the map file is given the name of the file-spec.

/[NO]SHAREABLE

/NOSHAREABLE (default)

The /SHAREABLE qualifier causes the linker to create a shareable image; the /NOSHAREABLE qualifier generates an executable image.

/[NO]TRACEBACK

/TRACEBACK (default)

The /TRACEBACK qualifier causes the linker to generate symbolic traceback information when error messages are produced; the /NOTRACEBACK qualifier suppresses traceback information.

3.2.3 Linker Input Files

You can specify the object modules to be included in an executable image in any of the following ways:

The linker uses the following default file types for input files:
File File Type
Object module .OBJ
Object library .OLB
Options file .OPT

3.2.4 Linker Output Files

When you enter the LINK command interactively and do not specify any qualifiers, the linker creates only an executable image file. By default, the resulting image file has the same file name as the first object module specified, and the file type .EXE.

In a batch job, the linker creates both an executable image file and a storage map file by default. The default file type for map files is .MAP.

To specify an alternative name for a map file or image file, or to specify an alternative output directory or device, you can include a file specification on the /MAP or /EXECUTABLE qualifier. For example:


$ LINK UPDATE/MAP=TEST

3.2.5 Using an Object Module Library

In a large development effort, the object modules for subprograms are often stored in an object module library. By using an object module library, you can make program modules contained in the library available to other programmers. To link modules contained in an object module library, use the /INCLUDE qualifier and specify the specific modules you want to link. For example:


$ LINK GARDEN, VEGGIES/INCLUDE=(EGGPLANT,TOMATO,BROCCOLI,ONION)

This example directs the linker to link the object modules EGGPLANT, TOMATO, BROCCOLI, and ONION with the main object module GARDEN.

Besides program modules, an object module library can also contain a symbol table with the names of each global symbol in the library, and the name of the module in which they are defined. You specify the name of the object module library containing symbol definitions with the /LIBRARY qualifier. When you use the /LIBRARY qualifier during a link operation, the linker searches the specified library for all unresolved references found in the included modules during compilation.

In the following example, the linker uses the library RACQUETS to resolve undefined symbols in BADMINTON, TENNIS, and RACQUETBALL:


$ LINK BADMINTON, TENNIS, RACQUETBALL, RACQUETS/LIBRARY

You can define an object module library, such as LNK$LIBRARY, to be your default library by using the DCL command DEFINE. The linker searches default user libraries for unresolved references after it searches modules and libraries specified in the LINK command. See the OpenVMS DCL Dictionary for more information about the DEFINE command.

For more information about object module libraries, see the OpenVMS Linker Utility Manual.

3.2.6 Linker Error Messages

If the linker detects any errors while linking object modules, it displays messages indicating the cause and severity of the error. If any error or fatal error conditions occur (errors with severities of E or F), the linker does not produce an image file.

The messages produced by the linker are descriptive, and you do not usually need additional information to determine the specific error. Some common errors that occur during linking are as follows:

If an error occurs when you link modules, you can often correct the error by reentering the command string and specifying the correct modules or libraries.

See the OpenVMS System Messages and Recovery Procedures Reference Manual for a complete list of linker messages.

3.3 Running a BASIC Program

After you link your program, use the DCL command RUN to execute it. The RUN command has the following format:

RUN [/[NO]DEBUG] file-spec [/[NO]DEBUG]

/[NO]DEBUG

The /[NO]DEBUG qualifier is optional. Specify the /DEBUG qualifier to request the debugger if the image is not linked with it. You cannot use /DEBUG on images linked with the /NOTRACEBACK qualifier. If the image is linked with the /DEBUG qualifier, and you do not want the debugger to prompt, use the /NODEBUG qualifier. The default action depends on whether the file is linked with the /DEBUG qualifier.

file-spec

The name of the file you want to execute.

The following example executes the image SAMPLE.EXE without invoking the debugger:


$ RUN SAMPLE/NODEBUG

See Chapter 4 for more information about debugging programs.

During program execution, an image can generate a fatal error called an exception condition. When an exception condition occurs, BASIC displays an error message. Run-time errors can also be issued by other facilities, such as the OpenVMS operating system. For more information about run-time errors, see Appendix B.

3.3.1 Improving Run-Time Performance of Alpha BASIC Programs

OpenVMS Alpha can substantially improve BASIC run-time performance relative to OpenVMS VAX. In addition to the performance gains that the Alpha hardware provides, the Alpha BASIC compiler produces highly optimized code.

Even with faster hardware and an optimizing compiler, you can still tune your code for run-time performance. This section provides recommendations to consider if further performance improvements are desirable.

To achieve the best performance for your application, it is important to let both the hardware and the optimizer/code generator take advantage of their full capabilities. This can be accomplished by minimizing, and in some cases avoiding, the use of language features and qualifiers that block optimal program execution.

3.3.1.1 Data Items

Choose data types and align data items with the following in mind:

3.3.1.2 Qualifiers

On your BASIC command line, consider the following when you specify qualifiers:

3.3.1.3 Statements

The statements used in a program can affect performance, as follows:


Previous Next Contents Index