TOC PREV NEXT INDEX DOC LIST MASTER INDEX



Package Libraries

Package Libraries provides resources to access a vendor's Ada program libraries.

Once the program libraries are accessed, you can obtain compilation unit information with the functions provided in package Compilation_Units.

For more information, click on a topic:


Resources in Package Libraries

The subprograms in package Libraries fall into several functional groups, as shown below.

To see detailed referenced information, click on the name of a subprogram:
Opening and closing libraries:
Associate Default_Name Dissociate
Close Default_Parameters Open
Library properties:
Exists Is_Equal Is_Open Parameters
Has_Associations Is_Identical Name


Key Concepts in Package Libraries

Package Libraries provides resources to access a vendor's Ada program libraries. Processing is divided into the following categories. To see more information, click on a topic:

Terminology for Libraries

The ASIS Library type is a handle to, and is intended to correspond closely with, a particular vendor's implementation of the Ada program library (Ada83 LRM 10.4, Ada95 LRM 10).

ASIS, however, does not require the Ada program library implementation and the ASIS library to be identical or even similar. For example, an ASIS Library can represent a logical or physical subset or superset of the vendor's Ada program library. ASIS might not even reference the Ada program library, instead reading structures generated by the compiler specifically for ASIS.

Because of these differences, a clear distinction between the concept of an Ada program library and an ASIS library is important. In this documentation, we use the following definitions:

An Ada program library and an ASIS library are both repositories for compilation units. After a successful access has been made to an ASIS library you can obtain handles to the compilation units that belong to that library, and then, with the compilation unit handles, obtain handles to the semantic elements that comprise the units. For more information, see package Compilation_Units, "Terminology for Compilation_Units," and package Elements, "Elements Defined."

Rational's ASIS Library Implementation

To understand Rational's ASIS library implementation you should be familiar with Rational's configuration management and version control (Summit/CM), subsystems, views, and configurations. Refer to Using and Customizing Summit/CM for information.

Accessing A Library - A Quick Look

To open a library, you must first initialize the ASIS environment and associate a name and a parameters value with the library. This code fragment illustrates a typical calling sequence:

Associate's parameters determine which physical compilation units belong to the library and the values of control parameters:

ASIS has functions that return defaults for both the Name and Parameters values. The default values specify your current location, which must be a view. If your current location is not a view, an exception is raised.

A call to Associate using the default values could look like this:

After the association has been made and the library has been opened, functions in package Compilation_Units are typically called to determine an appropriate set of compilation units for further analysis. Calls to other ASIS subprograms are then made to analyze each compilation unit.

To conclude ASIS processing, close any libraries you have opened and finalize the environment. After a library is closed, all compilation units and elements obtained with the library are invalid; calls to ASIS subprograms using these invalid values raise exceptions.

This code fragment illustrates a typical termination sequence:

Determining What Belongs to an ASIS Library

Which physical compilation units belong to a library depends on what kind of object Associate's Name parameter resolves to and whether the Parameters string specified a configuration:

By default, Rational ASIS uses lazy evaluation to determine library contents; evaluation of the library content is deferred and occurs as required by the application. This spreads out the closure-computation overhead, thus improving interactive response. Lazy evaluation is helpful for applications that:

Because processing is deferred, errors arising from missing compilation units and other objects can occur as a result of calls to most ASIS subprograms.

Lazy evaluation can be overridden, forcing closure calculations to be computed immediately, by specifying some or all of the following keywords in the Parameters string:

Library Closure Calculations

Internally, Rational ASIS constructs two import closures:

World closure: consisting recursively of all views referenced by the Name parameter and the configuration keyword of the Parameters string

Unit closure: consisting of all physical compilation units contained within the world closure

Click on a topic for more information:

World Closure Computations

If the Debug, World_Closure, or Unit_Closure parameters are specified or set to True, the world closure of the library is computed when it is first opened. If set to False, the closure is calculated incrementally, on demand.

The world closure consists of:

Unit Closure Computations

If the Debug or Unit_Closure parameters are specified or set to True, the unit closure of the library is computed when the library is first opened. If set to False, the closure is calculated incrementally, on demand.

The unit closure is the sum of all Ada units that appear in all views that belong to the library. This list can be expensive to compute, and it may not be required for a particular application.

Computing the unit closure requires ASIS to first compute the world closure.

If the unit closure has not been requested, whenever a particular named unit is required, but is not presently known to be a member of the library, the unit closure of additional views is computed until a unit with the required name is located. Computation of the closure is then deferred again, until the next compilation unit with an unknown name is required.

Library Properties

The Asis.Library type represents a handle to one or more Ada program libraries. Because comparisons of handles is not meaningful, and for operational considerations, the type is limited private. Thus, assignment and the relational operators, including the equality operator, are not exported for the type.

To determine whether two library values represent the same set of Ada compilation units, call Is_Equal. To determine whether two library values are identical (=), call Is_Identical.

Is_Equal can be called when the libraries are open or closed:

An uninitialized library variable is one for which the Associate procedure has not been called, or for which the Dissociate procedure has been called. An uninitialized library variable returns False from the Has_Associations function.

If a library variable has associations, as indicated by Has_Associations returning True, you can obtain the associated name with the Name function and the associated parameters value with the Parameters function.

Finally, you can determine whether a library variable represents an open library with the Is_Open function.

Opening Libraries

To open a library variable:

1. . Call the Associate procedure to assign name and parameters values to the library variable.

This procedure performs certain validity checks on the specified values, allocates a library handle, stores the specified values in the handle, and returns the handle.

2. . Call the Open procedure with the handle returned from the Associate procedure. This opens the objects identified by the name and parameters values, computes closures as required, and then returns to the user.

The library variable now tests as Is_Open, and can be specified in any of the ASIS subprograms that require an open library.

You can attempt to determine whether an Open might succeed with an initialized library variable by calling the Exists function. This function returns True if it appears that the specifications in the name and parameter values associated with the library identify one or more valid Ada program libraries. The library is not actually opened at this point, and access restrictions or other problems can still prevent the Open procedure from succeeding even though Exists returns True.

Closing Libraries

To close a library variable and release the resource allocated to it:

1. . Call the Close procedure to release all compilation units and elements associated with the library.

Use of these compilation units or elements after close has been called results in an exception being raised.

2. . Call the Dissociate procedure to release the name and parameter values associated with the library.

Note: The Close procedure does not alter the Name and Parameters values associated with the library; it is possible to call Open to reaccess the same library without specifying these values again.


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