TOC PREV NEXT INDEX


Rational Apex Release Notes

Release 4.2.0 B

Thank you for choosing Rational Apex!

Please read this document to learn about known product issues, important tips, and other Apex product information. The Release Notes are also available online in HTML format from the Help > Manuals command.

The online Release Notes are guaranteed to be the latest version of this document. If you find discrepancies between the hard-copy and online versions of the Release Note, please assume that the online document contains the most current information.

Objectives

These release notes provide information critical to installing and using Rational Apex, including supported platforms and known issues with this release.

Scope - Product Definition

This document applies to Release 4.2.0 B of Rational Apex for Sun Solaris, HP-UX,True64 UNIX, and SGI Irix, and IBM AIX. These release notes describe:

Before installing Rational Apex, be sure to read the Hardware/Software Information and Getting Started sections of this document. These sections contain important information for a smooth and successful installation.

Hardware/Software Information

This section provides basic information on the platforms supported and the hardware and software requirements for installing and running Rational Apex and its add-ins.

Supported Platforms

This document uses the following terms to designated the various platforms on which Rational Apex 4.2.0 B runs.

Table 1 Supported Platforms
Term
Platform
Solaris

Sun SPARC workstations running Solaris 2.6, Solaris 7, or Solaris 8.


AIX
IBM RS/6000 or PowerPC workstations running AIX 4.3.3
Alpha, OSF/1, Tru64 UNIX
Digital Alpha workstations running release 4.0d, 4.0.e, 4.0f , and 5.1(formerly known as OSF/1).
HP-UX or HP
HP PA workstations running release 11.0 and 11.11 of HP-UX (with and without threads)
IRIX
SGI workstations running IRIX 6.5 N32

Hardware Requirements

Hardware requirements are outlined in Installing Rational Apex.

If you wish to generate and/or execute SPARC V9 64-bit binaries, a Solaris 7 machine with the 64-bit Kernel is required. More information on determining if your Solaris 7 system has the 64-bit Kernel can be found in SPARC V9 Solaris 64-bit Support.

Software Requirements

Software requirements are outlined in Installing Rational Apex.

To use the Apex Web interface, the JDK 1.2.2 plug-in and the "appletviewer" tool (shipped with JDK 1.2.2) must be installed.

Getting Started

This section provides information about pre-installation and licensing issues for Apex.

Getting Announcements from Rational

New Apex products, layered products, new releases, patches, and critical technical information about these products are now announced through e-mail.

To sign up for automatic notification, send an e-mail message to majordomo@rational.com with the words subscribe apex-announcements in the body of the message.

If you already subscribe to this list and wish to be removed, send an e-mail message to majordomo@rational.com with the words unsubscribe apex-announcements in the body of the message.

We do not advertise on this list.

Installation Information

Installation instructions for Rational Apex are available in Installing Rational Apex.

Licensing

Apex 4.2.0 B will not introduce a new license FEATURE line, but the version number will be incremented to 4.200.

All Apex products require the following base license features:

Each of the following products requires both the base license features and the additional license features listed after it:

The components described below are included with the Apex product but require additional license features:

The components described below are included on the media with the Apex product but require additional license features to be purchased.

The host part of the name is one of alpha, hppa, mips, rs6k, sun4, or any.

Note: Once Apex is purchased for two or more O.S.'s, an any key is provided.

The licenses held by an Apex session can be viewed using the Tools > Session > Show Licenses command from a Jobs, Server or Output window.

Upgrading from Previous Releases

This release note applies to Release 4.2.0 B of Rational Apex. If you are upgrading from a previous release, after the installation is complete, upgrade your subsystems and views using the apex_upgrade command. This command is described in detail in the Command Reference.

If you are doing just a patch install, it is not necessary to run apex_upgrade. Installing a patch to an existing release is described in Installing Rational Apex.

Installation Issues

Required Operating System Patches

The latest information on patches for each of the Apex platforms can be found at the following URLs:

To view the current list of patches produced by Rational for the Apex products, visit the ftp://ftp.rational.com/patch_info/index.html patch information page on our FTP server.

Product Documentation

Rational Software Corporation provides a full set of online documentation with this release. These documents can be accessed through the Help > Manuals command from any directory viewer or the Doc List button in the navigation bar at the top of each HTML document. A subset of these documents is provided in hard-copy.

A specific discussion of online help using Netscape can also be found in the Getting Started manual.

Postscript Versions

Postscript versions of most of the manuals are also provided and can be printed using the Help > Print Manuals command.

In some cases, you may note discrepancies between the printed documentation and the online documentation. In these cases, the online documentation is the most up-to-date and should be followed.

Man Pages

For a list of available manual pages, enter the following command in an Apex xterm window:

An Apex xterm window is an xterm window generated from an Apex window using Tools > Shell.

Compatibility Issues

Reserved Words

Apex locates executables based on standard UNIX searchlist mechanisms. The following are words you should avoid using as names for scripts to be invoked in shell windows spawned from Apex:

apex
apex_display
apex_action
apex_output
visit
visit_ada
rada

Of special notice in this list is apex, which is the central command for shell usage. Because Apex provides multiple ways to invoke shell operations, problems caused by overloading the term apex might seem to occur in inconsistent ways.

In addition, avoid any name that begins with Apex_ (case is important). No specific names are provided because the list is subject to change.

New and Changed Features

This section outlines the changes, enhancements, and new features available in this release of Apex. The following are included in this section:

Miscellaneous

Ada Language Reference Manual (Ada LRM)

Since the release of Apex 4.0.0 the LRM has had some updates/corrections made by the Technical Corrigendum 1. You can find the latest copy with the most up-to-date information at http://www.ada-auth.org/arm.html.

Grep

With the 4.0 release of Apex the grep command was changed to first save any edit buffers to disk prior to performing the grep. A side effect of this change was that the grep operation could slow down greatly. With 4.2 the grep dialog box now allows the user to select whether files should be saved to disk prior to performing the grep operation. The behavior can also be controlled through the environment variable APEX_GREP_SAVEALL which can have the values:

TRUE
Save all files before performing the grep operation
FALSE
Do not save files and perform the grep operation on files currently on disk.

Linker

Solaris ld (linker) version 4 or later is required for use with Apex 4.2.x.

In developing release 4.2 it was found that the use of version 3 of the Solaris linker resulted in flawed binaries. Systems should be updated to have version 4 or 5 of the linker when using Apex 4.2. Current recommented patches from Sun contain the newest linkers.

To determine the version of the linker, run the command

The apexinit requirements checking has also been updated to detect if version 3 of the linker "ld" is installed when starting Apex and will issue a warning.

SPARC V9 Solaris 64-bit Support

This release provides the tool set that helps Apex users to develop and deploy SPARC V9 64-bit programs (Ada, C, C++) on 64-bit Solaris machines.

No new license is required as long as the Solaris Apex license is valid.

Basic System Requirement

In addition to the system requirements for installing Apex, a Solaris 7 machine with the 64-bit Kernel is required to generate and/or execute SPARC V9 64-bit binaries. All Solaris 7 machines don't have the 64-bit Kernel installed. The command to identify a Solaris 7 machine capable of generating and running 64-bit programs is: isainfo -v. The output of this command on a Solaris 7 machine with 64-bit kernel is:

Data Model - LP64

The fundamental difference between SPARC 32-bit model and SPARC V9 64-bit model is in the Data Model. The former supports the ILP32 model, where the integer type (int in C/C++ and Integer in Ada), long integer types (long in C/C++ and Long_Integer in Ada) and pointer/address type (pointers in C/C++ and Access/System.Address type in Ada), are all 32-bit. The object file format is ELF-32. The latter supports the LP64 model, where long integer types (long in C/C++ and Long_Integer in Ada) and pointer/address type (pointers in C/C++ and Access/System.Address type in Ada), are 64-bit, but integer type (int in C/C++ and Integer in Ada) is 32-bit. The object file format is ELF-64.

One major cause of worry when moving from ILP32 to LP64 is that the size of pointers and integers are no longer the same. This poses major problems for C programs written in K&R mode (where it is not mandatory to specify function prototypes) if prototypes for functions returning pointers are missing. The default return type is integer which is not the same size as pointers in LP64 model.

SPARC V9 64-bit Programming

In Apex, the key to generating a SPARC V9 64-bit Ada/C/C++ object is modeling your view with the appropriate model. Any model whose name starts with "sun4_solaris_64 " models your view to use the SPARC V9 64-bit compiler.

There is no static linking in SPARC V9 64-bit mode since the standard system libraries are available only as shared objects (there are no static archives). Given that, in any Ada view, even if the value of the link mode switch (LINK_CONTRIBUTION_DEFAULT_MODE) is set to static, the system libraries are linked in dynamically.

One cannot mix and match 32-bit objects and 64-bit objects. That is, a 32-bit object cannot be linked into a 64-bit object and vice-versa.

Ada Compilation System

The following have been implemented for this release of the Apex Ada compiler and runtimes.

Alignment of Types and Objects

The default alignment of types and objects has changed. In the absence of representation clauses specifying the alignment of a type or object, the compiler is free to choose the alignment it wants, in order to obtain the best performance.

In all cases, the default alignment of an object is the alignment of its type.

In this release, the default alignment for a composite type is the smallest power of two that is larger than the size, subject to architecture-dependent limits. This is, in general, the approach that results in the best performance, notably on RISC processors. However, it causes data structures to become larger, and this effect is especially noticeable for small composite types. This is a change from previous Apex releases, where the alignment of a composite type was the LCM of the alignments of the components. If the additional storage consumption is undesirable, the alignment of the type should be explicitly specified.

Alignment of types and objects is described in detail in the Appendix F and Annex M chapters of the Ada Compiler Reference.

Address Clause Alignment Check

The code generated for an address clause now includes a runtime check that the alignment of the specified address satisfies the alignment requirement of the specified object. Program_Error is raised if the check fails, as per RM95 1.1.5(12).

For example, a call to the following procedure will raise Program_Error:

Check Name Alignment_Check

An implementation-defined check name, Alignment_Check, has been added as permitted by RM95 11.5(27).

When an address clause for an object is elaborated, a check is made that the specified address is consistent with the alignment of the object. Program_Error is raised if this check fails. The check name Alignment_Check may be used in pragma Suppress to suppress this check.

Checking of Interfacing Pragmas For Composite Types

The checking of the interfacing pragmas (pragmas Import, Export and Convention) has been tightened up to avoid problems when interfacing with other languages. Consider the following example, which was legal in previous versions of Apex:

The type Data_Type has convention C, and is therefore laid out in a way which is consistent with a C struct: the components are not reordered (they occur in memory in the same order as in the declaration) and the record is 4-byte aligned.

Note however that no pragma Convention was applied to type Time_Type. This type therefore has convention Ada, meaning that Apex is free to use the layout that will give the best performance. On 64-bit processors this type is 8-byte aligned in order to get faster memory access. Unfortunately this 8-byte alignment results in a 4-byte gap between the components Id and Time of Data_Type, which is probably not what the author of the code intended.

Apex now rejects the pragma Convention on Data_Type, stating that type Time_Type does not have convention C. In order for the pragma Convention on Data_Type to be legal, a pragma Convention must also be applied to Time_Type, as follows:

With this change Time_Type is 4-byte aligned (for compatibility with C) and there is no gap between the components Id and Time of Data_Type.

There is one situation where adding a pragma Convention has a significant effect. Consider the following code:

This type is bit-packed, and occupies 3 bits in memory. Say that it becomes necessary to specify convention C for this type (presumably in order to be able to specify convention C for a composite type having a component of type Set). The naive way of effecting this change is to add a pragma Convention, as in:

Unfortunately, the presence of the pragma Convention causes the pragma Pack to be ignored. That's because array components in C must be independently addressable (C does not make much of a difference between pointers and arrays), and pragma Pack is only a hint, which has to be ignored if it conflicts with other requirements.

The correct way to declare a bit-packed array for interfacing with C is to use a component size clause, as in:

Note however that modular types may be a better way to interface with bit-level data structures in C.

Elaboration Order

The Apex compiler now takes subsystem/view importing information into account when choosing the elaboration order for the units in the closure of the main program. If view A imports view B, then all units of view B which need to be elaborated are elaborated before any units of view A are elaborated (excluding mutual imports and preelaborated units).

The following example formerly raised Program_Error because Text_Io.Put_Line was called after Text_Io had been finalized (in particular, after Standard_Output had been closed):

The elaboration order was

1 . Eo'Spec

2 . Text_Io and all of its friends and relations.

3 . Eo'Body

4 . Eo_Main

This new prelinker now selects the order and the execution proceeds correctly.

1 . Text_Io and all of its friends and relations.

2 . Eo'Spec

3 . Eo'Body

4 . Eo_Main

The decision about whether elaboration checking is to be suppressed for a two-part subprogram is now made when processing the compilation unit containing the first part of the subprogram.

If the spec and body of a subprogram occur in two different compilation units, then any elaboration-check suppression pragmas which occur in the compilation unit of the body have no effect on this decision.

Language.1.ada Removed from Predefined Subsystems

The package language.1.ada has been removed from the predefined subsystems for native platforms. On Embedded platforms, this package was removed in a previous release.

The typical use for language.1.ada was to supply the prefix for C code:

This is now handled through the use of the Ada95 pragma Import, which our compiler also supports for Ada83. With this pragma you no longer need the clumsy mechanism to supply the language prefix.

pragma Import(C, foo, external_name => "FOO");

When using pragma Import, the compiler determines whatever prefix is necessary. Note that you want to specify External_Name for C code, never Interface_Name. Refer to LRM95 Annex B for details.

New Parameter Passing Conventions

Two implementation-defined conventions, Ada_Pass_By_Copy and Ada_Pass_By_Reference, have been added as permitted by RM95 B.1(11). These conventions may be used in pragmas Import, Export and Convention.

These conventions may only be specified for types whose parameter passing mode is not defined by the language (in technical terms, types which are neither by-copy nor by-reference as defined in RM95 6.2(3-9)). They make it possible to select the parameter passing mode. For the purposes of checking the compatibility rules of RM95 B.1(14-19), these conventions are compatible with convention Ada.

If an object of a type having convention Ada_Pass_By_Reference is misaligned, an aligned copy will be created for parameter passing. The address of this copy will be passed to the called subprogram. When this situation arises, the following warning is emitted to inform the user that the address may not denote what she expects:

If a composite type contains a subcomponent with convention Ada_Pass_By_Reference, the composite type inherits convention Ada_Pass_By_Reference, unless another convention is explicitly specified for it.

The reason why these conventions have been added has to do with a change in parameter passing for types that are neither by-copy nor by-reference (types for which the parameter passing mode is not defined by the language). In previous versions of Apex such types were always passed by-reference. Consider however a small composite type, for instance:

For such a type, passing by-copy (i.e., in registers in most machines) is considerably more efficient than passing by-reference. Apex 4.2.0 incorporates a heuristic decision that passes types by-copy when the resulting code is deemed to be more efficient.

A parameter of an undiscriminated record type or of a constrained array type will be passed by value if:

Certain rep-specs may also cause a parameter not to be passed by value (e.g. specifying a larger size for an array type than the compiler would have chosen by default).

A parameter of an undiscriminated record type whose size is known statically and is greater than the size of an address may also be passed by value if it consists of <= 3 scalar (or access-to-object, or address-sized access-to-subprogram) components.

An undiscriminated record component may, for purposes of this computation, be "flattened" in some cases. For example, a parameter of type Has_3_Fields (see following) might be passed by value:

This "flattening" only occurs if the inner record occurs at the beginning of the enclosing record.

Most users should not have to worry about this change, which will only bring improved code performance. However, in rare situations the body of a subprogram may depend on its parameter being passed by-reference. In this case, the user will have to specify convention Ada_Pass_By_Reference to force the type to be passed as it used to be in prior versions of Apex:

In order to make it easier to detect the types for which the convention Ada_Pass_By_Reference may need to be explicitly specified, a warning is emitted if the parameter passing mode has changed since the previous version of Apex: 


T is passed by copy, but it was passed by

reference in the previous version of Apex;

this may cause incompatibilities

In Apex 4.0 Ada was synonymous with Ada_Pass_By_Reference for purposes of choosing parameter passing methods.

With Apex 4.2, Ada is symonymous, in this respect, with Ada_Pass_By_Copy. In 4.2.0 you do not get any additional passing-by-value if you specify Ada_Pass_By_Copy instead of Ada_Pass_By_Reference.

Pooling of Global Variables

Under previous releases of Apex, each global object was given its own link name. Under Apex , all of the global objects for a given package spec are placed in a single pool and referenced using a single base register (only the single pool object will be given a link name). This allows more efficient code for referencing global data and reduces TOC (GOT) consumption.

Pragma Concurrent_Processing_Policy

A new configuration pragma has been added to control the mechanism used to implement concurrent processing (i.e., tasking). The syntax of this pragma is as follows:

Where the policy_identifier must be one of Interleaved_Processing or Threaded_Processing.

Interleaved_Processing causes the prelinker to use the Rational Exec execution environment to simulate concurrency by using interleaving execution. The entire program runs on a single operating system thread.

Threaded_Processing causes the prelinker to use the underlying operating system's thread library to implement concurrent execution. Each Ada task executes on its own operating system thread.

Some policies may not be supported on some target (although evidently at least one policy is supported on each target).

At most one concurrent processing policy must be specified for the entire program. If no Concurrent_Processing_Policy pragma appears in any of the units comprising the program, the concurrent processing policy for that program is Interleaved_Processing.

The predefined subsystems and the model.ss subsystem do not have separate threaded and non-threaded views anymore. The pragma Concurrent_Processing_Policy is the mechanism whereby the user selects the threaded or non-threaded runtimes. This pragma typically appears in the main program, or in the pragma.1.ada file for the view containing the main program.

Pragma Convention (Intrinsic, Some_Random_User_Routine)

If a convention of Intrinsic is specified for a subprogram whose name is not one of Less, Less_Equal, Greater, Greater_Equal, Convert, Add, Subtract, Modulus, Shift_Left, Shift_Right, Shift_Right_Arithmetic, Rotate_Left, Rotate_Right, Return_Address, then calls to the that subprogram will raise Program_Error.

In the past, the name of the subprogram was interpreted as the linkname of an external subprogram. Note that this does not affect other intrinsic operations associated with Machine_Code when used in a code statement; these operations are affected if they are used in other contexts.

Pragma Suppress_Warning

A new pragma, Suppress_Warning, has been added to provide fine-grained suppression of warnings. In numerous instances the Apex compiler emits warnings to inform the user that some construct in her code might be problematic (e.g., might not work as intended, or might not be portable) or might involve a performance penalty. In general, it is good practice to modify the code so as to avoid warnings. There are situations however where it is impossible or impractical to do so. For instance, when using memory-mapped I/O to access external devices, it might be necessary to use record components with strange sizes and alignments; the compiler might warn that the layout will result in inefficiencies, but there is no way to avoid this (short of changing the hardware, which is generally not an option). The pragma Suppress_Warning provides a solution to eliminate warnings in this situation.

The syntax of this pragma is as follows:

Note: Suppress_Warning will only suppress the warnings that are emitted by the semanticist, i.e., at installation time. The pragma will not do anything with coding or link time warnings.

This pragma suppresses any warning that matches the given string expression in the declaration, statement, or pragma that immediately precedes the pragma Suppress_Warning (ignoring any intervening pragmas Suppress_Warning; this makes it possible to attach several pragmas Suppress_Warning to a single declaration, statement or pragma).

For the purpose of determining if a warning emitted by the compiler matches the static string expression given in the pragma, any parameter appearing in the message is ignored. So the warning:

matches the string:

as well as:

or even:

Note however that it is important to preserve the white space around parameters. In general it is recommended to use the message as emitted by the compiler, but the flexibility of omitting parameters is useful for messages that involve data that changes often (e.g., paths). It also makes it possible to define string constants and use them in many occurrences of the pragma, thereby reducing the maintenance effort in case the wording of some message changes in a future release of Apex.

Shared Library Version Numbering

Shared libraries in Apex 4.2.0 have some new controls. There are four new switches that control the new behavior and one old switch whose behavior is slightly different. The new behavior has been named "shared library version numbering". For any given view that produces a shared library, version numbering is either "on" or "off". "Off" is the default value and it causes the familiar pre-Apex 4.2.0 behavior and "on" produces the new behavior.

The SHARED_LIBRARY_NAME switch has been changed slightly. If version numbering is "off" then the change is purely cosmetic. Prior to Apex 4.2.0, the SHARED_LIBRARY_NAME switch had a default value of "lib<subsystem:r:t>.so". For a subsystem xyz.ss this caused the shared library for a view of that subsystem to be given the name "libxyz.so".

The default value has changed and it is now "lib<subsystem:t:r>.<if><view'host_architecture><eq>hppa_hpux<then>sl<else>so<endif>" What this does is produce a name of "libxyz.sl" for HPPA and a name of "libxyz.so" for all other targets.

With version numbering "off", this switch determines the name of the shared library file. With version numbering "on", this switch determines the name of a symbolic link that will point to the actual shared library file. Otherwise the use of this switch is unchanged. Except when there are multiple versions of the shared library file present in a view, the old functionality and the new functionality are indistinguishable.

There are four new switches that govern shared library version numbering.

Version numbering is turned "on" or "off" by SHARED_LIBRARY_VERSIONING. The default value for a view is "off". (It can also be set to "true"/"false" or "1"/"0".) When version numbering is "off", the other three switches are ignored.

SHARED_LIBRARY_VERSION_NUMBER is a simple number, of any Integer value. It is automatically incremented every time a version numbered shared library is created in the view. It is used to give each created library file a unique identity.

SHARED_LIBRARY_RETENTION is a simple number, of any Integer value. When negative (-1) it is interpreted as meaning "keep all old versions". When zero (0) it is interpreted as "keep no old versions". When positive (1..N) it is interpreted as "keep this many old versions". When a new version numbered shared library is created in a view, existing library files in that view are either kept or deleted according to their relative ages depending on this switch. Prior to Apex 4.2.0, the new library always replaced the old library.

This was the same as a value of zero (0) for this switch. It is possible to preserve any number of prior versions of the library being created. This allows programs linked against those prior versions to continue to operate.

SHARED_LIBRARY_VERSION_NAME determines the name of the actual shared library file when version numbering is "on". For example, using the default switch value, the name of the library file will be "libxyz.123.so" if the subsystem is xyz.ss and the incremented SHARED_LIBRARY_VERSION_NUMBER is 123. A symbolic link is also created pointing to the actual shared library file. The name of that symbolic link is controlled by the SHARED_LIBRARY_NAME, "libxyz.so" in this example.

As an example, imagine a view named /disk/space/xyz.ss/project.wrk that has these Policy/Switch values:

If there are no shared library files currently present in the view:

System Address

In this release, System.Address is now a private type implemented as an access type. In previous releases, it was a private type implemented as a modular type.

This means that default initialization is now performed in cases where it was not previously performed. For example,

X will now be initialized to null whereas before it would have been uninitialized.

One place where this can make a difference is when using address clauses. In this example

R_Var.F3 will be set to null. To suppress this default initialization, it is necessary to add

either after the declaration of R_Var or after the address clause.

Time Type Configuration

Apex represents the values of the types Ada.Real_Time.Time and Ada.Calendar.Time as 64-bit counts of Ada.Real_Time.Time_Unit. On 32-bit platforms, arithmetic on these types is done using software implementations off 64-bit operations. THese operations are much slower than integer operations provided by the hardware, particularly 64-bit multiplication and division. This reduces the performance of Time arithmetic and other operations that use it.

Some conversion operations in Ada.Real_Time are particularly slow, since they are implemented with 64-bit multiplication and division: Split, Time_Of, To_Duration, and To_Time_Span. These may be used implicitly, as when using the Calendar."-" operation to subtract two time values to obtain a duration value. The 64-bit subtraction is relatively fast, but it produces a Time_Span value; this must then be converted to Duration, which is much slower.

None of these conversion operator produce 64-bit results, and so do not need the full 64-bit arithmetic. The 56 bits of precision provided by double precision floating point is adequate. All the native platforms supported by Apex provide hardware which implements floating point operations that are much faster than 64-bit software integer operations. Apex now reimplements the Ada.Real_Time conversions listed above using floating point operations. This results in greatly increased performance for them and other Time operations that use them.

Note: This does not affect Apex embedded products since they cannot assume floating point hardware on the target platform.

Thread Concurrency

Most implementations of POSIX threads provide an extension allowing applications to provide the OS with a "hint" regarding the desired level of concurrency. This usually influences the mapping of threads to underlying kernel entities (e.g. Solaris LWP, SGI sproc) which control the actual allocation of hardware processing resources.

The Apex runtime provides several interfaces to specify the desired concurrency for threads used to implement Ada tasks. For Solaris, one of these is the environment variable ADA_CONCURRENCY_LEVEL. The value of this variable is interpreted as a number and passed to the OS interface thr_setconcurrency().

In Apex 3.2.0b, the code interpreting ADA_CONCURRENCY_LEVEL was left out, so the Apex runtime ignored the environment variable. It has been restored in this release.

This mechanism was developed for Solaris threads when it was the only threads platform supported by Apex that provided this interface. Most of the newer POSIX threads implementations now supported provide this interface, so it is now available for most threaded platforms.

Volatility

Compiler support is added for the case of declaring a volatile scalar object which is subject to an address clause

Multithreaded Ada Mutex Locking Policy Emulation

The Apex multithreaded Ada runtime, implemented over POSIX threads, provides an emulation of the POSIX_THREADS_PRIO_PROTECT (priority ceiling) mutex locking policy if it is not implemented by the operating system. This provides support for the Ada Ceiling_Locking polity defined in the Real Time Annex (Annex D). In Apex 3.2.0b, this emulation was implemented incorrectly. When a priority ceiling mutex was unlocked, for example, when leaving a protected object compiled with pragma Locking_Policy (Ceiling_Locking), the priority of the calling task was reset to its active priority at the time the mutex was locked. This is not necessarily correct. If the base priority of the task had been changed in the meantime, and if the mutex being unlocked is the last priority ceiling mutex held by the task, then the new base priority should become the active priority, not the base priority at the time that the mutex was originally locked. This is what currently occurs.

Interface to ANSI C and K&R C - Change in Default

The interface to both ANSI: and K&R C is now supported. In previous releases, Apex supported whichever was the standard for the system .h files.

The ANSI dialect is now the default. To specify otherwise, use pragma Import_Directive. This pragma can be included in pragma.1.ada to set the default to K&R.

It is also possible to control individual references. For example,

Single Rada and COMPILER_TOOLS_PATH

Apex 4.0.0 and beyond uses a unified rada. This means that the rada executable supplied with the native Apex product is the same one used to code files under the embedded Apex product. Implementing this change resulted in several changes that may effect customers.

How to Invoke rada

Under normal circumstances, rada is not invoked directly. Instead, users should invoke the specific rada functionality: analyze, clean, code, disassemble, link, migrate, parse, or pretty_print. For example,

Passing special options to rada

In general, options specified in the Apex documentation are known to the command interpreter (apex), and can be used directly on the command line. For example,

In rare cases, you may need to pass a special option to rada that the command interpreter does not recognize. In these cases, you will need to preface the option with -cmd_options. For example

Determining what tools rada is using

Starting with Apex 4.0.0, the target-specific tools used by rada (for example, apex_ada_cg_phase, apex_ada_optim_phase) are no longer on your path. Instead Ada views contain a COMPILER_TOOLS_PATH switch (in the Policy/Switches file). By default, this switch is set to a single directory containing target-specific tools.

The COMPILER_TOOLS_PATH value is not normally on the user's path. When rada is invoked, it prepends the COMPILER_TOOLS_PATH value to the $path before invoking tools.

To determine which tools rada is using, the user can invoke rada indirectly from an Ada view with the -show_tools option. For example,

COMPILER_TOOLS_PATH Switch

The COMPILER_TOOLS_PATH switch is used by the Ada compiler and other Apex tools to locate target-specific versions of each tools. It can be specified on the command line as -compiler_tools_path <list of filesystem directory pathnames> the Policy/Switches file as COMPILER_TOOLS_PATH: <list of filesystem directory pathnames>. The list of pathnames must be separated by ":"s (same conventions as $PATH.)

The COMPILER_TOOLS_PATH switch is specified in the Ada model. It is copied from the model into the Ada view a view creation and any time an apex remodel -update or -replace_switches command is invoked on the Ada view.

The default value is set by the Ada model being used.

Creating C/C++ Executables Linked with Ada Subroutines

It is now possible to create a C/C++ executable that is linked with Ada subroutines. This is described in Programming with Apex.

Miscellaneous Changes

The following additional changes have been made to the Ada compiler.

Ada Object Editor

Coloring

The default Ada object editor now does both language coloring and "as you type casing". These can be turned off by setting the APEX_NO_ADA_LANGUAGE_MARKS and APEX_NO_AS_YOU_TYPE_CASING environment variables to true.

The casing is consistent with the pretty printer switches. Currently only the Ada object editor does language coloring. The C/C++ editor does not do this.

The new color scheme is consistent with the color scheme used with Apex NT and with other environments such as MSVC++. Language constructs (keywords, strings, comments, etc.) have a foreground color with a white background while messages and prompts have a background color and a white foreground.

Here are the default settings for the common constructs:

Messages and Prompts
white foreground
Error Messages
red background
Warning Messages
orange background
Text Messages
blue background
Prompts
dark grey background (as before)
Language Colors
white background
Comments
darkgreen foreground
Keywords
blue foreground
Strings
brown foreground
Character Constants
brown foreground (same as strings)
Number Constants
DarkKhaki foreground (not implemented for Ada)
Braces
CadetBlue foreground (not implemented for Ada)
Preprocessor Lines
red foreground (not implemented for Ada)

Delimiter Alignment

The Apex Ada editor now supports delimiter alignment. Delimiter alignment is an option of the pretty-printer, which causes lexical delimiters to be vertically aligned to improve readability of the source code.

Delimiter alignment is controlled by the boolean context switch ALIGN_DELIMITERS. This switch defaults to False. To enable delimiter alignment, the switch must be set to True by editing the switch file for the appropriate view(s):

Once this switch has been set, the pretty-printer (invoked either by Compile:Pretty Print or by Compile:Syntax) will automatically perform delimiter alignment.

Expansion and Elision in the Completion Window

By default, the completion window shows each possible completion on one line, abbreviating it if necessary by adding ellipsis near the end of the declaration. This is convenient in most cases, as the abridged form is sufficient to select a completion, but it can become ambiguous for subprograms with long parameter parts. For instance, say that we are completing the call to P below:

The completion window that is brought up only shows the first four parameters of each subprogram.

The parameter Z, which is the only one that helps disambiguate the two subprograms, is not displayed, so it is hard to tell which of the entries in the completion window corresponds to which declaration. (The entries in the completion window are listed in the other in which they appear in the source code, so this gives a way to disambiguate, but in real programs this is rather awkward.)

It is now possible to use the Expand button to expand entries in the completion window. The parameter Z is now visible. Of course, the second entry could be expanded as well for maximum readability.

Hitting Complete on any of the entries will cause completion to happen with the desired declaration.

Once an entry has been expanded, it is possible to revert to the abbreviated, one-line description by using Elide.

Multiple Completion

When a completion window presents choices for completing several constructs, it was only possible to complete one of the constructs. This made it necessary to run completion over and over again, dealing with one construct at a time.

The completion window has been improved: it is now possible to select (at most) one completion for each construct, and have all of them completed in one fell swoop. For instance, say that the lines containing the calls to P and Q below are selected, and Complete is hit:

The following completion window is brought up. Now say that the first completion is selected for P and the second is selected for Q:

After hitting Complete on the completion window, the two subprogram calls are simultaneously completed:

Semantic Completion Dialog

Semantic completion in the Ada object editor can now be configured using the Completion Options dialog box. This dialog is displayed if the Control key is depressed while selecting Compile > Complete. The discussion of semantic description in Programming Using Apex has been improved and the new dialog is described in detail in the Online Reference.

Runtime

Fixed Point Rounding

The fixed point multiplication, division and conversion operations used to ROUND the result to the nearest machine representable number when the operation was executed at runtime, but it used truncation when the result was computed at compile-time. The Apex 4.2.0 compiler now uses truncation uniformly. For example:

would yield False for earlier versions of Apex and will yield True for the Apex 4.2.0 release. Under older versions of Apex Y1 = 5.0 and Y2 = 6.0. Under this release, both Y1 and Y2 will have the value 5.0.

Pragma Suppress

When a runtime check is suppressed using pragma Suppress (<check name>), the compiler not only omits the code to perform the check, but now assumes that the check would have passed. This assumption allows the optimizer to make the same inferences about the code as when then checks were present thus preventing code quality degradation in some cases when checks are suppressed.

In the case that a check would fail, RM 95 11.5(26) states:

If a given check has been suppressed, and the corresponding error situation occurs, the execution of the program is erroneous.

By assuming that suppressed checks will always pass, the Apex 4.2.0 compiler has changed the behavior of some erroneous programs. For example, it is dangerous to declare the size of an imported (variable size) array to be one:

will always update the first element of X regardless of the value since the optimizer is allowed to assume that then index check (I in 1 .. 1) will pass. In earlier releases of Apex, the compiler would (typically) generate code to update the Ith element of X.

Task Naming

Apex now systematically assigns a short, unique prefix to task names. The full task name (including the prefix) can be obtained at execution time from Ada.Task_Identification.Image. This name is also passed to LynxOS when the thread implementing the task is created, allowing the names to be displayed with the LynxOS ps command using the -t option.

The OS truncates the full task names, but the unique prefix will usually be visible. The debugger now provides a task_id flag that can be set to display these names using the lt command.

Further details can be found in the "Tasking" chapter of Using the Ada Runtime.

For Apex Solaris 4.0.0b native, the Ada runtime now checks for insufficient stack space to meet the requirements for stack space size as requested by either "pragma Main(Stack_Size => ...);" or by the configuration table parameter V_Usr_Conf.Configuration_Table(Main_Task_Stack_Size). Solaris does not allow a process to change its own stack size limit, so the solution we chose is to emit the following warning when the current stack space is insufficient:

Note that this message tells you the csh or tcsh command to use, not the sh, ksh, or bash command, which would be "ulimit -s yyy"

When assigning a priority to a task in the threaded runtime, Ada priorities are translated to POSIX priorities by transposing the Ada priority range into that of the scheduling policy of the underlying thread. However, this is not done when assigning a ceiling priority to a PTHREAD_PRIO_PROTECT mutex. This leads to unexpected behavior.

User Interface

The File > Run and File > Debug dialogs have been combined into one dialog. The new unified dialog has pages to select between running and debugging. Use the Run page to run a program. Use the Debug page to debug a program. The menu items have not changed. For example, selecting File > Debug will bring up the new dialog with the Debug page selected.

The Debugger Tasks window contains three new buttons: Default, Full, and Stack Usage. You can select all tasks, or a single task, then one of these buttons to change the format of the Task window display. Default corresponds to the simple lt case. Full corresponds to the lt all | <task number> (lt all or lt 5). Stack Usage corresponds to lt use or lt use 5.

The Debugger Session check box has been removed from the File > Debug dialog.

The descriptions of the options from the Print dialog have been corrected The Raw option has been added and Postscript has been changed to Formatted to match the actual entries on the dialog.

The Show Unused and Show Usage dialogs have changed extensively. These changes are also reflected in a new set of options for the show_unused and show_usage commands. These commands are documented in the Command Reference.

The "tear off" menu feature for Apex is no longer available. Apex 4.0 switched to using Motif 2.1 instead of 1.2. Motif 2.1 recommends against enabling tear off on shared menus.Motif strongly discourages it, suggesting that the user may encounter severe problems.

Apex Shadowing

A new context switch, REMOTE_CONTEXT_COMPLETION, is used when shadowing is enabled. It allows the view to specify a remote context relative path.

Currently the remote context is either specified directly in the shadow switches, or if USE_CONTEXT_AS_BASE is set, then the <subsystem_path>/<view_name> is append to the remote context.

Both switches are supported, but the new switch takes precedence over the old switch (the new switch can achieve the same thing as the old switch "<view>:s:r/<view>:t:r")

Summit/CM

Bill of Materials Command

A new command, apex_BOM, enables you to obtain a bill of materials from an Apex build if the Summit/CM configuration management system is being used. This command supports the generation of a Version Description Document. This command is described in detail in the Command Reference.

New Command Options

The abandon, control, set_history, and set_version commands now accept the -no_artifacts option. This option specifies that compilation artifacts should not be [abandoned, controlled, or set] with the source files. The default value is false.

The -goal <goal_state> option has been added to the copy command. The new objects will be copied along with artifacts appropriate  to the goal state.Units in the new views are compiled to the requested state as required, except in the case of preserve, which preserves the original state but does not perform any recompilation. The default value is preserve.

Tools

Reporting Problems to Apex Technical Support

A new version of the rreport tool is included in this release. This tool enables Apex customers to more easily and quickly report problems and suggestions to Apex Technical Support.

The rreport tool asks the customer for the problem description and automatically includes required Apex data (version, patches, installation log) to the report sent to Apex support. In addition, a service request is automatically created when rreport is used to report problems/make suggestions to Rational Software.

Apex Disassemble

The apex disassemble command has changed where it puts the assembly files. The new default location is in the source directory next to the .ada files. Two switches can modify this new default behavior.

Apex Trace

Support for call-return and basic block tracing has been removed from the Tasking Logic Analyzer product (apex_trace). Only runtime event tracing is now supported.

Documentation

Changes in Hard-Copy Documentation

The Rational Apex documentation set has been simplified. No longer are there separate manuals for each variant of Apex (Ada, C/C++, Duo). Where there is information that is specific to only a single variant, it is clearly labelled in the documentation.

Many of the titles of the Apex manuals have been changed to adhere to the Rational standards for manual titles. In addition, the manuals are now formatted using the standard Rational templates.

User Interface Changes in Help Files

In the online help system, a link to the Technical Support Solutions has been added to the HTML help files. The Solutions provide additional, in depth information on the Rational Apex product.

The Version button has been removed from the online help files. To view Version information, click Help > On Version.

RCI

Licensing

RCI is being removed from the Rational price list. RCI is considered to be part of the base Apex product and will now be supported as part of the standard Apex product. Licenses for RCI are issued as part of the normal set for both Apex Native and Apex Embedded products.

ClearCase support

Changes that may affect existing customizations

Existing RCI customizations, that work with previous releases of Apex, will have to be slightly adapted, to take into account the following changes in Apex 4.0.0b:

Please refer to the sample customizations provided with this release for examples of the updated test_version, clean and post_create_view scripts.

Handling of target library specifications

In previous Apex releases, in the File > New View, File > Copy (View) and RCI > Create Target Library dialogs, the RCI target "context" and "library name" specified by the user were combined by the dialog itself to generate a target directory pathname which was passed to the underlying Apex or RCI command.

This scheme had serious drawbacks when the target system was not the same as the host system, especially if the target system was not a UNIX system.

Starting with this release, the context and directory name specified by the user are passed unmodified from the dialog, through the underlying Apex or RCI command, all the way to the RCI post_create_view script, which may then interpret its -rci_target_directory and -rci_target_context parameters and compose them according to the target OS file naming rules, to generate the resulting RCI_TARGET_DIRECTORY name.

Also, when a "default" context or library name is selected by the user, this information is passed to the post_create_view script (-rci_default_target context and -rci_default_target_directory boolean parameters), which may then synthesize default values as appropriate for the customization.

Upgraded sample customizations

The Ada83 VADSself and Ada95 GNAT sample customizations delivered with RCI have been upgraded in various aspects in this release.

Support for new versions of target compilers

The VADSself customization now targets version 6.2.3d of VADSself Solaris.

The GNAT customization now targets version 3.12p of GNAT Solaris.

New setup for predefined views

The mapping of predefined units for the target environment to the $APEX_BASE/ada/xxxx.ss subsystem views for the sample customization has been reorganized, to have a setup similar to that of the standard Apex predefined views.

Revised customization scripts

The scripts provided in the $APEX_BASE/ada/keys/rci_xxx compiler key directories for the sample VADS and GNAT customizations have been extensively rewritten:

RCI customizers are strongly encouraged to study these sample scripts and use this new base for evolutions of their own customizations.

The scripts now have a more homogeneous format and coding style.

Comments have been revised, to better document the purpose of the scripts and the conditions where they get called.

Areas of the scripts that may need to be adapted for a new customization ("CUSTOMIZABLE CODE" boxes) have been more systematically identified and documented.

To encapsulate actions repeatedly performed by customization scripts, a number of utility scripts have been added, among which:

As a result, most of the scripts are now common between the VADS and GNAT sample customizations,

The sample customizations now come with an interactive setup script, which may be used to automate the setup of the customization for the local installation of the target compilation system (see the README file provided in the customizations' compiler key directory for details).

Guidelines and Restrictions on Using Rational Apex

The known limitations of Apex 4.2.0 B are described below. Workarounds are included where applicable.

Ada Compilation System

Running Apex binaries compiled on Solaris 2.7 under Solaris 2.6

New releases of operating systems usually provide several forms of backward compatibility. In particular, it is often possible to run binaries compiled for an older version of the OS on a new release. Running binaries compiled for the newer version of the OS on the older version may also be possible, though it is not usually supported and may cause problems.

Solaris 2.7 binaries in particular can often be run using Solaris 2.6 with varying degrees of success. However, binaries that make use of POSIX 1003.1b Real-Time Extensions will fail immediately for lack of the shared librt.so library with a message like:

Here librt.so.1 is the particular version of librt.so on this machine. A soft link from librt.so to librt.so.1 is provided in /usr/lib to direct the linker to the latest version of this library. Note that the linker looks through the soft link, including the name of the actual library file rather than the link in the resulting application binary. The Solaris 2.6 equivalent to this library is libposix4.so. Solaris 2.6 binaries using libposix4.so will work on Solaris 2.7, since a soft link from libposix4.so to librt.so is provided in /usr/lib. Apex always links against the name libposix4.so to support Ada.Calendar and other time related features, but again the linker looks past the soft link to the name of the library binary itself. Those linked on Solaris 2.7 will therefore attempt to load librt.so when executed. Under Solaris 2.6 this will fail since there is no library of that name.

In general it is best to avoid running Solaris 2.7 binaries on 2.6. However, this particular problem can be avoided by providing a link visible to the loader from the name needed by the binary to /usr/lib/libposix4.so. The easiest way to do this is to add the appropriate link in /usr/lib. For the example above:

This requires superuser privileges. In the absence of such privileges, any directory can be used by adding it to the LD_LIBRARY_PATH environment variable:

To make this visible to the loader, execute

If you are attempting to run the application outside of an Apex shell,
LD_LIBRARY_PATH may not be defined, in which case you should substitute:

Ada 95 Unimplemented Features

The following Ada95 features are not implemented in the Apex 4.2.0 B compiler:

Ada 95 Known Limitations

SPARC V9 Solaris 64-bit C/C++ Profiling

For Sol64, prof is not supported; only gprof is supported by Sun. In order to be able to profile a C/C++ program using the Apex C/C++ compiler, RCC, you must obtain the64-bit version oft he gprof run-ime object gcrt1.o and copy it over to the sol64 RCC area (CPP_COMPILER_HOME/self/lib). If you do not do this, the link will fail. Once the 64-bit version of gprof is in place, profiling support via gprof is complete for the Sol64 product.

This also applies to profiling mixed Ada/C/C++ programs with Ada/C++ as main (where RCC is doing the final link.) You must obtain the 64-bit "gcrt1.o" for the link to be successful.

Runtime

After setting the UNIX signal mask using V_Interrupts, executing a DELAY statement will corrupt the signal mask. Workaround: Remove the DELAY statement.

The following session switches are not supported:

APEX_TASK_PRIORITY_DEFAULT
APEX_TASK_STACK_SIZE_DEFAULT
AEPX_TIME_SLICE
APEX_STACK_SIZE
APEX_SIGNAL_STACK_SIZE

The Rational Ada runtimes do no support the fork() system call as a mechanism for creating a process. The posix.ss subsystem supports the industry standard bindings to POSIX which includes Posix_Process_Primitives.Start_Process, as the recommended way to create a new process from an Ada program.

Libraries

The multiplication function in the complex arithmetic package in $APEX_BASE/vads_compatibility.ss/.../verdixlib is incorrect. It incorrectly assumes that values of equal magnitude are equal, even if the signs are not. This results in incorrect values. Therefore (2,2) * (2,-2) yields (0,8) when it should yield (8,0). In Ada 95, Rational strongly recommends that you use the complex arithmetic implementation in $APEX_BASE/ada/numerics.ss.

The return code from procedure $APEX_BASE/vads_compatibility.ss/.../verdixlib/unix_calls.open is documented backwards. The routine returns True if there is an error and False if it succeeds.

Interfacing with C

When generating code for a function with a 32-bit floating point result, the Rational C compiler promotes the result to a 64-bit representation.

On targets which support 32-bit floating point registers, for example, Sun and SGI, this is incompatible with the conventions of the platform vendor's C compiler. On other targets, such as Dec Alpha, this promotion has no effect because all floating point results are returned in 64-bit registers.

The Rational Ada compiler expects C functions to follow the conventions of the platform vendor's C compiler. This means that the following example executes correctly if the .c file is compiled with the vendor's C compiler and fails on targets such as Sun and SGI if it is compiled with the Rational C compiler.

Workaround: Use 64-bit floats instead of 32-bit floats on those platforms for which this is a problem.

ASIS

The test install of ASIS is very slow. Link time takes up the bulk of the test install time. Link time can be reduced by a factor of 10 if the link is performed on the same machine that owns the disks on which the ASIS views are installed.

Optimizer

The optimizer assumes infinite precision for floating point operations. This is a problem in some cases. For example, if you have the expression

and x is continually reduced towards zero, the expected result is that when the value of x drops below float_type'EPSILON, the comparison will become false (i.e., x + 1.0 will equal 1.0). The optimizer assumes an infinite precision for x, such that even float_type'SMALL +1.0 /= 1.0. This is incorrect per LRM 4.5.7 and 3.5.6. The workaround is to turn off optimization.

Debugger
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 TECHNOTES APEX TIPS