Details

    • Type: Improvement Improvement
    • Status: Closed
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: 10.2.1.6
    • Fix Version/s: 10.2.2.0, 10.3.1.4
    • Component/s: Documentation
    • Labels:
      None
    • Urgency:
      Normal

      Description

      We need to update the Reference Guide to document the current list of SQLStates. This list goes into

      Reference Guide
      Derby exception messages and SQL states
      SQLState and error message reference

      The tool mentioned in DERBY-296 may be useful.

      1. code-4.diff
        2 kB
        Jean T. Anderson
      2. derby1566_DOCS1.diff
        300 kB
        Laura Stewart
      3. derby1566_DOCS2.diff
        300 kB
        Laura Stewart
      4. derby-1566-1.diff
        280 kB
        Jean T. Anderson
      5. derby-1566-2.diff
        314 kB
        Jean T. Anderson
      6. derby-1566-3.diff
        278 kB
        Jean T. Anderson
      7. derby-1566-generatorDavidJeanJohnRick.diff
        19 kB
        Rick Hillegas
      8. ErrorMessageGenerator_davidv3_john.diff
        1 kB
        John H. Embretsen
      9. ErrorMessageGenerator.david.diffs
        2 kB
        Jean T. Anderson
      10. ErrorMessageGenerator.david.diffs2
        2 kB
        Jean T. Anderson
      11. ErrorMessageGenerator.david.diffs3
        3 kB
        Jean T. Anderson
      12. ErrorMessageGenerator.david.java
        14 kB
        David Van Couvering
      13. ErrorMessageGenerator.java
        12 kB
        Jean T. Anderson
      14. newmsgs-10.2.txt
        15 kB
        Jean T. Anderson
      15. rrefexcept-2.html
        285 kB
        Jean T. Anderson
      16. rrefexcept-3.html
        218 kB
        Jean T. Anderson
      17. rrefexcept-4.dita
        151 kB
        Jean T. Anderson
      18. rrefexcept-4.html
        218 kB
        Jean T. Anderson
      19. rrefexcept71493_DOCS1.html
        256 kB
        Laura Stewart
      20. rrefexcept71493_DOCS2.html
        256 kB
        Laura Stewart
      21. rrefexcept71493.html
        219 kB
        Jean T. Anderson

        Issue Links

          Activity

          Hide
          Jean T. Anderson added a comment -

          ErrorMessageGenerator.java is a copy of DERBY-296's app modified as follows:

          1) Replaced the "//IBM//DTD DITA Reference//EN" with ""//OASIS//DTD DITA Reference//EN"

          2) Some tags needed a space . For example, the 'xml' in this tag:
          <reference id="rrefexcept13113"xml:lang="en-us">
          needed a space before the 'xml' so xml parsing would succeed:
          <reference id="rrefexcept13113" xml:lang="en-us">

          3) Needed some close tags for DITA processing to succeed.

          Running it outputs two errors:
          $ java ErrorMessageGenerator
          Unable to determine code for SQL State 0A000
          Unable to determine code for SQL State 39004

          The DITA source that it generates needs one manual change. The message for 42Y04 has '<' and '>' in the message.
          Change this: <full java path>.<method name>
          To this: <full java path>.<method name>

          rrefexcept71493.html shows sample output.

          Show
          Jean T. Anderson added a comment - ErrorMessageGenerator.java is a copy of DERBY-296 's app modified as follows: 1) Replaced the " //IBM//DTD DITA Reference//EN" with "" //OASIS//DTD DITA Reference//EN" 2) Some tags needed a space . For example, the 'xml' in this tag: <reference id="rrefexcept13113"xml:lang="en-us"> needed a space before the 'xml' so xml parsing would succeed: <reference id="rrefexcept13113" xml:lang="en-us"> 3) Needed some close tags for DITA processing to succeed. Running it outputs two errors: $ java ErrorMessageGenerator Unable to determine code for SQL State 0A000 Unable to determine code for SQL State 39004 The DITA source that it generates needs one manual change. The message for 42Y04 has '<' and '>' in the message. Change this: <full java path>.<method name> To this: <full java path>.<method name> rrefexcept71493.html shows sample output.
          Hide
          Jean T. Anderson added a comment -

          Compare rrefexcept71493.html uploaded to this issue to http://db.apache.org/derby/docs/10.1/ref/rrefexcept71493.html. Readily visible differences include:
          1) The old output has human-readable tags such as <tableName> and <valueName> and the new generated output has

          {0}

          ,

          {1}

          , etc. variable markers. I think the human-readable tags would be very labor-intensive to maintain.
          2) The new output includes a severity column

          Lots of sqlstates drop out in 10.2 and others get added. I'll try to summarize a list and post it tomorrow.

          Show
          Jean T. Anderson added a comment - Compare rrefexcept71493.html uploaded to this issue to http://db.apache.org/derby/docs/10.1/ref/rrefexcept71493.html . Readily visible differences include: 1) The old output has human-readable tags such as <tableName> and <valueName> and the new generated output has {0} , {1} , etc. variable markers. I think the human-readable tags would be very labor-intensive to maintain. 2) The new output includes a severity column Lots of sqlstates drop out in 10.2 and others get added. I'll try to summarize a list and post it tomorrow.
          Hide
          Jean T. Anderson added a comment -

          I removed the rrefexcept71493.html file I uploaded yesterday – I had inadvertently generated it on a 10.1.3 database. I'll upload a new one generated from a 10.2.1.1 database.

          Show
          Jean T. Anderson added a comment - I removed the rrefexcept71493.html file I uploaded yesterday – I had inadvertently generated it on a 10.1.3 database. I'll upload a new one generated from a 10.2.1.1 database.
          Hide
          David Van Couvering added a comment -

          This version adds elements for the new SQL State classes that have been added as part of the client internationalization work. Hopefully you can cut-and-paste Jean. Take a look at the static initializer which adds SQL State classes to the codes Hashtable.

          Show
          David Van Couvering added a comment - This version adds elements for the new SQL State classes that have been added as part of the client internationalization work. Hopefully you can cut-and-paste Jean. Take a look at the static initializer which adds SQL State classes to the codes Hashtable.
          Hide
          Jean T. Anderson added a comment -

          The ErrorMessageGenerator.david.java is almost there – it does produce a file without any errors, but it's missing some format and tags so the DITA doc build fails. More details about the fixes for that are below but, first, I attached two files:

          ErrorMessageGenerator.david.diffs - has the diffs between ErrorMessageGenerator.david.java and what I got working.

          rrefexcept71493.html: sample output for derby 10.2.1.1

          Here are more details for the changes to the java application:

          (1) The xml processing is sensitive to spacing – or at least it is for DITA processing. This format fails (notice the lack of a space before the words 'encoding' and 'xml'):

          <?xml version="1.0 "encoding="utf-8"?>
          <!DOCTYPE reference PUBLIC "-//IBM//DTD DITA Reference//EN"
          "../dtd/reference.dtd">
          <reference id="rrefexcept71493 "xml:lang="en-us">

          This format works (and note the switch from IBM to OASIS):

          <?xml version="1.0" encoding="utf-8"?>
          <!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN"
          "../dtd/reference.dtd">
          <reference id="rrefexcept71493" xml:lang="en-us">

          (2) Fix malformed close tags for <entry> and <title>:

          < sqlState + "/>");

          > sqlState + "</entry>");

          < currentComment + "<title>");

          > currentComment + "</title>");

          (3) Add missing close tags for the end of the file

          > ditaWriter.println("</tbody>");
          > ditaWriter.println("</tgroup>");
          > ditaWriter.println("</table>");
          > ditaWriter.println("</section>");
          > ditaWriter.println("</refbody>");
          > ditaWriter.println("</reference>");

          The generated dita file still needs a manual fix for sqlstate 42Y04 to convert the '<' and '>' to < and > respectively.

          Show
          Jean T. Anderson added a comment - The ErrorMessageGenerator.david.java is almost there – it does produce a file without any errors, but it's missing some format and tags so the DITA doc build fails. More details about the fixes for that are below but, first, I attached two files: ErrorMessageGenerator.david.diffs - has the diffs between ErrorMessageGenerator.david.java and what I got working. rrefexcept71493.html: sample output for derby 10.2.1.1 Here are more details for the changes to the java application: (1) The xml processing is sensitive to spacing – or at least it is for DITA processing. This format fails (notice the lack of a space before the words 'encoding' and 'xml'): <?xml version="1.0 "encoding="utf-8"?> <!DOCTYPE reference PUBLIC "-//IBM//DTD DITA Reference//EN" "../dtd/reference.dtd"> <reference id="rrefexcept71493 "xml:lang="en-us"> This format works (and note the switch from IBM to OASIS): <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "../dtd/reference.dtd"> <reference id="rrefexcept71493" xml:lang="en-us"> (2) Fix malformed close tags for <entry> and <title>: < sqlState + "/>"); — > sqlState + "</entry>"); < currentComment + "<title>"); — > currentComment + "</title>"); (3) Add missing close tags for the end of the file > ditaWriter.println("</tbody>"); > ditaWriter.println("</tgroup>"); > ditaWriter.println("</table>"); > ditaWriter.println("</section>"); > ditaWriter.println("</refbody>"); > ditaWriter.println("</reference>"); The generated dita file still needs a manual fix for sqlstate 42Y04 to convert the '<' and '>' to < and > respectively.
          Hide
          David Van Couvering added a comment -

          Diffs look goot to me... Seems like we could fix the &lt and &gt problem with some kind of parser... Doesn't Java have a utility method to normalize a string for HTML?

          Show
          David Van Couvering added a comment - Diffs look goot to me... Seems like we could fix the &lt and &gt problem with some kind of parser... Doesn't Java have a utility method to normalize a string for HTML?
          Hide
          Jean T. Anderson added a comment -

          derby-1566-1.diff is the patch for the dita source that goes with the rrefexcept71493.html review copy (forgot to upload the patch yesterday).

          Show
          Jean T. Anderson added a comment - derby-1566-1.diff is the patch for the dita source that goes with the rrefexcept71493.html review copy (forgot to upload the patch yesterday).
          Hide
          Jean T. Anderson added a comment -

          Here are some basic stats about what changed between 10.1 and 10.2:

          • 10.1.3 has 657 sqlstate entries
          • 10.2.1.1 has 849 sqlstate entries
          • 6 sqlstates dropped out of 10.2:
            X0X15|XML values are not allowed in top-level result sets; try using XMLSERIALIZE.
            X0X18|XML feature not supported: ' {0}'.
            X0XML|Encountered unexpected error while processing XML; see next exception for details.
            X0X16|XML syntax error; missing keyword(s): '{0}

            '.
            X0X14|Binding directly to an XML value is not allowed; try using XMLPARSE.
            X0X17|Invalid target type for XMLSERIALIZE: '

            {0}

            '.

          • 170 new messages were added to 10.2 and are listed in newmsgs-10.2.txt

          If you added or removed a message verifying your change would be appreciated.

          Show
          Jean T. Anderson added a comment - Here are some basic stats about what changed between 10.1 and 10.2: 10.1.3 has 657 sqlstate entries 10.2.1.1 has 849 sqlstate entries 6 sqlstates dropped out of 10.2: X0X15|XML values are not allowed in top-level result sets; try using XMLSERIALIZE. X0X18|XML feature not supported: ' {0}'. X0XML|Encountered unexpected error while processing XML; see next exception for details. X0X16|XML syntax error; missing keyword(s): '{0} '. X0X14|Binding directly to an XML value is not allowed; try using XMLPARSE. X0X17|Invalid target type for XMLSERIALIZE: ' {0} '. 170 new messages were added to 10.2 and are listed in newmsgs-10.2.txt If you added or removed a message verifying your change would be appreciated.
          Hide
          Jean T. Anderson added a comment -

          I spotted one more problem with the app – the "severity" column wasn't completely implemented. Here are new files:

          ErrorMessageGenerator.david.diffs2 - new patch that completes severity column
          derby-1566-2.diff - patch for derby/docs/trunk
          rrefexcept-2.html - updated html for review

          Show
          Jean T. Anderson added a comment - I spotted one more problem with the app – the "severity" column wasn't completely implemented. Here are new files: ErrorMessageGenerator.david.diffs2 - new patch that completes severity column derby-1566-2.diff - patch for derby/docs/trunk rrefexcept-2.html - updated html for review
          Hide
          Jean T. Anderson added a comment -

          The third time is a charm .... after discussion on derby-dev [1], this round removes the severity column. Files are:

          ErrorMessageGenerator.david.diffs3 - new patch that completely removes the severity column
          derby-1566-3.diff - patch for derby/docs/trunk
          rrefexcept-3.html - updated html for review
          [1] http://mail-archives.apache.org/mod_mbox/db-derby-dev/200608.mbox/%3c44F61E89.2000409@bristowhill.com%3e

          Show
          Jean T. Anderson added a comment - The third time is a charm .... after discussion on derby-dev [1] , this round removes the severity column. Files are: ErrorMessageGenerator.david.diffs3 - new patch that completely removes the severity column derby-1566-3.diff - patch for derby/docs/trunk rrefexcept-3.html - updated html for review [1] http://mail-archives.apache.org/mod_mbox/db-derby-dev/200608.mbox/%3c44F61E89.2000409@bristowhill.com%3e
          Hide
          John H. Embretsen added a comment -

          I was not able to find a utility method for creating HTML-friendly Strings in Java, but I made a simple one myself and added it to ErrorMessageGenerator.david.java after applying '...diffs3'. My diff is attached as 'ErrorMessageGenerator_davidv3_john.diff'. The method replaces "<" with "<" and ">" with ">" (other replacements must be added if needed). The utility method is used in the method generateMessages(), for error messages only. The output looks ok to my eyes.

          I hope this helps reducing the manual labor required to build the specific manual page in the future.

          Show
          John H. Embretsen added a comment - I was not able to find a utility method for creating HTML-friendly Strings in Java, but I made a simple one myself and added it to ErrorMessageGenerator.david.java after applying '...diffs3'. My diff is attached as 'ErrorMessageGenerator_davidv3_john.diff'. The method replaces "<" with "<" and ">" with ">" (other replacements must be added if needed). The utility method is used in the method generateMessages(), for error messages only. The output looks ok to my eyes. I hope this helps reducing the manual labor required to build the specific manual page in the future.
          Hide
          Laura Stewart added a comment -

          I understand the benefit of using the tool to generate current messages.
          Of course I do prefer the human readable variables instead of the markers like

          {0}

          and

          {1}

          .

          If we stick with this approach, I recommend that a sentence be added to the message files that explains the variable markers.

          Show
          Laura Stewart added a comment - I understand the benefit of using the tool to generate current messages. Of course I do prefer the human readable variables instead of the markers like {0} and {1} . If we stick with this approach, I recommend that a sentence be added to the message files that explains the variable markers.
          Hide
          Rick Hillegas added a comment -

          Committed derby-1566-generatorDavidJeanJohnRick.diff at subversion revision 439093. This checks in David's SQLState generator to trunk/java/build/org/apache/derbyBuild

          Thanks to David for writing this program and to Jean and John for improving it. I have made the following changes:

          1) Merged in John's changes which escape angle brackets in SQLState text.

          2) Moused in Jean's text, which addresses Laura's concerns.

          3) Fixed various issues with unclosed tags.

          I'm a little concerned that so many of the tags were unclosed. I hope that I have not grabbed the wrong version of this generator. In any event, it should be more straightforward to improve this code now that it's in the trunk.

          Show
          Rick Hillegas added a comment - Committed derby-1566-generatorDavidJeanJohnRick.diff at subversion revision 439093. This checks in David's SQLState generator to trunk/java/build/org/apache/derbyBuild Thanks to David for writing this program and to Jean and John for improving it. I have made the following changes: 1) Merged in John's changes which escape angle brackets in SQLState text. 2) Moused in Jean's text, which addresses Laura's concerns. 3) Fixed various issues with unclosed tags. I'm a little concerned that so many of the tags were unclosed. I hope that I have not grabbed the wrong version of this generator. In any event, it should be more straightforward to improve this code now that it's in the trunk.
          Hide
          Laura Stewart added a comment -

          Jean's wording looks good to me, but I would like to see the DITA file.
          Can someone attach it to this issue?

          On thing that I think needs to be fixed is the headings over the tables. They should not be centered over each table,
          but instead be left justified. And I see no reason why the tables need to be page wide (pgwide) = 1. Typically that tagging is used when content of a table can't easliy be compresses, such as when you have a large number of columns. By changing these DITA tagging issues, the titles will appear left alighned with the table instead of centered (as they are in the attached html) or indented (as they are in the 10.1 version of the docs.

          Show
          Laura Stewart added a comment - Jean's wording looks good to me, but I would like to see the DITA file. Can someone attach it to this issue? On thing that I think needs to be fixed is the headings over the tables. They should not be centered over each table, but instead be left justified. And I see no reason why the tables need to be page wide (pgwide) = 1. Typically that tagging is used when content of a table can't easliy be compresses, such as when you have a large number of columns. By changing these DITA tagging issues, the titles will appear left alighned with the table instead of centered (as they are in the attached html) or indented (as they are in the 10.1 version of the docs.
          Hide
          Jean T. Anderson added a comment -

          Since Rick was concerned about missing closed tags, I just generated a new dita file with the code he checked in to see if it still works. It may be that too many diffs didn't quite produce what was intended. If it produces a dita file that will actually build, I'll attach both it and the resulting html to this issue.

          Show
          Jean T. Anderson added a comment - Since Rick was concerned about missing closed tags, I just generated a new dita file with the code he checked in to see if it still works. It may be that too many diffs didn't quite produce what was intended. If it produces a dita file that will actually build, I'll attach both it and the resulting html to this issue.
          Hide
          Jean T. Anderson added a comment -

          Actually, the code Rick committed did better than I expected – it actually did build a dita doc, though with two small problems:

          1) The "-//OASIS//DTD DITA Reference//EN" change didn't make it in.
          2) The change for unimplementing the severity column didn't make it in, which leaves an empty column hanging out to the right in the PDF output.
          3) Table numbers don't increment for the PDF (everything is Table 1).

          I attached 3 files:

          code-4.diff - patch for ErrorMessageGenerator.java that fixes the first two problems
          rrefexcept-4.dita - dita source that gets generated
          rrefexcept-4.html - html output

          Show
          Jean T. Anderson added a comment - Actually, the code Rick committed did better than I expected – it actually did build a dita doc, though with two small problems: 1) The "-//OASIS//DTD DITA Reference//EN" change didn't make it in. 2) The change for unimplementing the severity column didn't make it in, which leaves an empty column hanging out to the right in the PDF output. 3) Table numbers don't increment for the PDF (everything is Table 1). I attached 3 files: code-4.diff - patch for ErrorMessageGenerator.java that fixes the first two problems rrefexcept-4.dita - dita source that gets generated rrefexcept-4.html - html output
          Hide
          Jean T. Anderson added a comment -

          Regarding this problem:
          3) Table numbers don't increment for the PDF (everything is Table 1).

          I just checked the PDF for 10.1 and it has the same issue, so this isn't a new problem. I just never noticed it before.

          Show
          Jean T. Anderson added a comment - Regarding this problem: 3) Table numbers don't increment for the PDF (everything is Table 1). I just checked the PDF for 10.1 and it has the same issue, so this isn't a new problem. I just never noticed it before.
          Hide
          Jean T. Anderson added a comment -

          In revision 439137 updated src/ref/rrefexcept71493.dita in the trunk with sqlstates and messages as of derby code line 439134. This commit is not to be merged to the 10.2 branch – the dita file will be generated separately for the 10.2 branch.

          Show
          Jean T. Anderson added a comment - In revision 439137 updated src/ref/rrefexcept71493.dita in the trunk with sqlstates and messages as of derby code line 439134. This commit is not to be merged to the 10.2 branch – the dita file will be generated separately for the 10.2 branch.
          Hide
          Rick Hillegas added a comment -

          Committed code-4.diff at subversion revision 439315. Thanks for re-incorporating these fixes, Jean.

          Show
          Rick Hillegas added a comment - Committed code-4.diff at subversion revision 439315. Thanks for re-incorporating these fixes, Jean.
          Hide
          Kim Haase added a comment -

          I think the problem of table numbering is covered by DERBY-408.

          Show
          Kim Haase added a comment - I think the problem of table numbering is covered by DERBY-408 .
          Hide
          Laura Stewart added a comment -

          I have been thinking more about how the variables appear in the text.
          And I think that for clarity, it it worth making the substitutions manually.
          And I am willing to take on this task.

          Show
          Laura Stewart added a comment - I have been thinking more about how the variables appear in the text. And I think that for clarity, it it worth making the substitutions manually. And I am willing to take on this task.
          Hide
          Rick Hillegas added a comment -

          Thanks, Laura. If you can make a first pass at this, then I can try to keep the evolving list current as I generate new beta/release candidates.

          Show
          Rick Hillegas added a comment - Thanks, Laura. If you can make a first pass at this, then I can try to keep the evolving list current as I generate new beta/release candidates.
          Hide
          Laura Stewart added a comment -

          Yes, I will work on this today so that it can be included in the mega merge tomorrow.

          Show
          Laura Stewart added a comment - Yes, I will work on this today so that it can be included in the mega merge tomorrow.
          Hide
          Jean T. Anderson added a comment -

          Initially I thought Laura's plan to update the rrefexcept71493.dita file in the trunk then merge to 10.2 wouldn't work because I expected 10.2 and trunk messages to be different. But based on a comparison of org.apache.derby.diag.ErrorMessages() fetched by 10.2.1.2 and the trunk, I can find only one difference, and that is in the message for sqlstate 42Z20:

          10.2.1.2 message:
          Column '

          {0}' cannot be made nullable. It is part of a primary key, which cannot have any nullable columns.

          trunk message:
          Column '{0}

          ' cannot be made nullable. It is part of a primary key or unique constraint, which cannot have any nullable columns.

          So, Laura, I think it's safe to update the refexcept71493.dita file in the trunk, then merge to the 10.2 doc branch.

          I'll doublecheck the 10.2.1.3 beta anticipated for tomorrow to see if those messages are still different.

          Show
          Jean T. Anderson added a comment - Initially I thought Laura's plan to update the rrefexcept71493.dita file in the trunk then merge to 10.2 wouldn't work because I expected 10.2 and trunk messages to be different. But based on a comparison of org.apache.derby.diag.ErrorMessages() fetched by 10.2.1.2 and the trunk, I can find only one difference, and that is in the message for sqlstate 42Z20: 10.2.1.2 message: Column ' {0}' cannot be made nullable. It is part of a primary key, which cannot have any nullable columns. trunk message: Column '{0} ' cannot be made nullable. It is part of a primary key or unique constraint, which cannot have any nullable columns. So, Laura, I think it's safe to update the refexcept71493.dita file in the trunk, then merge to the 10.2 doc branch. I'll doublecheck the 10.2.1.3 beta anticipated for tomorrow to see if those messages are still different.
          Hide
          Andrew McIntyre added a comment -

          Also, I beileve that the 42Z20 message has now changed in the 10.2 branch since Bryan merged over the ALTER COLUMN NOT NULL change.

          Show
          Andrew McIntyre added a comment - Also, I beileve that the 42Z20 message has now changed in the 10.2 branch since Bryan merged over the ALTER COLUMN NOT NULL change.
          Hide
          Andrew McIntyre added a comment -

          While Dan's suggestion here:

          http://mail-archives.apache.org/mod_mbox/db-derby-dev/200608.mbox/%3c44F62247.2080500@apache.org%3e

          to generate the message file and doc from a single XML file would be ideal, a simpler approach to implement would be to maintain the meanings of the markers in another properties file, identified by message key and marker number. So, e.g. the new properties file would contain:

          01500.0=<constraintName>
          01500.1=<tableName>

          Then ErrorMessageGenerator could look up the value of the markers by SQLState and MessageFormat marker number in the properties file, although this approach would require maintaining two files instead of one.

          Show
          Andrew McIntyre added a comment - While Dan's suggestion here: http://mail-archives.apache.org/mod_mbox/db-derby-dev/200608.mbox/%3c44F62247.2080500@apache.org%3e to generate the message file and doc from a single XML file would be ideal, a simpler approach to implement would be to maintain the meanings of the markers in another properties file, identified by message key and marker number. So, e.g. the new properties file would contain: 01500.0=<constraintName> 01500.1=<tableName> Then ErrorMessageGenerator could look up the value of the markers by SQLState and MessageFormat marker number in the properties file, although this approach would require maintaining two files instead of one.
          Hide
          Laura Stewart added a comment -

          Andrew - I think that your suggestion is great and will minimuze the type of errors that manually entering in the variable names is bound to introduce.

          Show
          Laura Stewart added a comment - Andrew - I think that your suggestion is great and will minimuze the type of errors that manually entering in the variable names is bound to introduce.
          Hide
          Rick Hillegas added a comment -

          If we adopt Andrew's approach, I would recommend co-locating the argument descriptiors in the same properties file which contains the messages. This will help keep the argument descriptors from drifting out of sync with the messages themselves--that is a substantial advantage of Dan's approach.

          Show
          Rick Hillegas added a comment - If we adopt Andrew's approach, I would recommend co-locating the argument descriptiors in the same properties file which contains the messages. This will help keep the argument descriptors from drifting out of sync with the messages themselves--that is a substantial advantage of Dan's approach.
          Hide
          Laura Stewart added a comment -

          Wow, this was very time consuming.
          There are 60+ different variable replacements.

          Attached are a diff file derby1566_DOCS1.diff and an html copy of the file
          rrefexcept71493.html

          Before we commit a patch for these updates, I would REALLY appreciate it if
          someone could review the file and ensure that the variable names that i have are accurate.

          Whenever a variable could be more than one type of object, I used <value>.

          However, I also used value when I did not know what should be used

          This is a very long file and it is possible that I might have missed a few of the variables.
          Please review carefully.

          Show
          Laura Stewart added a comment - Wow, this was very time consuming. There are 60+ different variable replacements. Attached are a diff file derby1566_DOCS1.diff and an html copy of the file rrefexcept71493.html Before we commit a patch for these updates, I would REALLY appreciate it if someone could review the file and ensure that the variable names that i have are accurate. Whenever a variable could be more than one type of object, I used <value>. However, I also used value when I did not know what should be used This is a very long file and it is possible that I might have missed a few of the variables. Please review carefully.
          Hide
          Jean T. Anderson added a comment -

          Thanks for doing this, Laura. I hope the pain of 60+ replacements is preferable to inserting 170 new messages manually.

          I think it's fine to put '<value>' where you aren't sure. The best opportunity to providing real names is with Andrew's properties approach, which will be post-10.2. And post-10.2 is also the best time to fine tune the grammar, etc. in messages.

          It looks like the 10.1 variable names were brought forward, so I focused on the 170 new messages and assembled a list below. I guessed a few, so would appreciate it if others would check my suggested replacement.

          === 01J08 ===
          "Unable to open resultSet type <datatypeName>. ResultSet type <datatypeName> opened."

          Change '<datatypeName>' to '<resultSetType>' (possible values include TYPE_FORWARD_ONLY
          and TYPE_SCROLL_INSENSITIVE).

          === 08001 ===
          "<value> : Error connecting to server <serverName> on port <portNumber> with message <messageText>."
          "SocketException: '<value>'"
          "Unable to open stream on socket: '<value>'."

          Change '<value>' to '<error>'.

          === 28508 ===
          "User '<authorizationID>' does not have <permissionType> permission on column '<2>' of table '<schemaNamet>'.'<tableName>'."

          Change '<2>' to '<columnName>' and '<schemaNamet>' to '<schemaName>'.

          === 28509 ===
          "User '<authorizationID>' does not have <1> permission on column '<2>' of table '<schemaNamet>'.'<tableName>' for grant."

          Change '<1>' to 'permissionType', '<2>' to '<columnName>', and '<schemaNamet>'
          to '<schemaName>'.

          === 2850A, 2850B, 2850C, 2850D, 2850E ===
          Change "schemaNamet" to "schemaName" in all these messages.

          === 58009 ===
          "SocketException: '<value>'"

          Change '<value>' to '<error>'.

          === 58014, 58105, 58106, 58017 ===
          Each message has a parameter that looks like this:

          0x<commandName>
          0x<objectName>
          0x<parameterName>
          0x<value>

          Change all these to <value> unless somebody suggests a good replacement.
          --The 0x suggests hex codes to me.

          === XJ091 ===
          "Invalid argument: parameter index <indexName> is not an OUT or INOUT parameter."

          Change '<indexName>' to '<indexNum>'. In other words, I think the message will
          look something like this: "parameter index 3 is not an OUT or INOUT parameter".

          === XJ113 ===
          "Unable to open file <fileName> : <value>"

          Change '<value>' to '<error>'

          === XSDAL ===
          "Record handle <0value> unexpectedly points to overflow page."

          Change '<0value>' to '<value>'.

          === XSRSC ===
          "Cannot backup the database to <value>, it is a database directory."

          Change '<value>' to '<directory location>'.

          Show
          Jean T. Anderson added a comment - Thanks for doing this, Laura. I hope the pain of 60+ replacements is preferable to inserting 170 new messages manually. I think it's fine to put '<value>' where you aren't sure. The best opportunity to providing real names is with Andrew's properties approach, which will be post-10.2. And post-10.2 is also the best time to fine tune the grammar, etc. in messages. It looks like the 10.1 variable names were brought forward, so I focused on the 170 new messages and assembled a list below. I guessed a few, so would appreciate it if others would check my suggested replacement. === 01J08 === "Unable to open resultSet type <datatypeName>. ResultSet type <datatypeName> opened." Change '<datatypeName>' to '<resultSetType>' (possible values include TYPE_FORWARD_ONLY and TYPE_SCROLL_INSENSITIVE). === 08001 === "<value> : Error connecting to server <serverName> on port <portNumber> with message <messageText>." "SocketException: '<value>'" "Unable to open stream on socket: '<value>'." Change '<value>' to '<error>'. === 28508 === "User '<authorizationID>' does not have <permissionType> permission on column '<2>' of table '<schemaNamet>'.'<tableName>'." Change '<2>' to '<columnName>' and '<schemaNamet>' to '<schemaName>'. === 28509 === "User '<authorizationID>' does not have <1> permission on column '<2>' of table '<schemaNamet>'.'<tableName>' for grant." Change '<1>' to 'permissionType', '<2>' to '<columnName>', and '<schemaNamet>' to '<schemaName>'. === 2850A, 2850B, 2850C, 2850D, 2850E === Change "schemaNamet" to "schemaName" in all these messages. === 58009 === "SocketException: '<value>'" Change '<value>' to '<error>'. === 58014, 58105, 58106, 58017 === Each message has a parameter that looks like this: 0x<commandName> 0x<objectName> 0x<parameterName> 0x<value> Change all these to <value> unless somebody suggests a good replacement. --The 0x suggests hex codes to me. === XJ091 === "Invalid argument: parameter index <indexName> is not an OUT or INOUT parameter." Change '<indexName>' to '<indexNum>'. In other words, I think the message will look something like this: "parameter index 3 is not an OUT or INOUT parameter". === XJ113 === "Unable to open file <fileName> : <value>" Change '<value>' to '<error>' === XSDAL === "Record handle <0value> unexpectedly points to overflow page." Change '<0value>' to '<value>'. === XSRSC === "Cannot backup the database to <value>, it is a database directory." Change '<value>' to '<directory location>'.
          Hide
          Laura Stewart added a comment -

          Thank you Jean. Yes, entering in the variables is much better than typing up 170 new messages
          I look forward to Andrew's solution post 10.2.

          For the most part I did use what was there for 10.1. However, in many cases "value" was used instead of databaseName where it seemed obvious to me that it should be changed. There are others like that which I changed as well. But only the obvious ones.

          I'll make these updates now. How long do you think I should wait for additional comments before submitting a patch?

          Show
          Laura Stewart added a comment - Thank you Jean. Yes, entering in the variables is much better than typing up 170 new messages I look forward to Andrew's solution post 10.2. For the most part I did use what was there for 10.1. However, in many cases "value" was used instead of databaseName where it seemed obvious to me that it should be changed. There are others like that which I changed as well. But only the obvious ones. I'll make these updates now. How long do you think I should wait for additional comments before submitting a patch?
          Hide
          Jean T. Anderson added a comment -

          Feel free to update and upload a new patch any time it's convenient for you. I can help update this file to incorporate comments that come in later. I would have directly edited it with the comments I just posted, but I wanted to make my guesses readily visible for others to correct if needed.

          Show
          Jean T. Anderson added a comment - Feel free to update and upload a new patch any time it's convenient for you. I can help update this file to incorporate comments that come in later. I would have directly edited it with the comments I just posted, but I wanted to make my guesses readily visible for others to correct if needed.
          Hide
          Laura Stewart added a comment -

          Updated the SQL State messages file based on
          Jean's comments.

          The files are:
          derby1566_DOCS2.html
          rrefexcept71493_DOCS2.html

          Show
          Laura Stewart added a comment - Updated the SQL State messages file based on Jean's comments. The files are: derby1566_DOCS2.html rrefexcept71493_DOCS2.html
          Hide
          Jean T. Anderson added a comment -

          Committed patch derby1566_DOCS2.diff to the trunk, revision 442381.
          Rick, I'll let you decide how you want to incorporate this into the 10.2 branch.
          Thanks, Laura!

          Show
          Jean T. Anderson added a comment - Committed patch derby1566_DOCS2.diff to the trunk, revision 442381. Rick, I'll let you decide how you want to incorporate this into the 10.2 branch. Thanks, Laura!
          Hide
          Rick Hillegas added a comment -

          Moving to 10.2.2.0.

          Show
          Rick Hillegas added a comment - Moving to 10.2.2.0.
          Hide
          Andrew McIntyre added a comment -

          I think this should be marked closed as FixIn 10.2.1.0, the work to document the SQL states has been done there. A separate issue should be filed for implementing a way to generate the English names for the parameter markers in the doc.

          Show
          Andrew McIntyre added a comment - I think this should be marked closed as FixIn 10.2.1.0, the work to document the SQL states has been done there. A separate issue should be filed for implementing a way to generate the English names for the parameter markers in the doc.
          Hide
          Rick Hillegas added a comment -

          Closing this issue. I have created a new issue, DERBY-1868, to track the further evolution of David's tool and Laura's painstaking improvements.

          Show
          Rick Hillegas added a comment - Closing this issue. I have created a new issue, DERBY-1868 , to track the further evolution of David's tool and Laura's painstaking improvements.

            People

            • Assignee:
              Jean T. Anderson
              Reporter:
              Rick Hillegas
            • Votes:
              0 Vote for this issue
              Watchers:
              0 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved:

                Development