HP OpenVMS Systems Documentation

HP BASIC for OpenVMS
User Manual

Remarks

• /SEPARATE_COMPILATION causes the compiler to place each routine in a separate module within the output object.
• /NOSEPARATE_COMPILATION, in most cases, allows more interprocedural optimizations.

/SHOW = (CDD_DEFINITIONS, ENVIRONMENT, INCLUDE, MAP, NOOVERRIDE)
(default)

Remarks

• The size value for dynamically mapped arrays is the size of the actual array.
• /LISTING must be specified for /SHOW to be effective.
• CDD_DEFINITIONS controls whether the translation of a CDD/Repository record is displayed in the listing.
• ENVIRONMENT lets you display all defaults that were in effect when the program was compiled. This is the compilation listing equivalent of the SHOW command in the environment.
• INCLUDE controls whether files accessed with the %INCLUDE directive are displayed in the listing.
• MAP determines whether the listing contains an allocation map. The allocation map lists all program variables, their size, and their data type.
• OVERRIDE helps you debug code by disabling the effect of the %NOLIST directive.
• /NOSHOW causes the compiler to display only the source listing.
• /SHOW = ALL is the same as /SHOW = (CDD_DEFINITIONS,
  ENVIRONMENT, INCLUDE,MAP, OVERRIDE).
• /SHOW = NONE is the same as /NOSHOW.

/[NO]SYNCHRONOUS_EXCEPTIONS

/NOSYNCHRONOUS_EXCEPTIONS (default)

A = B
C = D / E
G = F

If the value of E is zero, the second statement will generate a divide by zero error. As a result of instruction reordering, it is possible that the assignment A = B will not take place. Further, it is possible that the assignment G = F will take place even though the previous statement generated an error.

The /SYNCHRONOUS_EXCEPTIONS qualifier disables reordering. Use this qualifier for programs that rely on arithmetic exceptions to occur at precise times during program execution.

The /SYNCHRONOUS_EXCEPTIONS qualifier impacts only arithmetic exceptions and variable assignments in the immediate area of the excepting statement.

Very few programs should require the /SYNCHRONOUS_EXCEPTIONS qualifier to produce correct results.

/TYPE_DEFAULT = REAL (default)

Remarks

• EXPLICIT specifies that all program variables must be explicitly declared in DECLARE, EXTERNAL, COMMON, MAP, or DIM statements.
• INTEGER, REAL, or DECIMAL specify that only variables and data which are not explicitly declared default to integer, real, or packed decimal.
• INTEGER_SIZE, REAL_SIZE, and DECIMAL_SIZE cause the compiler to specify the actual size of variables and data.

/VARIANT = int-const

Remarks

• If /VARIANT is not specified, the default value is 0.
• If /VARIANT is specified without a value, the default is 1.

/WARNINGS = (INFORMATIONAL,WARNINGS,NOALIGNMENT) (default)

Remarks

• /WARNINGS = NOWARNINGS causes the compiler to display informational messages but not warning messages.
• /WARNINGS = NOINFORMATIONALS causes the compiler to display warning messages but not informational messages.
• /NOWARNINGS causes the compiler to suppress any informational or warning messages.
• /WARNINGS = ALIGNMENT causes the compiler to flag all occurrences of non-naturally aligned RECORD fields, variables within COMMONs and MAPs, and RECORD arrays.
  An aligned data item starts on an address that is natural for that data type. Unaligned data accesses on Alpha can significantly reduce performance. Table 2-1 lists the natural boundaries for the supported data types.

  Table 2-1 Natural Boundaries For Supported Data Types

  Data Type	Natural Boundary
  BYTE	BYTE
  DECIMAL	BYTE
  DOUBLE	QUADWORD
  DYNAMIC STRING	BYTE
  GFLOAT	QUADWORD
  LONG	LONGWORD
  QUAD	QUADWORD
  RECORD	Depends on contents
  RFA	BYTE
  SFLOAT	LONGWORD
  SINGLE	LONGWORD
  STATIC STRING	BYTE
  TFLOAT	QUADWORD
  WORD	WORD
  XFLOAT	OCTAWORD

  
  /WARNINGS = NOALIGNMENT, the default, causes the compiler not to issue any warning messages about unaligned data.
  The compiler naturally aligns all local variables and arrays, but it is the responsibility of the BASIC programmer to naturally align COMMONs, MAPS, and RECORDs. The /WARNINGS = ALIGNMENT qualifier flags all occurrences of non-naturally aligned items. This helps the programmer identify and correct unaligned entities.
  An entity can be unaligned in the following ways:
  • The entity does not start on a natural boundary for its data type. There are several actions a programmer can take to resolve this:
    • Rearrange the RECORD, MAP, or COMMON so that all entities start on natural boundaries.
    • Force proper alignment with fill items, as needed.
    
    Note that the natural alignment for a RECORD is equal to the largest alignment required by any of its fields. As an example, if a RECORD has a byte, long, and double field, the alignment of the RECORD would be quadword.
  • For arrays of RECORDs and GROUPs, items can be unaligned if the size of a RECORD or GROUP is not a multiple of the alignment requirements of that RECORD or GROUP. For example, if a RECORD has a natural alignment of quadword, the size of the RECORD must be a multiple of eight. Otherwise, all array elements after the first might start on an unaligned boundary. Avoid unaligned accesses by padding the end of the RECORD with fill items.
• /WARNINGS = ALL is the same as /WARNINGS = (INFORMATIONAL, WARNINGS, ALIGNMENT).
• /WARNINGS = NONE is the same as /NOWARNINGS.

The following qualifiers are declining features:

/BYTE
/DOUBLE
/GFLOAT
/LONG
/SINGLE
/TIE
/WORD

It is recommended that you replace them with newer qualifiers, as follows:

See the description of the /[NO]FLAG = [NO]DECLINING qualifier in this chapter. Also see the descriptions of the /INTEGER_SIZE and /REAL_SIZE qualifiers in this chapter. The old qualifiers are described in the HP BASIC for OpenVMS Reference Manual.

2.1.4 Compiler Listings

A compiler listing provides information that can help you debug your HP BASIC program. To generate a listing file, specify the /LISTING qualifier when you compile your HP 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 2.2.2 for a complete description of these and other LINK command qualifiers.

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

2.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:

/command-qualifier

Specifies one or more output file options.

file-spec

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

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 HP 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 2.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 HP OpenVMS Linker Utility Manual.

The linker uses the following default file types for input 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

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 HP OpenVMS DCL Dictionary for more information about the DEFINE command.

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

2.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.