DERBY-1566: "SQL error messages and exceptions" doc

["Jean T. Anderson" <jt...@bristowhill.com>]

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.

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.

Feedback? Opinions? Preferences?

thanks,

 -jean

Re: DERBY-1566: "SQL error messages and exceptions" doc

["Jean T. Anderson" <jt...@bristowhill.com>]

Jean T. Anderson wrote:
...
> I removed the "severity" column and the review copy is here:
> 
> https://issues.apache.org/jira/secure/attachment/12339926/rrefexcept-3.html
> 
> feedback is welcome,

I'll go ahead and commit the dita source for this at the end of today
unless somebody spots a problem with it. That way it'll make it into the
nightly dev build and, hopefully, into the next 10.2 snapshot/beta/whatever.

thanks,

-jean

Re: DERBY-1566: "SQL error messages and exceptions" doc

["Jean T. Anderson" <jt...@bristowhill.com>]

Jean T. Anderson wrote:
> Daniel John Debrunner wrote:
>>Jean T. Anderson wrote: 
> ...
>>>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. 
...
>>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.
> 
> thanks -- this makes an excellent reason for removing that severity
> column and I'll do so.

I removed the "severity" column and the review copy is here:

https://issues.apache.org/jira/secure/attachment/12339926/rrefexcept-3.html

feedback is welcome,

 -jean

Re: DERBY-1566: "SQL error messages and exceptions" doc

["Jean T. Anderson" <jt...@bristowhill.com>]

Daniel John Debrunner wrote:
> Jean T. Anderson wrote:
...
>>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.

thanks -- this makes an excellent reason for removing that severity
column and I'll do so.

 -jean

Re: DERBY-1566: "SQL error messages and exceptions" doc

[Daniel John Debrunner <dj...@apache.org>]

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.

Re: DERBY-1566: "SQL error messages and exceptions" doc

[David Van Couvering <Da...@Sun.COM>]

I had earlier suggested derbyBuild and Andrew concurred.  No, I'm not 
going to try and find the email :).  Another round of discussions can 
occur, but I had assumed lazy majority with that last go-round and was 
planning to check it into derbyBuild.

David

Jean T. Anderson wrote:
> Rick Hillegas wrote:
>> Hi Jean and David,
>>
>> Thanks for all this great, painstaking work! Here's where I hope we can
>> end up:
>>
>> A) David's tool is checked into the codeline.
>>
>> B) Just before building the docs, the release manager can run the tool
>> in order to generate the latest and greatest version.
>>
>> So I have a question and a comment.
>>
>> The question is this: Has (A) happened?
> 
> (A) has not happened. I think specific location might need to be
> discussed and agreed upon. David's original suggested package
> org.apache.derby.tools, his current suggests org.apache.derbyBuild.
> 
> (B) needs a little more work -- a manual post-processing step is
> required to html-encode the message for sqlstate 42Y04 because it
> includes '<' and '>'.
> 
>>> 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.
>>>  
>> I think that those substitutions make for better documentation but I
>> don't see how we can teach David's tool to perform those
>> substitutions--certainly not in the short run. In my opinion, more value
>> is added by David's automated process for generating an accurate,
>> up-to-date list of SQLStates. So I am happy with your solution: don't
>> substitute the variable markers.
> 
> I agree that accurate is more valuable. Also, I think the context for
> most of the messages makes it pretty clear what the marker means.
> 
>  -jean

Re: DERBY-1566: "SQL error messages and exceptions" doc

["Jean T. Anderson" <jt...@bristowhill.com>]

Rick Hillegas wrote:
> Hi Jean and David,
> 
> Thanks for all this great, painstaking work! Here's where I hope we can
> end up:
> 
> A) David's tool is checked into the codeline.
> 
> B) Just before building the docs, the release manager can run the tool
> in order to generate the latest and greatest version.
> 
> So I have a question and a comment.
> 
> The question is this: Has (A) happened?

(A) has not happened. I think specific location might need to be
discussed and agreed upon. David's original suggested package
org.apache.derby.tools, his current suggests org.apache.derbyBuild.

(B) needs a little more work -- a manual post-processing step is
required to html-encode the message for sqlstate 42Y04 because it
includes '<' and '>'.

>> 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.
>>  
> I think that those substitutions make for better documentation but I
> don't see how we can teach David's tool to perform those
> substitutions--certainly not in the short run. In my opinion, more value
> is added by David's automated process for generating an accurate,
> up-to-date list of SQLStates. So I am happy with your solution: don't
> substitute the variable markers.

I agree that accurate is more valuable. Also, I think the context for
most of the messages makes it pretty clear what the marker means.

 -jean

Re: DERBY-1566: "SQL error messages and exceptions" doc

[Rick Hillegas <Ri...@Sun.COM>]

Hi Jean and David,

Thanks for all this great, painstaking work! Here's where I hope we can 
end up:

A) David's tool is checked into the codeline.

B) Just before building the docs, the release manager can run the tool 
in order to generate the latest and greatest version.

So I have a question and a comment.

The question is this: Has (A) happened?

The comment follows your second question below.

Thanks,
-Rick

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.
>
>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.
>  
>
I think that those substitutions make for better documentation but I 
don't see how we can teach David's tool to perform those 
substitutions--certainly not in the short run. In my opinion, more value 
is added by David's automated process for generating an accurate, 
up-to-date list of SQLStates. So I am happy with your solution: don't 
substitute the variable markers.

>Feedback? Opinions? Preferences?
>
>thanks,
>
> -jean
>
>  
>