![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
Procedure Associate
procedure Associate (Library : in out Asis.Library; Name : in Asis.Asis_String; Parameters : in Asis.Asis_String := Default_Parameters);Expanded Name Asis.Libraries.Associate
Associates a name and set of parameter values with the specified library.
Description
This procedure must be called prior to opening a library. It returns an initialized library variable if the processing does not result in an error. It raises an exception if called with a library that is already open.
Any name and parameters values that had been previously associated with the specified library are lost.
The Name string specifies one view or configuration. The Parameters string optionally specifies a configuration and processing modes. The format and content of both parameters is vendor-specific and described in more detail below.
Certain validity checks are performed on the specified Name and Parameters values. The library is not actually opened at this point and access restrictions or other problems could prevent the subsequent call to the Open procedure from succeeding.
Parameters
Library : in out Asis.Library;Specifies the library with which to associate the name and set of parameter values.
Name : in Asis.Asis_String;Specifies a single view or configuration name. An individual Ada compilation unit name cannot be specified. The string can contain wildcard characters but it must resolve to a single file name. The name is case sensitive.
Which units belong to the library depend not only on the value of the Name string but on the value of any configuration specified in the Parameters string. See "Determining What Belongs to an ASIS Library" for a full description.
Parameters : in Asis.Asis_String := Default_Parameters;Specifies the set of parameter values to be associated with the specified library. These values determine:
- The configuration to use for the view specified in the Name parameter
- The setting for debugging
- When to compute the world and unit closures
This information is specified with keywords followed by a value; keywords' purposes and default values are:
- Configuration: Specifies the name of a file containing the configuration for the view specified in the Name parameter. Defaults to a nil string which causes the standard imports for the view to be used.
- Debug: Specifies whether to perform additional dangling-pointer checks during execution. This extra checking slows performance slightly but can identify more application errors. Defaults to False.
- Unit_Closure: Specifies whether to compute the unit closure when the library is opened. If the unit closure must be computed, the world enclosure is first computed. Defaults to False.
- World_Closure: Specifies whether to compute the view closure when the library is opened. Defaults to False.
Standard Rational syntax is used to specify keyword parameters:
- If multiple keywords are specified, separate them with commas
- The form Keyword => Value assigns the specified Value to the Keyword
- The form Keyword is equivalent to Keyword => True
- Keywords can be abbreviated to their shortest unique forms
If a keyword is specified multiple times, the value associated with the last instance takes precedence.
Errors
Asis_Inappropriate_Library is raised if the Library is currently open.
Asis_Failed is raised if the content of the Parameters string is invalid.
Examples
Cross-References
Procedure Close
procedure Close (Library : in out Asis.Library);Expanded Name Asis.Libraries.Close
Description
The name and set of parameter values associated with Library are retained so that the Open procedure can be called again if desired.
All compilation unit and element values obtained from a library become invalid after it is closed. Subsequent calls to ASIS resources using such values are erroneous. ASIS attempts to detect such usage and raise Asis_Failed. However, this cannot be guaranteed and unpredictable behavior may result.
Parameters
Library : in out Asis.Library;Specifies the library to close.
Errors
Asis_Inappropriate_Library is raised and Environment.Status is set to Value_Error if a library variable is specified that is no longer open.
Examples
Cross-References
Function Debug_Image
function Debug_Image (Library : in Asis.Library) return Asis.Asis_String;Expanded Name Asis.Libraries.Debug_Image
Returns an implementation-defined string representing the specified library.
Description
Rational ASIS returns a single line of text; its content depends on whether the library is unassociated, invalid, or associated:
- An unassociated library returns:
<Nil_Library>
- An invalid library (which cannot occur without use of Unchecked_Conversion or memory corruption) returns:
<Invalid Library>
- An associated library returns:
<16#dd# 16#dd#, Unique_Id => id, Name => "name", Parameters =>"parameters", Open => open>
The first two numbers (in Ada hex format) and the id are useful to maintainers of Rational ASIS. The other syntactic categories are:
Syntactic Category
Definition
The Name string specified in Associate procedure.
Boolean. If False, the library has not yet been opened.
The Parameters string specified in the Associate procedure.
Parameters
Library : in Asis.Library;Specifies the library for which debug information is desired.
return Asis.Asis_String;Returns implementation-defined debug information for the specified library.
Errors
Examples
Cross-References
Function Default_Name
function Default_Name return Asis.Asis_String;Expanded Name Asis.Libraries.Default_Name
Returns an Asis.Asis_String containing the default library name.
Description
Returns Asis.Nil_Asis_String. ASIS interprets this as ".", which is short-hand for the name of the current directory. The current directory must represent a view or the Associate procedure will raise an exception.
The function can be used as the value for the Name parameter in a call to the Associate procedure.
Parameters
return Asis.Asis_String;Returns Asis.Nil_Asis_String.
Errors
Examples
Cross-References
Function Default_Parameters
function Default_Parameters return Asis.Asis_String;Expanded Name Asis.Libraries.Default_Parameters
Returns an Asis.Asis_String containing the default library parameters.
Description
The function can be used as the value for the Parameters parameter in a call to the Associate procedure.
Parameters
return Asis.Asis_String;Returns Asis.Nil_Asis_String.
Errors
Examples
Cross-References
Procedure Dissociate
procedure Dissociate (Library : in out Asis.Library);Expanded Name Asis.Libraries.Dissociate
Clears any previously established name and parameters associations for the specified library.
Description
Call Dissociate for libraries that have been given a name and set of parameter values but are no longer needed, so that ASIS can release the resources allocated to these items.
If no name or set of parameter values are established for the specified library, the procedure has no effect.
Parameters
Library : in out Asis.Library;Specifies the library for which to clear the name and parameter associations.
Errors
Asis_Inapropriate_Library is raised and Enviornment.Status is set to Value_Error if the Dissociate procedure is called with an open library.
Examples
Cross-References
Function Exists
function Exists (Library : in Asis.Library) return Boolean;Expanded Name Asis.Libraries.Exists
Returns a Boolean value indicating whether the vendor Ada libraries associated with the specified library exists.
Description
- Specified library is open
- Library is initialized and the name and parameters associated with the specified library appear valid and represent a library that exists
- Specified library is uninitialized
- The library is initialized and the name and set of parameter values associated with the specified library are invalid or do not represent a library that exists
It is not possible to validate all name and set of parameter values prior to opening the library. Thus, Exists can return True and the Open procedure can still fail.
Parameters
Library : in Asis.Library;Specifies the library to check for existence.
return Boolean;Returns True if the specified library is open or if a name and set of parameter values are associated with the specified library appear valid and represent a library that exists.
Errors
Examples
Cross-References
Function Has_Associations
function Has_Associations (Library : in Asis.Library) return Boolean;Expanded Name Asis.Libraries.Has_Associations
Returns a Boolean value indicating whether the library has been initialized with the Associate procedure.
Description
Returns True if a name and set of parameter values are associated with the specified library.
Returns False if the Associate procedure has not been called or the Dissociate procedure has been called subsequent to Associate.
Parameters
Library : in Asis.Library;Specifies the library to check.
return Boolean;Returns True if a name and set of parameter values are associated with the specified library.
Errors
Examples
Cross-References
Function Is_Equal
function Is_Equal (Left : in Asis.Library; Right : in Asis.Library) return Boolean;Expanded Name Asis.Libraries.Is_Equal
Returns a Boolean value indicating whether the libraries represent the same name and set of parameter values or the same set of physical compilation units.
Description
This function returns True if either:
- One or both libraries are not open and the name and set of parameter values for each library are exactly the same.
- Both libraries are open and both libraries contain the same physical compilation units. If the libraries contain multiple versions of a physical compilation unit, all versions must match.
Note that Is_Equal can return True prior to the libraries being opened and False after. This could typically happen only if the Ada program library was updated between the two opens.
Similarly, it is possible for Is_Equal to return False prior to the libraries being opened and True after. This could happen, for example, if the keywords in the parameters string were specified in a different order.
Obsolete units take part when the library contents are compared.
Parameters
Left : in Asis.Library;
Right : in Asis.Library;
return Boolean;Returns True if both libraries are open and they contain the same physical compilation units or if either are closed and the Name and set of parameter values match.
Errors
Examples
Cross-References
Function Is_Identical
function Is_Identical (Left : in Asis.Library; Right : in Asis.Library) return Boolean;Expanded Name Asis.Libraries.Is_Identical
Returns a Boolean value indicating whether both parameters represent the same library.
Description
The library type is defined as limited private and each associated library variable contains a unique value, different from all other associated library variables. The Is_Identical function can be used to compare two library variables to determine whether they are identical.
Returns True if Left and Right are the same library variable. Returns False if either library variable is not open, or if they are not the same library.
No two distinct library variables that the user has associated are ever Is_Identical.
Library values obtained from the Compilation_Units.Enclosing_Library function can be compared between each other or library variables. An open library variable and a Compilation_Units.Enclosing_Library value are only Is_Identical if the compilation unit was derived from that library.
Parameters
Left : in Asis.Library;
Right : in Asis.Library;
return Boolean;Returns the status of the comparison between the two libraries.
Errors
Examples
Cross-References
Function Is_Open
function Is_Open (Library : in Asis.Library) return Boolean;Expanded Name Asis.Libraries.Is_Open
Returns a Boolean value indicating whether the specified library is open.
Description
A library is considered open after the successful completion of the Open procedure.
Parameters
Library : in Asis.Library;Specifies the library for which the access status is desired.
return Boolean;Returns True if the specified library is open; otherwise, returns False.
Errors
Examples
Cross-References
Function Name
function Name (Library : in Asis.Library) return Asis.Asis_String;Expanded Name Asis.Libraries.Name
Returns an Asis.Asis_String containing the name value currently associated with the specified library.
Description
If a name value is not currently associated with the specified library, Asis.Nil_Asis_String is returned
The name value is assigned when the Associate procedure is called with the specified library. The value can be removed from the library by calling the Dissociate procedure; which again causes Asis.Nil_Asis_String to be returned.
Parameters
Library : in Asis.Library;Specifies the library for which to return a name.
return Asis.Asis_String;Returns the name of the specified library.
Errors
Examples
Cross-References
Procedure Open
procedure Open (Library : in out Asis.Library);Expanded Name Asis.Libraries.Open
Opens the specified library using a previously associated name and set of parameter values.
Description
The Associate procedure must have previously been called to associate a name and set of parameter values with the library or the open will fail.
For Open to succeed, the user must have read access to all the objects specified and any objects referenced by the name and set of parameter values provided with the Associate procedure.
Parameters
Library : in out Asis.Library;Specifies the library to be opened.
Errors
Asis_Inappropriate_Library is raised and Environment.Status is set to Parameter_Error if the library is already open or a name has not been established by calling the Associate procedure.
Asis_Failed is raised if the library could not be opened for any reason. The library could fail to open because of an incorrect name, access restrictions, invalid parameter combinations, storage limitations, or other reasons. The most common Environment.Status values are Name_Error, Use_Error, Data_Error and Parameter_Error.
Note that if closures are not immediately calculated, errors can occur any time ASIS searches for a physical compilation unit with a name not yet known.
Examples
Cross-References
- "Accessing A Library - A Quick Look"
- "Opening Libraries"
- "Determining What Belongs to an ASIS Library"
Function Parameters
function Parameters (Library : in Asis.Library) return Asis.Asis_String;Expanded Name Asis.Libraries.Parameters
Returns an Asis.Asis_String containing the set of parameter values currently associated with the specified library.
Description
If a set of parameter values is not currently associated with the specified library, Asis.Nil_Asis_String is returned
The set of parameter values is assigned when the Associate procedure is called with the specified library. The value can be removed from the library by calling the Dissociate procedure; which again causes Asis.Nil_Asis_String to be returned.
Parameters
Library : in Asis.Library;Specifies the library for which to return a set of parameter values.
return Asis.Asis_String;Returns the set of parameter values associated with the specified library.
Errors
Examples
Cross-References
Package Operations
package Operations is -- For Asis.Library function Is_Equal (Left, Right : ... function Is_Identical (Left, Right : ...end Operations;Expanded Name Asis.Libraries.Operations
Package Operations provides a simple way to obtain visibility to operators for types used in package Libraries. The package typically is referenced in a use clause by an application.
Cross-References
- function Is_Equal
- function Is_Identical
- type Asis.Library
Rational Software Corporation
http://www.rational.com support@rational.com techpubs@rational.com Copyright © 1993-2001, Rational Software Corporation. All rights reserved. |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |