Derby
  1. Derby
  2. DERBY-5226

SQLJ system procedures should be documented in Reference Manual

    Details

    • Type: Bug Bug
    • Status: Closed
    • Priority: Minor Minor
    • Resolution: Fixed
    • Affects Version/s: 10.8.1.2
    • Fix Version/s: 10.8.2.2, 10.9.1.0
    • Component/s: Documentation
    • Labels:
      None

      Description

      The system procedures SQLJ.INSTALL_JAR, SQLJ.REMOVE_JAR, and SQLJ.REPLACE_JAR are currently documented in the Tools and Utilities Guide (and briefly referenced in the Developer's Guide). This reference material should be moved to the system procedures section of the Reference Manual and revised to be consistent in style with the other topics in that section.

      DERBY-1780 mentions this situation, as do comments on DERBY-484.

      This issue should be fixed before DERBY-484 so that the new topic can link correctly to the new reference topics.

      1. DERBY-5226.diff
        23 kB
        Kim Haase
      2. DERBY-5226.stat
        0.5 kB
        Kim Haase
      3. DERBY-5226.zip
        11 kB
        Kim Haase
      4. DERBY-5226-2.diff
        23 kB
        Kim Haase
      5. DERBY-5226-2.zip
        11 kB
        Kim Haase

        Issue Links

          Activity

          Kim Haase created issue -
          Kim Haase made changes -
          Field Original Value New Value
          Link This issue blocks DERBY-484 [ DERBY-484 ]
          Kim Haase made changes -
          Link This issue relates to DERBY-1780 [ DERBY-1780 ]
          Hide
          Kim Haase added a comment -

          Attaching DERBY-5226.diff, DERBY-5226.stat, and DERBY-5226.zip, with the following changes:

          M src/tools/derbytools.ditamap
          D src/tools/ttoolsjarload1002986.dita
          D src/tools/ctoolsstorejardb.dita
          M src/tools/ctoolspre23947.dita
          D src/tools/rtoolsjarload3284.dita
          D src/tools/ttoolsjarload1003120.dita
          D src/tools/ttoolsjarload1003059.dita
          M src/devguide/rdevdeploy856948.dita
          A src/ref/rrefstorejarremove.dita
          A src/ref/crefstorejardb.dita
          A src/ref/rrefstorejarinstall.dita
          A src/ref/rrefstorejarreplace.dita
          M src/ref/refderby.ditamap

          I removed information about SQLJ procedures from the Tools Guide and added it to the Reference Manual, reworking task topics into reference topics. I removed the link to this section from "How this guide is organized" topic in the Tools Guide. I changed a cross-reference in Developer's Guide to point to the Reference Manual.

          I've put some questions in some of the reference topics (in bold italics), since the Tools Guide topics had incomplete information. I hope someone knows the answers.

          Thanks in advance!

          Show
          Kim Haase added a comment - Attaching DERBY-5226 .diff, DERBY-5226 .stat, and DERBY-5226 .zip, with the following changes: M src/tools/derbytools.ditamap D src/tools/ttoolsjarload1002986.dita D src/tools/ctoolsstorejardb.dita M src/tools/ctoolspre23947.dita D src/tools/rtoolsjarload3284.dita D src/tools/ttoolsjarload1003120.dita D src/tools/ttoolsjarload1003059.dita M src/devguide/rdevdeploy856948.dita A src/ref/rrefstorejarremove.dita A src/ref/crefstorejardb.dita A src/ref/rrefstorejarinstall.dita A src/ref/rrefstorejarreplace.dita M src/ref/refderby.ditamap I removed information about SQLJ procedures from the Tools Guide and added it to the Reference Manual, reworking task topics into reference topics. I removed the link to this section from "How this guide is organized" topic in the Tools Guide. I changed a cross-reference in Developer's Guide to point to the Reference Manual. I've put some questions in some of the reference topics (in bold italics), since the Tools Guide topics had incomplete information. I hope someone knows the answers. Thanks in advance!
          Kim Haase made changes -
          Attachment DERBY-5226.diff [ 12479366 ]
          Attachment DERBY-5226.stat [ 12479367 ]
          Attachment DERBY-5226.zip [ 12479368 ]
          Kim Haase made changes -
          Issue & fix info [Patch Available]
          Hide
          Rick Hillegas added a comment -

          Hi Kim,

          These changes look good to me. Here are some answers to the questions you posed:

          For more information on the SQLJ procedures, the following summary by Andrew Eisenberg is useful: www.sigmod.org/publications/sigmod-record/9912/standards.pdf.gz

          rrefstorejarinstall.html:

          I think that 32672 is ok as the length of the String arguments to install_jar.

          As you noted, Derby does not use the trailing deploy argument. According to the SQLJ documentation, if that argument is set to 1, it tells the database to look inside the jar file for an SQL script (a deployment descriptor) and run that script when the jar file is put into the database. The script registers the routines and types defined in the jar file and grants access to them.

          rrefstorejarremove.html

          I think that the unused trailing undeploy argument, if set to 1, indicates that the jar file contains a de-registration script which should be run when the jar file is removed. The summary document above doesn't discuss this in detail.

          Show
          Rick Hillegas added a comment - Hi Kim, These changes look good to me. Here are some answers to the questions you posed: For more information on the SQLJ procedures, the following summary by Andrew Eisenberg is useful: www.sigmod.org/publications/sigmod-record/9912/standards.pdf.gz rrefstorejarinstall.html: I think that 32672 is ok as the length of the String arguments to install_jar. As you noted, Derby does not use the trailing deploy argument. According to the SQLJ documentation, if that argument is set to 1, it tells the database to look inside the jar file for an SQL script (a deployment descriptor) and run that script when the jar file is put into the database. The script registers the routines and types defined in the jar file and grants access to them. rrefstorejarremove.html I think that the unused trailing undeploy argument, if set to 1, indicates that the jar file contains a de-registration script which should be run when the jar file is removed. The summary document above doesn't discuss this in detail.
          Hide
          Kim Haase added a comment -

          Thanks for the edits and information, Rick!

          Based on the background info and what you said, I wonder if the language about the deploy and undeploy arguments should be something like the following:

          "If set to 1, indicates the existence of an SQLJ deployment descriptor file. Derby ignores this argument, so it is normally set to 0."

          Would this work? I suppose if they set it to 1 it would be harmless, so there's no need to say that it must be set to 0.

          Also thanks for the tactful correction of my typo on the varchar size. I gather 32672 is correct, not 32762.

          I notice that several topics in the manuals have the same typo; I should probably file another JIRA to fix these:

          rtoolsimport64241.dita, "Parameters for the import procedures" (COLUMNINDEXES entry)
          rrefgetdbpropfunc.dita, "SYSCS_UTIL.SYSCS_GET_DATABASE_PROPERTY system function"
          rrefsyscsruntimestatsfunc.dita, "SYSCS_UTIL.SYSCS_GET_RUNTIMESTATISTICS system function"
          rrefimportdataproc.dita, "SYSCS_UTIL.SYSCS_IMPORT_DATA system procedure"
          rrefimportdataproclobs.dita, "SYSCS_UTIL.SYSCS_IMPORT_DATA_LOBS_FROM_EXTFILE system procedure"

          So do some of the code files (in comments only):

          java/engine/org/apache/derby/catalog/SystemProcedures.java
          java/drda/org/apache/derby/impl/drda/DDMReader.java
          java/engine/org/apache/derby/impl/sql/catalog/DataDictionaryImpl.java

          Show
          Kim Haase added a comment - Thanks for the edits and information, Rick! Based on the background info and what you said, I wonder if the language about the deploy and undeploy arguments should be something like the following: "If set to 1, indicates the existence of an SQLJ deployment descriptor file. Derby ignores this argument, so it is normally set to 0." Would this work? I suppose if they set it to 1 it would be harmless, so there's no need to say that it must be set to 0. Also thanks for the tactful correction of my typo on the varchar size. I gather 32672 is correct, not 32762. I notice that several topics in the manuals have the same typo; I should probably file another JIRA to fix these: rtoolsimport64241.dita, "Parameters for the import procedures" (COLUMNINDEXES entry) rrefgetdbpropfunc.dita, "SYSCS_UTIL.SYSCS_GET_DATABASE_PROPERTY system function" rrefsyscsruntimestatsfunc.dita, "SYSCS_UTIL.SYSCS_GET_RUNTIMESTATISTICS system function" rrefimportdataproc.dita, "SYSCS_UTIL.SYSCS_IMPORT_DATA system procedure" rrefimportdataproclobs.dita, "SYSCS_UTIL.SYSCS_IMPORT_DATA_LOBS_FROM_EXTFILE system procedure" So do some of the code files (in comments only): java/engine/org/apache/derby/catalog/SystemProcedures.java java/drda/org/apache/derby/impl/drda/DDMReader.java java/engine/org/apache/derby/impl/sql/catalog/DataDictionaryImpl.java
          Hide
          Rick Hillegas added a comment -

          Thanks Kim. I think that's a good approach to documenting the unused deployment descriptor flags.

          Further muddying the waters, I have created DERBY-5235, a newcomer issue for restoring the original java.lang.Integer.MAX_VALUE upper bound on VARCHAR length.

          Show
          Rick Hillegas added a comment - Thanks Kim. I think that's a good approach to documenting the unused deployment descriptor flags. Further muddying the waters, I have created DERBY-5235 , a newcomer issue for restoring the original java.lang.Integer.MAX_VALUE upper bound on VARCHAR length.
          Hide
          Kim Haase added a comment -

          I hope you can change the VARCHAR limit to maxint (32768, right?). Do you think you'll be doing that soon? If so, I will not bother to file the typo-correction issue and will file another doc issue to change all the values, once DERBY-5235 is completed. We'll have to fix occurrences of the following:

          32672
          32762
          32,672

          Show
          Kim Haase added a comment - I hope you can change the VARCHAR limit to maxint (32768, right?). Do you think you'll be doing that soon? If so, I will not bother to file the typo-correction issue and will file another doc issue to change all the values, once DERBY-5235 is completed. We'll have to fix occurrences of the following: 32672 32762 32,672
          Hide
          Kim Haase added a comment -

          Thanks for answering all my questions, Rick. I'm attaching a second patch, DERBY-5226-2.diff, with DERBY-5226-2.zip, containing these fixes. Please let me know if any further changes are needed.

          Show
          Kim Haase added a comment - Thanks for answering all my questions, Rick. I'm attaching a second patch, DERBY-5226 -2.diff, with DERBY-5226 -2.zip, containing these fixes. Please let me know if any further changes are needed.
          Kim Haase made changes -
          Attachment DERBY-5226-2.diff [ 12479469 ]
          Attachment DERBY-5226-2.zip [ 12479470 ]
          Hide
          Rick Hillegas added a comment -

          Hi Kim. No-one has grabbed DERBY-5235 yet although some useful discussion is happening over there. I don't think that work can be done in a maintenance release, so we probably won't see that improvement until 10.9 at the earliest. I wouldn't expect to see 10.9 for another 6-12 months from now.

          Show
          Rick Hillegas added a comment - Hi Kim. No-one has grabbed DERBY-5235 yet although some useful discussion is happening over there. I don't think that work can be done in a maintenance release, so we probably won't see that improvement until 10.9 at the earliest. I wouldn't expect to see 10.9 for another 6-12 months from now.
          Hide
          Rick Hillegas added a comment -

          The revised patch looks great, Kim. +1

          Show
          Rick Hillegas added a comment - The revised patch looks great, Kim. +1
          Hide
          Kim Haase added a comment -

          Thanks, Rick!

          I'll go on and file the typo-correction patch then. Might as well be consistent.

          Show
          Kim Haase added a comment - Thanks, Rick! I'll go on and file the typo-correction patch then. Might as well be consistent.
          Hide
          Kim Haase added a comment -

          Committed patch DERBY-5226-2.diff to documentation trunk at revision 1104454.
          Merged to 10.8 doc branch at revision 1104469

          Show
          Kim Haase added a comment - Committed patch DERBY-5226 -2.diff to documentation trunk at revision 1104454. Merged to 10.8 doc branch at revision 1104469
          Kim Haase made changes -
          Status Open [ 1 ] Resolved [ 5 ]
          Issue & fix info [Patch Available]
          Fix Version/s 10.8.1.3 [ 12316378 ]
          Fix Version/s 10.9.0.0 [ 12316344 ]
          Resolution Fixed [ 1 ]
          Hide
          Kim Haase added a comment -

          Changes have appeared in Latest Alpha Manuals.

          Show
          Kim Haase added a comment - Changes have appeared in Latest Alpha Manuals.
          Kim Haase made changes -
          Status Resolved [ 5 ] Closed [ 6 ]
          Rick Hillegas made changes -
          Fix Version/s 10.8.1.4 [ 12316500 ]
          Fix Version/s 10.8.1.3 [ 12316378 ]
          Knut Anders Hatlen made changes -
          Fix Version/s 10.8.1.5 [ 12316676 ]
          Fix Version/s 10.8.1.4 [ 12316500 ]
          Myrna van Lunteren made changes -
          Fix Version/s 10.8.2.0 [ 12317955 ]
          Fix Version/s 10.8.1.6 [ 12316676 ]
          Myrna van Lunteren made changes -
          Fix Version/s 10.8.2.2 [ 12317968 ]
          Fix Version/s 10.8.2.0 [ 12317955 ]
          Gavin made changes -
          Workflow jira [ 12613179 ] Default workflow, editable Closed status [ 12801086 ]

            People

            • Assignee:
              Kim Haase
              Reporter:
              Kim Haase
            • Votes:
              0 Vote for this issue
              Watchers:
              0 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved:

                Development