TOC PREV NEXT INDEX DOC LIST MASTER INDEX




Procedure Associate

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

Specifies the library with which to associate the name and set of parameter values.

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.

Specifies the set of parameter values to be associated with the specified library. These values determine:

This information is specified with keywords followed by a value; keywords' purposes and default values are:

Standard Rational syntax is used to specify keyword parameters:

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

Related subprograms:

Related topics:


Procedure Close

Expanded Name Asis.Libraries.Close

Closes the specified library.

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

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

Related subprogram:

Related topic:


Function Debug_Image

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:

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

Specifies the library for which debug information is desired.

Returns implementation-defined debug information for the specified library.

Errors

None.

Examples

Cross-References

Related subprograms:


Function Default_Name

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

Returns Asis.Nil_Asis_String.

Errors

None.

Examples

Cross-References

Related subprograms:

Related topic:


Function Default_Parameters

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

Returns Asis.Nil_Asis_String.

Errors

None.

Examples

Cross-References

Related subprograms:

Related topics:


Procedure Dissociate

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

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

Related subprograms:

Related topic:


Function Exists

Expanded Name Asis.Libraries.Exists

Returns a Boolean value indicating whether the vendor Ada libraries associated with the specified library exists.

Description

Returns True if the:

Returns False if the:

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

Specifies the library to check for existence.

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

None.

Examples

Cross-References

Related subprogram:

Related topic:


Function Has_Associations

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

Specifies the library to check.

Returns True if a name and set of parameter values are associated with the specified library.

Errors

None.

Examples

Cross-References

Related subprograms:

Related topic:


Function Is_Equal

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:

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

Specifies the first library.

Specifies the second library.

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

None.

Examples

Cross-References

Related subprograms:

Related topic:


Function Is_Identical

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

Specifies the first library.

Specifies the second library.

Returns the status of the comparison between the two libraries.

Errors

None.

Examples

Cross-References

Related subprograms:

Related topic:


Function Is_Open

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

Specifies the library for which the access status is desired.

Returns True if the specified library is open; otherwise, returns False.

Errors

None.

Examples

Cross-References

Related subprograms:

Related topic:


Function Name

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

Specifies the library for which to return a name.

Returns the name of the specified library.

Errors

None.

Examples

Cross-References

Related subprograms:

Related topic:


Procedure Open

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

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

Related subprograms:

Related topics:


Function Parameters

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

Specifies the library for which to return a set of parameter values.

Returns the set of parameter values associated with the specified library.

Errors

None.

Examples

Cross-References

Related subprograms:

Related topic:


Package 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

Related subprograms:

Related topic:


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