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:

• Source Program Listing
  The source program section contains the source code and line numbers generated by the compiler.
• Cross Reference
  The cross reference section is present if the /CROSS_REFERENCE qualifier was specified. It contains cross references of variables, symbols, and so forth.
• Allocation Map
  The allocation map section contains summary information about program sections, variables, and arrays.
• Qualifier Summary
  The qualifier summary section lists the qualifiers used with the BASIC command and the compilation statistics.
• Machine Code
  The machine code section is present if the /MACHINE_CODE qualifier was specified. It contains a symbolic representation of the machine instructions generated for the program section.

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:

• Resolves local and global symbolic references in the object code
• Assigns values to the global symbolic references
• Signals an error message for any unresolved symbolic reference
• Produces an executable image

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.

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

• Specify input file specifications for the object modules.
  If no file type is specified, the linker assumes that an input file is an object file with the file type .OBJ.
• Specify one or more object module library files.
  You can either specify the name of an object module library with the /LIBRARY qualifier, or specify the names of object modules contained in an object module library with the /INCLUDE qualifier. The uses of object module libraries are described in Section 3.2.5.
• Specify an options file.
  An options file can contain additional file specifications for the LINK command as well as special linker options. You must use the /OPTIONS qualifier to specify an options file. For more information about options files, see the OpenVMS Linker Utility Manual.

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:

• An object module has compilation errors.
  This error occurs when you attempt to link a module that has warnings or errors during compilation. You can usually link compiled modules for which the compiler generated messages, but you should verify that the modules will actually produce the output you expect.
• The input file has a file type other than .OBJ and no file type was specified on the command line.
  If you do not specify a file type, the linker assumes the file has a file type of .OBJ by default. If the file is not an object file and you do not identify it with the appropriate file type, the linker signals an error message and does not produce an image file.
• You tried to link a nonexistent module.
  The linker signals an error message if you misspell a module name on the command line or if the compilation contains fatal diagnostics.
• A reference to a symbol name remains unresolved.
  An error occurs when you omit required module or library names from the command line and the linker cannot locate the definition for a specified global symbol reference. For example, a main program module OCEAN.OBJ calls the subprograms located in object modules REEF.OBJ, SHELLS.OBJ, and SEAWEED.OBJ. However, the following LINK command does not reference the object module SEAWEED.OBJ:

  $ LINK OCEAN, REEF, SHELLS

  
  This example produces the following error messages:

  %LINK-W-NUDFSYMS, 1 undefined symbol %LINK-I-UDFSYMS, SEAWEED %LINK-W-USEUNDEF, module "OCEAN" references undefined symbol "SEAWEED" %LINK-W-DIAGISUED, completed but with diagnostics

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

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

• Align data items in MAP, COMMON, and RECORD statements. This is the recommended first step to improve performance. For more information on alignment, see Section 3.1.2 under /WARNING = ALIGNMENT.
• Use LONG or QUAD data items instead of BYTE and WORD; accessing LONG or QUAD items is faster than BYTE and WORD, which require multiple hardware instructions.
• Use GFLOAT or TFLOAT data items instead of DOUBLE; operations are faster on GFLOAT and TFLOAT items. Operations on DOUBLE operands are performed by converting to GFLOAT, performing the operation in GFLOAT, and converting back to DOUBLE.
• Choose packed decimal lengths that are the most efficient while still meeting the needs of the application. The most efficient sizes are the default size of 15 digits (which fits exactly in a quadword) and 7 digits (which fits exactly in a longword). If you use one of these preferred sizes, it should be aligned on a quadword or longword boundary.
• Use packed decimal only when it is the appropriate data type. For example, do not use packed decimal to specify array subscripts, which are integers.
• Minimize mixed data type expressions, especially when you use packed decimal.

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

• Use overflow and bounds checking only if they are needed. (See Section 3.1.2; bounds checking is needed if your program is not thoroughly debugged.) Both of these /CHECK options are on by default and will hinder performance.
• The use of the /LINES qualifier can impede optimization. /LINES is needed in Alpha BASIC only for the ERL function and to print BASIC line numbers in run-time error messages. /NOLINES is the default in Alpha BASIC.
• The default optimization level, /OPTIMIZATION=LEVEL=4, provides the highest level of optimization.
• The /SYNCHRONOUS_EXCEPTIONS qualifier inhibits many optimizations. For more information on /SYNCHRONOUS_EXCEPTIONS, see Section 3.1.2.

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

• If you use error handling, the default ON ERROR GO BACK has the least impact on performance. ON ERROR GOTO {target} and WHEN blocks have a greater impact. If the application spends a large percentage of time in one routine, consider writing the routine with default error handling, if possible.
• RESUME without a target impedes optimization. (This applies only to RESUME statements that do not specify a target.)
• A MOVE TO or FIELD statement limits optimizations in the entire routine (SUB, FUNCTION, or main) where the statement is found. There is no additional cost for any statement after the first.
• OPTION INACTIVE = SETUP can dramatically minimize routine startup times by omitting RTL calls that initialize and close down routines. For small BASIC routines, the overhead of these RTL calls can be significant. Use this option for routines that are frequently called.
  If your routine contains any of the following elements, the compiler provides an informational diagnostic and emits calls to the RTL initialization and close-down routines.

  CHANGE statements
  DEF statements
  Dynamic string variables
  Executable DIM statements
  EXTERNAL string functions
  MAT statements
  MOVE statements for an entire array
  ON ERROR statements
  READ statements
  REMAP statements
  RESUME statements
  WHEN blocks
  String concatenation
  Built-in string functions
  Virtual arrays

  
  Routines using OPTION INACTIVE = SETUP cannot perform I/O and have no error-handling capabilities. If an error occurs in such a routine, the error is resignaled to the calling routine.
  Using OPTION INACTIVE = SETUP instructs the compiler not to emit code to initialize local variables. This also improves run-time performance, but impacts routines that rely upon the automatic initialization of local variables.
• CONTINUE without a target and RETRY can limit optimizations within the scope of the WHEN blocks associated with the handler that contains these statements. This impact can be significant if the handler is associated with a large WHEN block. The code within the associated WHEN blocks will be minimally optimized.