[jira] Commented: (DERBY-2527) Add documentation for import/export of LOBS and other binary data types.

["Laura Stewart (JIRA)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/DERBY-2527?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12494139 ] 

Laura Stewart commented on DERBY-2527:
--------------------------------------

Suresh - 

I updated the topics based on your comments and answers to my questions. I will post a patch and updated PDFs soon.

My responses to your comments/questions are below:

Derby Reference Manual: 

1) Usage - There are several sections typically used in SQL References, for example:
Invocation, Authorization, Syntax, Notes (numbered notes on the syntax), Description (where the parameters are described), Usage, Examples.
Not all of these are used but can be.  I do think that we need to have something, so I left Usage in because it does point off to the Tools Guide where we do talk about usage. However, I did move the paragraph you were concerned about outside of the Usage section.

2) We still need an example for 
SYSCS_UTIL.SYSCS_EXPORT_QUERY_LOBS_TO_EXTFILE

3) lobsFileName parameter description needs a small change - DONE 


Derby Tools Guide : 
------------------ 

1) a /(slash) is missing the reference format. - DONE 

2) 
a) It may be better to say, something like: "export data from columns of types " - DONE  

b) I think, it might be to say: "To import data into a table, that has columns of these data types, the data in the 
import file for those column must be in the hexadecimal format"  - DONE

3) ... you may want to remove the phrase " No result is returned from this procedure" - DONE 

4) I think we should mention user can use "SYSCS_UTIL.SYSCS_IMPORT_DATA_LOBS_FROM_EXTFILE"  - DONE

5) Same as page 49/50, you may want to remove the phrase " No result is returned from this procedure"  - DONE

6) update the description of the lobsFileName parameter. - DONE

7)  
a) Some of the examples have table name lower case as 'staff table name in all of the should be in upper case as 'STAFF'  - DONE

b) Please add the following two new examples using SYSCS_UTIL.SYSCS_IMPORT_DATA and 
SYSCS_UTIL.SYSCS_IMPORT_DATA_LOBS_FROM_EXTFILE - DONE

>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. 

*** (LS) I left  the examples in both Ref Guide and Tools Guide for now...

> 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. 

*** (LS) Okay. No Change.


> 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. 

*** (LS) Changed to uppercase.
  
>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. 

*** (LS) DONE

> 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. 

*** (LS) The parameters for each system procedure MUST be listed with the syntax in the Ref Guide, so I can't combine them like we do in the Tools Guide.  I have left the duplication there for now, but in the future I will be asking derby-dev about improving the docs and avoiding duplication.  Generally all reference info, examples, parameters etc should be in the Ref Guide and the Tools guide should show usage with pointers to the ref info, not duplicate what is in the Ref Guide.  But I'll ask the community and see what they say... probably post 10.3 :-)

> 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. 

 *** (LS) DONE

> 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". 
 
*** (LS) Same response, left duplication there for now.

> 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. 

*** (LS) I'm still missing an example for SYSCS_UTIL.SYSCS_EXPORT_QUERY_LOBS_TO_EXTFILE

> 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. 

*** (LS) DONE


> 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. 

*** (LS) Thanks!

> 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.