![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
Function Discriminant_Associations_Include_Defaults
function Discriminant_Associations_Include_Defaults return Boolean;Expanded Name Asis.Environment.Discriminant_Associations_Include-
_DefaultsReturns a Boolean value indicating whether discriminant association lists include defaulted parameters.
Description
ASIS implementations can choose to always include defaulted parameters in discriminant lists.
If True is returned, discriminant lists will always include defaults and the lists may contain expressions that are not in the actual variable declaration or constraint.
Parameters
return Boolean;Errors
Examples
type Text (Length : Natural := 80) is record Text : String (1 .. Length); end record;Normal : Text;Jumbo : Text (500);The definition of Normal allows the discriminant Length to take on its default value. If Discriminant_Associations_Include-
_Defaults returns True, the discriminant list for Normal will include Length. If False is returned, the ASIS application can control the Normalized parameter to the Type_Definitions.Discriminant_Associations function.Cross-References
Function Discriminant_Associations_Normalized
function Discriminant_Associations_Normalized return Boolean;Expanded Name Asis.Environment.Discriminant_Associations_Normalized
Returns a Boolean value indicating whether the ASIS implementation always includes formal-parameter names and defaulted expressions in discriminant parameter lists.
Description
If True is returned, the Type_Definitions.Discriminant_Associations 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
Type Error_Kinds
type Error_Kinds is (...);Expanded Name Asis.Environment.Error_Kinds
Describes the kinds of errors that can be returned by Status.
Enumerations
Capacity_ErrorASIS has reached some internal or system-imposed capacity limit.
Data_ErrorA library or some other file is damaged.
Environment_ErrorA call to Initialize, Finalize, Libraries.Associate, or Libraries-
.Open was made with an invalid parameter value.
Initialization_ErrorAn ASIS subprogram was called before ASIS was initialized.
Internal_ErrorAn internal error has been detected in ASIS internal processing and should be reported to the vendor.
Name_ErrorA library or some other file could not be opened. The Name parameter in Libraries.Open may not have contained sufficient information to open the library.
Not_An_ErrorNo error has been recorded or the last error has been cleared.
Not_Implemented_ErrorThe subprogram or option is not implemented. Refer to the Rational ASIS release notes for a summary of subprogram and options not yet available.
Obsolete_Reference_ErrorAn attempt to use information stored in a unit or an element failed because the semantic information is obsolete.
Parameter_ErrorAn invalid Parameter string value was provided to the Initialize procedure.
Storage_ErrorASIS has reached a system-imposed limit on storage capacity. ASIS has caught the exception and recovered to the extent possible. The requested operation did not complete but ASIS use may continue.
Unhandled_Exception_ErrorAn unexpected exception was raised during ASIS processing. It has been caught and converted to this error. This indicates an ASIS internal error and should be reported to the vendor.
Use_ErrorA library or some other file could not be opened. The named library, named compilation unit, or some other library component cannot be accessed.
Value_ErrorAn argument to an ASIS subprogram was inappropriate, uninitialized, or otherwise invalid.
Cross-References
- function Finalize
- function Initialize
- procedure Set_Status
- function Status
- procedure Libraries.Associate
- procedure Libraries.Open
Procedure Finalize
procedure Finalize (Parameters : in Asis.Asis_String := Asis.Nil_Asis_String);Expanded Name Asis.Environment.Finalize
Performs any necessary ASIS termination activities; should be the last ASIS procedure called by an application.
Description
Performs any necessary ASIS termination activities. The Finalize procedure releases all ASIS resources and closes all open libraries. Use of elements (see package Elements, "Element Kinds and Properties," for more information) or other resources after Finalize has been called is erroneous. ASIS attempts to detect such usage and to raise Asis_Failed. This cannot be guaranteed, however, and unpredictable application behavior may result.
Finalize should be the last ASIS procedure called by an application. The call does not produce an error if ASIS is not currently initialized. Calls to ASIS subprograms, other than those in package Environment, after calls to Finalize are erroneous.
If an ASIS application aborts, the operating system closes all open libraries and releases all memory allocated to ASIS.
Parameters
Parameters : in Asis.Asis_String := Asis.Nil_Asis_String;Specifies any vendor-specific parameters needed to finalize the ASIS environment.
Rational ASIS does not define any parameters and raises Asis-
_Failed if Asis.Nil_Asis_String is not passed.Errors
Asis_Failed is raised if the ASIS environment fails to finalize or if Parameters is not Asis.Nil_Asis_String. The Status will be Internal_Error or Parameter_Error.
Examples
Cross-References
Function Function_Call_Parameters_Include_Defaults
function Function_Call_Parameters_Include_Defaults return Boolean;Expanded Name Asis.Environment.Function_Call_Parameters_Include-
_DefaultsReturns a Boolean value indicating whether function-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 list may contain expressions that are not in the actual text of the function call.
Parameters
return Boolean;Errors
Examples
Cross-References
Function Function_Call_Parameters_Normalized
function Function_Call_Parameters_Normalized return Boolean;Expanded Name Asis.Environment.Function_Call_Parameters_Normalized
Returns a Boolean value indicating whether the ASIS implementation always includes formal-parameter names and defaulted expressions in function-call parameter lists.
Description
If True is returned, the Expressions.Function_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.
Parameters
return Boolean;Errors
Examples
Cross-References
Function Generic_Parameters_Include_Defaults
function Generic_Parameters_Include_Defaults return Boolean;Expanded Name Asis.Environment.Generic_Parameters_Include_Defaults
Returns a Boolean value indicating whether generic-instantiation parameter lists always include defaulted parameters.
Description
ASIS implementation can choose to always include defaulted parameters in generic-instantiation parameter lists.
If True is returned, parameter lists will always include defaults and the lists may contain expressions that are not in the actual generic instantiation.
Parameters
return Boolean;Errors
Examples
Cross-References
Function Generic_Parameters_Normalized
function Generic_Parameters_Normalized return Boolean;Expanded Name Asis.Environment.Generic_Parameters_Normalized
Returns a Boolean value indicating whether the ASIS implementation always includes formal-parameter names and defaulted expressions in generic-instantiation parameter lists.
Description
If True is returned, the Declarations.Generic_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
Procedure Initialize
procedure Initialize (Parameters : in Asis.Asis_String := Asis.Nil_Asis_String);Expanded Name Asis.Environment.Initialize
Initializes the ASIS environment.
Description
Initialize must be called before the use of any subprogram except those in package Environment and Portable_Transfer. It typically is the first ASIS procedure to be called.
If ASIS has already been initialized, the call has no effect and does not produce an error.
The Parameters string can be used to specify implementation-defined processing options as described in the Parameters section.
Note: ASIS applications can only be executed in an Apex shell. ASIS fails to initialize if the application is started elsewhere.
Caution: ASIS is not tasking safe. An application must not call ASIS subprograms concurrently.
Processing Nonterminal Symbols
Rational Apex allows nonterminals, or prompts, to appear in compilation units. For example, [statement] might appear in a unit where a statement is required. These nonterminals represent incomplete implementations and are normally present during iterative development.
You control whether nonterminals represent valid elements with the Enable_Nonterminals keyword.
If Enable_Nonterminals is False:
- Nonterminals found in a compilation unit are ignored by the Elements.Traverse_Element generic. They are not visited during preoperation ( thus not visited during postoperation).
- Other subprograms raise Asis_Failed with an Environment.Status of Obsolete_Reference_Error if they are required to return a nonterminal. For example, given the following declaration:
A : Integer := [expression];
The Declarations.Initial_Value function results in Asis_Failed; other Asis functions appropriate for the declaration work normally.
If Enable_Nonterminals is specified as True, nonterminals are treated as if they represented a normal element:
- They are returned by the Elements.Traverse_Element_Generic
- They can be returned by most functions that return elements
- Can be passed to any Boolean function or function that returns a kind
- Have an Elements.Enclosing_Element
- Have a Compilation_Unit.Enclosing_Compilation_Unit
You can identify an element that represents a nonterminal with the following code fragment:
if not Asis.Elements.Is_Nil (Element) and then Asis.Elements.Element_Kind (Element) = Not_An_Element then <Element is a nonterminal> end if;(continued) Procedure Initialize
Parameters
Parameters : in Asis.Asis_String := Asis.Nil_Asis_String;Specifies vendor-specific parameters that must be provided to initialize the ASIS environment. In Rational ASIS, the parameters string specifies:
- The maximum number of file descriptors that should be used when working with Text.Lines values
- Whether nonterminal symbols appearing in compilation units should be treated as valid elements
These values are specified with keywords. The possible keywords, their purposes, and their default values are:
Keyword Purpose
Maximum_Asis_Text_Files Specifies the maximum number of file descriptors that Rational ASIS can use when working with Asis.Lines values. If you specify a value that is too large, Asis_Failed can be raised with a Status of Capacity_Error when subprograms in package Text are called. If you specify a value that is too small, your application will run slowly as files are opened and closed so as not to exceed the specified limit. The default value is 4.
Enable_Nonterminals Specifies whether nonterminals appearing in compilation units should be treated as valid elements. If False is specified, references to nonterminals cause Asis_Failed to be raised with a Status of Obsolete_reference_Error. If True is specified, nonterminals are treated as they where any other element. See "Processing Nonterminal Symbols" for more information. The default value is 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
Errors
Asis_Failed is raised and Status will be Environment_Error or Parameter_Error if the ASIS environment fails to initialize or if Parameters contains an invalid keyword or value.
Examples
Cross-References
- "Controlling the ASIS Environment State"
- "Determining the ASIS Environment State"
- package Text, "File Descriptors"
Function Is_Commentary_Supported
function Is_Commentary_Supported return Boolean;Expanded Name Asis.Environment.Is_Commentary_Supported
Returns a Boolean value indicating whether the ASIS implementation can return comments.
Description
If True is returned, the ASIS implementation can return comments. If False is returned, the Text.Comment_Image function will always return Asis.Nil_Asis_String and the Text.Image function will not include any comment text.
Parameters
return Boolean;Errors
Examples
Cross-References
Function Is_Finalized
function Is_Finalized return Boolean;Expanded Name Asis.Environment.Is_Finalized
Returns a Boolean value indicating whether the ASIS environment is finalized or has not been initialized.
Description
The ASIS environment is finalized before Initialize is called and after a call to Finalize.
Parameters
return Boolean;If True is returned, the ASIS environment has not been initialized or has been finalized.
Errors
Examples
Cross-References
Function Is_Formal_Parameter_Named-
_Notation_Supported
function Is_Formal_Parameter_Named_Notation_Supported return Boolean;Expanded Name Asis.Environment.Is_Formal_Parameter_Named-
_Notation_SupportedReturns a Boolean value indicating whether the ASIS implementation can identify the use of named notation.
Description
If True is returned, the ASIS implementations can identify the use of named notation. In named notation, the name of the formal parameter, component, or discriminant is included with the value. 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)
If False is returned, the implementation cannot identify use of named notation and will always return parameter lists using either named (normalized) or positional notation. In this case, the Statements.Formal_Parameter function always returns Asis.Nil_Element unless the parameter list was obtained with Normalized set to True.
Parameters
return Boolean;Errors
Examples
Cross-References
- function Declarations.Generic_Parameters
- function Expressions.Components
- function Expressions.Function_Call_Parameters
- function Statements.Formal_Parameter
- function Type_Definitions.Discriminant_Associations
- "Miscellaneous Other Capabilities"
- Ada83 LRM 3.7.2, Ada95 LRM
3.7.1- Ada83 LRM 4.3, Ada95 LRM
4.3- Ada83 LRM 6.4, Ada95 LRM
6.4- Ada83 LRM 6.4.1, Ada95 LRM 6.4.1
- Ada83 LRM 12.3, Ada95 LRM
12.3
Function Is_Initialized
function Is_Initialized return Boolean;Expanded Name Asis.Environment.Is_Initialized
Returns a Boolean value indicating whether the ASIS environment is currently initialized.
Description
If True is returned, the ASIS environment is currently initialized.
If calls to subprograms in packages other than Environment are made when ASIS is not initialized, ASIS raises Asis_Failed and sets Status to Initialization_Error.
Parameters
return Boolean;If True is returned, the ASIS environment is currently initialized.
Errors
Examples
Cross-References
Function Is_Line_Number_Supported
function Is_Line_Number_Supported return Boolean;Expanded Name Asis.Environment.Is_Line_Number_Supported
Returns a Boolean value indicating whether the ASIS implementation supports the retrieval of source-code line numbers for program elements.
Description
If True is returned, the ASIS implementation can retrieve the line numbers where program elements appeared in the source file. If False is returned, the functions in package Text that return Line_Numbers, Line_Lists, or Spans will always return 0, Asis.Nil_Line_List, or Asis.Nil_Span.
Parameters
return Boolean;Errors
Examples
Cross-References
- function Text.Compilation_Span
- function Text.Compilation_Unit_Span
- function Text.Element_Span
- function Text.First_Line_Number
- function Text.Last_Line_Number
Function Is_Prefix_Call_Supported
function Is_Prefix_Call_Supported return Boolean;Expanded Name Asis.Environment.Is_Prefix_Call_Supported
Returns a Boolean value indicating whether the ASIS implementation can identify the use of prefix notation for function calls.
Description
If True is returned, the ASIS implementation can identify function calls that used prefix notation (as opposed to infix notation). If False is returned, the function Expressions.Is_Prefix_Call will always return False.
A := B + C;X := "+"(Y, Z);The addition of B and C uses infix notation and will never be reported as prefix notation.
The addition of Y and Z uses prefix notation. If False is returned from Is_Prefix_Call_Supported, ASIS reports this as infix notation; otherwise, ASIS reports it as prefix notation.
Parameters
return Boolean;Errors
Examples
Cross-References
Function Is_Span_Column_Position_Supported
function Is_Span_Column_Position_Supported return Boolean;Expanded Name Asis.Environment.Is_Span_Column_Position_Supported
Returns a Boolean value indicating whether the ASIS implementation can provide column locations for program elements.
Description
If True is returned, the ASIS implementation can return valid column positions for program elements. If False is returned, the functions in package Text that return a Span return Asis.Nil-
_Span. This function always returns False if Is_Line_Number_Supported returns False.Parameters
return Boolean;Errors
Examples
Cross-References
Function Minimal_Inconsistent_Units
function Minimal_Inconsistent_Units return Boolean;Expanded Name Asis.Environment.Minimal_Inconsistent_Units
Returns a Boolean value indicating whether the ASIS implementation returns unit relationships in minimal form.
Description
If True is returned, a Compilation_Units.Relationship contains a minimal set of relationships.
If False is returned, a Relationship is returned as a maximal set of relationships.
See package Compilation_Units, "The Inconsistent Units List," for a description of the minimal and maximal organizations of the inconsistent-units list.
Parameters
return Boolean;Errors
Examples
Cross-References
Related subprograms and types:
- function Compilation_Units.Compilation_Order
- function Compilation_Units.Elaboration_Order
- function Compilation_Units.Recompilation_Order
- function Compilation_Units.Related_Compilation_Units
- type Compilation_Units.Relation_Kinds
Procedure Set_Status
procedure Set_Status (Status : Error_Kinds := Not_An_Error; Diagnosis : Asis.Asis_String := Asis.Nil_Asis_String);Expanded Name Asis.Environment.Set_Status
Allows an application to set the current ASIS status value and diagnosis text.
Description
The default status and diagnosis values, or values provided by the user, are saved by ASIS and overwrite any existing values. These values are returned by subsequent calls to the Status or Diagnosis functions until ASIS raises an exception, which provides new values, or another call is made to Set_Status.
If Status is set to Not_An_Error and Diagnosis is not Asis.Nil_Asis_String, Asis_Failed is raised and the status will be set to Internal_Error.
This procedure sets the status but does not normally raise an exception. If your application is using Set_Status as a means of passing status, it should typically raise an exception after making the call. Alternatively, Set_Status can be used to clear the current error status.
Parameters
Status : Error_Kinds := Not_An_Error;Specifies the Error_Kinds that should be returned when the Status function is called.
If Status is being set to Not_An_Error, Diagnosis must be set to Asis.Nil_Asis_String.
Diagnosis : Asis.Asis_String := Asis.Nil_Asis_String;Specifies the text that should be returned when the Diagnosis function is called. In Rational ASIS there is no limit (other than heap memory size) on the size of the diagnosis text.
Errors
Asis_Failed is raised with a status of Internal_Error and a
diagnosis of Asis.Nil_Asis_String if the Status parameter is set
to Not_An_Error and the Diagnosis parameter is not
Nil_Asis_String.Examples
Cross-References
Function Status
function Status return Error_Kinds;Expanded Name Asis.Environment.Status
Returns an Error_Kinds indicating the last ASIS error.
Description
Returns an indication of the last ASIS error. ASIS errors are the result of invalid parameter values, capacity limitations, internal errors, or other causes.
When ASIS detects an error, two things occur in sequence: the error condition is saved both as an Error_Kinds and an Asis-
_String, and then an exception is raised.An application may set Status by calling Set_Status.
Parameters
return Error_Kinds;Returns an indication of the last ASIS error.
Examples
Cross-References
Related subprograms and types:
Package Operations
package Operations is -- For Error_Kinds function "=" (Left, Right : ...end Operations;Expanded Name Asis.Environment.Operations
Package Operations provides a simple way to obtain visibility to operators for types used in package Environment. The package typically is referenced in a use clause by an application.
Cross-References
Rational Software Corporation
http://www.rational.com support@rational.com techpubs@rational.com Copyright © 1993-2001, Rational Software Corporation. All rights reserved. |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |