![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
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 LibrariesThe 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 LibrariesPackage 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"
- "Rational's ASIS Library Implementation"
- "Accessing A Library - A Quick Look"
- "Determining What Belongs to an ASIS Library"
- "Library Closure Calculations"
- "Library Properties"
- "Opening Libraries"
- "Closing Libraries"
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:
- library, ASIS library: the ASIS concept of a library.
- Ada program library: the Ada program library as in the LRM.
- library variable: a variable of the type Asis.Library. The value of the parameter references an ASIS library.
- Library: appears often as both the name of a parameter and of a type. In this case, Library is the parameter having that name. The value of the parameter references an ASIS library.
If a distinction between the parameter and the type is required, the term is qualified. For example, "Library parameter" or "Library type."
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:
Asis.Environment.Initialize;Asis.Libraries.Associate (My_Library, Name =>...; Parameters =>...);Asis.Libraries.Open (My_Library);Associate's parameters determine which physical compilation units belong to the library and the values of control parameters:
- Name: Explicitly names a single view or configuration whose physical compilation units belong to the library.
- Parameters: Optionally specifies what configuration to use to identify the views that belong to the library.
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:
Asis.Libraries.Associate (My_Library, Name => Asis.Libraries.Default_Name, Parameters => Asis.Libraries.Default_Parameters);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:
Asis.Libraries.Close (My_Library);Asis.Libraries.Dissociate (My_Library);Asis.Environment.Finalize;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:
- If Name specifies a view and Parameters does not specify a configuration, ASIS opens the view and the view's imports.
- If Name specifies a view and Parameters specifies a configuration, ASIS opens the view and the specified configuration. The imports specified by the view are ignored.
- If Name specifies a configuration and Parameters does not specify a configuration, ASIS opens the configuration and all views described by the configuration.
- If both Name and Parameters specifies a configuration, an error results. Two configurations cannot be specified.
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:
- Do not always need to manipulate the full closure of a library
- Process very large libraries and do not wish to appear to pause for a long time when a library is initially opened
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:
- Debug
- Unit_Closure
- World_Closure
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:
- The view named in the Name string or all views contained in the configuration named in the Name string
- All views contained in any configuration specified in the Parameters string
- All views imported by the above named or referenced views
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:
- If one or both of the libraries are closed, a comparison is done on the name and parameters values associated with the library. If the name and parameters values are exactly the same (case, ordering, names, and so on), Is_Equal returns True.
- If both libraries are open, they must represent the same set of Ada program libraries and contain the same physical compilation units, for Is_Equal to return True.
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
- 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. |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |