Certain errors can produce multiple lines of informational text to aid
in program correction. For example, the error message
"Inconsistency detected during overload resolution" is
followed by supplemental messages that provide information about how
the overloading resolution was attempted. Terminal output of such
supplemental messages is limited to six lines, provided a listing is
also being produced (which contains the full message). Otherwise, the
full message is displayed. Error messages frequently provide
information on what was found and what was expected and give suggested
corrections.

Warning messages and each class of informational messages can be
selectively enabled or disabled to each of the listing, terminal, and
diagnostics files.

All messages are in English. Messages take the general form of host
operating system error messages with further informational text.

The compiler tries to identify errors as accurately in the source code
as possible. A dot and numeral (......1) display is used to show the
correspondence of error messages to points in the source code.

No object file is produced for units containing errors. However, the
object file is produced if there are only warning or informational
messages.

When the ACS LOAD, COMPILE, or RECOMPILE commands are used, any program
library manager output and diagnostic messages generated before the
compiler is invoked are directed to SYS$OUTPUT by default. The
/OUTPUT=file-spec qualifier can be used to direct program library
manager output and diagnostic messages to a file.

On DIGITAL UNIX systems, terminal messages are written to standard
error. Interactive error messages displayed on the terminal can be
directed to a file for later reference by redirecting standard error.

Error Messages

Error messages provide extensive supplemental information (for example:
how the compiler attempted to resolve overloading, what syntactic token
the compiler expected at a particular point and what it actually found,
and so on).

The compiler uses an error-correcting parser. Attempts are made to
diagnose as many errors as possible while minimizing cascading errors.

There is no "restart at a position" ability in the compiler.

Warning Messages

A warning message is produced if a pragma is ignored and compilation
proceeds.

Informational Messages

An informational message is produced for the following conditions:

An exception that is sure to be raised

Unreachable source code

An object that is declared but not used (in which case no storage
is allocated)

Subprogram formal parameters and discriminants of type declarations
that are not referenced within the subprogram or type, respectively

Use of an unassigned (uninitialized) variable On Alpha systems,
the compiler flags uninitialized variables but does not reject a
program that depends on them. On OpenVMS VAX and Alpha, the compiler
optionally flags variables, formal parameters of subprograms, and
discriminants that are never referenced.

Informational messages are produced for the latter three conditions
only if the appropriate symbol was set or option was specified when the
compilation command was issued.

DEC Ada Version 3.5 for OpenVMS Alpha includes a Report Mapper
utility that maps Ada and ACS commands to their approximations in the
GNAT environment. This is an informational tool, intended to
help users understand the correspondence between DEC Ada commands
and GNAT commands.

The Report Mapper (or ADAMAP) is an executable image that runs in the
OpenVMS Alpha environment.

ADAMAP has two modes of operation:

Interactive: ADAMAP accepts input from the keyboard

File-driven: ADAMAP reads input from a text file containing commands

Interactive mode is useful for experimenting with a variety of
commands. In interactive mode the program prompts you to input Ada or
ACS commands to be mapped to GNAT commands. ADAMAP output is directed
to the screen (SYS$OUTPUT).

File-driven mode is useful for examining your existing command files.
In file-driven mode you include the name of a command file on the
command line, and ADAMAP reads the commands from the specified command
file. ADAMAP output IS directed to the screen, but can be redirected to
a file.

A command file can contain a mix of DEC Ada commands and other
commands. ADAMAP will selectively evaluate only the DEC Ada
commands on a one-by-one basis, ignoring the other commands.

Note

The ADAMAP output file is not directly applicable in the GNAT
environment, but is an intermediate aid that you can evaluate as an aid
in using the GNAT environment.

Some features that you should consider are as follows:

Defined symbols (such as commands) are not expanded during the
mapping operation

The context of any other commands surrounding the currently mapped
command is not used

You may invoke the ADAMAP command verb with or without a name of a
command file to be analyzed.

Note

Before you use ADAMAP you should execute the command file
ADA$EXAMPLES:ADAMAP.COM, which will set up the necessary symbol for the
command verb.

ADAMAP is invoked as follows:

ADAMAP [ qualifiers ] [ file-spec]

qualifiers can be added to specify special processing.
(Qualifiers are described in more detail in Section 8.3.)

file-spec is the file specification of the command
file to be processed. Wildcards are not permitted. If file-spec is
given, ADAMAP works in file-driven mode. If file-spec is omitted,
ADAMAP works in interactive mode, requesting commands from the user.

In file-driven mode, the report can either be redirected to a file by
using the /OUTPUT qualifier. In both modes, output can be formatted
into a specified number of lines with the /PAGE qualifier.

There are two possible scenarios, depending on whether a file-spec is
provided:

If no file-spec is provided on the command line, ADAMAP will
briefly describe its operation on the terminal screen and prompt you
for input as shown in the following example:

ADAMAP V1.0 - DEC Ada to GNAT Mapper
The DEC Ada to GNAT Mapper (ADAMAP) accepts an ACS or
ADA command and produces an approximation to that
command for GNAT, the Ada Core Technology Ada 95
Compiler. In addition, ADAMAP produces informational
notes.
At the prompt, type a command beginning with ADA or ACS
and end the command by pressing the Return key.
To recall commands, use the up arrow key.
To exit, type CTRL/Z or EXIT followed by the Return
key.
DEC Ada Command>

If a file-spec is provided on the command line, ADAMAP will read
the commands in the specified command file and produce suggested
translations and informational notes on the screen. If an extension
is not included in file-spec, .COM is assumed as shown in the following
example:

ADAMAP mybuildfile

ADAMAP will analyze the file mybuildfile.com and send output
messages to the terminal screen. To generate a report file, use the
/OUTPUT qualifier as shown in the following example:

ADAMAP/OUT mybuildfile

...ADAMAP will read the file mybuildfile.com and produce the report
file mybuildfile.grpt. With the following example:

ADAMAP mybuildfile/OUT=myreport

...ADAMAP will read the file mybuildfile.com and produce the report
file myreport.grpt.

ADAMAP output will normally be sent to SYS$OUTPUT (usually your
screen). The qualifier /OUTPUT=file-name may be used to redirect the
output to the specified file.

In interactive mode, /OUTPUT is ignored. In file-driven mode /OUTPUT
with no file name will produce a file named for input-file, with the
extension .GRPT added.

If you enter /OUTPUT= with a partial file specification, the partial
file specification will be extended with the name of the input-file and
the extension .GRPT. For example, /OUTPUT=A:[HOME] will construct the
file-specification A:[HOME]INFILE.GRPT, if INFILE was the name of the
input-file.

/PAGE[=no-of-lines]

The /PAGE qualifier is used to control screen output. If no-of-lines is
specified, ADAMAP will produce that number of lines then output the
screen message "PRESS RETURN TO CONTINUE" and wait for your keyboard
input. If /PAGE is used and no value is specified, the default value of
23 lines will be used.

If you do not specify /PAGE the screen output will scroll until the end
of the input file is reached. You may use the keyboard F1 key to pause
both screen output and program progress through the input file.

/BRIEF

ADAMAP will produce all informational messages that are triggered by
the analysis of each ACS or Ada command. You may add the /BRIEF
qualifier to suppress redundant messages. Each initial instance of a
given message for a command will be produced, but subsequent instances
(repeats) of that message for that same command will be suppressed.

Messages for incorrect input or unsupported qualifiers will not
be suppressed.

The ADAMAP output shows, for each Ada or ACS command, the GNAT
approximation of that command. Direct commands (DCL commands that are
neither Ada nor ACS) are listed separately in the report. In addition
to the suggested replacement command, ADAMAP provides helpful
information about any differences between GNAT and DEC Ada for
the particular command. An example of ADAMAP output is given in
Section 8.5.1, Sample ADAMAP Output.

The Report Output generated for the DOC.COM in Section 8.5 is shown
in the following example:

ADAMAP V1.0 - DEC Ada to GNAT Mapper
The DEC Ada to GNAT Mapper (ADAMAP) reads ACS and ADA
commands and produces an approximation to those
commands for GNAT, the Ada Core Technology Ada 95
Compiler. In addition, ADAMAP produces informational
notes.
ADAMAP reads commands from your input file
(maptest:typical.com). ADAMAP processes each Ada or ACS
command in your file and lists these commands as DEC
Ada Commands. ADAMAP lists other commands as Direct
Commands, but does no processing of these commands.
Direct Commands:
$ set ver
$ set def [home.x]
$
$! Create and Set Library
DEC Ada Command:
$ acs crea lib [.adalib]
GNAT Equivalent:
$ CREATE/DIRECTORY [.adalib]
Notes:
The ACS CREATE LIBRARY command creates a program
library.
IEEE is the default float representation for GNAT and
its use is suggested. To get a VAX_FLOAT library, use
the GNAT MAKE LIBRARY command with the /CONFIG
qualifier.
To see the commands that the mapper produces to get a
VAX_FLOAT library ( the DEC Ada default) in the GNAT
environment, try the ACS CREATE LIBRARY command with
the /FLOAT_REPRESENTATION=VAX qualifier
The [.adalib] directory will contain the .ADB,.ADS,.ALI,
and .OBJ files
GNAT does not have a library system like the DEC Ada
compilation system. GNAT uses the current directory as
the library.
DEC Ada Command:
$ acs set lib [.adalib]
GNAT Equivalent:
$ COPY *.ADA [.adalib]
$ SET DEFAULT [.adalib]
Notes:
The SET LIBRARY command defines the current operating
library.
You can choose to update the files in the original
directory and copy them into the working directory
after each change or you can update the files in the
working directory.
The *.ADA files will be changed to .ADS or .ADB files
by the GNAT CHOP utility.
GNAT does not have a library system like the DEC Ada
compilation system. GNAT uses the current directory as
the library.
The [.adalib] directory will contain the .ADB,.ADS,.ALI,
and .OBJ files
Direct Commands:
$
$! Begin Compilation
DEC Ada Command:
$ acs load alpha,beta
GNAT Equivalent:
$ GNAT CHOP/REFERENCE/OVERWRITE alpha.ADA
$ GNAT CHOP/REFERENCE/OVERWRITE beta.ADA
Notes:
The ACS LOAD Command processes Ada units contained in
one or more source files and partially compiles the
units to detect syntax errors and determine unit
dependencies.
GNAT CHOP reads the specified file to create, in the
current directory, an .ADB file for each body, and an
.ADS file for each specification. CHOP also performs
syntax analysis.
The CHOP /REFERENCE qualifier assumes the chopped files
are temporary so development refers to the original
unchopped file.
The CHOP /OVERWRITE qualifier allows GNAT CHOP to
overwrite a file with the same name in the target
directory.
DEC Ada Command:
$ acs compile alpha
GNAT Equivalent:
$ GNAT COMPILE /83 alpha.ADB
Notes:
The ACS COMPILE command compiles from external sources
any unit in the closure ( except entered units )
revised since the unit was last compiled into the
current program library.
The GNAT COMPILE command compiles a file with the
extension .ADB and .ADS. The results of a successful
compilation is an object file with the extension .OBJ
and an Ada Library Information file with the extension
.ALI.
The GNAT /83 qualifier enforces Ada 83 restrictions.
If a language specification has a separate body, only
the body need be compiled.
Direct Commands:
$
$! Now link and go
DEC Ada Command:
$ acs link alpha
GNAT Equivalent:
$ GNAT BIND alpha.ALI
$ GNAT LINK alpha
Notes:
The ACS LINK command creates an executable image file
for the specified units.
The GNAT Binder checks that a program is consistent and
that an acceptable elaboration order exists. It
generates a main program incorporating the elaboration
order and determines the set of object files required.
The GNAT Linker uses the Binder file to link programs
and build an executable file.
The GNAT MAKE command can be used to automatically
determine the files to be compiled. It then compiles,
binds, and links them to create an executable program.
Direct Commands:
$ run alpha
$
$ set nover

DEC Ada programs can be debugged using the standard host system
debugger, the OpenVMS Debugger. The OpenVMS Debugger provides extensive
facilities to aid the debugging of programs, including programs in
multilanguage environments. The following sections describe these
facilities and commands.

OpenVMS Debugger General Facilities

The general debugger facilities that apply to all supported languages
allow users to perform the following operations:

Stop execution (set breakpoints) at selected locations, specified
either by routine name or by source module and line number or when
exceptions occur.

Single step in increments of single hardware instructions or source
lines. Stepping can selectively pass into called routines or treat the
execution of a routine call as a single instruction.

Watch the value of specified variables and interrupt execution when
the value of a variable is changed.

Call procedures that are part of the program. (Functions cannot be
called as part of expression evaluation but can be called as a
procedure and the result displayed.)

The debugger automatically establishes the language in which the main
program is written as the language of discourse. Thereafter, the
language can be changed as appropriate to the parts of the program
where debugging is in progress. The language setting adjusts the
debugger syntax and interpretation of expressions as appropriate to
that language.

The support that the debugger provides for Ada language expressions is
not complete. The debugger does, however, provide extensive
capabilities for interpreting Ada expressions in a useful manner.

The debugger supports the following aspects of Ada expressions:

Syntax of identifiers: function designators that are operator names
must begin with the prefix %NAME (for example, %NAME'+')

Numeric, character, and string literals

Indexed component, slice, selected component, and attribute
notations

Evaluation of the following attributes: CONSTRAINED, FIRST and
FIRST(n), LAST and LAST(n), LENGTH and LENGTH(n), POS, PRED, SIZE,
SUCC, and VAL

Evaluation of operators, except that relational operators are
supported only for scalar and string types, catenation operators are
supported only for string types, and the logical operators are not
supported for bit arrays

Qualified expressions, but only to resolve overloaded enumeration
literals (literals that have the same identifier but belong to
different enumeration types)

The debugger does not support the following:

Overloading resolution Ambiguities are reported and special
means are available to indicate how to interpret ambiguous names.

Aggregates

Operations (other than examination) on entire arrays or records

User-defined operators

Short-circuit control forms: and then, or
else

Membership tests: in, not in

Type conversions

Allocators

Universal expressions

OpenVMS Debugger Tasking Facilities

Debugging programs involving Ada tasks requires additional facilities
beyond those applicable to most languages. These additional facilities
are described in the following list:

Display the state of given tasks or all tasks in a program. The
possible states are as follows:

Running

Ready

Suspended (including when initially created)

Terminated

Display more detailed substates of the main state:

Abnormal

Waiting at an accept statement

Activating (elaborating its declarative part)

Activating tasks (waiting for dependent tasks to finish activating)

Completed normally, completed because of an exception, or completed
abnormally

Delay

Dependents (waiting for dependent tasks to terminate, either
normally or because of an exception)

Entry call

Invalid state

Input-output or AST

Not yet activated

Select, with or without delay or terminate alternatives

Shared resource

Terminated normally, terminated because of an exception, or
terminated abnormally

Timed entry call

Place a task on hold so that it is not scheduled for execution

Establish a given task to be the active task (that is, perform a
task switch)

Change the priority of a task

Abort a task

Change the time-slice interval used for task scheduling (this
feature is not available on all targets)

Display tasking run-time statistics: number of entry calls, tasks
activated, accept and select operations, and so on

Suspend execution (set breakpoints) for various tasking events:

An exception is about to be handled: in any handler or just an
others choice

An exception is about to propagate from a rendezvous

An exception is waiting for dependents to terminate

A task is about to terminate, because of an exception, abort
statement, or normally

A task is about to execute, for the first time or any time

A task is preempted by a higher priority task

A task starts its activation

A task becomes suspended

A number of debugger lexical functions and commands have been
implemented specifically to support the debugging of DEC Ada programs.
These functions and commands supplement the general debugger
capabilities. Lexical functions provide various means to obtain
information about the program being debugged and to control the
interpretation of debugger names and expressions.

Debugging Restrictions

In general, the debugging environments and capabilities on OpenVMS VAX
and OpenVMS Alpha systems are not identical because of the differences
in code generators used.

On OpenVMS VAX systems, the debugger can use the source file in the ACS
library. On OpenVMS Alpha systems, the debugger uses the source file
from the directory where it is compiled. If you put your DEC Ada source
files in CMS libraries after compilation, CMS deletes the source from
your directory by default. The result is that the debugger does not
find the source file.

The workaround is either to use a SET SOURCE command in the debugger or
to put the original source file back in the directory where it was
compiled.

Another important restriction is that the error message "Source
line not available" appears if the source file is not in the
directory where it was compiled.

These restrictions and others are detailed in the release notes for
each platform.

On ULTRIX systems, DEC Ada programs are debugged using the
dbx
debugger.

These debuggers are source-level debuggers. They provide facilities to
aid the debugging of programs in multilanguage environments.

Note that users must understand C syntax to debug DEC Ada code. For
example, Ladebug and
dbx
support the unary "*" as the dereferencing operator to get
the complete accessed value. Both debuggers also support the use of
"->" to access a component of the accessed record. These
are both examples where the debugger requires C syntax (not Ada syntax).

On both systems, DEC Ada provides the
ada_debug
function, which (in combination with the debugger) allows the debugging
of tasking programs.

The DEC Ada compiler generates standard DIGITAL UNIX or ULTRIX object
files containing both the instructions and data for an Ada program.
Optionally, they contain additional symbol table information that is
used by the debugger and the
ada_debug
function.

The following sections briefly describe using a debugger and the
ada_debug
function to debug Ada programs.

DIGITAL UNIX and ULTRIX Debugger General Facilities

To compile units for debugging, specify the
-g
option. The following commands show how a program is compiled and
linked for execution under debugger control:

Both
ladebug
and the
ada_debug
routine are used to debug Ada tasking programs. The
ada_debug
routine allows the user to observe task characteristics and task
states. Also, it monitors events that are specific to tasks, such as
rendezvous. To use the
ada_debug
routine, the user runs the program under the control of the debugger,
sets a breakpoint where tasks are to be examined or modified, and
enters the following command:

(debug) print ada_debug()

This command calls the
ada_debug
routine, which issues the following prompt:

ada_debug>

At this point, the
ada_debug
commands are available.

In addition to the
ada_debug
routine, the DEC Ada Run-Time Library system provides other routines
that provide exception information, task ID information, and
information about exception-related events. Table 9-1 lists and
describes these routines.