db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Daniel John Debrunner <...@apache.org>
Subject Re: DERBY-1566: "SQL error messages and exceptions" doc
Date Wed, 30 Aug 2006 23:41:59 GMT
Jean T. Anderson wrote:

> A lot changed between 10.1.3 and 10.2.1.1. Six sqlstates dropped out,
> 170 were added, and the current doc file for the Reference Guide isn't
> up to date.
> 
> Adding all the sqlstates in manually would be an effort for which I
> don't believe we have time and it would be error prone. This is where
> David's app comes into play that generates a new doc based on info
> retrieved with the org.apache.derby.diag.ErrorMessages() vti.
> 
> Here's the current 10.1 doc:
> http://db.apache.org/derby/docs/10.1/ref/rrefexcept71493.html
> 
> Here's the 10.2 draft (uploaded to DERBY-1566):
> https://issues.apache.org/jira/secure/attachment/12339910/rrefexcept-2.html
> 
> I believe the 10.2 draft is a good candidate that accurately reflects
> reality -- 849 entries made it into the new dita file, which matches the
> number of rows returned by the vti query ... always a good sign. :-)
> 
> But I'll point out two differences between the 10.1 and 10.2 docs:
> 
> 1) 10.2 severity column. I bet there's a story why that column didn't
> make it into 10.1, but I sure don't remember. Anyone should feel free to
> provide that info. If people don't like it for whatever reason, I can
> easily remove it.

The severity by definition (SQLException.getErrorCode) is a non-standard
piece of Derby. I prefer not to document these values since it might
encourage JDBC applications to depend on them, thus making it hard to
migrate applications from Derby. (Ie. leads to Derby lock-in). JDBC 4
addresses some of the requirements here by having specific classes of
SQLException that applications can use, we should be encouraging their
use instead of non-standard items.

> 2) The 10.1 doc replaces the variable markers, such as {0}, with human
> readable tags, such as <constraintName>.
> I don't intend to replace those {n} tags with human readable names. If
> anyone would like to offer to do so, feel free.

A great project for someone would be to have the error messages in XML
and from that generate the properties files and the DITA docs.

<message>
<sqlstate>22005</sqlstate>
<text language="en">An attempt was made to get a data value of type
'{0:DATATYPE}' from a data value of type '{1:DATATYPE}'.</text>
<description language="en">
A CAST or column assignment has been attempted between two data types
that cannot be assigned to each other.
</description>
<action language="en">
Change the SQL statement to use a cast or a function to convert types
</action>
<translation notes>
type is a SQL type, data value is a SQL value
</translation notes>
</message>

which would result in the properties file

22005=An attempt was made to get a data value of type '{0}' from a data
value of type '{1}'.

and some documentation that had

22005 An attempt was made to get a data value of type 'DATATYPE' from a
data value of type 'DATATYPE'.

Description
A CAST or column assignment has been attempted between two data types
that cannot be assigned to each other.
Action
Change the SQL statement to use a cast or a function to convert types

etc.

Until we have that I think your format is good and it has up to date
messages :-)
Dan.




Mime
View raw message