TOC PREV NEXT INDEX DOC LIST MASTER INDEX



Migrating from VADS to Apex

This manual discusses porting application software from VADS to Apex.

The following topics are covered here:


A Brief Summary of VADS and Apex Library Structure

An application compiled under VADS is composed of one (or more) VADS libraries. A VADS library is a directory that has been initialized by the VADS a.mklib command.

VADS does not include support for configuration management or version control (Summit/CM). Users must provide their own.

Source code in one VADS library can contain references to source code compiled in other VADS libraries (using with's), if those other libraries are on that library's ADAPATH. The ADAPATH specifies the libraries that are to be made visible, and is usually the transitive closure of those libraries.

An application compiled under Apex is composed of one (or more) subsystems. A subsystem is a source control repository for a set of source files. The files of a subsystem are not directly used during software development. Instead, development is done in a view of the subsystem. A view contains a set of source files from the subsystem, each having a specific version. Views are the Apex mechanism for team development, version control and build management, and for maintaining build and compilation context. There are commands in Apex for creating subsystems and views as well as for performing version control operations such as check in and check out.

If a VADS library references another using the ADAPATH, then all the interfaces in the target library are visible, that is, they are imported to the referencing library. Apex provides mechanisms for a view to control what interfaces get exported to other views. The Apex equivalent to the VADS ADAPATH are a combination of view's exports and imports, which provide compilation unit visibility between subsystems. It is necessary to import only those views to which specific references are made, rather than the transitive closure of the imported views as required by VADS.

Apex provides a configuration management and version control (Summit/CM) system that is highly integrated with the GUI, the compiler, debugger and other tools. Apex is a development environment as well as a compilation system.

The program library structure of both systems is largely similar. However, there are crucial differences in the details. Those differences are the primary focus of this document.


From a VADS library To an Apex/Summit Subsystem/View

Subsystems are the Apex mechanism for decomposing a software system into manageable components (see Developing a System Architecture). Under VADS, the Ada library is used for the same purpose.

Our examples assume that the software architecture has decomposed the system into components that are each represented by a VADS Ada library. The natural mapping is from a VADS library to an Apex subsystem.

The VADS to Apex porting effort involves creating a subsystem and view(s) for each VADS library in the VADS application and then migrating the sources into the subsystem/view.

In addition to creating and populating subsystems and views, an application's development and system build processes must also be ported. The development process is the engineer's day to day methodology for building the executables on the application. The system build process is the preparation of the application for release.

The following two examples discuss in some detail the mechanics of porting a VADS application to Apex. The first example is quite simple and the second is a little more complicated. The examples concentrate on the application development process. A full discussion of system building and release is larger than the scope of this document.


Porting Small Applications

Consider an application that has the following characteristics:

To port this application to Apex, follow these steps:

1 . Create a subsystem and view for the application:

From the Apex GUI select File > New > New Subsystem and it displays a simple dialogue to create a subsystem.

From an Apex UNIX shell command line, use:

    Note: When a subsystem is created, you must use the complete pathname.

2 . Create a view:

From the Apex GUI, select File > New > New View to get a dialogue for creating a view.

From an Apex UNIX shell command line, use the create_working command:

A view has many attributes or parameters whose values are initialized at creation time. Some of these parameters are obtained from a model view, which serves as a prototype. In the above create_working command the model is not specified and the value of the Apex session switch APEX_DEFAULT_MODEL is used.

Some example attributes are:

3 . Migrate the source files from VADS to Apex.

Apex provides a convenient tool to convert from foreign naming conventions into files containing Ada units in the Apex environment. This tool can be invoked as Compile > Maintenance > Import Text Files from the GUI or as apex migrate (or import_text_files) from the command line:

This command creates new Apex source files in the eng.wrk view from the source files in the VADS libraries. The units are also parsed and entered into the Apex Ada library.

The apex migrate command cannot process source files that contain a.app preprocessor commands. See the Preprocessor discussion for some suggestions for handling these files.

4 . Build the small application

After running s apex migrate on all the VADS source files (or after parsing all the Ada units), Apex has registered the units in the Ada library.

Just like VADS, only one command is required to compile and link the application. In VADS the command is a.make. Apex has the link command. In the Apex GUI, if you are in a directory view for eng.wrk, select the name of the main unit and click the link... button. From the command line, run the link command specifying the file name of the main unit:

The Apex compiler compiles any unit required to link main_program.2.ada, and then run the linker to create the executable main_program.

There is no a.make build utility for Apex; the build utility is built into the compiler.


Porting a More Complex Application

Consider a slightly more complex application.

Assume there is a team of engineers working on this application and each engineer can and does work on code in any of the VADS libraries.

From VADS Libraries to Rational Subsystem Views

We make the same assumption that we did for the example above, namely that the software architecture has decomposed the system into components that are each developed in a VADS library. As in the small application example, we maintain the existing software architecture by creating one Apex subsystem to correspond to each VADS library.

Building the executable program(s) of a software system must be done from a consistent set of views, one view from each subsystem. There are multiple methodologies possible for configuring views for development. One common methodology is to designate one view in each subsystem as the up-to-date good view. So instead of each engineer having their own view in each subsystem, this designated view can be used by anyone not making changes to the files in that subsystem.

To set up the initial environment, it is easiest to first build up-to-date good views and get them to work. Then individual engineers can copy any of these views they need to work on files in the subsystem.

1 . Create the subsystems:

From the GUI, select File > New > New View.

On the command line, use:

After creating the subsystems, cd into /usr/src to make typing the rest of the commands easier:

2 . Create the views:

From the GUI, select File > New > New View.

In this example we use a special user-id, solid, to designate the VADS libraries where the up-to-date source are maintained. We use this same naming convention for creating the Apex views (remember, our current directory is /usr/src):

3 . Change the imports for this architecture to reflect the ADAPATHs in the VADS libraries. This step can be done as part of new view creation if working in the GUI. First we have the view in lib2 import from lib1:

4 . Migrate the sources from VADS into Apex:

5 . Build the application (main.2.ada is the main program):

6 . Copy the views for personal use.

With the initial instance of the application compiled and linked (and tested and working), each engineer can copy any or all of the solid views for their own use.

Apex provides the powerful copy_view command, for copying a set of related views. The copy_view command can be used to copy a single view or an entire configuration at once.

The first step in copying the entire configuration is to use the create_config command to create a configuration file that names each view in the architecture. Create the file /usr/src/solid.cfg, which has the following contents:

Use this configuration file to copy the entire solid.wrk configuration as follows:

The copy_view command creates each of the views:

Copy_view preserves the import structure of the newly created views so that /usr/src/lib2.ss/eng2.wrk imports the newly created copy /usr/src/lib1.ss/eng2.wrk and not the original /usr/src/lib1.ss/solid.wrk.

Remember, it is not necessary for each engineer to have their own view of each subsystem. An engineer needs a view in the subsystems where he is modifying the sources and also in the subsystem where the program is built (linked). For all the other subsystems, the solid views can be used.


Comparing VADS Commands To Apex Commands

The following list contains the commands provided with a VADS product. Each command is followed by a description of how to get corresponding functionality in Apex.

This table is a quick index into the list:

ada
a.db
a.ls
a.path
a.run
a.view
a.app
a.du
a.make
a.pr
a.symtab
a.which
a.ar
a.error
a.map
a.prof
a.tags
a.xdb
a.cca
a.header
a.mklib
a.report
to_srec
a.xref
a.cp
a.help
a.mkvar
a.rm
a.trace
a.xtrace
a.cvt
a.info
a.mv
a.rmlib
a.vadsrc
xlink
a.das
a.ld

ada - the Ada compiler

Ada Compilation in Apex is broken down into 4 compilation steps with each step building on the previous one. An Ada unit can be in one of five compilation states. Here is a summary:

Initial State
Compilation Step
New State
Archived
parse
Source
Source
analyze
Installed
Installed
code
Coded
Coded
link
Linked
Linked
none: run the program

Each compilation step is exposed in the Compile menu on the Apex directory and source viewer window in the GUI. Compile > Code generates an object file for the selected unit. Note that each compilation step performs any of the required previous steps. If you select a file that has never been compiled, for example, archived, and click on Compile > Code, the file is parsed, analyzed, and then coded.

The Compile > Semanticize command is a quick version of the analyze command. It does not look at all the dependency information, just the local unit. It is very handy for doing a quick check to see if the unit you are editing, compiles. Semanticize does not advance the unit to the installed state.

a.app - the Ada preprocessor

The Apex Ada Preprocessor is a subset of the VADS preprocessor, but should work in the majority of situations.

The apex migrate (or import_text_files) command can be used to move VADS source files into Apex views. However, apex migrate cannot process source files that contain a.app preprocessor commands. See the Preprocessor discussion for some suggestions for handling these files.

a.ar - create an archive library of Ada object files

Apex has a much more thorough treatment of packaging software in archives (or libraries) than VADS. An Apex view can be designated a library view by setting the BUILD_POLICY switch.

a.cca - (optional product) code coverage analyzer

The Apex Testmate product is used for code coverage. Refer to the Rational Testmate User's Guide using the Help > Manuals pull-down menu.

a.cleanlib - reinitialize library directory

The Apex clean command is the equivalent of a.cleanlib. From the GUI, select Compile > Maintenance > Clean.

The VADS a.cleanlib command was all or nothing. The Apex clean command lets you clean all units to a certain state, see the compilation states table, above. If you clean all the units to the installed state, all the object files are removed, but not the Diana intermediate files; re-coding all the units is quick.

a.cp - copy unit and library information

The Apex copy command (File > Copy Object from the GUI) copies source files, directories, views, or subsystems. The command takes into account the version control characteristics of the file. The copy/move matrix describes the source and destination interactions.

a.cvt - convert VOX object and executable formats

The VADS converter is a component of the Apex embedded products, known as the Format Converter. You can invoke it with Tools > Convert... or with convert from an Apex shell.

a.das - (disassembly) show generated code for units

To get disassembly of an Ada unit, select the unit in the GUI and select Compile > Show > Disassemble...

a.db - debug Ada and C/C++ programs

The Apex debugger is based on the VADS debugger. It can be invoked from the Apex GUI (see a.xdb below) or invoked from an Apex shell.

    Note: Invoking the debugger to debug a native workstation program is different from invoking he debugger to debug an embedded program. Although these invocation methods are different, the debugger in either case behaves pretty much the same. For information about the embedded debugger, Refer to the Embedded Programming Guide for Rational Exec using the Help > Manuals pull-down menu.

    When invoked from a shell, the debugger can be run in either line-mode or screen-mode, familiar to VADS users.

    When you run the debugger from the GUI, if you set the View > Show Source toggle in the debugger log window, a source window is displayed within the log window. This GUI debugging environment is similar to screen-mode, including most of the single character commands.

a.du - summarize disk usage for Ada libraries

There is no equivalent of this command in Apex. You can use the Unix du tool. Since Apex enforces a strict naming convention and follows that convention everywhere, you can use the du output to accurately attribute disk usage.

a.error - analyze and disperse error messages

If you are interested in a.error, use the Apex GUI to invoke the compiler. It automatically highlights the errors in your source. The message-> and message<- buttons move from error to error. If you click on Help > Explain, the explanation for the error is displayed in the Message Window.

Remember to press the Edit toggle when you want to change the source code. Until you do this, the source is read-only.

a.header - print the information stored in a unit's header

Apex has no single command to display the environment that was in place when a unit was compiled.

a.help - invoke the interactive help utility

Apex has an excellent GUI-based help facility. In Apex all the manualsare in HTML format and can be viewed on-line by a web browser such as Netscape or Microsoft's Internet Explorer.

Apex also has a context-sensitive help facility. For example, you can select Help > On Context and you get a special cursor. Click that cursor on the item for which you want help. If you click it on a highlighted error in your Ada source, the reason for the error is displayed in the messages window. If you click on one of the menu buttons in an Apex window and then on one of the selections (and on one of the subsequent selections ...) you get help on the final item you select.

a.info - list or change VADS library directives

Switches are the Apex mechanism for specifying parameters about the view, compilation, etc. Use Control > Show > Switches to get the current settings of all switches. Control > Maintenance > Set Switch is used to change a switch setting.

a.ld - (prelinker) build and executable from compiled units

The Apex prelinker is invoked as one of the functions when you select Compile > Link in the GUI or use the link command in an Apex shell. Like the VADS a.ld command, Compile > Link searches the program library to find the closure of the selected unit. Since linking a program requires that all units be in the coded state, that is, object files must have been created, the compile codes as necessary. The Compile > Link command is more like a.make than a.ld in this respect.

Once all units are in the coded state, the linker is invoked with all the correct object files. For native development, the host linker is used. For an embedded development, Apex utilizes the same xlink cross linker as VADS.

a.list - produce a source code listing

From within an Apex editor window or a directory viewer, highlight the Ada source files you want to print and select on File > Print.

a.ls - list compiled units

This command provides a list of the units compiled in the current or specified Apex view.

a.make - recompile units in dependency order

The Ada compiler in Apex understands how to recompile all the units in a program's closure necessary to bring a program up to date. It also understands how to recompile these units in dependency order.

If you highlight the main unit of a program, for example, in the directory viewer and select Compile > Link in the GUI or the link command in the Apex shell. the compiler compiles all the necessary dependent units, in the correct order, so that an executable program can be linked.

The a.ld description above discusses this as well.

a.map - print VOX symbol table information

For Apex embedded products, the Tools > Symbol Info command from the GUI is the same as a.map. Also, from an Apex shell the following command works like a.map:

a.mklib - create a VADS library directory

An Apex Ada library is an Ada view of a subsystem. The GUI command File > New > New Subsystem (create_subsystem) creates a subsystem. The GUI command File > New > New View (create_working) creates a new view in a subsystem.

Look at Porting Small Applications and Porting a More Complex Application to see some complete examples. The overview in A Brief Summary of VADS and Apex Library Structure describes some general Apex facilities and supplies links to other parts of the manuals.

a.mkvar - create or list an object file archive

Apex has a much more thorough treatment of packaging software in archives (or libraries) than VADS. An Apex view can be designated a library view by setting the BUILD_POLICY switch.

a.mv - move unit and library information

The Apex move command (File > Move Object from the GUI) moves source files, directories, views, or subsystems. The command takes into account the version control characteristics of the file. The copy/move matrix describes the source and destination interactions.

a.path - report or change VADS library search list

Apex has much more sophisticated mechanisms for importing and exporting objects from one Ada library to another than VADS.

In VADS you use a.path to import all the objects of an Ada library into the current Ada library. The similar command in Apex is the import command. Apex also supports the export command which lets you restrict the objects that other views are permitted to import. The imports of a view can be setup when the view is created.

There are additional import-related commands such as show_imports of a view (Control > Show > Imports), remove_import from a view, and more. These facilities are available from the Apex dialogue Control > Change View Properties...

a.pr - format (pretty print) Ada source code

The Apex pretty_print command formats Ada source code.

In the GUI, the Apex Text Editor has the Compile > Pretty Print command, which formats Ada source. There are a set of pretty printer switches that control how the pretty printer works. These are listed in the master index under Pretty Printing Switches. The Ada Editor describes the powerful Ada-specific features of the editor.

a.prof - (optional product) analyze and display profile data

The Tools > Profiling can be used for statistical profiling an executable program. For Apex native systems, either the UNIX prof or gprof may be used.

For Apex embedded products, the support is almost identical to VADS. The File > Run command has cross run options to enable profiling. The File > Run command for Apex Embedded systems invokes the apex_execute command, which can be used from an Apex shell.

a.report - file a deficiency or suggestion

There is an report script available with Apex that works like a.report.

a.rm - remove an Ada unit from library

In Apex, in the directory viewer, click on the unit or units you want to remove, then select File > Delete Object... This brings up a dialogue box. If you click on OK the units are removed. From an Apex shell the discard command may be used.

a.rmlib - remove a VADS library directory

File > Delete Object... is used to remove a view. See also a.rm. As described in From VADS Libraries to Rational Subsystem Views, an Ada view in Apex is the natural equivalent of an Ada library in VADS.

a.run - download and execute a program on an embedded target

From the GUI. File > Download brings up a dialogue for downloading an executable. After it is downloaded use File > Run to execute or debug it. File > Debug can be used directly to debug. The GUI File > Run command for Apex embedded systems invokes the apex_execute command, which also can be used from an Apex shell.

In an Apex directory viewer, if you select an embedded executable and then select File > Run, the program automatically downloads. An xterm pops up and the familiar download dots of the VADS a.run or a.db command are displayed. This xterm is also where output from the program is printed.

In Apex Embedded, if you have not selected a target prior to selecting File > Run, File > Debug, or File > Download then a target control dialogue pops up. If you want to explicitly set up the target to run/debug, that is, make the target known to Apex, select Tools > Target Control... Setting up the program to run and debug programs is described in "Getting Started" in the Embedded Programming Guides for Rational Apex Embedded products.

The following related commands can be executed from an Apex shell: apex_debug, apex_download, apex_execute, apex_profile, and apex_target_control. These and additional commands are described in "Command-Line Interface" in the Embedded Programming Guides for Rational Apex Embedded products.

a.symtab - display symbol information

There is currently no Apex command to provide symbol table information.

a.tags - create a source file cross reference for the vi editor

The Apex GUI editor for Ada understands every name in your source code, assuming the unit has been analyzed. So you can put your cursor on a name and click Visit to be taken to the declaration of the item. This includes the standard Ada packages delivered with Apex such as text_io.

This is a much more powerful facility than provided by a.tags. Most important, the Visit facility understands overloading and takes you to the declaration for the name you selected -- the same one the compiler used when it analyzed the code.

Apex has additional powerful facilities for Ada names in the GUI, notably Compile > Show > Usage lets you view all usages of an object (show_usage from an Apex shell). This feature lets you quickly evaluate the impact of changing an object's declaration by taking you to each usage of that object.

to_srec - convert VOX format to S-record format

See a.cvt. The Apex version of a.cvt has an S RECORD conversion option.

a.trace - (optional product) Tasking Logic Analyzer

Apex fully supports the Tasking Logic Analyzer. It is part of the Apex Analysis product.

This functionality is also available using an Apex shell as apex_trace_driver and apex_xtrace.

a.vadsrc - display versions and create library configuration file

a.view - provide aliases and history for C shell user

In the Apex GUI if you click on Tools > Shell you are brought up in an Apex xterm. This is pretty close to the functionality of a.view.

a.which - determine which VADS library contains a unit

Apex does not require a command like a.which. In the Ada editor in the GUI you can put the mouse cursor on any name, including a unit name, and click Visit to visit the unit. Once you are viewing the source of the unit, select Navigate > Enclosing to get into the directory viewer of the view that contains the unit.

An alternative method is select Navigate > Visit Ada Name which brings up a dialogue for visiting any name.

a.xdb - X window GUI for debugger

The Apex debugger has a GUI interface. If you are using the Apex GUI, the File > Run or File > Debug dialogues give you the option of debugging the program, which automatically brings up the GUI debugger interface.

The Apex debugger is based on the VADS debugger. There are two source display modes in the GUI. One is to use the Apex editor windows. The other is to let the debugger do the display. A VADS user will be most familiar with this second, show source, mode.

a.xref - print cross-reference information

Apex does not provide a cross-reference program. There are two very useful related commands in the GUI: Compile > Show > Usage, which displays the usages of a name and Compile > Show > Unused, which displays unused declarations.

As mentioned in the a.tags section, the Apex GUI editor has powerful navigation facilities for getting to the declaration of a name.

a.xtrace - graph tasking logic analyzer events

In the Apex GUI, when you select Tools > Trace... the Trace dialogue box comes up. Under the Output section if you click on Graphical, trace information is displayed graphically. This functionality is also available using an Apex shell as apex_trace_driver and apex_xtrace

In Apex the environment variable AUTOMATIC_TRACE used by VADS is replaced by APEX_TRACE_DRIVER. This should only be of concern if you are using the command-line interface.

xlink - cross linker

Apex and VADS use the same cross linker. The file that controls the linker's operation is called the Linker Options File in VADS. In Apex it is called the Linker Description File. The Linker Description File is described in "Linking and Executing Programs" in the Embedded Programming Guides for Rational Apex Embedded products.


Considerations For More Complex Applications

Circular ADAPATHs

VADS allows two (or more) libraries to reference each other in a circular manner. For example, library lib1 can have library lib2 on its ADAPATH and lib2 can have lib1 on its ADAPATH.

Apex supports the concept of mutual imports which can be used in this situation.

Duplicate Units

VADS allows the duplication of library units in different libraries. If library lib1 contains unit lib_pack, and library lib2 contains a different unit named lib_pack, a third library can reference either of them, depending upon which of lib1 or lib2 appears first on the third library's ADAPATH.

Apex does not allow a unit name to be duplicated within a tower.

There are different approaches that can be used to remove or resolve the duplicate names:

Default Access to Files

The default access to created files in Apex is rwxrwxr-x which is Posix compliant but not typically what is desired.

Solutions: Use pragma Main (POSIX_COMPLIANT => FALSE); or add the FORM parameter to the create call. Using pragma Main is rather obscure, as Main is usually a different unit. If you use the FORM parameter, use the following syntax: FORM => "USER => Read_Write, GROUP => Read_Write, OTHER => Read" or whatever you want. Note that it is "OTHER" not "OTHERS" (the usual UNIX usage).

Creating Existing Files

VADS allows you to create a file that already exists if your mode is Out_file. In Apex, Posix access defaults to no replacement, so you get a Use_Error if you attempt to create a file that already exists.

Solutions: Either catch the exception and open the file or add the FORM parameter, FORM => "REPLACE => TRUE", to the create call.

Preprocessor: VADS and Apex

The Apex Ada Prepocessor handles a subset of the VADS a.app command. We expect almost all source files containing a.app preprocessor commands to work with the Apex Ada Preprocessor. If the preprocessor has been used to parameterize the source for host/target dependencies, you can create new Summit/CM version histories in the appropriate views for those hosts and targets.

apex_migrate

The program apex_migrate is available to help migrate VADS source that contains a.app preprocessor commands to Apex. The program does not work 100% of the time, but it should work in most cases. Apex_migrate is invoked from the command line in an Apex shell.

If apex_migrate does not work, then the strategy for moving files with preprocessor commands into Apex is to first make sure there is one Ada unit per source file and then rename each source file to follow file naming conventions described in the Apex Ada Preprocessor invocation section.

The apex_migrate command takes as input a set of files. For each file, it determines how many compilation units the file contains, breaks the file up so that there is only one compilation unit per file (as Apex requires), and gives each fragment the name required by Apex.

Unlike the apex migrate command, apex_migrate does not parse the input file. It locates the boundaries between compilation units by searching for specific keywords and counting ENDs. This approach has advantages and disadvantages. It means that apex_migrate can succeed on files containing minor syntax errors or preprocessor directives. On the other hand, if the BEGINs and ENDs do not match or if complex preprocessor syntax is used, apex_migrate might get confused. For example, given a file containing the following, apex_migrate does not detect that there are two compilation units:

apex_migrate divides the input files at compilation unit boundaries. Each piece is given a name ending in .app or .ada depending on whether that piece contains any preprocessor syntax.

The apex_migrate command line contains a list of files to be migrated and options.

The position of the options on the command line has no effect on their meaning. The options are:

-into <directory>
Names the directory into which the .ada and .app files are place. If not specified, they are put into the directory from which the command is run.
-ada95
The scanning and counting algorithm used to locate the compilation unit boundaries works equally well for Ada 83 and Ada 95, with one exception. If -ada95 is specified, the keyword PROTECTED is considered to require a matching END.
-single
Assume that the input already has one compilation unit per file, so that each file is simply copied and given a new name. This option can be useful if a syntax error or complex preprocessor syntax is confusing the search-and-count algorithm.
-name_only
Does not create any files; simply prints out the names of the compilation units in each input file.
-help
Prints a brief description of the available options.

apex_migrate messages are not in the same format as those of other Apex commands. As this command matures, its messages will adopt the standard Apex format.


Compilation Differences

Predefined Types

Predefined types in Apex and VADS are compatible with the exception of Standard.Tiny_Integer. To comply with the Ada 95 Standard, replace the use of Standard.Tiny_Integer with Interfaces.Integer_8.

Directives and Switches

There is a basic correspondence between VADS INFO directives and Apex Switches. Both are used to configure the compiler.

'Ref of Constants

In machine code insertions, VADS permitted references of the form constant'ref in a context where a memory operand was required. For example, the following code will compile and execute as expected using VADS,

Under Apex, the reference to S'Ref will lead to a compilation error because Apex does not create a concrete representation (a physical memory location) for scalar constants. In most circumstances, the workaround is to declare the constant as a variable:


Execution Differences

Default Permissions On Text_io Created Files

The default permissions for created files in Apex is rwxrwxr-x which is Posix compliant. The default permissions for VADS is rw-rw-r--.

Use the FORM parameter to the create call to supply permissions, for example:

Note: It is "OTHER" not "OTHERS" (the usual Unix usage).

Creating Existing Files

VADS lets you create a file that already exists if your mode is Out_file. In Apex, Posix compliance defaults to no replacement so a Use_Error exception is raised. You may either catch the exception and open the existing file or add the form parameter to create the call:

Sequential or Direct IO

There are a few minor differences in VADS and Apex for handling files of bytes. For example, if you declare a Direct_Io file with a 512 byte record size:

And then open the file and get the size, VADS rounds up if there is a remainder while Apex rounds down; Block_Io.Size on a 513 byte file returns 1 for Apex and 2 for VADS.

Apex May Reorder Record Field Declarations

The layout of a record generated by the Apex compiler may not place the fields in the same order as declared by the record type. This can be overridden with a rep spec.

Address + Integer

The following code is accepted by VADS but is ambiguous in Apex:

In Apex, use

Tiny_Integer

Tiny_Integer is Short_Short_Integer in Apex. Unsigned_Tiny_Integer is available in package Unsigned_Types.

Standard_Error

Apex Ada83 does not support Text_Io.Standard_Error. Apex Ada95 does.

Compiling with Checks Suppressed

SUPPRESS_ALL_CHECKS Switch.


VADS-Supplied Packages

VADS predefined packages are provided with Apex. Some of the directories are restructured and file names have been changed to follow the Apex conventions.

The following subsystems have been created in Apex that contain Ada source code usually supplied with VADS.

$APEX_BASE/ada/rts_vads_exec.ss

This subsystem contains the VADSexec interface to the RTS.

$APEX_BASE/ada/rational.ss

This subsystem contains the interface to the runtime system (RTS). Many of the files in this subsystem are from the directory standard that is supplied with VADS.

This subsystem also contains two files from the VADS standard library, language.1.ada and unsigned_types.1.ada.

$APEX_BASE/ada/vads_compatibility.ss

This subsystem contains subdirectories named standard, verdixlib, publiclib, and usr_conf, It also contains the units from those directories from VADS that were not moved to any of the other subsystems listed above.

Importing the VADS-Supplied Packages

Most VADS libraries have the VADS libraries standard and verdixlib on their ADAPATHs. So most Apex views containing VADS source code need to import the rational.ss, and vads_compatibility.ss subsystems.

Applications that have vads_exec on their ADAPATH need to import the rts_vads_exec.ss subsystem.


Appendix F

Pragmas

VADS Pragma
Apex support
Bit_Pack
Not supported. In Apex, pragma Pack has the same effect
Built_In
Not supported
Byte_Pack
Not supported
Controlled
Not supported (same as VADS)
Elaborate
Supported
External
Identical support
External_Name
Supported
Implicit_Code

Initialize

Inline

Inline_Only

Interface

Interface_Name

Link_With

List

Local_Access
Not supported
No_Image
Not supported
Non_Reentrant
Not supported
Not_Elaborated

Optimize

Optimize_Code

Pack

Page

Passive
Not supported
Priority

Remote_Access
Not supported
Rts_Interface
Not supported
Share_Code

Shared

Storage_Unit

Suppress

System_Name

Task_Attributes
Not supported
Volatile

Address Clauses

In embedded VADS programs, Ada address clauses for with static addresses are represented by a linker group to prevent overlapping use of the memory associated with address clause variables. This feature is no longer supported by the Apex compiler. The Apex compiler allocates a pointer to the address specified in the address clause and all accesses to the variable are implemented as indirect references through this pointer.

In some circumstances the optimizer is able to optimize away the pointer and make references directly to the specified address. There is no mechanism to assure that the specified memory address isn't allocated by the linker to some other part of the user program.


Default Initialization with Address Representation Attribute Clauses

Default initialization of an object with an address representation attribute clause is different in Ada 83 versus Ada 95. Default initialization for an object may be either implicit initialization as required by the language, or explicit initialization in the data type definition. An address representation attribute is a "for x use at ?" clause in Ada 83 and a "for pragma Initializex'address use ?" clause in Ada 95.

Implicit default initialization occurs in either Ada 83 or Ada 95 for access types, discriminants of constrained discriminated subtypes, and in Apex 3.0, for filler "gaps" between record or array components. Filler gaps must be initialized because Apex 3.0 code does record comparisons by comparing two data regions without regard for where the data is stored.

Explicit default initialization occurs when a default assignment is specified for a type definition component.

In both Ada 83 and Ada 95, normal objects are always default initialized.

However, when an address representation attribute clause is present, Ada 83 and Ada 95 differ. Ada 83 rules permitted an implementation to ignore any default initialization (implicit or explicit) of an object with an address clause. VADS and Apex 83 both chose to not perform default initialization when an address clause is specified for an object. Apex Ada 83 added the non-standard "pragma Initialize" to force default initialization if desired by the user.

With Ada 95, the language designers chose to require default initialization even when an address clause is specified for the object. However, the language designers also provided the alternative. Default initialization will not be performed for any object for which pragma Import is specified, RM B.1(24).

Unfortunately, this means that when converting Ada 83 to Ada 95, all cases where an address representation attribute clause is applied to an object must be examined, and if there is default initialization, the code must be changed appropriately.

For example, consider the following type definition:

In Ada 83, the following object declaration will have no default initialization:

In Ada 95, a pragma must be added to have no default initialization:

In Ada 83, the following object will have default initialization:

In Ada 95, the pragma must be removed to have default initialization:

Note that pragma Import does not generate a symbol reference because it uses an "Ada" import with an address clause specified. If "pragma Import(C,val_no_init)" were used, then there would be a symbol reference that would have to be satisfied during linking.


Runtime Configuration

In VADS the runtime system is configured by modifying the body of the package V_Usr_Conf in the file usr_conf/v_usr_conf_b.a, and adding a WITHn INFO directive to the library specifying that the object file for that package body be included in any subsequent link.

To configure the runtime system in Apex, create a view of the base/usr_conf.ss subsystem and modify the package bodies of V_Usr_Conf, Real_Time, and Calendar_Configuration, as needed. If Real_Time or Calendar_Configuration are modified, they should be named in a with statement in the context clause of the body of V_Usr_Conf so that the corresponding object files will be linked into your application.

Import this view into the view containing the main program procedure for your application. This causes the modified body of V_Usr_Conf and its closure to be included in any links of the main program.


Hints For an Easier Transition To Apex

The following are a few tips that may help new Apex users transition from VADS to Apex, and provide some ways to speed up your work.

Basic Command-Line Commands

There are some basic Apex command-line commands that are particularly useful. Note that you do not need to prepend each command with apex, for example you can type visit instead of apex visit.

  • To code everything in a view:
  • To blow away the object code for a view and recompile:
  • To see all legal Apex commands:
  • To see a list of all available Apex man pages:

    Useful Key Bindings

    The following is a list of some useful key bindings for new Emacs users.

    Note: Many other tools use the Emacs bindings so your best bet is to give in and learn Emacs ("Resistance is futile!").

    These are for use in any text field in any Apex dialog box.

    ^a
    Move to beginning of line/field
    ^e
    Move to end of line/field
    ^f
    Forward one character (or right-arrow)
    ^b
    Backward one character (or left-arrow)
    ^k
    Delete to end of line
    ^p
    Move up one line (prev)
    ^n
    Move down one line (next)
    ^v
    Move down one page (also PGUP and PGDN work)
    ^d
    Delete character in front of cursor
    ^s
    Search for string forward
    ^r
    Search for string reverse
    ^a^k
    Clear the text of a text field
    TAB
    Complete files name in any filed which has the completion icon (looks like a jigsaw puzzle)
    MB3
    Used on the Completion icon, displays a list of possible completions
    meta-<
    Moves to top of file
    meta->
    Moves to end of file


  • Rational Software Corporation 
    http://www.rational.com
    support@rational.com
    techpubs@rational.com
    Copyright © 1993-2002, Rational Software Corporation. All rights reserved.
    TOC PREV NEXT INDEX DOC LIST MASTER INDEX TECHNOTES APEX TIPS