[
https://issues.apache.org/jira/browse/DERBY-2527?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12492759
]
Suresh Thalamati commented on DERBY-2527:
-----------------------------------------
Laura Stewart (JIRA) wrote:
> [
> https://issues.apache.org/jira/browse/DERBY-2527?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
> ]
>
Thanks Laura, My answers are inline:
>General Questions:
> Most reference guides include examples for each procedure. But it does not
> seem right to have examples in both the Reference Manual and the Tools Guide.
> Should the examples in the Tools guide be moved to the specific procedures in
> the Ref Manual?
Tools guide section should have example for sure, because it easy understand
while reading about import/export. I think showing an simple example usage
might be helpful in reference section also, but I am not particular about it.
> Also, the other system procedures in the Ref Manual have separate examples
> for JDBC and SQL. Should the import/export have separate examples?
I think , there is one example in the doc , which show how to call the
import/export procedure from a JDBC code. It is the something for all
the other procedures. In my opinion, it just unnecessary to provide
both usages for all the procedures.
> The other procedures use all uppercase for the parameters in the syntax in the
> Reference Manual. > The new import/export procedures show mixed case
(for example fileName and > tableName). > Should the syntax in both the Ref
> Manual and Tools Guide show all uppercase for the parameters?
As long as we are consistent within the Import/Export section of both manuals,
then it is OK. I actually like mixed case names , just easier to read than all
capital case ONES. Please change all of them to one format, whichever you feel
is better, i have no special preference.
>Specific Topic Questions - Tools Guide
>In the topic "Bulk import and export requirements and considerations" the
> section "Restrictions on the REPLACE option". This is really the replace
>parameter that users specify in the procedure isn't it? I think we
> should use consist terminology and say "replace parameter". Okay?
yes, replace option is actually parameter to the import procedures.
I agree with you, it may be better to say it is a parameter.
> Regarding the topic "Parameters for the import procedures", these parameters
> are already described in the Ref Manual along with the syntax of the
> procedure.
> I think that we should delete this topic (since it contains the same info as
> the Ref Manual) and
> have a cross-reference from the topic "Importing data using the built-in
> procedures" in the the
> Tools Guide to the procedure description in the Ref Manual.
I agree, there is a duplication of info. But I would like to see
the information about various parameters provided in the tools guide,
because that is all the only info we have about the parameters in
the tools guide. It will provide complete details about how to
use the import/export, just by reading the tools guide.
If I had to choose one place, I will actually keep the description about
parameters in the tools guide and remove it from the reference
manual, and provide reference to the tools guide.
If you decide to keep them Currently , reference manual describes parameters
for each procedure; may be we can follow the tools guide model and document
as two section ; one for All import procedures and another one for Export
Procedures.
> Does the topic "Import into tables that contain identity columns" need to be
> updated to mention
> the new procedure "SYSCS_UTIL.SYSCS_IMPORT_DATA_LOBS_FROM_EXTFILE" ???
yes. Users can use SYSCS_UTIL.SYSCS_IMPORT_DATA_LOBS_FROM_EXTFILE also.
I noted this in review comments.
> Regarding the topic "Parameters for the export procedures", these parameters
> are already described in the Ref Manual along with the syntax of the
> procedure. I think that we should delete this topic (since it contains the
> same info as the Ref Manual) and
> have a cross-reference from the topic "Exporting data using the built-in
> procedures" in the the
> Tools Guide to the procedure description in the Ref Manual.
Same issues as "Parameters for the import procedures".
> In the topic "Examples of bulk import and export" please provide examples for
> SYSCS_UTIL.SYSCS_IMPORT_DATA_LOBS_FROM_EXTFILE and
> SYSCS_UTIL.SYSCS_IMPORT_DATA
Added in my review my comments.
> In the topic "Bulk import and export requirements and considerations" in the
> section "Data types" it
> says "You can import and export only data of the non-binary, built-in data
> types." Is that statement still true with the new procedures?
No. Please correct it. Only XML type is not supported.
> In the topic "Bulk import and export of large objects" I created 2 paragraphs
> at the beginning to try to explain the difference between CLOB/BLOB data and
> the FOR BIT DATA types. , I don't know if I expressed this correctly. Please
> confirm.
looks good , posted comments I had as part of review comments.
> Add documentation for import/export of LOBS and other binary data types.
> ---------------------------------------------------------------------------
>
> Key: DERBY-2527
> URL: https://issues.apache.org/jira/browse/DERBY-2527
> Project: Derby
> Issue Type: Improvement
> Components: Documentation
> Affects Versions: 10.3.0.0
> Reporter: Suresh Thalamati
> Assigned To: Laura Stewart
> Attachments: derbytools.pdf, iexlobs_v1.txt, refderby.pdf
>
>
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
