![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
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 EnvironmentThe 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 EnvironmentPackage Environment provides access to Ada declarations and specifications. Processing is divided into the following categories. To see more information, click on a topic:
- "Determining ASIS Vendor Details and Release Levels"
- "Initializing and Terminating ASIS Processing"
- "Determining or Setting the ASIS Error State"
- "Determining the Capabilities of the ASIS Implementation"
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:
Asis.Environment.Initialize;-- Use of various ASIS facilities.Asis.Environment.Finalize;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
ImplementationPackage 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"
- "Normalization of Parameter Lists"
- "Commentary, Line Numbering, and Element Span"
- "Miscellaneous Other Capabilities," including:
- Function-call notation
- Identification of named-parameter usage
- Identification of implicit in modes on parameters in subprogram, entry, and generic formal parameter
declarationsDefault 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):
- Call_Parameters_Include_Defaults
- Discriminant_Associations_Include_Defaults
- Function_Call_Parameters_Include_Defaults
- Generic_Parameters_Include_Defaults
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:
procedure Print_File (File : String; Print_Header : Boolean := True; Print_Trailer : Boolean := False);Assume that the procedure is called as follows and ASIS is used to interpret this calling statement:
Print_File ("compile.log", Print_Trailer => True);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:
- Call_Parameters_Normalized
- Components_Normalized
- Discriminant_Associations_Normalized
- Function_Call_Parameters_Normalized
- Generic_Parameters_Normalized
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:
procedure Print_File (File : String; Print_Header : Boolean := True; Print_Trailer : Boolean := False);Assume that the procedure is called as follows and ASIS is used to interpret this calling statement:
Print_File ("compile.log", Print_Trailer => True);If Call_Parameters_Normalized returns True, the parameter list returned by Statements.Call_Parameters will:
- Include an entry for each defaulted parameter (such as Print_Header)
- Be ordered as in the declaration of Print_File
- Include the formal parameter name for each parameter
If Call_Parameters_Normalized returns False, the parameter list returned by Statements.Call_Parameters will:
- Not include any defaulted parameters (such as Print_Header)
- Be ordered as in the call to Print_File
- Include only the formal-parameter names included in the source code
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 CapabilitiesNot 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:
- Component associations (Ada83 LRM 4.3, Ada95 LRM 4.3)
- Discriminant associations (Ada83 LRM 3.7.2, Ada95 LRM 3.7.1)
- Generic associations (Ada83 LRM 12.3, Ada95 LRM 12.3)
- Parameter associations (Ada83 LRM 6.4, 6.4.1, Ada95 LRM 6.4, 6.4.1)
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
function Asis_Vendor return Asis.Asis_String;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
return Asis.Asis_String;Rational ASIS returns: "Rational, Santa Clara, Ca., USA"
Errors
Examples
Cross-References
Function Asis_Vendor_Information
function Asis_Vendor_Information return Asis.Asis_String;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
return Asis.Asis_String;Rational ASIS returns: "Copyright (c) 1992, 1993"
Errors
Examples
Cross-References
Function Asis_Vendor_Version
function Asis_Vendor_Version return Asis.Asis_String;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
return Asis.Asis_String;Refer to the Rational ASIS release notes for the current version number for Rational ASIS.
Errors
Examples
Cross-References
Function Asis_Version
function Asis_Version return Asis.Asis_String;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
return Asis.Asis_String;Errors
Examples
Cross-References
Function Attributes_Are_Supported
function Attributes_Are_Supported return Boolean;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
return Boolean;Errors
Examples
Cross-References
Function Call_Parameters_Include_Defaults
function Call_Parameters_Include_Defaults return Boolean;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
return Boolean;Errors
Examples
Cross-References
Function Call_Parameters_Normalized
function Call_Parameters_Normalized return Boolean;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
return Boolean;Errors
Examples
Cross-References
Function Components_Normalized
function Components_Normalized return Boolean;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
return Boolean;Errors
Examples
Cross-References
Function Default_In_Mode_Supported
function Default_In_Mode_Supported return Boolean;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:
procedure Put_Error(Text : String; Error : in Boolean);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
return Boolean;Errors
Examples
Cross-References
Function Diagnosis
function Diagnosis return Asis.Asis_String;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
return Asis.Asis_String;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
Examples
Cross-References
Rational Software Corporation
http://www.rational.com support@rational.com techpubs@rational.com Copyright © 1993-2001, Rational Software Corporation. All rights reserved. |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |