Updated Status Vector - Functional Specification
Description
The InterBase status vector is a mechanism which allows information about the current operation to pass throughout the engine and client. The information in the status vector usually consists of error messages, but in InterBase 6.0, it may also contain warnings and informational messages.
One limitation of the current status vector is that the error codes that are returned by it are only useful if they are located in the SYSTEM_ERROR messages facility. All of the message interpretation functions are coded to only look at the SYSTEM_ERROR message facility.
Another limitation of the current status vector with respect to messaging is that there is no way, based on an error code, to determine the error's severity and / or facility. This new specification will attempt to solve both problems.
In addition to being able to determine the facility and severity of an error, it is useful for the server to report a warning to the Client. A warning does not impede normal client/server operations, but may advise the client of a problem that needs investigation.
The SQL specification points out several instances where warnings are to be issued.
DELETE FROM tab WHERE 1 = 0;
This delete statement affects no rows. SQL specifies that a "Completion Condition" be reported back to the SQL Client. Completion conditions are not an indication of any error - but does indicate that the user may have issued the wrong query.
User interface/Usability
This feature will be available to all API calls that make use of a status vector for reporting information. This new functionality should be invisible to the end user since most status vector interpretation is done by the client (or server).
The typical use of the status vector is:
if (isc_api_call (status_vector, param1, param2))
{
isc_print_status (status_vector);
exit (1);
}
The 'error' codes returned by the V6 status vector will contain three elements:
- The error code (warning message, information)
- The type of message (error, warning, information)
- The facility in which the message was generated and can be found
This error code will be interpreted by isc_interprete to determine the facility for the code and pass this information onto isc_msg_format so that the correct information can be retrieved. The function isc_decode would now provide the information on the facility being used as well the error number.
In detail, all InterBase Server API functions return error information in a Status Vector which is defined as:
typedef ULONG ISC_STATUS;
#define ISC_STATUS_LENGTH 20
ISC_STATUS status_vector[ISC_STATUS_LENGTH];
where ISC_STATUS_LENGTH is currently set to 20.
When an error is returned, a status vector is formatted as follows:
isc_arg_gds isc_arith_except isc_arg_end ?
With no error (the normal case) a status vector appears as:
isc_arg_gds 0 isc_arg_end ?
Application programs typically check for no errors by examining the 2nd element of the status vector. A zero entry indicates no error. GPRE itself generates code with this assumption.
Additionally, all API calls return 0 if no error, and return an error code identical to the 2nd element of the status vector if there is an error.
With InterBase warnings, a warning code is emitted after the last isc_arg_gds code clump in a status vector, and before the isc_arg_end.
In the case of an error with a warning, the status vector would appear as:
isc_arg_gds isc_arith_except isc_arg_warning isc_no_rows_affected isc_arg_end ?
With no errors, and one warning, a status vector appears as:
isc_arg_gds 0 isc_arg_warning isc_no_rows_affected isc_arg_end ?
If multiple warnings occur as part of a statement, the warnings are sequential (identical to how errors are stacked inside a status vector):
isc_arg_gds 0 isc_arg_warning isc_no_rows_affected isc_arg_warning isc_random isc_arg_string "Danger Will Robinson" isc_arg_end ?
Warning messages can thus have parameterized inserts, as do error messages.
API calls that result in a warning, but no errors, return 0. The return code from an API call indicates if an ERROR occurred only.
Interface Changes
GPRE:
None. When an SQLCODE is constructed it ignores warning messages.
ISQL:
New command line parameter -no_warnings;
The default for ISQL will display any warning messages returned in a status vector, even if no error occurred during the statement. If -no_warnings is specified on the command line when starting ISQl, then warnings will be displayed only if an error also occurred in the statement.
Usage of Warnings:
Warnings can be issued for the following conditions (this feature will concentrate on the infrastructure and not on where to put warnings):
SQL Statement with no effect (DELETE or UPDATE of an empty set of rows)
Usage of SQL expressions that results in different data manipulation semantics in V5 vs V6. In InterBase V5 the statement:
SELECT 4 / 3 FROM tab;
returns 1.333333333 (a floating point number). In InterBase V6, with SQL Dialect 2 or 3, the ISO SQL specification semantics for division are enforced. The calculation (4 / 3) is performed using Integer division, resulting in a return value of 1 (an INTEGER). Similar constructs occur for AVG() & TIMESTAMP arithmetic.
- API calls which will be replaced in future versions of the product. For example, the API calls for modifying the security database will be slowly phased out in favor of the services on the server since they are easier to use and more robust. API calls which meet this criteria will return the warning:
isc_api_call_deprecated -> This API call is no longer supported and will be removed in a future version of the product. Use %s instead.
When a database shutdown is pending, all API calls should return a warning.
Requirements and Constraints
General InterBase requirements apply.
The addition of the new information to the status vector should not, in anyway, change the existing functionality or existing error codes. If any of the existing error codes were to change, older clients would not be able to interpret information from an InterBase V6.0 server.
The purpose of this project is not to introduce warnings into existing areas of the engine. This project will focus only on the infrastructure needed to add warning information to the status vector so that it may be interpreted by a client application.
Migration Issues
None. Warning information should not be passed to pre InterBase V6.0 clients connecting to the server.
Future Usage
In a future release of InterBase, the warning mechanism can be used in additional constructs.
For instance, in the Procedure / Trigger language, we can trap for warnings with an "ON WARNING W" construct, similar to the existing traps for SQLCODE or GDS_CODE.
In Embedded SQL, constructs such as SQLWARNING are defined by the SQL specification. This technology provides the basis for a future implementation of SQLWARNING or SQLERROR.
If a warning is surfaced via a statement in a stored procedure, they will be stored in the status vector until the stored procedure is finished and the status vector is printed. For InterBase V6.0, there will be no provision for storing line and/or statement information pertaining to the warning.
Reference Documents
ANSI SQL 3 Draft Specification, Oct 1997. (Note: DATE & TIME support was finalized in SQL 92, the SQL 3 specification introduces some clarifications).
ANSI SQL 3: Part 3 Call-Level Interface (SQL/CLI)