Derby
  1. Derby
  2. DERBY-482

GENERATED BY DEFAULT option should be documented in Derby Tools and Utilities guide under "Importing into tables with identity columns" section.

    Details

    • Type: Improvement Improvement
    • Status: Closed
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: 10.1.1.0
    • Fix Version/s: 10.6.1.0
    • Component/s: Documentation
    • Labels:
      None

      Description

      Tomohito added support for import into identity columns by adding GENERATED BY DEFAULT option. This is documented in the Reference Guide but not in the Tools and Utilites Guide which is where a user would look for details on import. IMHO, there should be information about this in "Importing into tables with identity columns" section in Tools and Utilities Guide.

      1. importIdentityCol.diff
        7 kB
        Bryan Pendleton
      2. derby482.diff
        5 kB
        Jeff Levitt
      3. ctoolsimportidentitycol.html
        7 kB
        Jeff Levitt
      4. ctoolsimportidentitycol.html
        10 kB
        Bryan Pendleton

        Activity

        Hide
        Bryan Pendleton added a comment -

        Thanks Kim for the review. I felt the bullet items were a bit awkward, so took
        your advice to simplify that portion of the page, and committed the change
        to the docs trunk as revision 886656.

        Show
        Bryan Pendleton added a comment - Thanks Kim for the review. I felt the bullet items were a bit awkward, so took your advice to simplify that portion of the page, and committed the change to the docs trunk as revision 886656.
        Hide
        Kim Haase added a comment -

        This looks great and is very clear.

        I'm not sure the bullet list at the beginning is appropriate since this is really just a sentence rather than a list, but it's not a big deal.

        +1 to commit.

        Show
        Kim Haase added a comment - This looks great and is very clear. I'm not sure the bullet list at the beginning is appropriate since this is really just a sentence rather than a list, but it's not a big deal. +1 to commit.
        Hide
        Bryan Pendleton added a comment -

        I took a stab at re-writing this page in the Tools guide.
        Attached is 'importIdentityCol.diff', and the resulting
        HTML page.

        I used a few of Jeff's original ideas, and also used Mamta's
        ideas, and threw in a few ideas of my own.

        Please have a look at the revised page and let me know what you think.

        Show
        Bryan Pendleton added a comment - I took a stab at re-writing this page in the Tools guide. Attached is 'importIdentityCol.diff', and the resulting HTML page. I used a few of Jeff's original ideas, and also used Mamta's ideas, and threw in a few ideas of my own. Please have a look at the revised page and let me know what you think.
        Hide
        Kathey Marsden added a comment -

        Unchecking Patch Available after Mamta's comments. Jeff has unassigned himself from this issue so probably it is available to be picked up.

        Show
        Kathey Marsden added a comment - Unchecking Patch Available after Mamta's comments. Jeff has unassigned himself from this issue so probably it is available to be picked up.
        Hide
        Mamta A. Satoor added a comment -

        Jeff, I looked through the html file and have couple comments.
        1)I don't understand the line in the first paragraph "You can specify the GENERATED ALWAYS or GENERATED BY DEFAULT options when using the procedure to define identity column values". I haven't paid close attention to changes to SYSCS_UTIL.SYSCS_IMPORT_DATA, but I don't think it needs to know if it is dealing with GENERATED ALWAYS or GENERATED BY DEFAULT. In fact, from what I know, there is no way to specify to the SYSCS_UTIL.SYSCS_IMPORT_DATA procedure whether it is dealing with GENERATED ALWAYS or GENERATED BY DEFAULT.
        2)IMHO, the information on GENERATED ALWAYS and GENERATED BY DEFAULT is not flowing very smoothly on the html page.

        I like the format for GENERATED ALWAYS where we first give the create table sql and then 2 different forms of import files and how to use the import procedure to import from them. In addition to these 2 examples for GENERATED ALWAYS, I think it will be good to add another example where user is trying to import from a file with values for identity column data and import procedure uses that data for GENERATED ALWAYS. Such an import will fail for GENERATED ALWAYS. eg
        Robert,1,45.2,J
        Mike,2,23.4,I
        Leo,3,23.4,I
        CALL SYSCS_UTIL.SYSCS_IMPORT_DATA (NULL, 'TAB1', 'C1,C2,C3,C4' , '1,2,3,4','empfile.del',null, null,null,0)

        We should keep similar format for GENERATED BY DEFAULT. Show create table sql for it, and then show couple examples of import data file where the value is specified for the column or DEFAULT is specified for the column or the column values are not included in the import data file. And then for these various import files, show how data can be imported into the table with GENERATED BY DEFAULT.

        Show
        Mamta A. Satoor added a comment - Jeff, I looked through the html file and have couple comments. 1)I don't understand the line in the first paragraph "You can specify the GENERATED ALWAYS or GENERATED BY DEFAULT options when using the procedure to define identity column values". I haven't paid close attention to changes to SYSCS_UTIL.SYSCS_IMPORT_DATA, but I don't think it needs to know if it is dealing with GENERATED ALWAYS or GENERATED BY DEFAULT. In fact, from what I know, there is no way to specify to the SYSCS_UTIL.SYSCS_IMPORT_DATA procedure whether it is dealing with GENERATED ALWAYS or GENERATED BY DEFAULT. 2)IMHO, the information on GENERATED ALWAYS and GENERATED BY DEFAULT is not flowing very smoothly on the html page. I like the format for GENERATED ALWAYS where we first give the create table sql and then 2 different forms of import files and how to use the import procedure to import from them. In addition to these 2 examples for GENERATED ALWAYS, I think it will be good to add another example where user is trying to import from a file with values for identity column data and import procedure uses that data for GENERATED ALWAYS. Such an import will fail for GENERATED ALWAYS. eg Robert,1,45.2,J Mike,2,23.4,I Leo,3,23.4,I CALL SYSCS_UTIL.SYSCS_IMPORT_DATA (NULL, 'TAB1', 'C1,C2,C3,C4' , '1,2,3,4','empfile.del',null, null,null,0) We should keep similar format for GENERATED BY DEFAULT. Show create table sql for it, and then show couple examples of import data file where the value is specified for the column or DEFAULT is specified for the column or the column values are not included in the import data file. And then for these various import files, show how data can be imported into the table with GENERATED BY DEFAULT.
        Hide
        Jeff Levitt added a comment -

        Thats so strange. It did it to me too, and I looked at the original copy on my local machine and it looked fine. Mamtam when you try again, maybe just force it to an html extension by stripping the .xml it adds to the file name. Then open it up again and you should read it fine.

        Show
        Jeff Levitt added a comment - Thats so strange. It did it to me too, and I looked at the original copy on my local machine and it looked fine. Mamtam when you try again, maybe just force it to an html extension by stripping the .xml it adds to the file name. Then open it up again and you should read it fine.
        Hide
        John H. Embretsen added a comment -

        Hmm, I did a quick check myself, and found that I got roughly the same error as Mamta when trying to view the HTML document with Internet Explorer 6. With Opera the html renders just fine, and with Firefox it is displayed as unrendered xml, with the message "This XML file does not appear to have any style information associated with it. The document tree is shown below.". When I try to "Save target as...", even Opera seems to think it's an xml document. However, if I do save it as html, I am able to open the local copy (as rendered html) in all browsers.

        I looked, but could not find anything (different from other derby-doc htmls) in the source (html and the patch) that may explain why this happens to this particular document.

        Show
        John H. Embretsen added a comment - Hmm, I did a quick check myself, and found that I got roughly the same error as Mamta when trying to view the HTML document with Internet Explorer 6. With Opera the html renders just fine, and with Firefox it is displayed as unrendered xml, with the message "This XML file does not appear to have any style information associated with it. The document tree is shown below.". When I try to "Save target as...", even Opera seems to think it's an xml document. However, if I do save it as html, I am able to open the local copy (as rendered html) in all browsers. I looked, but could not find anything (different from other derby-doc htmls) in the source (html and the patch) that may explain why this happens to this particular document.
        Hide
        Mamta A. Satoor added a comment -

        Jeff, when I click on the .html attachement, I get following error
        The XML page cannot be displayed
        Cannot view XML input using XSL style sheet. Please correct the error and then click the Refresh button, or try again later.

        --------------------------------------------------------------------------------

        Use of default namespace declaration attribute in DTD not supported. Error processing resource 'http://issues.apache.org/jira/secure/attachment/12323139/ctoolsimportidentitycol.html'. Line 2, Position 37

        <html lang="en-us" xml:lang="en-us">

        I was able to look at .html attachements to JIRA by Eric recently on other documentation changes.

        Show
        Mamta A. Satoor added a comment - Jeff, when I click on the .html attachement, I get following error The XML page cannot be displayed Cannot view XML input using XSL style sheet. Please correct the error and then click the Refresh button, or try again later. -------------------------------------------------------------------------------- Use of default namespace declaration attribute in DTD not supported. Error processing resource 'http://issues.apache.org/jira/secure/attachment/12323139/ctoolsimportidentitycol.html'. Line 2, Position 37 <html lang="en-us" xml:lang="en-us"> I was able to look at .html attachements to JIRA by Eric recently on other documentation changes.
        Hide
        Jeff Levitt added a comment -

        For this patch, I copied the information in the Reference Manual on GENERATED BY DEFAULT and placed it in the "Importing into tables with identity columns" topic in the Tools and Utilities Guide after the information on GENERATED ALWAYS. I then modified the introductory paragraph of the topic to mention both options. I am including an HTML output file for review with this patch. I'd appreciate any feedback. Thanks!

        Show
        Jeff Levitt added a comment - For this patch, I copied the information in the Reference Manual on GENERATED BY DEFAULT and placed it in the "Importing into tables with identity columns" topic in the Tools and Utilities Guide after the information on GENERATED ALWAYS. I then modified the introductory paragraph of the topic to mention both options. I am including an HTML output file for review with this patch. I'd appreciate any feedback. Thanks!

          People

          • Assignee:
            Bryan Pendleton
            Reporter:
            Mamta A. Satoor
          • Votes:
            0 Vote for this issue
            Watchers:
            0 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved:

              Development