You are viewing a plain text version of this content. The canonical link for it is here.
Posted to derby-dev@db.apache.org by "Jeff Levitt (JIRA)" <de...@db.apache.org> on 2005/05/17 09:52:08 UTC
[jira] Created: (DERBY-296) Document
Document
--------
Key: DERBY-296
URL: http://issues.apache.org/jira/browse/DERBY-296
Project: Derby
Type: Task
Components: Documentation
Environment: all
Reporter: Jeff Levitt
Assigned to: Jeff Levitt
Priority: Minor
I've spent some time compiling a list of error messages for Derby, to expand on the error messages section currently in the Reference Manual. I am about ready to submit a candidate patch, and I am opening up a JIRA issue to contain it.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see:
http://www.atlassian.com/software/jira
Re: [jira] Commented: (DERBY-296) Document error messages in the Derby
Reference Manual
Posted by David Van Couvering <Da...@Sun.COM>.
Hi, Jeff, I am working hard to review your error messages, just trying
to make sure they match. I hope to have an answer for you this evening.
David
Jeff Levitt wrote:
> --- Myrna van Lunteren <m....@gmail.com> wrote:
>
>
>> At the same time, to recreate your doc with
>>additional comments, it must be
>>possible to write a program that uses the
>>ErrorMessages vti in combination
>>with an extra file(/extra files) & attaches the
>>extra hints for each
>>errormessage...And build the error message doc up
>>that way. So you'd miss a
>>manual step to keep error messages and debugging
>>hints in sync.
>>
>
>
> That could be a very helpful method if we can get it
> working. I suspect we should defer something like
> that to at least the next release, since time is
> probably too short for 10.1. In the meantime, is
> there any objection to the current patch to the
> documentation to list the messages in the Reference
> Manual? See
> http://issues.apache.org/jira/browse/DERBY-296 for
> reference. I think David was finishing up his review
> of my changes based on his patch to the actual
> messages. Does everything look good David?
>
> Thanks!
> Jeff
Re: [jira] Commented: (DERBY-296) Document error messages in the Derby Reference Manual
Posted by Jeff Levitt <de...@mylevita.com>.
--- Myrna van Lunteren <m....@gmail.com> wrote:
> At the same time, to recreate your doc with
> additional comments, it must be
> possible to write a program that uses the
> ErrorMessages vti in combination
> with an extra file(/extra files) & attaches the
> extra hints for each
> errormessage...And build the error message doc up
> that way. So you'd miss a
> manual step to keep error messages and debugging
> hints in sync.
>
That could be a very helpful method if we can get it
working. I suspect we should defer something like
that to at least the next release, since time is
probably too short for 10.1. In the meantime, is
there any objection to the current patch to the
documentation to list the messages in the Reference
Manual? See
http://issues.apache.org/jira/browse/DERBY-296 for
reference. I think David was finishing up his review
of my changes based on his patch to the actual
messages. Does everything look good David?
Thanks!
Jeff
Re: [jira] Commented: (DERBY-296) Document error messages in the
Derby Reference Manual
Posted by Satheesh Bandaram <sa...@Sourcery.Org>.
I think so. The syntax is non standard...
Satheesh
David Van Couvering wrote:
> I had read Jeff's earlier request to file a JIRA bug and did so
> (DERBY-357) prior to reading this email. Should I go ahead and
> cancel/close this request?
>
> Thanks,
>
> David
>
> Satheesh Bandaram wrote:
>
>> I am not sure if we should document this syntax. This is highly
>> unusual syntax and definitely not standard.
>>
>> An interesting enhancement to Derby would be to convert these
>> diagnostic VTIs into pseudo system tables. Derby has SYSCS_UTIL and
>> other system schemas and it would be great to provide a pseudo system
>> table interface to all diagnostic VTIs as system tables in one of
>> these system schemas. Would be a great project to learn and enhance
>> Derby SQL compilation and schema management areas.
>>
>> If there is any interest, I could file a Jira ENHANCEMENT request and
>> provide some information....
>>
>> Satheesh
>>
>>> The way to get it to work currently I found in the tests
>>> (org.apache.derbyTesting.functionTests.tests.lang.errorCode.java)
>>> you do: (in ij:)
>>> select * from new org.apache.derby.diag.ErrorMessages() c
>>> and that dumps out all messages.
>>> To get just one particular message, you'd do:
>>> select * from new org.apache.derby.diag.ErrorMessages() c where
>>> sql_state='07000';
>>>
>>> I am wondering though, is it ok to document this?
>>> It's very non-standard way of doing things...
>>>
>>> At the same time, to recreate your doc with additional comments, it
>>> must be possible to write a program that uses the ErrorMessages vti
>>> in combination with an extra file(/extra files) & attaches the extra
>>> hints for each errormessage...And build the error message doc up
>>> that way. So you'd miss a manual step to keep error messages and
>>> debugging hints in sync.
>>>
>>>
>>
>>
>
>
>
Re: [jira] Commented: (DERBY-296) Document error messages in the Derby
Reference Manual
Posted by David Van Couvering <Da...@Sun.COM>.
I had read Jeff's earlier request to file a JIRA bug and did so
(DERBY-357) prior to reading this email. Should I go ahead and
cancel/close this request?
Thanks,
David
Satheesh Bandaram wrote:
> I am not sure if we should document this syntax. This is highly unusual
> syntax and definitely not standard.
>
> An interesting enhancement to Derby would be to convert these diagnostic
> VTIs into pseudo system tables. Derby has SYSCS_UTIL and other system
> schemas and it would be great to provide a pseudo system table interface
> to all diagnostic VTIs as system tables in one of these system schemas.
> Would be a great project to learn and enhance Derby SQL compilation and
> schema management areas.
>
> If there is any interest, I could file a Jira ENHANCEMENT request and
> provide some information....
>
> Satheesh
>
>> The way to get it to work currently I found in the tests
>> (org.apache.derbyTesting.functionTests.tests.lang.errorCode.java)
>> you do: (in ij:)
>> select * from new org.apache.derby.diag.ErrorMessages() c
>> and that dumps out all messages.
>> To get just one particular message, you'd do:
>> select * from new org.apache.derby.diag.ErrorMessages() c where
>> sql_state='07000';
>>
>> I am wondering though, is it ok to document this?
>> It's very non-standard way of doing things...
>>
>> At the same time, to recreate your doc with additional comments, it
>> must be possible to write a program that uses the ErrorMessages vti in
>> combination with an extra file(/extra files) & attaches the extra
>> hints for each errormessage...And build the error message doc up that
>> way. So you'd miss a manual step to keep error messages and debugging
>> hints in sync.
>>
>>
>
Re: [jira] Commented: (DERBY-296) Document error messages in the Derby Reference Manual
Posted by Myrna van Lunteren <m....@gmail.com>.
On 6/13/05, Jeff Levitt <de...@mylevita.com> wrote:
[snip]
> The above two reasons provide better information to
> the user than just telling them to output it from the
> VTI, but also make it hard to run some sort of script
> to create DITA from the VTI output. While I think
> that would be very helpful indeed (and much faster),
> we would still have to go back each time and add the
> message details and user responses, as well as the
> substituted parameter values.
>
> However, if there is indeed a way to print out the
> messages from the VTI, I think if a user just wants to
> do that instead of looking at the docs, and the
> command is available to them, then there should be
> instructions on how to do that in the docs. If
> someone wants to open a JIRA issue to do that, I'd be
> happy to take on that task. I'd appreciate it if you
> could provide the command to do it, as well as a
> suggestion of which book and which part of that book
> to place it, as that will make creating the pacth much
> easier, and more likely to make it in 10.1.
>
I had said the engine javadoc describe the vti, and it's true (
org.apache.derby.diag.ErrorMessages) but the javadoc is out of date...
The way to get it to work currently I found in the tests (
org.apache.derbyTesting.functionTests.tests.lang.errorCode.java)
you do: (in ij:)
select * from new org.apache.derby.diag.ErrorMessages() c
and that dumps out all messages.
To get just one particular message, you'd do:
select * from new org.apache.derby.diag.ErrorMessages() c where
sql_state='07000';
I am wondering though, is it ok to document this?
It's very non-standard way of doing things...
At the same time, to recreate your doc with additional comments, it must be
possible to write a program that uses the ErrorMessages vti in combination
with an extra file(/extra files) & attaches the extra hints for each
errormessage...And build the error message doc up that way. So you'd miss a
manual step to keep error messages and debugging hints in sync.
Re: [jira] Commented: (DERBY-296) Document error messages in the Derby
Reference Manual
Posted by David Van Couvering <Da...@Sun.COM>.
I think you have a good point about being able to add troubleshooting
tips to specific error messages over time. This does add value to this
document over and above what the ErrorMessages VTI can do.
David
Myrna van Lunteren wrote:
> On 6/10/05, *David Van Couvering (JIRA)* <derby-dev@db.apache.org
> <ma...@db.apache.org>> wrote:
>
> [
> http://issues.apache.org/jira/browse/DERBY-296?page=comments#action_12313354
> <http://issues.apache.org/jira/browse/DERBY-296?page=comments#action_12313354>]
>
> David Van Couvering commented on DERBY-296:
> -------------------------------------------
>
> Well, I'm looking at the patch, and while I'm I spend time verifying
> they are all correct, I want to ask a couple of meta questions:
> [..snip..]
> - I know there is an ErrorMessage VTI that prints out all the error
> messages and SQLSTATEs. Would it make more sense just to document
> to a user how they could use ij to print out these messages from the
> VTI? This way you wouldn't have to continue to maintain this list
> and try and make sure it's consistent with reality, which seems like
> a task meant more for Sisyphus than anyone else :)
> [..snip..]
>
>
> My 2c...: It's in the engine javadoc...But I admit it was harder to find
> than I thought. In old Cloudscape manuals this was documented...I
> couldn't find an obvious spot in the current manuals...(sorry if I was
> particularly blind & it's there).
> I am wondering whether users are so used to browsing error message
> manuals for other databases that they have a hard time using the
> ErrorMessage VTI? Plus, you'd need ij...(or issue a separate sql command
> at least).
> Maybe we can add more value to this document over the VTI by adding
> debugging tips and hints where it seems appropriate at some point...?
>
> Myrna
Re: [jira] Commented: (DERBY-296) Document error messages in the Derby Reference Manual
Posted by Jeff Levitt <de...@mylevita.com>.
--- Myrna van Lunteren <m....@gmail.com> wrote:
> On 6/10/05, David Van Couvering (JIRA)
> <de...@db.apache.org> wrote:
> >
> > [
>
http://issues.apache.org/jira/browse/DERBY-296?page=comments#action_12313354
>
> > ]
> >
> > David Van Couvering commented on DERBY-296:
> > -------------------------------------------
> >
> > Well, I'm looking at the patch, and while I'm I
> spend time verifying they
> > are all correct, I want to ask a couple of meta
> questions:
> > [..snip..]
> > - I know there is an ErrorMessage VTI that prints
> out all the error
> > messages and SQLSTATEs. Would it make more sense
> just to document to a user
> > how they could use ij to print out these messages
> from the VTI? This way you
> > wouldn't have to continue to maintain this list
> and try and make sure it's
> > consistent with reality, which seems like a task
> meant more for Sisyphus
> > than anyone else :)
> > [..snip..]
>
> My 2c...: It's in the engine javadoc...But I admit
> it was harder to find
> than I thought. In old Cloudscape manuals this was
> documented...I couldn't
> find an obvious spot in the current manuals...(sorry
> if I was particularly
> blind & it's there).
> I am wondering whether users are so used to browsing
> error message manuals
> for other databases that they have a hard time using
> the ErrorMessage VTI?
> Plus, you'd need ij...(or issue a separate sql
> command at least).
> Maybe we can add more value to this document over
> the VTI by adding
> debugging tips and hints where it seems appropriate
> at some point...?
>
> Myrna
>
Yes, my thoughts were similar to Myrna's. At a later
date, it might be nice to include more information
here for many of the problem messages. A more
detailed explanation as well as a suggested user
response to the error are good ways to help the user
in ways they wouldn't get if they just had the error
message itself. For this release, my idea was to just
get the messages doc'd, so we'd have a baseline for
future releases. For now, the only thing these doc'd
message offer that the actual message strings lack is
a value name for the parameters. This can help users
who may not have named databases, tables, views, etc
very clearly, or don't understand what the values are
that the message is returning. So instead of seeing a
{0} in the message text, the doc replaces it with
<tableName> for example. As we work on documenting
these messages better, we can replace some of the more
generic values with more descriptive substitutions.
The above two reasons provide better information to
the user than just telling them to output it from the
VTI, but also make it hard to run some sort of script
to create DITA from the VTI output. While I think
that would be very helpful indeed (and much faster),
we would still have to go back each time and add the
message details and user responses, as well as the
substituted parameter values.
However, if there is indeed a way to print out the
messages from the VTI, I think if a user just wants to
do that instead of looking at the docs, and the
command is available to them, then there should be
instructions on how to do that in the docs. If
someone wants to open a JIRA issue to do that, I'd be
happy to take on that task. I'd appreciate it if you
could provide the command to do it, as well as a
suggestion of which book and which part of that book
to place it, as that will make creating the pacth much
easier, and more likely to make it in 10.1.
Re: [jira] Commented: (DERBY-296) Document error messages in the Derby Reference Manual
Posted by Myrna van Lunteren <m....@gmail.com>.
On 6/10/05, David Van Couvering (JIRA) <de...@db.apache.org> wrote:
>
> [ http://issues.apache.org/jira/browse/DERBY-296?page=comments#action_12313354
> ]
>
> David Van Couvering commented on DERBY-296:
> -------------------------------------------
>
> Well, I'm looking at the patch, and while I'm I spend time verifying they
> are all correct, I want to ask a couple of meta questions:
> [..snip..]
> - I know there is an ErrorMessage VTI that prints out all the error
> messages and SQLSTATEs. Would it make more sense just to document to a user
> how they could use ij to print out these messages from the VTI? This way you
> wouldn't have to continue to maintain this list and try and make sure it's
> consistent with reality, which seems like a task meant more for Sisyphus
> than anyone else :)
> [..snip..]
My 2c...: It's in the engine javadoc...But I admit it was harder to find
than I thought. In old Cloudscape manuals this was documented...I couldn't
find an obvious spot in the current manuals...(sorry if I was particularly
blind & it's there).
I am wondering whether users are so used to browsing error message manuals
for other databases that they have a hard time using the ErrorMessage VTI?
Plus, you'd need ij...(or issue a separate sql command at least).
Maybe we can add more value to this document over the VTI by adding
debugging tips and hints where it seems appropriate at some point...?
Myrna
[jira] Updated: (DERBY-296) Document error messages in the Derby Reference Manual
Posted by "Jeff Levitt (JIRA)" <de...@db.apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-296?page=all ]
Jeff Levitt updated DERBY-296:
------------------------------
Attachment: derby296withchanges.zip
Thanks David for the feedback! And also for your hard work in fixing the message text! It is much appreciated. I'm sorry for the late response to your feedback, as I was on vacation for awhile, but attached is a new patch with your changes incorporated, as well as a fix due to Derby 180:
http://issues.apache.org/jira/browse/DERBY-180
The html output in the zip is for reviewing. Thanks!
> Document error messages in the Derby Reference Manual
> -----------------------------------------------------
>
> Key: DERBY-296
> URL: http://issues.apache.org/jira/browse/DERBY-296
> Project: Derby
> Type: Task
> Components: Documentation
> Versions: 10.1.0.0
> Environment: all
> Reporter: Jeff Levitt
> Assignee: Jeff Levitt
> Priority: Minor
> Fix For: 10.1.0.0
> Attachments: derby296withchanges.zip
>
> I've spent some time compiling a list of error messages for Derby, to expand on the error messages section currently in the Reference Manual. I am about ready to submit a candidate patch, and I am opening up a JIRA issue to contain it.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see:
http://www.atlassian.com/software/jira
[jira] Commented: (DERBY-296) Document error messages in the Derby Reference Manual
Posted by "Jeff Levitt (JIRA)" <de...@db.apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-296?page=comments#action_12313324 ]
Jeff Levitt commented on DERBY-296:
-----------------------------------
Could someone review my patch to verify that all the correct changes are in? If everything looks good, then I'd like to have this committed so that the messages are available in the documentation for 10.1. Thanks!
> Document error messages in the Derby Reference Manual
> -----------------------------------------------------
>
> Key: DERBY-296
> URL: http://issues.apache.org/jira/browse/DERBY-296
> Project: Derby
> Type: Task
> Components: Documentation
> Versions: 10.1.0.0
> Environment: all
> Reporter: Jeff Levitt
> Assignee: Jeff Levitt
> Priority: Minor
> Fix For: 10.1.0.0
> Attachments: derby296withchanges.zip
>
> I've spent some time compiling a list of error messages for Derby, to expand on the error messages section currently in the Reference Manual. I am about ready to submit a candidate patch, and I am opening up a JIRA issue to contain it.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see:
http://www.atlassian.com/software/jira
[jira] Updated: (DERBY-296) Document error messages in the Derby Reference Manual
Posted by "David Van Couvering (JIRA)" <de...@db.apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-296?page=all ]
David Van Couvering updated DERBY-296:
--------------------------------------
Attachment: results.out
After further thought, it seemed to me if by eyeballing I could catch some missing messages, there might be more. I found
to do an automated check of this, and I have attached what I have found. A couple of SQLStates are not found in
ErrorMessagesVTI, and a number of SQLStates in ErrorMessages VTI were not found in the document.
I am attaching the output. Jeff. Sorry I didn't think of doing this sooner.
> Document error messages in the Derby Reference Manual
> -----------------------------------------------------
>
> Key: DERBY-296
> URL: http://issues.apache.org/jira/browse/DERBY-296
> Project: Derby
> Type: Task
> Components: Documentation
> Versions: 10.1.0.0
> Environment: all
> Reporter: Jeff Levitt
> Assignee: Jeff Levitt
> Priority: Minor
> Fix For: 10.1.0.0
> Attachments: ErrorMessageGenerator.java, derby296finaldraft.zip, results.out, rrefexcept13113.dita
>
> I've spent some time compiling a list of error messages for Derby, to expand on the error messages section currently in the Reference Manual. I am about ready to submit a candidate patch, and I am opening up a JIRA issue to contain it.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see:
http://www.atlassian.com/software/jira
[jira] Updated: (DERBY-296) Document error messages in the Derby Reference Manual
Posted by "Jeff Levitt (JIRA)" <de...@db.apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-296?page=all ]
Jeff Levitt updated DERBY-296:
------------------------------
Attachment: derby296finaldraft.zip
Attached zip (derby296finaldraft.zip) includes latest patch with html output. This patch includes the Synonym messages as well as the ones David identified as missing from the document. Those two messages have been placed in new tables because each was in a new class code. Please let me know if any further changes are required, and if not, we can commit!
> Document error messages in the Derby Reference Manual
> -----------------------------------------------------
>
> Key: DERBY-296
> URL: http://issues.apache.org/jira/browse/DERBY-296
> Project: Derby
> Type: Task
> Components: Documentation
> Versions: 10.1.0.0
> Environment: all
> Reporter: Jeff Levitt
> Assignee: Jeff Levitt
> Priority: Minor
> Fix For: 10.1.0.0
> Attachments: ErrorMessageGenerator.java, derby296finaldraft.zip, rrefexcept13113.dita
>
> I've spent some time compiling a list of error messages for Derby, to expand on the error messages section currently in the Reference Manual. I am about ready to submit a candidate patch, and I am opening up a JIRA issue to contain it.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see:
http://www.atlassian.com/software/jira
[jira] Updated: (DERBY-296) Document error messages in the Derby Reference Manual
Posted by "Samuel Andrew McIntyre (JIRA)" <de...@db.apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-296?page=all ]
Samuel Andrew McIntyre updated DERBY-296:
-----------------------------------------
Summary: Document error messages in the Derby Reference Manual (was: Document)
Version: 10.1.0.0
Fix Version: 10.1.0.0
This document also needs to be updated to include the change for DERBY-180.
> Document error messages in the Derby Reference Manual
> -----------------------------------------------------
>
> Key: DERBY-296
> URL: http://issues.apache.org/jira/browse/DERBY-296
> Project: Derby
> Type: Task
> Components: Documentation
> Versions: 10.1.0.0
> Environment: all
> Reporter: Jeff Levitt
> Assignee: Jeff Levitt
> Priority: Minor
> Fix For: 10.1.0.0
> Attachments: derby296.zip
>
> I've spent some time compiling a list of error messages for Derby, to expand on the error messages section currently in the Reference Manual. I am about ready to submit a candidate patch, and I am opening up a JIRA issue to contain it.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see:
http://www.atlassian.com/software/jira
Re: [jira] Commented: (DERBY-296) Document
Posted by David Van Couvering <Da...@Sun.COM>.
I'll make it a subtask, and make sure derbyall passes when I'm done. I'm
not sure what you mean by "gotchas in the locale files," any tips would
be appreciated; otherwise I'm going to focus on cleaning up the text and
fixing any necessary diffs in test output.
Cheers,
David
Jean T. Anderson wrote:
> David Van Couvering wrote:
>
>>I could do this; every time I talk to customers they hammer into me that
>>clear and helpful error messages are key.
>
>
> Users would definitely appreciate your contribution!
>
>
>>It would *really* help if I knew which message texts were modified in
>>the doc. Is it limited to the Derby-specific messages with SQLStates
>>starting with "X"?
>
>
> Unfortunately Jeff is on vacation, will be back June 6 if I remember
> right. So all I know is what he posted to Jira.
>
>
>>Would I submit this as an independent patch to the same JIRA item? Note
>
>
> Or maybe open a sub task and submit a patch to that?
>
> My guess is there are additional things to watch out for; for example,
> updating the tests to reflect the changed messages so derbyall passes.
> Also, I don't know what gotchas might be out in the locale files --
> would be another thing to follow up on. Anything else, derby developers?
>
>
>>also that I may find "bugs" in the messages that would require a redo of
>>the documentation...
>
>
> In my opinion, the docs (including any doc patches submitted) should be
> changed to match the code.
>
> -jean
>
>
Re: [jira] Commented: (DERBY-296) Document
Posted by "Jean T. Anderson" <jt...@bristowhill.com>.
David Van Couvering wrote:
> I could do this; every time I talk to customers they hammer into me that
> clear and helpful error messages are key.
Users would definitely appreciate your contribution!
> It would *really* help if I knew which message texts were modified in
> the doc. Is it limited to the Derby-specific messages with SQLStates
> starting with "X"?
Unfortunately Jeff is on vacation, will be back June 6 if I remember
right. So all I know is what he posted to Jira.
> Would I submit this as an independent patch to the same JIRA item? Note
Or maybe open a sub task and submit a patch to that?
My guess is there are additional things to watch out for; for example,
updating the tests to reflect the changed messages so derbyall passes.
Also, I don't know what gotchas might be out in the locale files --
would be another thing to follow up on. Anything else, derby developers?
> also that I may find "bugs" in the messages that would require a redo of
> the documentation...
In my opinion, the docs (including any doc patches submitted) should be
changed to match the code.
-jean
Re: [jira] Commented: (DERBY-296) Document
Posted by David Van Couvering <Da...@Sun.COM>.
Well, actually, I *was* planning on only correcting the message property
files. I think fixing SQL State and adding comments in prep for JDBC 4
is beyond the scope of this bug...
I suggest we add a separate JIRA item for the task you are suggesting...
David
Lance J. Andersen wrote:
> David.
>
> If you are planning on doing this and making a pass throughout the code
> to make sure the correct SQLState is set correctly (not just correcting
> the message property files), it might be worthwhile to add some type of
> marker comment in places where the code will need to be changed for JDBC
> 4 in order to bring the SQLExceptions being thrown in line with the
> changes for the new SQLExceptions based on the SQL state class values.
>
> By at least having an easy to find comment, it will make it easier to
> go back and do the retrofit. Of course this only makes sense if you are
> going to make a pass through the entire derby codeline for this adventure.
>
> just a thought if you are looking to have some more fun 8-)
>
> David Van Couvering wrote:
>
>
>>I could do this; every time I talk to customers they hammer into me
>>that clear and helpful error messages are key.
>>
>>It would *really* help if I knew which message texts were modified in
>>the doc. Is it limited to the Derby-specific messages with SQLStates
>>starting with "X"?
>>
>>Would I submit this as an independent patch to the same JIRA item?
>>Note also that I may find "bugs" in the messages that would require a
>>redo of the documentation...
>>
>>David
>>
>>Jean T. Anderson wrote:
>>
>>
>>>David Van Couvering wrote:
>>>
>>>
>>>>I would agree... I think the right thing to do would be to fix the
>>>>code.
>>>>
>>>>David
>>>
>>>
>>>
>>>
>>>is that an offer? :-)
>>>
>>> -jean
>>>
>>>
>>>
>>>>Jean T. Anderson (JIRA) wrote:
>>>>
>>>>
>>>>> [
>>>>>http://issues.apache.org/jira/browse/DERBY-296?page=comments#action_65717
>>>>>]
>>>>> Jean T. Anderson commented on DERBY-296:
>>>>>----------------------------------------
>>>>>
>>>>>Regarding this:
>>>>>
>>>>>
>>>>>
>>>>>>During my work, I discovered that many of the messages could use
>>>>>>some spellchecking, grammar checking, etc. Rather than document
>>>>>>them this way, I corrected them. At some point a separate JIRA
>>>>>>issue should be made, and someone should undertake the task of
>>>>>>fixing the actual message strings to reflect the correct grammar,
>>>>>>spelling, punctuation, etc. used in this document.
>>>>>
>>>>>
>>>>>
>>>>>
>>>>>
>>>>>I'm concerned users might be confused if the error message an
>>>>>application spits out does not exactly match the error message
>>>>>string documented in the Reference Manual.
>>>>>I think this work shouldn't be committed until doc matches code
>>>>>(whether it involves changing the messages in this patch or
>>>>>modifying the code to match these).
>>>>>
>>>>>
>>>>>
>>>>>
>>>>>
>>>>>
>>>>>>Document
>>>>>>--------
>>>>>>
>>>>>> Key: DERBY-296
>>>>>> URL: http://issues.apache.org/jira/browse/DERBY-296
>>>>>> Project: Derby
>>>>>> Type: Task
>>>>>> Components: Documentation
>>>>>>Environment: all
>>>>>> Reporter: Jeff Levitt
>>>>>> Assignee: Jeff Levitt
>>>>>> Priority: Minor
>>>>>>Attachments: derby296.zip
>>>>>>
>>>>>>I've spent some time compiling a list of error messages for Derby,
>>>>>>to expand on the error messages section currently in the Reference
>>>>>>Manual. I am about ready to submit a candidate patch, and I am
>>>>>>opening up a JIRA issue to contain it.
>>>>>
>>>>>
>>>>>
>>>>>
>>>>>
Re: [jira] Commented: (DERBY-296) Document
Posted by "Lance J. Andersen" <La...@Sun.COM>.
David.
If you are planning on doing this and making a pass throughout the code
to make sure the correct SQLState is set correctly (not just correcting
the message property files), it might be worthwhile to add some type of
marker comment in places where the code will need to be changed for JDBC
4 in order to bring the SQLExceptions being thrown in line with the
changes for the new SQLExceptions based on the SQL state class values.
By at least having an easy to find comment, it will make it easier to
go back and do the retrofit. Of course this only makes sense if you are
going to make a pass through the entire derby codeline for this adventure.
just a thought if you are looking to have some more fun 8-)
David Van Couvering wrote:
> I could do this; every time I talk to customers they hammer into me
> that clear and helpful error messages are key.
>
> It would *really* help if I knew which message texts were modified in
> the doc. Is it limited to the Derby-specific messages with SQLStates
> starting with "X"?
>
> Would I submit this as an independent patch to the same JIRA item?
> Note also that I may find "bugs" in the messages that would require a
> redo of the documentation...
>
> David
>
> Jean T. Anderson wrote:
>
>> David Van Couvering wrote:
>>
>>> I would agree... I think the right thing to do would be to fix the
>>> code.
>>>
>>> David
>>
>>
>>
>>
>> is that an offer? :-)
>>
>> -jean
>>
>>
>>> Jean T. Anderson (JIRA) wrote:
>>>
>>>> [
>>>> http://issues.apache.org/jira/browse/DERBY-296?page=comments#action_65717
>>>> ]
>>>> Jean T. Anderson commented on DERBY-296:
>>>> ----------------------------------------
>>>>
>>>> Regarding this:
>>>>
>>>>
>>>>> During my work, I discovered that many of the messages could use
>>>>> some spellchecking, grammar checking, etc. Rather than document
>>>>> them this way, I corrected them. At some point a separate JIRA
>>>>> issue should be made, and someone should undertake the task of
>>>>> fixing the actual message strings to reflect the correct grammar,
>>>>> spelling, punctuation, etc. used in this document.
>>>>
>>>>
>>>>
>>>>
>>>>
>>>> I'm concerned users might be confused if the error message an
>>>> application spits out does not exactly match the error message
>>>> string documented in the Reference Manual.
>>>> I think this work shouldn't be committed until doc matches code
>>>> (whether it involves changing the messages in this patch or
>>>> modifying the code to match these).
>>>>
>>>>
>>>>
>>>>
>>>>
>>>>> Document
>>>>> --------
>>>>>
>>>>> Key: DERBY-296
>>>>> URL: http://issues.apache.org/jira/browse/DERBY-296
>>>>> Project: Derby
>>>>> Type: Task
>>>>> Components: Documentation
>>>>> Environment: all
>>>>> Reporter: Jeff Levitt
>>>>> Assignee: Jeff Levitt
>>>>> Priority: Minor
>>>>> Attachments: derby296.zip
>>>>>
>>>>> I've spent some time compiling a list of error messages for Derby,
>>>>> to expand on the error messages section currently in the Reference
>>>>> Manual. I am about ready to submit a candidate patch, and I am
>>>>> opening up a JIRA issue to contain it.
>>>>
>>>>
>>>>
>>>>
>>>>
>>
Re: [jira] Commented: (DERBY-296) Document
Posted by David Van Couvering <da...@vancouvering.com>.
I could do this; every time I talk to customers they hammer into me that
clear and helpful error messages are key.
It would *really* help if I knew which message texts were modified in
the doc. Is it limited to the Derby-specific messages with SQLStates
starting with "X"?
Would I submit this as an independent patch to the same JIRA item? Note
also that I may find "bugs" in the messages that would require a redo of
the documentation...
David
Jean T. Anderson wrote:
> David Van Couvering wrote:
>
>> I would agree... I think the right thing to do would be to fix the code.
>>
>> David
>
>
>
> is that an offer? :-)
>
> -jean
>
>
>> Jean T. Anderson (JIRA) wrote:
>>
>>> [
>>> http://issues.apache.org/jira/browse/DERBY-296?page=comments#action_65717
>>> ]
>>> Jean T. Anderson commented on DERBY-296:
>>> ----------------------------------------
>>>
>>> Regarding this:
>>>
>>>
>>>> During my work, I discovered that many of the messages could use
>>>> some spellchecking, grammar checking, etc. Rather than document them
>>>> this way, I corrected them. At some point a separate JIRA issue
>>>> should be made, and someone should undertake the task of fixing the
>>>> actual message strings to reflect the correct grammar, spelling,
>>>> punctuation, etc. used in this document.
>>>
>>>
>>>
>>>
>>> I'm concerned users might be confused if the error message an
>>> application spits out does not exactly match the error message string
>>> documented in the Reference Manual.
>>> I think this work shouldn't be committed until doc matches code
>>> (whether it involves changing the messages in this patch or modifying
>>> the code to match these).
>>>
>>>
>>>
>>>
>>>
>>>> Document
>>>> --------
>>>>
>>>> Key: DERBY-296
>>>> URL: http://issues.apache.org/jira/browse/DERBY-296
>>>> Project: Derby
>>>> Type: Task
>>>> Components: Documentation
>>>> Environment: all
>>>> Reporter: Jeff Levitt
>>>> Assignee: Jeff Levitt
>>>> Priority: Minor
>>>> Attachments: derby296.zip
>>>>
>>>> I've spent some time compiling a list of error messages for Derby,
>>>> to expand on the error messages section currently in the Reference
>>>> Manual. I am about ready to submit a candidate patch, and I am
>>>> opening up a JIRA issue to contain it.
>>>
>>>
>>>
>>>
>
Re: [jira] Commented: (DERBY-296) Document
Posted by "Jean T. Anderson" <jt...@bristowhill.com>.
David Van Couvering wrote:
> I would agree... I think the right thing to do would be to fix the code.
>
> David
is that an offer? :-)
-jean
> Jean T. Anderson (JIRA) wrote:
>
>> [
>> http://issues.apache.org/jira/browse/DERBY-296?page=comments#action_65717
>> ]
>> Jean T. Anderson commented on DERBY-296:
>> ----------------------------------------
>>
>> Regarding this:
>>
>>
>>> During my work, I discovered that many of the messages could use some
>>> spellchecking, grammar checking, etc. Rather than document them this
>>> way, I corrected them. At some point a separate JIRA issue should be
>>> made, and someone should undertake the task of fixing the actual
>>> message strings to reflect the correct grammar, spelling,
>>> punctuation, etc. used in this document.
>>
>>
>>
>> I'm concerned users might be confused if the error message an
>> application spits out does not exactly match the error message string
>> documented in the Reference Manual.
>> I think this work shouldn't be committed until doc matches code
>> (whether it involves changing the messages in this patch or modifying
>> the code to match these).
>>
>>
>>
>>
>>
>>> Document
>>> --------
>>>
>>> Key: DERBY-296
>>> URL: http://issues.apache.org/jira/browse/DERBY-296
>>> Project: Derby
>>> Type: Task
>>> Components: Documentation
>>> Environment: all
>>> Reporter: Jeff Levitt
>>> Assignee: Jeff Levitt
>>> Priority: Minor
>>> Attachments: derby296.zip
>>>
>>> I've spent some time compiling a list of error messages for Derby, to
>>> expand on the error messages section currently in the Reference
>>> Manual. I am about ready to submit a candidate patch, and I am
>>> opening up a JIRA issue to contain it.
>>
>>
>>
Re: [jira] Commented: (DERBY-296) Document
Posted by David Van Couvering <da...@vancouvering.com>.
I would agree... I think the right thing to do would be to fix the code.
David
Jean T. Anderson (JIRA) wrote:
> [ http://issues.apache.org/jira/browse/DERBY-296?page=comments#action_65717 ]
>
> Jean T. Anderson commented on DERBY-296:
> ----------------------------------------
>
> Regarding this:
>
>
>>During my work, I discovered that many of the messages could use some spellchecking,
>>grammar checking, etc. Rather than document them this way, I corrected them. At some
>>point a separate JIRA issue should be made, and someone should undertake the task of
>>fixing the actual message strings to reflect the correct grammar, spelling, punctuation,
>>etc. used in this document.
>
>
> I'm concerned users might be confused if the error message an application spits out does not exactly match the error message string documented in the Reference Manual.
>
> I think this work shouldn't be committed until doc matches code (whether it involves changing the messages in this patch or modifying the code to match these).
>
>
>
>
>
>>Document
>>--------
>>
>> Key: DERBY-296
>> URL: http://issues.apache.org/jira/browse/DERBY-296
>> Project: Derby
>> Type: Task
>> Components: Documentation
>> Environment: all
>> Reporter: Jeff Levitt
>> Assignee: Jeff Levitt
>> Priority: Minor
>> Attachments: derby296.zip
>>
>>I've spent some time compiling a list of error messages for Derby, to expand on the error messages section currently in the Reference Manual. I am about ready to submit a candidate patch, and I am opening up a JIRA issue to contain it.
>
>
[jira] Commented: (DERBY-296) Document
Posted by "Jean T. Anderson (JIRA)" <de...@db.apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-296?page=comments#action_65717 ]
Jean T. Anderson commented on DERBY-296:
----------------------------------------
Regarding this:
> During my work, I discovered that many of the messages could use some spellchecking,
> grammar checking, etc. Rather than document them this way, I corrected them. At some
> point a separate JIRA issue should be made, and someone should undertake the task of
> fixing the actual message strings to reflect the correct grammar, spelling, punctuation,
> etc. used in this document.
I'm concerned users might be confused if the error message an application spits out does not exactly match the error message string documented in the Reference Manual.
I think this work shouldn't be committed until doc matches code (whether it involves changing the messages in this patch or modifying the code to match these).
> Document
> --------
>
> Key: DERBY-296
> URL: http://issues.apache.org/jira/browse/DERBY-296
> Project: Derby
> Type: Task
> Components: Documentation
> Environment: all
> Reporter: Jeff Levitt
> Assignee: Jeff Levitt
> Priority: Minor
> Attachments: derby296.zip
>
> I've spent some time compiling a list of error messages for Derby, to expand on the error messages section currently in the Reference Manual. I am about ready to submit a candidate patch, and I am opening up a JIRA issue to contain it.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see:
http://www.atlassian.com/software/jira
[jira] Updated: (DERBY-296) Document error messages in the Derby Reference Manual
Posted by "Jeff Levitt (JIRA)" <de...@db.apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-296?page=all ]
Jeff Levitt updated DERBY-296:
------------------------------
Attachment: derby296revised.zip
Attached is a patch that removes message 0A001, since it was a typo and we have 0A000 in there which is the same message. For the messages that are duplicates, I did not remove them. I think (and hopefully someone more familiar with the messages can validate this) that those are messages where Derby wanted to deviate from the original message string in some places. However, I cant tell you exactly how Derby knows when to call one and not the other. In any case, they are duplicated in the VTI output, and I think the docs should match that. If the messages themselves should change, then maybe we can add on a change to the docs that corresponds to that change. But for now, do you think we can commit this and make future changes to this message list as a baseline? I think it would be prudent to get this much larger patch committed and then make proper tweaks if the corresponding code changes later.
> Document error messages in the Derby Reference Manual
> -----------------------------------------------------
>
> Key: DERBY-296
> URL: http://issues.apache.org/jira/browse/DERBY-296
> Project: Derby
> Type: Task
> Components: Documentation
> Versions: 10.1.0.0
> Environment: all
> Reporter: Jeff Levitt
> Assignee: Jeff Levitt
> Priority: Minor
> Fix For: 10.1.0.0
> Attachments: ErrorMessageGenerator.java, derby296revised.zip, results.out, rrefexcept13113.dita
>
> I've spent some time compiling a list of error messages for Derby, to expand on the error messages section currently in the Reference Manual. I am about ready to submit a candidate patch, and I am opening up a JIRA issue to contain it.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see:
http://www.atlassian.com/software/jira
[jira] Commented: (DERBY-296) Document error messages in the Derby Reference Manual
Posted by "David Van Couvering (JIRA)" <de...@db.apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-296?page=comments#action_66952 ]
David Van Couvering commented on DERBY-296:
-------------------------------------------
I want to remind Jeff that I did not adopt verbatim all of his recommended changes. Jeff, take a look at the attachment to DERBY-305 called
spelling_grammar_changes_with_comments.txt
that shows which messages I either modified or didn't change and why; you'll need to update your doc accordingly (or convince me otherwise :)).
Thanks,
David
> Document error messages in the Derby Reference Manual
> -----------------------------------------------------
>
> Key: DERBY-296
> URL: http://issues.apache.org/jira/browse/DERBY-296
> Project: Derby
> Type: Task
> Components: Documentation
> Versions: 10.1.0.0
> Environment: all
> Reporter: Jeff Levitt
> Assignee: Jeff Levitt
> Priority: Minor
> Fix For: 10.1.0.0
> Attachments: derby296.zip
>
> I've spent some time compiling a list of error messages for Derby, to expand on the error messages section currently in the Reference Manual. I am about ready to submit a candidate patch, and I am opening up a JIRA issue to contain it.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see:
http://www.atlassian.com/software/jira
[jira] Updated: (DERBY-296) Document error messages in the Derby Reference Manual
Posted by "Jeff Levitt (JIRA)" <de...@db.apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-296?page=all ]
Jeff Levitt updated DERBY-296:
------------------------------
Attachment: derby296finaldraft2.zip
Thanks David! Good pickup. I put those messages in the doc and the attached patch (derby296finaldraft2.zip) has the changes and sample output. For the messages in the doc but not in the VTI, maybe we need a separate JIRA issue to add them? Or should they be removed from the doc? One thing I did notice is that you identified 22007 as missing from the VTI, and it actually appears twice with different message strings in the doc. I checked your DITA output file that you generated from the VTI, and both 22007 messages appeared there, so I'm not sure why they didn't show up when you checked against the VTI.
> Document error messages in the Derby Reference Manual
> -----------------------------------------------------
>
> Key: DERBY-296
> URL: http://issues.apache.org/jira/browse/DERBY-296
> Project: Derby
> Type: Task
> Components: Documentation
> Versions: 10.1.0.0
> Environment: all
> Reporter: Jeff Levitt
> Assignee: Jeff Levitt
> Priority: Minor
> Fix For: 10.1.0.0
> Attachments: ErrorMessageGenerator.java, derby296finaldraft2.zip, results.out, rrefexcept13113.dita
>
> I've spent some time compiling a list of error messages for Derby, to expand on the error messages section currently in the Reference Manual. I am about ready to submit a candidate patch, and I am opening up a JIRA issue to contain it.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see:
http://www.atlassian.com/software/jira
[jira] Commented: (DERBY-296) Document error messages in the Derby Reference Manual
Posted by "David Van Couvering (JIRA)" <de...@db.apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-296?page=comments#action_12313354 ]
David Van Couvering commented on DERBY-296:
-------------------------------------------
Well, I'm looking at the patch, and while I'm I spend time verifying they are all correct, I want to ask a couple of meta questions:
- Can you give me a sense of how a user would use this? All the error messages I have seen in the log print out the SQLSTATE and the error message. Are there situations when all you get is the SQLSTATE? Or is this for developers so they can write code to perform certain actions when they get a specific SQLSTATE?
- I know there is an ErrorMessage VTI that prints out all the error messages and SQLSTATEs. Would it make more sense just to document to a user how they could use ij to print out these messages from the VTI? This way you wouldn't have to continue to maintain this list and try and make sure it's consistent with reality, which seems like a task meant more for Sisyphus than anyone else :)
- Alternately, could you write a script that runs the VTI and generates the DITA for you? I could probably write one pretty quick if you'd like...
> Document error messages in the Derby Reference Manual
> -----------------------------------------------------
>
> Key: DERBY-296
> URL: http://issues.apache.org/jira/browse/DERBY-296
> Project: Derby
> Type: Task
> Components: Documentation
> Versions: 10.1.0.0
> Environment: all
> Reporter: Jeff Levitt
> Assignee: Jeff Levitt
> Priority: Minor
> Fix For: 10.1.0.0
> Attachments: derby296withchanges.zip
>
> I've spent some time compiling a list of error messages for Derby, to expand on the error messages section currently in the Reference Manual. I am about ready to submit a candidate patch, and I am opening up a JIRA issue to contain it.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see:
http://www.atlassian.com/software/jira
[jira] Closed: (DERBY-296) Document error messages in the Derby Reference Manual
Posted by "Jean T. Anderson (JIRA)" <de...@db.apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-296?page=all ]
Jean T. Anderson closed DERBY-296:
----------------------------------
Resolution: Fixed
Committed, revision 191353, Jeff Levitt's patch that documents errors messages. Modified file:
$ svn status
M src/ref/rrefexcept13113.dita
> Document error messages in the Derby Reference Manual
> -----------------------------------------------------
>
> Key: DERBY-296
> URL: http://issues.apache.org/jira/browse/DERBY-296
> Project: Derby
> Type: Task
> Components: Documentation
> Versions: 10.1.1.0
> Environment: all
> Reporter: Jeff Levitt
> Assignee: Jeff Levitt
> Priority: Minor
> Fix For: 10.1.1.0
> Attachments: ErrorMessageGenerator.java, derby296revised.zip, results.out, rrefexcept13113.dita
>
> I've spent some time compiling a list of error messages for Derby, to expand on the error messages section currently in the Reference Manual. I am about ready to submit a candidate patch, and I am opening up a JIRA issue to contain it.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see:
http://www.atlassian.com/software/jira
[jira] Commented: (DERBY-296) Document error messages in the Derby Reference Manual
Posted by "David Van Couvering (JIRA)" <de...@db.apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-296?page=comments#action_12313948 ]
David Van Couvering commented on DERBY-296:
-------------------------------------------
+1, sounds good to me.
> Document error messages in the Derby Reference Manual
> -----------------------------------------------------
>
> Key: DERBY-296
> URL: http://issues.apache.org/jira/browse/DERBY-296
> Project: Derby
> Type: Task
> Components: Documentation
> Versions: 10.1.1.0
> Environment: all
> Reporter: Jeff Levitt
> Assignee: Jeff Levitt
> Priority: Minor
> Fix For: 10.1.1.0
> Attachments: ErrorMessageGenerator.java, derby296revised.zip, results.out, rrefexcept13113.dita
>
> I've spent some time compiling a list of error messages for Derby, to expand on the error messages section currently in the Reference Manual. I am about ready to submit a candidate patch, and I am opening up a JIRA issue to contain it.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see:
http://www.atlassian.com/software/jira
[jira] Updated: (DERBY-296) Document error messages in the Derby Reference Manual
Posted by "David Van Couvering (JIRA)" <de...@db.apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-296?page=all ]
David Van Couvering updated DERBY-296:
--------------------------------------
Attachment: ErrorMessageGenerator.java
rrefexcept13113.dita
Hi, Jeff. I tried to automatically compare your message texts with the output of ErrorMessages VTI, but I wasn't able
to get there due to issues like line breaks and substitution of "{0}" and "{1}" with actual text.
In the process, however, I did catch a couple of things:
- There are two SQL States that don't appear to match any of the classes you defined, and which are actually missing
from your document:
0A000 - "Feature not implemented: {0}."
39004 - "A NULL value cannot be passed to a method which takes a parameter of primitive type '{0}'."
- The messages for the new SYNONYM feature are missing: 42916 and 01522
In the process of trying to do the automated diffs, I did end up writing a tool that generates the DITA file from the
ErrorMessage VTI. I have attached this along with the resulting output. Note that you do lose the replacements
of argument position numbers (e.g. "{0}") with meaningful text, but I thought perhaps you might still be tempted
to just generate your file rather than try to maintain it by hand...
David
> Document error messages in the Derby Reference Manual
> -----------------------------------------------------
>
> Key: DERBY-296
> URL: http://issues.apache.org/jira/browse/DERBY-296
> Project: Derby
> Type: Task
> Components: Documentation
> Versions: 10.1.0.0
> Environment: all
> Reporter: Jeff Levitt
> Assignee: Jeff Levitt
> Priority: Minor
> Fix For: 10.1.0.0
> Attachments: ErrorMessageGenerator.java, derby296withchanges.zip, rrefexcept13113.dita
>
> I've spent some time compiling a list of error messages for Derby, to expand on the error messages section currently in the Reference Manual. I am about ready to submit a candidate patch, and I am opening up a JIRA issue to contain it.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see:
http://www.atlassian.com/software/jira
[jira] Updated: (DERBY-296) Document
Posted by "Jeff Levitt (JIRA)" <de...@db.apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-296?page=all ]
Jeff Levitt updated DERBY-296:
------------------------------
Attachment: derby296.zip
Attached is a patch that adds all of the messages I have compiled into tables in one topic to the Reference Manual. Included in the zip is the html output for review.
Some notes:
- The attempt was to include all of the messages/SQLStates used in and by Derby. Please let me know if any are missing.
- During my work, I discovered that many of the messages could use some spellchecking, grammar checking, etc. Rather than document them this way, I corrected them. At some point a separate JIRA issue should be made, and someone should undertake the task of fixing the actual message strings to reflect the correct grammar, spelling, punctuation, etc. used in this document.
- A lot of messages include "parameters". For example, a message might say "The table 'abctable' could not be found." However, in the documentation, we have to substitute the actual table name with some sort of marker. So in the above example, you would find that message looking like this in my document: "The table '<tableName>' could not be found." I have done my best to find appropriate substitutions to help label these parameters, but there were quite a few (over 150) where it simply was not clear as to what the parameter should be labeled. So in those cases, I simply used the generic <value>.
I think further work on this project might include adding any (if at all?) Network Client messages to this list, as well as replacing the various <value> parameters with perhaps more meaninful ones.
For now though, the major work is done, and I would like to submit it as a patch. I think its essential that a compiled list of messages be available as soon as possible, and we can always open more issues to improve upon this baseline submission.
> Document
> --------
>
> Key: DERBY-296
> URL: http://issues.apache.org/jira/browse/DERBY-296
> Project: Derby
> Type: Task
> Components: Documentation
> Environment: all
> Reporter: Jeff Levitt
> Assignee: Jeff Levitt
> Priority: Minor
> Attachments: derby296.zip
>
> I've spent some time compiling a list of error messages for Derby, to expand on the error messages section currently in the Reference Manual. I am about ready to submit a candidate patch, and I am opening up a JIRA issue to contain it.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see:
http://www.atlassian.com/software/jira
[jira] Commented: (DERBY-296) Document error messages in the Derby Reference Manual
Posted by "David Van Couvering (JIRA)" <de...@db.apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-296?page=comments#action_12313564 ]
David Van Couvering commented on DERBY-296:
-------------------------------------------
I forgot to add, I did do some spot-checks of your final document, and it looks good. I can't guarantee I didn't miss anything, though.
> Document error messages in the Derby Reference Manual
> -----------------------------------------------------
>
> Key: DERBY-296
> URL: http://issues.apache.org/jira/browse/DERBY-296
> Project: Derby
> Type: Task
> Components: Documentation
> Versions: 10.1.0.0
> Environment: all
> Reporter: Jeff Levitt
> Assignee: Jeff Levitt
> Priority: Minor
> Fix For: 10.1.0.0
> Attachments: ErrorMessageGenerator.java, derby296withchanges.zip, rrefexcept13113.dita
>
> I've spent some time compiling a list of error messages for Derby, to expand on the error messages section currently in the Reference Manual. I am about ready to submit a candidate patch, and I am opening up a JIRA issue to contain it.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see:
http://www.atlassian.com/software/jira
[jira] Commented: (DERBY-296) Document error messages in the Derby Reference Manual
Posted by "David Van Couvering (JIRA)" <de...@db.apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-296?page=comments#action_12313825 ]
David Van Couvering commented on DERBY-296:
-------------------------------------------
Great, Jeff.
For the messages in the doc but not in the VTI, I think I need to respond to each in turn:
0A001 - I think this is just a typo, notice that 0A000 is missing from the list
22007 - I am not sure what happened here, you're right, it shows up twice (which is a bit disconcerting), each with a different message. Can anyone explain what's going on here and why we don't get conflicts when printing out a message? Or is this just a bug?
"The syntax of the string representation of a datetime value is incorrect."
"The string representation of a datetime value is out of range."
42601 is another one that is a duplicate, maybe there's a bug in my program where it calls out duplicates as a false positive, but that's probably a good thing!
"In an ALTER TABLE statement, the column '{0}' has been specified as NOT NULL and either the DEFAULT clause was not specified or..." (truncated in ij)
"ALTER TABLE statement cannot add an IDENTITY column to a table."
42815 - Duplicate
"The data type, length or value of arguments '{0}' and '{1}' is incompatible.:
"The replacement value for '{0}' is invalid."
XJ081- Duplicate
"Invalid value '{0}' passed as parameter '{1}' to method '{2}'"
"Conflicting create/restore/recovery attributes specified."
I think that these duplicates are probably a separate bug that needs to be addressed, probably by adjusting the error numbers so there are no longer duplicates. I am not sure what to recommend for the document -- someone looking up an error number may be confused about which one applies.
> Document error messages in the Derby Reference Manual
> -----------------------------------------------------
>
> Key: DERBY-296
> URL: http://issues.apache.org/jira/browse/DERBY-296
> Project: Derby
> Type: Task
> Components: Documentation
> Versions: 10.1.0.0
> Environment: all
> Reporter: Jeff Levitt
> Assignee: Jeff Levitt
> Priority: Minor
> Fix For: 10.1.0.0
> Attachments: ErrorMessageGenerator.java, derby296finaldraft2.zip, results.out, rrefexcept13113.dita
>
> I've spent some time compiling a list of error messages for Derby, to expand on the error messages section currently in the Reference Manual. I am about ready to submit a candidate patch, and I am opening up a JIRA issue to contain it.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see:
http://www.atlassian.com/software/jira