TOC PREV NEXT INDEX DOC LIST MASTER INDEX



Error Processing


General Error Processing

This chapter discusses the ASIS approach to error handling.

ASIS reports all operational errors by raising an exception.

Before an ASIS implementation raises one of the exceptions declared in package Asis.Exceptions, it sets these values to indicate the cause of the error:

The Status and Diagnosis values can be retrieved with Environment.Status and Environment.Diagnosis.

ASIS applications are encouraged to follow this same convention whenever they explicitly raise any ASIS exception, that is, they always record a Status and Diagnosis before raising the exception. Use Environment.Set_Status to set both values.

Whenever an exception is raised, the resulting Status will not be Not_An_Error. The possible values for Status are shown in Table 4 along with the associated contents of the Diagnosis string.

Note: Each ASIS implementation provides its own values for Diagnosis —— either Nil_Asis_String or some arbitrary text description of the error.

The following table shows Diagnosis information that might be provided by the vendor if Nil_Asis_String is not returned.

Table 4 ASIS Status Values, Meanings, and Diagnosis Values1

Status Value


Meaning

Diagnosis Value If Not
Nil_Asis_String

Not_An_Error2
No error has been recorded, or the last error has been reset.
Always Nil_Asis_String.
Value_Error3
Programmer error —— e.g., an argument to an ASIS routine is inappropriate, uninitialized, or otherwise invalid, such as use of a Nil_Element value in a structural query, of a library that is not open, of an invalid Element_Unit, etc. See Parameter_Error for specific interfaces that do not use this error.
Indicates the type of the argument, the name of the ASIS routine, and the nature of the error —— e.g., ``String_Name: Not an identifier.''
Parameter_Error
Application error. A call was made to Environment.Initialize or Finalize or to Libraries.Associate or Open with an invalid Parameters argument.
Indicates a specific problem —— e.g., "Argument is empty," "Argument is not empty."
Initialization_Error
Environment.Initialize has not been called.
Indicates whether the environment has never been initialized or has been finalized and needs reinitialization.
Environment_Error
Environment.Initialize failed to complete.
Indicates a specific problem —— e.g., "Product not licensed," "Insufficient memory available."
Capacity_Error
The ASIS implementation has reached some internal or system-imposed capacity limit.
Indicates what sort of capacity limit has been reached and a possible workaround —— e.g., "Too many libraries in use," "Too many open files."
Name_Error
A program library, or some other file-system object, could not be found. The Name parameter for a library might not directly designate something that an implementation regards as a program library component.
Indicates a specific problem —— e.g., "Name does not correspond to any existing object," "Name is not the name of a library file," "Name is not the name of an Ada librarian directory or object."
Use_Error
A program library, or some other file-system object, could not be opened. The named program library, named Ada compilation unit, or some other required library component cannot be used for some reason.
Indicates a specific problem —— e.g., "Library is protected," "Library is locked," "Library is off-line," "Library is not of the correct sort."
Data_Error
A program library, or some other file-system object, is damaged. Some library (component) was involved in an ASIS operation. It may or may not have been an explicit argument in a routine call (all elements have an Enclosing_Compilation_Unit,all compilation units have an Enclosing_Library, and libraries are implicit arguments to any ASIS function that takes an element or compilation-unit argument).
Indicates what library, compilation unit, or other implementation object is damaged and the nature of the damage.
Storage_Error
Storage_Error was raised and has been caught by the ASIS implementation; the requested operation did not complete, the ASIS implementation has recovered to the extent possible, and it is ready to attempt to continue.
Indicates the nature of the storage that was being allocated —— e.g., ran out of space while allocating Id file buffers.
Obsolete_Reference_Error
An attempt to utilize some piece of semantic information stored in a compilation unit and/or an element failed because the semantic information is obsolete. This may occur while traversing ineligible units or as the result of simultaneous library updates rendering current ASIS compilation units and elements obsolete.
Indicates the unit that contains the element with the obsolete reference.
Unhandled_Exception_Error
An unexpected exception was caught and suppressed by the ASIS implementation; this may indicate an error in the implementation.
Indicates the name of the unhandled exception and the name of the ASIS routine that suppressed it.
Not_Implemented-
_Error

Some portion of the ASIS specification has not been implemented.
Indicates the name, or a description, of the unimplemented functionality.
Internal_Error
No other, more specific error has occurred. An error may have occurred within the implementation or within the application, may indicate some form of bad data within a library, or may be the result of some sort of hardware failure.
Provides as much information as possible to aid debugging and end-user recovery and problem reporting.
1 All are associated with Asis_Failed except as noted.

2 Returned only when no exception has been raised or after the status has been cleared with Environment.Set_Status.

3 Can be used with any exception.


Exceptions in ASIS

All ASIS subprograms catch, handle, and recover from all exceptions (with a when others => exception handler) and do one of the following:

This attempts to ensure that the only exceptions propagated from an ASIS subprogram to a user's application are ASIS exceptions. There are at least the following cases where an ASIS implementation may not be able to prevent the raising or propagation of a non-ASIS exception:

I/O Exceptions

The I/O interfaces, exported by the Asis.Ids package, are expected to raise the various predefined Ada I/O exceptions when appropriate —— for example, Io_Exceptions.Use_Error.

Exceptions from Enumeration Functions

ASIS functions that return enumeration values raise only these exceptions and no others:

This prevents simple queries that ask for the kind of an element or ask if an element is of a certain variety from raising an exception simply because the argument is not of some constrained kind. These functions have no inappropriate argument kinds.

Unimplemented ASIS Features

The ASIS standard does not require that all vendors implement all features of ASIS. Hence, it is possible for your application to invoke an unimplemented ASIS feature. When this occurs, Asis_Failed is raised, Status is set to Not_Implemented_Error, and Diagnosis is also set. The minimal Diagnosis is Nil_Asis_String. Some implementations might provide a Diagnosis value that includes a description or name for the unimplemented functionality.

Exceptions Raised by ASIS

The following exceptions can be raised by ASIS:

Each is described below.

Asis_Failed

Raised by any ASIS routine that cannot complete its operation normally. This exception typically indicates a failure of, or a programmer error in, the ASIS implementation.

This is a catch-all exception that may be raised for different reasons in different ASIS implementations.

When Asis_Failed is raised, the implementation should provide at a minimum a Status of Internal_Error and a Diagnosis of Nil_Asis_String.

Asis_Inappropriate_Compilation_Unit

Raised when ASIS is passed a compilation unit that is invalid or inappropriate. This exception typically indicates that a programmer error has occurred in the application.

Reasons include:

Asis_Inappropriate_Element

Raised when ASIS is given an element that is invalid or inappropriate. This exception typically indicates that a programmer error has occurred in the application.

Reasons include:

Asis_Inappropriate_Library

Raised when ASIS is passed a library that is inappropriate for the operation. This exception typically indicates that a programmer error has occurred in the application.

Reasons include:

Asis_Inappropriate_Line

Raised when ASIS is given a line that is invalid or inappropriate.

Reasons include:

Asis_Inappropriate_Line_Number

Raised when ASIS is given a Line_Number value that is not appropriate. This exception typically indicates that a programmer error has occurred in the application.

Reasons include:


Rational Software Corporation 
http://www.rational.com
support@rational.com
techpubs@rational.com
Copyright © 1993-2002, Rational Software Corporation. All rights reserved.
TOC PREV NEXT INDEX DOC LIST MASTER INDEX TECHNOTES APEX TIPS