Derby
  1. Derby
  2. DERBY-1780

Document all supplied system procedures in the Server and Administration Guide (e.g. class loading utils and import/export)

    Details

    • Type: Improvement Improvement
    • Status: Closed
    • Priority: Minor Minor
    • Resolution: Fixed
    • Affects Version/s: 10.0.2.1, 10.1.2.1, 10.1.3.1
    • Fix Version/s: 10.8.2.2, 10.9.1.0
    • Component/s: Documentation
    • Labels:
      None

      Description

      Most of the utilities cataloged in SYSCS_UTIL are used to setup/initialize a Derby system and are invoked using an existing connection using the 'CALL' command, Such topics are best covered in the the Server and Administration Guide. Currently the procedures install_jarfiles, replace_jarfiles, remove_jarfiles, SYSCS_IMPORT_TABLE / DATA and SYSCS_EXPORT_TABLE / QUERY are documented in the Tools and Utilities Guide.

      I recommend reserving the Tools and Utilities Guide for routines that have a standalone interface (e.g. an existing connection is not required to invoke the routine), currently that is IJ, sysinfo and dblook.

      1. DERBY-1780-1.diff
        80 kB
        Kim Haase
      2. DERBY-1780-1.stat
        0.8 kB
        Kim Haase
      3. DERBY-1780-1.zip
        45 kB
        Kim Haase
      4. DERBY-1780-2.diff
        94 kB
        Kim Haase
      5. DERBY-1780-2.stat
        1 kB
        Kim Haase
      6. DERBY-1780-2.zip
        16 kB
        Kim Haase
      7. DERBY-1780-3.diff
        12 kB
        Kim Haase
      8. DERBY-1780-3.stat
        0.5 kB
        Kim Haase
      9. DERBY-1780-3.zip
        29 kB
        Kim Haase

        Issue Links

          Activity

          Hide
          Kim Haase added a comment -

          I am moving the information on the SQLJ system procedures from the Tools Guide to the Reference Manual, where it clearly belongs (see DERBY-5226).

          I would be happy to move the conceptual information on using the bulk export/import system procedures to the Admin Guide, as suggested here. It's been in the Tools Guide for a long time, however, and people may be used to finding it there by now. I would appreciate any comments, pro and con, on this idea.

          Show
          Kim Haase added a comment - I am moving the information on the SQLJ system procedures from the Tools Guide to the Reference Manual, where it clearly belongs (see DERBY-5226 ). I would be happy to move the conceptual information on using the bulk export/import system procedures to the Admin Guide, as suggested here. It's been in the Tools Guide for a long time, however, and people may be used to finding it there by now. I would appreciate any comments, pro and con, on this idea.
          Hide
          Dag H. Wanvik added a comment -

          I think we should take this opportunity to improve the logical placement. Making it easy to find for newcomers trumps the possible minor convenience for existing users, I think.

          Show
          Dag H. Wanvik added a comment - I think we should take this opportunity to improve the logical placement. Making it easy to find for newcomers trumps the possible minor convenience for existing users, I think.
          Hide
          Kim Haase added a comment -

          Attaching an initial patch containing only the Admin Guide changes – adding the topics from the Tools Guide, fixing typos, and fixing the references elsewhere in the manual. These are the changes:

          A src/adminguide/radminexportarguments.dita
          A src/adminguide/radminimport91458.dita
          A src/adminguide/cadminimport98264.dita
          A src/adminguide/cadminimport16245.dita
          M src/adminguide/cadminreplicstartrun.dita
          A src/adminguide/radminimportcodeset.dita
          M src/adminguide/cadminov83312.dita
          A src/adminguide/cadminimport27052.dita
          A src/adminguide/cadminimportnulls.dita
          A src/adminguide/cadminimportlobs.dita
          M src/adminguide/derbyadmin.ditamap
          M src/adminguide/cadminpreface23947.dita
          A src/adminguide/cadminimportidentitycol.dita
          A src/adminguide/cadminimportdefaultformat.dita
          A src/adminguide/radminimport64241.dita
          A src/adminguide/cadminimportjdbc.dita
          A src/adminguide/tadminimporting.dita
          A src/adminguide/tadminexporting.dita

          I put the import/export topics between the backup/restore section and the replication section of the Admin Guide. Is there a more logical place?

          "How this guide is organized" (cadminpreface23947.dita) hasn't been modified in some time – a couple of sections (sample programs, replication) were missing. I added them in addition to the new section. "Administrative tools" (cadminov83312.dita) also needed updating. "Starting and running replication" (cadminreplicstartrun.dita) needed to point to the changed locations for the SQLJ utilities.

          Please let me know of any needed changes. In the meantime I'll work on removing the topics from the Tools Guide and fixing cross-references in the Reference Manual (and elsewhere, if any).

          I noticed that three topics in the Tools Guide source files that deal with the import/export utilities are not currently used in the manual:

          ctoolsimport12925.dita, "Bulk import and export"
          rtoolsimport57005.dita, "Bulk-Import"
          rtoolsimport92876.dita, "Exporting bulk data"

          They appear to contain information covered in other topics. I'm planning to remove them; please let me know if you see a reason not to.

          Show
          Kim Haase added a comment - Attaching an initial patch containing only the Admin Guide changes – adding the topics from the Tools Guide, fixing typos, and fixing the references elsewhere in the manual. These are the changes: A src/adminguide/radminexportarguments.dita A src/adminguide/radminimport91458.dita A src/adminguide/cadminimport98264.dita A src/adminguide/cadminimport16245.dita M src/adminguide/cadminreplicstartrun.dita A src/adminguide/radminimportcodeset.dita M src/adminguide/cadminov83312.dita A src/adminguide/cadminimport27052.dita A src/adminguide/cadminimportnulls.dita A src/adminguide/cadminimportlobs.dita M src/adminguide/derbyadmin.ditamap M src/adminguide/cadminpreface23947.dita A src/adminguide/cadminimportidentitycol.dita A src/adminguide/cadminimportdefaultformat.dita A src/adminguide/radminimport64241.dita A src/adminguide/cadminimportjdbc.dita A src/adminguide/tadminimporting.dita A src/adminguide/tadminexporting.dita I put the import/export topics between the backup/restore section and the replication section of the Admin Guide. Is there a more logical place? "How this guide is organized" (cadminpreface23947.dita) hasn't been modified in some time – a couple of sections (sample programs, replication) were missing. I added them in addition to the new section. "Administrative tools" (cadminov83312.dita) also needed updating. "Starting and running replication" (cadminreplicstartrun.dita) needed to point to the changed locations for the SQLJ utilities. Please let me know of any needed changes. In the meantime I'll work on removing the topics from the Tools Guide and fixing cross-references in the Reference Manual (and elsewhere, if any). I noticed that three topics in the Tools Guide source files that deal with the import/export utilities are not currently used in the manual: ctoolsimport12925.dita, "Bulk import and export" rtoolsimport57005.dita, "Bulk-Import" rtoolsimport92876.dita, "Exporting bulk data" They appear to contain information covered in other topics. I'm planning to remove them; please let me know if you see a reason not to.
          Hide
          Dag H. Wanvik added a comment -

          Thanks, Kim! I see the topic in cadminov83312.html has the title "Administrative tools", which may explain its previous placement
          in the tools guide. Should we use another term than "tools" here to avoid confusion?

          Show
          Dag H. Wanvik added a comment - Thanks, Kim! I see the topic in cadminov83312.html has the title "Administrative tools", which may explain its previous placement in the tools guide. Should we use another term than "tools" here to avoid confusion?
          Hide
          Kim Haase added a comment -

          Actually, that particular topic ("Administrative tools") has always been in the Admin Guide. If you look at http://db.apache.org/derby/docs/dev/adminguide/, it is about 8 topics down from "How this guide is organized", nested.) I am now wondering if it should be deleted entirely, since it is a bit redundant with "How this guide is organized" and we have been forgetting to update it.

          Show
          Kim Haase added a comment - Actually, that particular topic ("Administrative tools") has always been in the Admin Guide. If you look at http://db.apache.org/derby/docs/dev/adminguide/ , it is about 8 topics down from "How this guide is organized", nested.) I am now wondering if it should be deleted entirely, since it is a bit redundant with "How this guide is organized" and we have been forgetting to update it.
          Hide
          Kim Haase added a comment -

          This patch contains Tools Guide changes. Attaching DERBY-1780-2.diff, DERBY-1780-2.stat, and DERBY-1780-2.zip, with the following changes:

          D src/tools/rtoolsimport57005.dita
          M src/tools/rtools1003161.dita
          M src/tools/ctoolsijtools30948.dita
          M src/tools/ctoolsijtools90477.dita
          D src/tools/ctoolsimport27052.dita
          D src/tools/ctoolsimportnulls.dita
          M src/tools/ctoolsijtools37363.dita
          D src/tools/ctoolsimportlobs.dita
          M src/tools/derbytools.ditamap
          M src/tools/ctools1004764.dita
          D src/tools/ctoolsimportidentitycol.dita
          M src/tools/ctoolspre22460.dita
          D src/tools/ctoolsimportdefaultformat.dita
          D src/tools/rtoolsimport64241.dita
          D src/tools/ctoolsimportjdbc.dita
          D src/tools/rtoolsimport92876.dita
          D src/tools/ctoolsimport12925.dita
          D src/tools/ttoolsimporting.dita
          D src/tools/ttoolsexporting.dita
          M src/tools/ctoolsijtools26429.dita
          M src/tools/ctoolspre23947.dita
          D src/tools/rtoolsimport91458.dita
          M src/tools/ctoolspre11181.dita
          D src/tools/ctoolsimport98264.dita
          D src/tools/rtoolsexportarguements.dita
          D src/tools/ctoolsimport16245.dita
          D src/tools/rtoolsimportcodeset.dita

          In addition to removing the import and export topic files, I did some cleanup in the introductory sections:

          Removed jar and import/export tools from "Purpose of this document" (ctoolspre11181.dita)
          Fixed formatting of "Audience" (ctoolspre22460.dita)
          Removed import/export reference from "How this guide is organized" (ctoolspre23947.dita)
          Reworded "What are the Derby tools and utilities?" somewhat (ctoolsijtools26429.dita)
          Removed jar and import/export tools from "Overview" (ctoolsijtools30948.dita)
          Removed info on jar and import/export tools from "Environment setup and the Derby tools" (ctoolsijtools37363.dita)
          Stopped referring to derbyrun.jar as new in "Classpath" (rtools1003161.dita)
          Removed unneeded ids and link within topic from "About locales" (ctools1004764.dita)
          Changed really, really old date in "Formatting display of locale-sensitive data" (ctoolsijtools90477.dita)

          What additional changes are needed?

          In addition, three topics in the Tools Guide source files that deal with the import/export utilities are not currently used in the manual:

          ctoolsimport12925.dita, "Bulk import and export"
          rtoolsimport57005.dita, "Bulk-Import"
          rtoolsimport92876.dita, "Exporting bulk data"

          They appear to contain information covered in other topics. I removed them and did not transfer them to the Admin Guide.

          Show
          Kim Haase added a comment - This patch contains Tools Guide changes. Attaching DERBY-1780 -2.diff, DERBY-1780 -2.stat, and DERBY-1780 -2.zip, with the following changes: D src/tools/rtoolsimport57005.dita M src/tools/rtools1003161.dita M src/tools/ctoolsijtools30948.dita M src/tools/ctoolsijtools90477.dita D src/tools/ctoolsimport27052.dita D src/tools/ctoolsimportnulls.dita M src/tools/ctoolsijtools37363.dita D src/tools/ctoolsimportlobs.dita M src/tools/derbytools.ditamap M src/tools/ctools1004764.dita D src/tools/ctoolsimportidentitycol.dita M src/tools/ctoolspre22460.dita D src/tools/ctoolsimportdefaultformat.dita D src/tools/rtoolsimport64241.dita D src/tools/ctoolsimportjdbc.dita D src/tools/rtoolsimport92876.dita D src/tools/ctoolsimport12925.dita D src/tools/ttoolsimporting.dita D src/tools/ttoolsexporting.dita M src/tools/ctoolsijtools26429.dita M src/tools/ctoolspre23947.dita D src/tools/rtoolsimport91458.dita M src/tools/ctoolspre11181.dita D src/tools/ctoolsimport98264.dita D src/tools/rtoolsexportarguements.dita D src/tools/ctoolsimport16245.dita D src/tools/rtoolsimportcodeset.dita In addition to removing the import and export topic files, I did some cleanup in the introductory sections: Removed jar and import/export tools from "Purpose of this document" (ctoolspre11181.dita) Fixed formatting of "Audience" (ctoolspre22460.dita) Removed import/export reference from "How this guide is organized" (ctoolspre23947.dita) Reworded "What are the Derby tools and utilities?" somewhat (ctoolsijtools26429.dita) Removed jar and import/export tools from "Overview" (ctoolsijtools30948.dita) Removed info on jar and import/export tools from "Environment setup and the Derby tools" (ctoolsijtools37363.dita) Stopped referring to derbyrun.jar as new in "Classpath" (rtools1003161.dita) Removed unneeded ids and link within topic from "About locales" (ctools1004764.dita) Changed really, really old date in "Formatting display of locale-sensitive data" (ctoolsijtools90477.dita) What additional changes are needed? In addition, three topics in the Tools Guide source files that deal with the import/export utilities are not currently used in the manual: ctoolsimport12925.dita, "Bulk import and export" rtoolsimport57005.dita, "Bulk-Import" rtoolsimport92876.dita, "Exporting bulk data" They appear to contain information covered in other topics. I removed them and did not transfer them to the Admin Guide.
          Hide
          Kim Haase added a comment -

          This final patch is for cross-references in other documents. Attaching DERBY-1780-3.diff, DERBY-1780-3.stat, and DERBY-1780-3.zip, with changes to the following:

          M src/getstart/cgsusingtoolsutils.dita
          M src/getstart/rgsdocs17307.dita
          M src/ref/rrefimportproc.dita
          M src/ref/rrefimportdataproc.dita
          M src/ref/rrefexportproctablelobs.dita
          M src/ref/rrefimportdataproclobs.dita
          M src/ref/rrefimporttableproclobs.dita
          M src/ref/rrefexportselectionproclobs.dita
          M src/ref/rrefexportproc.dita
          M src/ref/rrefexportselectionproc.dita
          M src/tuning/ctunperf16800.dita

          Getting Started:

          Swapped info from Tools to Admin guide in "Product documentation for Derby" (rgsdocs17307.dita)
          Changed xref on import/export procedures in "Using the Derby tools and startup utilities" (cgsusingtoolsutils.dita)

          Reference Manual:

          Fixed xrefs in the topics on the import and export procedures:

          rrefexportproc.dita
          rrefexportproctablelobs.dita
          rrefexportselectionproc.dita
          rrefexportselectionproclobs.dita
          rrefimportdataproc.dita
          rrefimportdataproclobs.dita
          rrefimportproc.dita
          rrefimporttableproclobs.dita

          Tuning Guide:

          Fixed reference to import procedure info in "Avoid inserts in autocommit mode if possible" (ctunperf16800.dita)

          Have I missed any that you know of?

          Show
          Kim Haase added a comment - This final patch is for cross-references in other documents. Attaching DERBY-1780 -3.diff, DERBY-1780 -3.stat, and DERBY-1780 -3.zip, with changes to the following: M src/getstart/cgsusingtoolsutils.dita M src/getstart/rgsdocs17307.dita M src/ref/rrefimportproc.dita M src/ref/rrefimportdataproc.dita M src/ref/rrefexportproctablelobs.dita M src/ref/rrefimportdataproclobs.dita M src/ref/rrefimporttableproclobs.dita M src/ref/rrefexportselectionproclobs.dita M src/ref/rrefexportproc.dita M src/ref/rrefexportselectionproc.dita M src/tuning/ctunperf16800.dita Getting Started: Swapped info from Tools to Admin guide in "Product documentation for Derby" (rgsdocs17307.dita) Changed xref on import/export procedures in "Using the Derby tools and startup utilities" (cgsusingtoolsutils.dita) Reference Manual: Fixed xrefs in the topics on the import and export procedures: rrefexportproc.dita rrefexportproctablelobs.dita rrefexportselectionproc.dita rrefexportselectionproclobs.dita rrefimportdataproc.dita rrefimportdataproclobs.dita rrefimportproc.dita rrefimporttableproclobs.dita Tuning Guide: Fixed reference to import procedure info in "Avoid inserts in autocommit mode if possible" (ctunperf16800.dita) Have I missed any that you know of?
          Hide
          Kim Haase added a comment -

          Has anyone had second thoughts about moving these files, or does anyone have comments on the patches? I would like to commit the patches in the next day or two if possible.

          Show
          Kim Haase added a comment - Has anyone had second thoughts about moving these files, or does anyone have comments on the patches? I would like to commit the patches in the next day or two if possible.
          Hide
          Dag H. Wanvik added a comment -

          I say, go for it! It's a big step in cleaning up the docs, I think. I only made spot checks, though, but they looked good to me.

          Show
          Dag H. Wanvik added a comment - I say, go for it! It's a big step in cleaning up the docs, I think. I only made spot checks, though, but they looked good to me.
          Hide
          Kim Haase added a comment -

          Thanks for the go-ahead, Dag!

          Committed patch DERBY-1780-1.diff to documentation trunk at revision 1129814.
          Merged to 10.8 doc branch at revision 1129817.

          This is patch 1 of 3, which adds the new topics to the Admin Guide.

          Show
          Kim Haase added a comment - Thanks for the go-ahead, Dag! Committed patch DERBY-1780 -1.diff to documentation trunk at revision 1129814. Merged to 10.8 doc branch at revision 1129817. This is patch 1 of 3, which adds the new topics to the Admin Guide.
          Hide
          Kim Haase added a comment -

          Committed patch DERBY-1780-2.diff to documentation trunk at revision 1129834.
          Merged to 10.8 doc branch at revision 1129837.

          This is patch 2 of 3, which removes the old topics from the Tools Guide.

          Show
          Kim Haase added a comment - Committed patch DERBY-1780 -2.diff to documentation trunk at revision 1129834. Merged to 10.8 doc branch at revision 1129837. This is patch 2 of 3, which removes the old topics from the Tools Guide.
          Hide
          Kim Haase added a comment -

          Committed patch DERBY-1780-3.diff to documentation trunk at revision 1129857.
          Merged to 10.8 doc branch at revision 1129837.

          This is patch 3 of 3, which modifies 8 topics in the Reference Manual, 2 in Getting Started, and 1 in the Tuning Guide so that they refer readers to the Admin Guide rather than the Tools Guide.

          Show
          Kim Haase added a comment - Committed patch DERBY-1780 -3.diff to documentation trunk at revision 1129857. Merged to 10.8 doc branch at revision 1129837. This is patch 3 of 3, which modifies 8 topics in the Reference Manual, 2 in Getting Started, and 1 in the Tuning Guide so that they refer readers to the Admin Guide rather than the Tools Guide.
          Hide
          Kim Haase added a comment -

          Changes appeared in 10.8.2 documentation, so closing.

          Show
          Kim Haase added a comment - Changes appeared in 10.8.2 documentation, so closing.

            People

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

              Dates

              • Created:
                Updated:
                Resolved:

                Development