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.
