TOC PREV NEXT INDEX DOC LIST MASTER INDEX



Package Environment

Package Environment provides subprograms to initialize, finalize, and obtain status concerning the ASIS environment or the ASIS implementation.

For more information, click on a topic:


Resources in Package Environment

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

To see detailed referenced information, click on the name of a subprogram:
Determining ASIS vendor details and release levels:
Asis_Vendor Asis_Vendor_Version
Asis_Vendor_Information Asis_Version
Controlling the ASIS environment state:
Finalize
Initialize
Determining the ASIS environment state:
Is_Finalized
Is_Initialized
Determining or setting the ASIS error state:
Diagnosis Status
Set_Status
Determining how defaulted parameters are implemented:
Call_Parameters_Include_Defaults Discriminant_Associations_Include_Defaults Function_Call_Parameters_Include_Defaults Generic_Parameters_Include_Defaults

Determining how normalization of parameter lists is implemented:
Call_Parameters_Normalized Components_Normalized Discriminant_Associations_Normalized Function_Call_Parameters_Normalized Generic_Parameters_Normalized
Determining whether commentary and element line and column placement can be identified:
Is_Commentary_Supported Is_Line_Number_Supported Is_Span_Column_Position_Supported
Determining whether notation for prefix function calls can be identified:
Is_Prefix_Call_Supported

Determining whether compilation-unit attributes are supported:
Attributes_Are_Supported

Determining whether use of named parameters can be identified:
Is_Formal_Parameter_Named_Notation_Supported
Determining whether implicit use of the mode in can be
identified:

Default_In_Mode_Supported


Key Concepts for Package Environment

Package Environment provides access to Ada declarations and specifications. Processing is divided into the following categories. To see more information, click on a topic:

The subprograms in this package are typically called first and last in an ASIS application.

This package contains the only ASIS subprograms that can be called before initialization (or after finalization) of the ASIS
environment.

Determining ASIS Vendor Details and Release Levels

The Asis_Version function allows an application to determine the ASIS version level to which the implementation conforms. An ASIS application can use this information to support multiple ASIS implementation levels (although the standard is expected to remain stable at 1.1 for several years).

Several ASIS subprograms require vendor-specific parameters or return vendor-specific results. ASIS provides the Asis_Vendor function to determine which vendor's implementation is being used. This information can be used to determine how to construct the parameters for the Initialize and Finalize procedures and interpret the results of the Diagnosis function.

The Asis_Vendor_Version and Asis_Vendor_Information functions allow an application to obtain the implementing vendor's version number and other vendor-defined information.

Initializing and Terminating ASIS Processing

Before using most ASIS subprograms, the ASIS environment must be initialized. Before application termination, the ASIS environment should be terminated. ASIS provides subprograms to perform the initialization and termination and to determine whether the ASIS environment is currently initialized.

Controlling the ASIS Environment State

Package Environment provides the subprograms that perform the initialization and termination of ASIS processing. A typical application contains steps similar to the following:

Before calling subprograms in other ASIS packages, the ASIS environment must be initialized with the Initialize procedure. This allocates the resources and structures needed to support ASIS processing. Initialization can fail from a lack of resources (typically memory) or other reasons. Applications should anticipate failures and handle the exceptions that can be raised.

Note: ASIS applications can be executed only in an Apex shell. ASIS fails to initialize if the application is started elsewhere.

Before an application terminates, it should call the Finalize procedure to allow ASIS to release the resources obtained during the initialization and subsequent use of the ASIS interfaces. It is possible for Finalize to fail. Applications should anticipate failures and handle the exceptions that can be raised.

An application may initialize and finalize ASIS as many times as required. Repeated initialization and finalization of ASIS does not cause loss of memory (memory leakage) or of other resources.

Determining the ASIS Environment State

An application can determine if ASIS is initialized by calling the Is_Initialized or Is_Finalized function. Is_Initialized will be True after the successful execution of Initialize and before successful execution of Finalize. Is_Finalized returns True at all other times.

Determining or Setting the ASIS Error State

ASIS raises an exception when any error occurs. Errors can be caused by a lack of resources, incorrect calling sequences within the application program, incorrect parameter values, and many other reasons. The exceptions raised by ASIS are defined in package Asis.

An application can obtain more details about the cause of an exception by calling the Status function, which returns an Error_Kinds enumeration value. It is also possible to call the Diagnosis function to obtain vendor-specific text describing the error. The values returned by these functions do not change unless the application causes ASIS to raise another exception or calls the Set_Status procedure.

Your ASIS application can simulate an ASIS error by setting the error status and raising an appropriate exception. By calling Set_Status, your application can provide an error status and diagnosis text to ASIS. Calling Set_Status without parameters clears the current error status. These values are returned from ASIS by subsequent calls to Status or Diagnosis.

Determining the Capabilities of the ASIS
Implementation

Package Environment can be used to determine the capabilities of the ASIS implementation. This is important when writing a generalized ASIS application, where the presence or lack of a capability must be taken into account. For example, an ASIS implementation may not be able to return commentary that existed in the Ada source code; a tool constructed to determine whether an application is commented according to coding standards will always fail under such an ASIS implementation.

Because of variations in Ada library implementation, all ASIS implementations are not able to present an identical view of program elements. These variations impact (click on a topic for more information):

Default Parameter Processing

Because of variations in Ada library implementation, all ASIS implementations are not able to present an identical view of defaulted parameters. An ASIS implementation can choose to always include defaulted parameters or never include defaulted parameters when parameter lists are returned.

Defaulted parameters can appear in procedure, function, and entry calls, variable declarations, and in generic instantiations. Functions are available that return Boolean values indicating the implementation method for each of these cases (except for variable declarations):

For example, the Call_Parameters_Include_Defaults function returns the ASIS implementation method for handling defaulted parameters for subprograms and entries. The application would use this information when using the Statements.Call_Parameters function, which returns parameter lists for procedures and entries, or the Expressions.Function_Call_Parameters function, which returns parameter lists for function calls.

Consider the following procedure declaration:

Assume that the procedure is called as follows and ASIS is used to interpret this calling statement:

If Call_Parameters_Include_Defaults returns True, the parameter list returned by Statements.Call_Parameters includes an entry for Print_Header.

If Call_Parameters_Include_Defaults returns False, the parameter list reflects the actual code and does not include an entry for Print_Header.

The ordering of parameters and the relationship between defaults and normalized parameter lists is described in the section "Normalization of Parameter Lists."

Rational ASIS does not always include defaults in parameter lists.

Normalization of Parameter Lists

Because of variations in Ada library implementation, all ASIS implementations are not able to present an identical view of parameter lists with respect to the use of named associations. An ASIS implementation can choose to always return parameter lists in normalized format.

Normalized lists are artificial ASIS constructs that provide a single name-value pair per parameter. Each name-value pair consists of a formal parameter name (which can be obtained with Statements.Formal_Parameter) and an actual parameter (which can be obtained with Statements.Actual_Parameter). These artificial name-element associations return an Expressions.Is_Normalized value of True.

Normalized parameter lists always provide named associations.

Named associations can appear in procedure and entry calls, function calls, generic instantiations, type constraints, variable declarations, and aggregate values (for both arrays and records). Functions are available that return a Boolean value indicating the implementation method for each of these cases:

For example, the Call_Parameters_Normalized function returns the ASIS implementation's normalization method for procedure and entry calls. The application would use this information when using the Statements.Call_Parameters function, which returns parameter lists for procedure and entry calls.

Consider the following procedure declaration:

Assume that the procedure is called as follows and ASIS is used to interpret this calling statement:

If Call_Parameters_Normalized returns True, the parameter list returned by Statements.Call_Parameters will:

If Call_Parameters_Normalized returns False, the parameter list returned by Statements.Call_Parameters will:

Since normalized parameter lists include defaulted parameters when Call_Parameters_Normalized returns True, Call_Parameters_Include_Defaults also returns True.

Rational ASIS does not always normalize parameter lists.

Commentary, Line Numbering, and Element Span

Because of variations in Ada library implementation, all ASIS implementations are not able to present an identical view of line numbering, column positioning, and commentary.

If an Ada library does not retain source-code commentary, Is_Commentary_Supported will return False. In this case, calls to the Text.Comment_Image function will always return a Nil_Asis_String and calls to the Text.Image function will not include commentary.

If an Ada library does not retain line numbers for program elements, the Is_Line_Number_Supported function will return False. Calls to functions in package Text that return line numbers, lists of line numbers, or spans (a structure that includes the starting and ending line numbers and column positions) of elements return 0, Asis.Nil_Line_List, or Asis.Nil_Span.

An Ada library may support line numbers but may not support the column positions of program elements. In this case, Is_Span_Column_Position_Supported will return False. Calls to functions in package Text that return a span will return Asis.Nil_Span.


Miscellaneous Other Capabilities

Not all ASIS implementations support detection of prefix notation in function calls. In prefix notation, the function operator is specified before the parameter(s). The Is_Prefix_Call_Supported function can be used to determine whether the ASIS implementation can identify the use of prefix notation.

Not all ASIS implementations support compilation-unit attributes. Compilation-unit attributes are name-value pairs assigned to a unit. The Attributes_Are_Supported function can be used to determine whether the ASIS implementation supports compilation-unit attributes.

Not all ASIS implementations support detection of named notation in the source text. In named notation, the name of the formal parameter is included, along with its value in the call, aggregate, or declaration. Ada uses named notation in the following constructs:

The Is_Formal_Parameter_Named_Notation_Supported function can be used to determine whether the ASIS implementation can detect the use of named notation.

Not all ASIS implementations can identify implicit in modes for subprogram or entry parameter declarations. The Default_In-
_Mode_Supported
function can be used to determine if the ASIS implementation can identify implicit in parameters.


Function Asis_Vendor

Expanded Name Asis.Environment.Asis_Vendor

Returns the ASIS implementor's name in a vendor-defined format.

Description

The vendor name can be used to perform processing specific to a particular ASIS implementation. For example, the function Asis_Vendor_Information returns vendor-defined information. Asis_Vendor can be used to determine what this information is.

Parameters

Rational ASIS returns: "Rational, Santa Clara, Ca., USA"

Errors

None.

Examples

Cross-References

Related subprograms:

Related concept:


Function Asis_Vendor_Information

Expanded Name Asis.Environment.Asis_Vendor_Information

Returns vendor-specific information concerning the ASIS
implementation.

Description

The information and format are vendor-defined.

An application can call Asis_Vendor to determine the vendor information for the ASIS implementation.

Parameters

Rational ASIS returns: "Copyright (c) 1992, 1993"

Errors

None.

Examples

Cross-References

Related subprograms:

Related concept:


Function Asis_Vendor_Version

Expanded Name Asis.Environment.Asis_Vendor_Version

Returns the implementor's version number in a vendor-defined format.

Description

The version number is in a vendor-defined format.

The version number can be used to enable alternate processing for problems in a particular implementation of ASIS.

Parameters

Refer to the Rational ASIS release notes for the current version number for Rational ASIS.

Errors

None.

Examples

Cross-References

Related subprograms:

Related concept:


Function Asis_Version

Expanded Name Asis.Environment.Asis_Version

Returns the ASIS version number to which the implementation conforms.

Description

The version number returned is identical to the version number of the ASIS standard from which the implementation was derived.

The version number can be used to allow an application to operate correctly on several different releases of the ASIS standard.

Parameters

Rational ASIS returns: "1.1"

Errors

None.

Examples

Cross-References

Related subprograms:

Related concept:


Function Attributes_Are_Supported

Expanded Name Asis.Environment.Attributes_Are_Supported

Returns a Boolean value indicating whether the ASIS implementation supports compilation-unit attributes.

Description

Compilation-unit attributes are name-value pairs. The name may be a compilation switch or other indicator. The value represents the setting for the attribute.

Rational ASIS does not support compilation-unit attributes.

Parameters

Rational ASIS returns False.

Errors

None.

Examples

Cross-References

Related subprogram:

Related concept:


Function Call_Parameters_Include_Defaults

Expanded Name Asis.Environment.Call_Parameters_Include_Defaults

Returns a Boolean value indicating whether procedure and entry-call parameter lists always include defaulted parameters.

Description

ASIS implementations can choose to always include defaulted parameters in parameter lists.

If True is returned, parameter lists will always include defaults and the lists may contain expressions that are not in the actual text of the procedure or entry call.

Parameters

Rational ASIS returns False.

Errors

None.

Examples

Cross-References

Related subprogram:

Related concept:


Function Call_Parameters_Normalized

Expanded Name Asis.Environment.Call_Parameters_Normalized

Returns a Boolean value indicating whether the ASIS implementation always includes formal-parameter names and defaulted expressions in procedure and entry-call parameter lists.

Description

If True is returned, the Statements.Call_Parameters function will always behave as if its Normalized parameter is True. If False is returned, the ASIS application can control the Normalized parameter to the function.

Parameters

Rational ASIS returns False.

Errors

None.

Examples

Cross-References

Related subprogram:

Related concept:


Function Components_Normalized

Expanded Name Asis.Environment.Components_Normalized

Returns a Boolean value indicating whether the ASIS implementation always includes discriminant and component names and values in record-aggregate component lists.

Description

If True is returned, the Expressions.Components function will always behave as if its Normalized parameter is True. If False is returned, the ASIS application can control the Normalized parameter to the function.

Parameters

Rational ASIS returns False.

Errors

None.

Examples

Cross-References

Related subprogram:

Related concept:


Function Default_In_Mode_Supported

Expanded Name Asis.Environment.Default_In_Mode_Supported

Returns a Boolean value indicating whether the ASIS implementation can distinguish between implied in parameters and explicitly specified in mode parameters in subprogram, entry, and generic declarations.

Description

ASIS implementations may not be able to identify the implicit use of an in mode. For example:

In the above code, Text contains an implied in mode and Error contains an explicit in mode. If False is returned from Default-
_In_Mode_Supported, the ASIS implementation will indicate that Text has an implicit in mode.

Parameters

Rational ASIS returns True.

Errors

None.

Examples

Cross-References

Related subprogram:

Related concept:


Function Diagnosis

Expanded Name Asis.Environment.Diagnosis

Returns a string describing the most recent error.

Description

ASIS diagnosis values are vendor-dependent and vary between implementations.

If the error status is Not_An_Error, Asis.Nil_Asis_String will be returned.

An application may set the diagnosis value by calling Set_Status.

Parameters

Rational ASIS returns full sentences that describe the most recent error. The content of these messages may change over time.


Caution: Applications that depend on specific Diagnosis values will not be portable across ASIS implementations.


Errors

None.

Examples

Cross-References

Related subprograms:

Related concept:


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