You are viewing a plain text version of this content. The canonical link for it is here.
Posted to derby-dev@db.apache.org by "Suresh Thalamati (JIRA)" <ji...@apache.org> on 2007/04/05 21:11:32 UTC
[jira] Created: (DERBY-2527) Add documentation for import/export
of LOBS and other binary data types.
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
Attachments: iexlobs_v1.txt
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (DERBY-2527) Add documentation for import/export
of LOBS and other binary data types.
Posted by "Suresh Thalamati (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2527?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12497112 ]
Suresh Thalamati commented on DERBY-2527:
-----------------------------------------
Thanks Laura, I reviewed the import/export related sections in the attached
pdf files, changes looks good. Please commit the changes.
Some Minor things I noticed when I was reading through the doc again :
Derby tools Guide :
1)
On Page 46 :
It says , in the second section : "The import and export procedures read and
write only text files" not true any more , import/export writes and reads
binary data from the external lob file.
Please remove that sentence or change it to the following :
The import and export procedures read and write only text files, except when
blob data is imported or exported using an external file.
2) on Page 47 : section :Bulk import and export requirements and
considerations:
"
Restrictions on delimiters
You cannot specify Hex decimal characters (0-9, a-f, A-F) as delimiters for the import
and export procedures"
you may want to remove the above , I don't want users to think that is the only
delimiter restriction.
This restriction is already listed under "File format for input and output" on
page page 49 :( Delimiters cannot be hex decimal characters (0-9, a-f, A-F).)
along with other delimiter restrictions.
3) I really like the way you listed procedures. One minor thing I noticed is :
a)
On page 50 :
1. Choose the correct procedure for the type of import that you want to perform:
and
For examples using these procedures, see Examples of bulk import and export.
Derby Tools and Utilities Guide
52
looks out of place.
you may want to have heading as : "Import Procedures "
and the below/above the table , write something like:
Choose the correct procedure for the type of import that you want to perform
from the table. For examples using these procedures,
see Examples of bulk import and export.Derby Tools and Utilities Guide
b) on page 52 , please do the same for export procedures.
Derby Reference Guide :
On page 126: SYSCS_UTIL.SYSCS_EXPORT_TABLE_LOBS_TO_EXTFILE example:
CALL SYSCS_UTIL.SYSCS_EXPORT_TABLE_LOBS_TO_EXTFILE(
'APP', 'STAFF', 'c:\data\staff.del', ', ', '"',
'UTF-8', 'c:\data\pictures.dat')
delete the space in the column delimiter parameter value : ', '
it shoud be just ','
Thanks
-suresh
> 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: derby2527_1.diff, derbytools.pdf, derbytools.pdf, iexlobs_v1.txt, refderby.pdf, refderby.pdf
>
>
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (DERBY-2527) Add documentation for import/export
of LOBS and other binary data types.
Posted by "Suresh Thalamati (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2527?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12488527 ]
Suresh Thalamati commented on DERBY-2527:
-----------------------------------------
#2 : I agree with you. "Changging the sentence to "Passing a NULL value will result in an error." makes it more clear.
#3. I will post an example using SYSCS_UTIL.SYSCS_IMPORT_DATA_LOBS_FROM_EXTFILE(...)
[
> 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: iexlobs_v1.txt
>
>
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Updated: (DERBY-2527) Add documentation for import/export
of LOBS and other binary data types.
Posted by "Suresh Thalamati (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2527?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Suresh Thalamati updated DERBY-2527:
------------------------------------
Attachment: iexlobs_v1.txt
updated version of spec and some notes for the documentation.
> 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
> Attachments: iexlobs_v1.txt
>
>
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (DERBY-2527) Add documentation for import/export
of LOBS and other binary data types.
Posted by "Laura Stewart (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2527?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12488210 ]
Laura Stewart commented on DERBY-2527:
--------------------------------------
In the list of arguments, there is this text on many of the parameters "Passing a null will result in an error."
The current text might be confusing since other parameters allow a NULL value.
I propose that we change it to:
"Omitting this parameter or passing a NULL value will result in a error"
Is this new phrasing accurate?
> 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: iexlobs_v1.txt
>
>
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (DERBY-2527) Add documentation for import/export
of LOBS and other binary data types.
Posted by "Suresh Thalamati (JIRA)" <ji...@apache.org>.
[ 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.
[jira] Commented: (DERBY-2527) Add documentation for import/export
of LOBS and other binary data types.
Posted by "Suresh Thalamati (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2527?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12487958 ]
Suresh Thalamati commented on DERBY-2527:
-----------------------------------------
Thanks for volunteering to write the documentation , Laura. My comments are
below for the questions you posted.
1) Regarding null arguments.
yes. if user passes null value for any of the argument for import/export procedures ,
default value is used. If user passes null as argument for schema
name, current schema is used. Default value for for column delimiter
is comma (,) and the default value for character delimiter is double
quote("). Default for the codeset depends on the environment user has started the jvm.
It might be better to have an example that does not have null, to be more
clear. Please use the following example instead of the ones in the spec.
CALL SYSCS_UTIL.SYSCS_EXPORT_TABLE_LOBS_TO_EXTFILE('APP','STAFF',
'c:\data\staff.del',',','"','UTF-8', 'c:\data\pictures.dat');
CALL SYSCS_UTIL.SYSCS_IMPORT_TABLE_LOBS_FROM_EXTFILE(
'APP','STAFF','c:\data\staff.del',',','"','UTF-8',0);
2)Reading how to document definition of the procedures.
This is not my creativity, I have just been following the same format as
other ones already in the documentation.
>> Laur wrote:
>>SYSCS_UTIL.SYSCS_IMPORT_DATA (IN SCHEMANAME VARCHAR(128),
>IN TABLENAME VARCHAR(128), IN INSERTCOLUMNS VARCHAR(32672),
>>IN COLUMNINDEXES VARCHAR(32672), IN FILENAME VARCHAR(32672),
>>IN COLUMNDELIMITER CHAR(1), IN CHARACTERDELIMITER CHAR(1),
>> IN CODESET VARCHAR(128), IN REPLACE SMALLINT)
>>The syntax should appear in the docs as:
>> SYSCS_UTIL.SYSCS_IMPORT_DATA(
>> SCHEMANAME, TABLENAME, INSERTCOLUMNS, COLUMNINDEXES, FILENAME, COLUMNDELIMITER,
>> CHARACTERDELIMITER, CODESET, REPLACE
>> )
No. It can not be that simple. Type of the arguments needs to be documented.
"IN" is to indicate that it is an input parameter. Procedure can have
OUT or INOUT type parameters. I find the above definition useful , just
by looking at the syntax , I can set the correct parameters instead of reading
through the whole doc.
May be the current way of documenting is not the best approach. If you have
some ideas to improve it, please file a separate jira. May be others will
have some opinions.
> 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: iexlobs_v1.txt
>
>
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (DERBY-2527) Add documentation for import/export
of LOBS and other binary data types.
Posted by "Laura Stewart (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2527?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12488198 ]
Laura Stewart commented on DERBY-2527:
--------------------------------------
I have a question about this text:
In the topic "Bulk import/export requirements and considerations"
The table must exist
For you to import data into a table, the table must already exist in Derby.
The table does not have to be empty. If the table is not empty, bulk import
performs single inserts which results in slower performance.
The phrase "performs single inserts" ... should that be "performs single row inserts" ???
> 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: iexlobs_v1.txt
>
>
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (DERBY-2527) Add documentation for import/export
of LOBS and other binary data types.
Posted by "Suresh Thalamati (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2527?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12492425 ]
Suresh Thalamati commented on DERBY-2527:
-----------------------------------------
Thanks Laura, I read through the sections related to this issue in the PDF
files you attached. Changes looks good, I have few comments :
Derby Reference Manual:
1) In pages 131/133: do we really need the heading "Usage" , it is kind of
misleading to me. Info under is more of detail on how references to
lob are stored in the main import file. Not really usage. May be
it is correct, just thought I will mention it.
Context : Pages 131/ 133
"
Usage
This procedure will read the LOB data using the reference that is stored in the
main
"
2) Examples need to be added for all the new procedures
SYSCS_EXPORT_TABLE_LOBS_TO_EXTFILE , SYSCS_EXPORT_QUERY_LOBS_TO_EXTFILE,
SYSCS_IMPORT_LOBS_FROM_EXTFILE and SYCS_IMPORT_DATA_LOBS_FROM_EXTFILE
3) lobsFileName parameter description needs a small change. It is not updated in the spec.
In pages 126/ 128:
lobsFileName:
current:
"
Specifies the file that the large object data is exported to. If the path is omitted, the
current working directory is used."
lob files are created in the same location as the main export if the path is
not specified.
Correct Description should be :
"
Specifies the file that the large object data is exported to. If the path is omitted, the
lob file is created in the same directory as the main export file."
Derby Tools Guide :
------------------
1) page 28 , in the first paragraph :
"in the main import file in the format lobsFileName.Offset.length, which is the
same way"
a /(slash) is missing the reference format. it should be : lobsFileName.Offset.length/
2) page 47:
a)
current:
"When you export the data types CHAR FOR BIT DATA, VARCHAR FOR BIT DATA,"
It may be better to say, something like:
"export data from columns of types " instead of "export the data types"
b)
"To import these data types into a table, the data in the import file must be in the hexadecimal format."
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"
3) In Page 49/50, Great job with table that shows when to use , what procedure.
you may want to remove the phrase " No result is returned from this procedure" or
add it to the new procedure cases also, because they also don't return any result.
In my opinion the phrase does not add any value in this context.
4) On Page 51: I think we should mention user can use "SYSCS_UTIL.SYSCS_IMPORT_DATA_LOBS_FROM_EXTFILE"
something like :
You can use the SYSCS_UTIL.SYSCS_IMPORT_DATA or
SYSCS_UTIL.SYSCS_IMPORT_DATA_LOBS_FROM_EXTFILE procedures
to import data into a table that contains an identity column.
If the identity column is defined as GENERATED
5) On page : 52 , Same as page 49/50
you may want to remove the phrase " No result is returned from this procedure"
6) On page 53 : Please update the description of the lobsFileName parameter.
"If the path is omitted, the current working directory is used"
should be changed to : "If the path is omitted, the
lob file is created in the same directory as the main export file"
7) On Page 54:
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'
first example :
CALL SYSCS_UTIL.SYSCS_IMPORT_TABLE
(null,'staff','myfile.del',null,null,null,0);
table name shoud be 'STAFF'
please do the same for all the examples in this page.
b) Please add the following two new examples using SYSCS_UTIL.SYSCS_IMPORT_DATA and
SYSCS_UTIL.SYSCS_IMPORT_DATA_LOBS_FROM_EXTFILE into the example section in the
derby tools guild and also to the reference guide in the appropriate sections.
1)
Example importing only some columns from a delimited file
The following example shows how to import data into only some of the
columns of the staff table in a sample database from a specific columns
in the delimited data file staff.del. This example assumes data in the
import file is formatted using the double quote (") as the string delimiter,
and a comma(,) as the column delimiter. The data will be appended to the
existing data in the table.
CALL SYSCS_UTIL.SYSCS_IMPORT_DATA(NULL, 'STAFF',
'NAME,DEPT,SALARY', '2,3,4', 'c:\data\staff.del',',','"','UTF-8', 0)
2)
Example importing data into only some columns from both a main import file
that contains references that point to a separate file that contains LOB data
The following example shows how to import data into some columns of
the STAFF table, which includes a LOB column in a sample database from a
delimited data file staff.del, which has references to LOB data in an
external file.
This example assumes data in the import file is formatted using
double quote (") as the string delimiter, and a comma(,) as the
column delimiter. The data will be appended to the existing data
in the table.
CALL SYSCS_UTIL.SYSCS_IMPORT_DATA_LOBS_FROM_EXTFILE(NULL, 'STAFF',
'NAME,DEPT,SALARY,PICTURE', '2,3,4,6', 'c:\data\staff.del', ',','"','UTF-8',
0)
--
> 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.
[jira] Updated: (DERBY-2527) Add documentation for import/export
of LOBS and other binary data types.
Posted by "Laura Stewart (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2527?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Laura Stewart updated DERBY-2527:
---------------------------------
Attachment: derbytools.pdf
refderby.pdf
I have drafted the new topics and updated the existing topics that are associated with this issue.
I have attached the PDF files for the Ref Manual and Tools Guide because there are quite a few topics impacted by these updates. I have not attached a patch at this time because there are several questions that I would like to get answers to which will impact the final set of updated topics.
To review the updates:
*** In the Reference Manual, go to the section "Built-in system procedures". The import and export procedures are all groupded together.
*** In the Tools Guide, go the section "Using the bulk import and export procedures".
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?
Also, the other system procedures in the Ref Manual have separate examples for JDBC and SQL. Should the import/export have separate examples?
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?
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?
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.
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" ???
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.
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
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?
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.
> 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.
[jira] Commented: (DERBY-2527) Add documentation for import/export
of LOBS and other binary data types.
Posted by "Laura Stewart (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2527?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12488193 ]
Laura Stewart commented on DERBY-2527:
--------------------------------------
Suresh -
I see your point about the syntax. What should *ideally* appear is the syntax followed by an explanation of each parameter. That explanation contains the data type, lentgth, and if it is an IN, OUT, or INOUT parameter. For example:
SYSCS_UTIL.SYSCS_IMPORT_DATA(
SCHEMANAME, TABLENAME, INSERTCOLUMNS, COLUMNINDEXES, FILENAME, COLUMNDELIMITER,
CHARACTERDELIMITER, CODESET, REPLACE)
SCHEMANAME
An IN parameter that specifies the name of the schema. This parameter must be a VARCHAR data type with a maximum length of 128. If NULL is
specified for this parameter, the current schema is used.
TABLENAME
An IN parameter that specifies the name of the table. This parameter must be a VARCHAR data type with a maximum length of 128.
The TABLENAME is a required parameter.
etc...
For now, I will document it using the current convention in the books, but I will be opening a discussion about this to change it in the future. I justed wanted to explain this to you so that you would understand my ultimate goal.
> 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: iexlobs_v1.txt
>
>
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (DERBY-2527) Add documentation for import/export
of LOBS and other binary data types.
Posted by "Laura Stewart (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2527?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12488524 ]
Laura Stewart commented on DERBY-2527:
--------------------------------------
Suresh - Thank you for the responses.
#2 - There is a difference between using "null" and "NULL" in a sentence. Typically "null" means omitting the parameter value and "NULL" means speciflying NULL as the value. So for REPLACE, I would like to change this sentence:
"Passing a null value will result in an error."
to
"Passing a NULL value will result in an error."
Okay?
#3 - I see my confusion. ALL of the import examples are examples of IMPORT_TABLE instead of IMPORT_DATA. It would be helpful if we could show an example like the others but using SYSCS_UTIL.SYSCS_IMPORT_DATA_LOBS_FROM_EXTFILE(...)
> 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: iexlobs_v1.txt
>
>
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Resolved: (DERBY-2527) Add documentation for import/export
of LOBS and other binary data types.
Posted by "Laura Stewart (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2527?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Laura Stewart resolved DERBY-2527.
----------------------------------
Resolution: Fixed
Derby Info: (was: [Patch Available])
> 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: derby2527_1.diff, derby2527_2.diff, derby2527_3.diff, derbytools.pdf, derbytools.pdf, iexlobs_v1.txt, refderby.pdf, refderby.pdf
>
>
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (DERBY-2527) Add documentation for import/export
of LOBS and other binary data types.
Posted by "Suresh Thalamati (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2527?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12497107 ]
Suresh Thalamati commented on DERBY-2527:
-----------------------------------------
Thanks for addressing my comments, Laura. I read through your comments,
looks like you need my input only for this one:
>>We still need an example for
>>SYSCS_UTIL.SYSCS_EXPORT_QUERY_LOBS_TO_EXTFILE
Yes, it is similar to other SYSCS_EXPORT_QUERY procedures, But I agree with you
it will good to have an example for this one too.
Example exporting data from a query, using a separate export file for the LOB
data
The following example shows how to export employee data in department 20 from the
STAFF table in a sample database to the main file staff.del and the lob
data to the file pictures.dat.
CALL SYSCS_UTIL.SYSCS_EXPORT_QUERY_LOBS_TO_EXTFILE(
'SELECT * FROM STAFF WHERE dept=20',
'c:\data\staff.del', ',','"','UTF-8','c:\data\pictures.dat');
> 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: derby2527_1.diff, derbytools.pdf, derbytools.pdf, iexlobs_v1.txt, refderby.pdf, refderby.pdf
>
>
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (DERBY-2527) Add documentation for import/export
of LOBS and other binary data types.
Posted by "Laura Stewart (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2527?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12488225 ]
Laura Stewart commented on DERBY-2527:
--------------------------------------
Hi Suresh -
I'm confused about the import examples. Are the insertColumns and columnIndexes arguments optional? If so, then we should state that in the topic the describes the arguments. If not, then the examples need to be updated. Please advise :-)
> 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: iexlobs_v1.txt
>
>
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Updated: (DERBY-2527) Add documentation for import/export
of LOBS and other binary data types.
Posted by "Laura Stewart (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2527?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Laura Stewart updated DERBY-2527:
---------------------------------
Derby Info: [Patch Available]
> 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: derby2527_1.diff, derbytools.pdf, derbytools.pdf, iexlobs_v1.txt, refderby.pdf, refderby.pdf
>
>
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Assigned: (DERBY-2527) Add documentation for import/export
of LOBS and other binary data types.
Posted by "Laura Stewart (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2527?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Laura Stewart reassigned DERBY-2527:
------------------------------------
Assignee: Laura Stewart
> 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: iexlobs_v1.txt
>
>
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (DERBY-2527) Add documentation for import/export
of LOBS and other binary data types.
Posted by "Laura Stewart (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2527?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12487589 ]
Laura Stewart commented on DERBY-2527:
--------------------------------------
Thanks for the spec. I have a few questions.
I'm a little confused by the example:
CALL SYSCS_UTIL.SYSCS_EXPORT_TABLE_LOBS_TO_EXTFILE( null,'staff','c:\data\staff.del',null,null,null, 'c:\data\pictures.dat');
I don't quite understand all of the arguments for the SYSCS_UTIL.SYSCS_EXPORT_TABLE_LOBS_TO_EXTFILE system procedure.
Have these been documented yet?
Please explain the arguments in your example:
null = ? Is this supposed to be the schema name? If the user enters "null" does Derby take the current schema name?
staff' = source table name
'c:\data\staff.del' = main export file path and name
null = ? Is this supposed to be the columnDelimiter? If the user enters "null" what does Derby do? Is there a default columnDelimiter?
null = ? Is this supposed to be the characterdelimiter? If the user enters "null" what does Derby do? Is there a default characterdelimiter?
null = ?Is this supposed to be the codeset? If the user enters "null" what does Derby do? Is there a default codeset?
'c:\data\pictures.dat' = LOB column export file path and name
I see the current syntax for the IMPORT and EXPORT system procedures in the docs. And am glad to see that NULL is explained for each argument. But the syntax is shown in a very poor way. The user NEVER specifies "IN".
Instead of this:
SYSCS_UTIL.SYSCS_IMPORT_DATA (IN SCHEMANAME VARCHAR(128),
IN TABLENAME VARCHAR(128), IN INSERTCOLUMNS VARCHAR(32672),
IN COLUMNINDEXES VARCHAR(32672), IN FILENAME VARCHAR(32672),
IN COLUMNDELIMITER CHAR(1), IN CHARACTERDELIMITER CHAR(1),
IN CODESET VARCHAR(128), IN REPLACE SMALLINT)
The syntax should appear in the docs as:
SYSCS_UTIL.SYSCS_IMPORT_DATA(
SCHEMANAME, TABLENAME, INSERTCOLUMNS, COLUMNINDEXES, FILENAME, COLUMNDELIMITER,
CHARACTERDELIMITER, CODESET, REPLACE
)
The "IN", data type, and length should not appear in the syntax but in the explanation... do you agree???
> 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
> Attachments: iexlobs_v1.txt
>
>
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Updated: (DERBY-2527) Add documentation for import/export
of LOBS and other binary data types.
Posted by "Laura Stewart (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2527?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Laura Stewart updated DERBY-2527:
---------------------------------
Attachment: derbytools.pdf
refderby.pdf
derby2527_1.diff
Attaching the patch file and PDFs for the ref Guide and the Tools Guide.
> 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: derby2527_1.diff, derbytools.pdf, derbytools.pdf, iexlobs_v1.txt, refderby.pdf, refderby.pdf
>
>
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Updated: (DERBY-2527) Add documentation for import/export
of LOBS and other binary data types.
Posted by "Laura Stewart (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2527?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Laura Stewart updated DERBY-2527:
---------------------------------
Attachment: derby2527_3.diff
This patch resolves some conflicts with the svn revisions for the ref guide.
> 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: derby2527_1.diff, derby2527_2.diff, derby2527_3.diff, derbytools.pdf, derbytools.pdf, iexlobs_v1.txt, refderby.pdf, refderby.pdf
>
>
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (DERBY-2527) Add documentation for import/export
of LOBS and other binary data types.
Posted by "Suresh Thalamati (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2527?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12488505 ]
Suresh Thalamati commented on DERBY-2527:
-----------------------------------------
Thanks Laura. My comments are below for the questions you posted.
1)
>> The phrase "performs single inserts" ... should that be "performs single row
>>inserts" ???
yes. "performs single row inserts" is better.
2)
>>In the list of arguments, there is this text on many of the parameters "Passing a null will result in an error."
>>The current text might be confusing since other parameters allow a NULL value.
>>I propose that we change it to:
>> "Omitting this parameter or passing a NULL value will result in a error"
>>>Is this new phrasing accurate?
Omitting a parameter will result an error for all the system procedures. I think
it is not necessary to explicitly say that for some cases.
3)
>> I'm confused about the import examples. Are the insertColumns and
>>columnIndexes arguments optional?
No. There are required arguments when using SYSCS_UTIL.SYSCS_IMPORT_DATA(..)
or SYSCS_UTIL.SYSCS_IMPORT_DATA_LOBS_FROM_EXTFILE(...) .
They are not arguments for SYSCS_UTIL.SYSCS_IMPORT_TABLE() and
SYSCS_UTIL.SYSCS_IMPORT_TABLE_LOBS_FROM_EXTFILE(..)
My understanding of the doc in the tools guide is, user
follows the syntax defined for the procedures and finds the explanation for
the arguments in the "Arguments to import procedure page"(
http://db.apache.org/derby/docs/10.2/tools/rtoolsimport64241.html) depending
on what procedure he/she is using.
>>If so, then we should state that in the topic
>>the describes the arguments. If not, then the examples need to be
>>updated. Please advise :-)
If you find any examples, that are not correct. Please let me know,
I will verify them.
> 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: iexlobs_v1.txt
>
>
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (DERBY-2527) Add documentation for import/export
of LOBS and other binary data types.
Posted by "Laura Stewart (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2527?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12497503 ]
Laura Stewart commented on DERBY-2527:
--------------------------------------
The ref guide was updated with
Committed revision 540195.
> 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: derby2527_1.diff, derby2527_2.diff, derby2527_3.diff, derbytools.pdf, derbytools.pdf, iexlobs_v1.txt, refderby.pdf, refderby.pdf
>
>
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (DERBY-2527) Add documentation for import/export
of LOBS and other binary data types.
Posted by "Laura Stewart (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2527?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12497496 ]
Laura Stewart commented on DERBY-2527:
--------------------------------------
The tools guide was updated with
Committed revision 540191.
> 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: derby2527_1.diff, derby2527_2.diff, derbytools.pdf, derbytools.pdf, iexlobs_v1.txt, refderby.pdf, refderby.pdf
>
>
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Updated: (DERBY-2527) Add documentation for import/export
of LOBS and other binary data types.
Posted by "Laura Stewart (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2527?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Laura Stewart updated DERBY-2527:
---------------------------------
Attachment: derby2527_2.diff
Attaching updated patch.
> 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: derby2527_1.diff, derby2527_2.diff, derbytools.pdf, derbytools.pdf, iexlobs_v1.txt, refderby.pdf, refderby.pdf
>
>
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (DERBY-2527) Add documentation for import/export
of LOBS and other binary data types.
Posted by "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.