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 Susan Cline <ho...@pacbell.net> on 2006/09/06 21:28:41 UTC
dblook and lower-case table names created with double-quotes, doc bug or "bug" bug?
In reviewing the dblook examples in the Tools and Utilities Guide:
http://db.apache.org/derby/docs/dev/tools/rtoolsdblookexamples.html
I noticed the output from using the -t flag with dblook to specify a particular table created using
lower case names and double-quotes is inconsistent when creating tablenames in upper case and double-quoting the name.
Testing these combinations, case 3 and 5 do not work as expected.
Create tables in lower and upper case, some with one word, and quoted, some with multiple words:
1) create table lower_case_one_word(id integer);
2) create table UPPER_CASE_ONE_WORD(id integer);
3) create table "lower_case_quoted_word"(id integer);
4) create table "UPPER_CASE_QUOTED_WORD"(id integer);
5) create table "lower_case quoted three_words"(id integer);
6) create table "UPPER_CASE QUOTED THREE_WORDS"(id integer);
I tested using dblook directly, org.apache.derby.tools.dblook and derbyrun.jar, with the same
results.
Use the -t argument for dblook:
3) create table "lower_case_quoted_word"(id integer);
This does not work if it is passed if lower case, upper case or double quotes or not are used:
java -jar C:\derby_src\db-derby-10.2.1.2-bin\lib\derbyrun.jar dblook -d jdbc:derby://localhost:1527/C:\derby_s
rc\db-derby-10.2.1.2-bin\demo\databases\toursDB -z APP -t lower_case_quoted_word
-- Timestamp: 2006-09-06 11:01:30.9
-- Source database is: C:\derby_src\db-derby-10.2.1.2-bin\demo\databases\toursDB
-- Connection URL is: jdbc:derby://localhost:1527/C:\derby_src\db-derby-10.2.1.2
-bin\demo\databases\toursDB
-- The dblook utility will consider only specified tables.
-- Specified schema is: APP
-- appendLogs: false
java -jar C:\derby_src\db-derb-10.2.1.2-bin\lib\derbyrun.jar dblook -d jdbc:derby://localhost:1527/C:\derby_s
rc\db-derby-10.2.1.2-bin\demo\databases\toursDB -z APP -t "lower_case_quoted_word"
-- Timestamp: 2006-09-06 11:03:32.585
-- Source database is: C:\derby_src\db-derby-10.2.1.2-bin\demo\databases\toursDB
-- Connection URL is: jdbc:derby://localhost:1527/C:\derby_src\db-derby-10.2.1.2
-bin\demo\databases\toursDB
-- The dblook utility will consider only specified tables.
-- Specified schema is: APP
-- appendLogs: false
java -jar C:\derby_src\db-derby-10.2.1.2-bin\lib\derbyrun.jar dblook -d jdbc:derby://localhost:1527/C:\derby_s
rc\db-derby-10.2.1.2-bin\demo\databases\toursDB -z APP -t "LOWER_CASE_QUOTED_WORD"
-- Timestamp: 2006-09-06 12:17:43.425
-- Source database is: C:\derby_src\db-derby-10.2.1.2-bin\demo\databases\toursDB
-- Connection URL is: jdbc:derby://localhost:1527/C:\derby_src\db-derby-10.2.1.2
-bin\demo\databases\toursDB
-- The dblook utility will consider only specified tables.
-- Specified schema is: APP
-- appendLogs: false
java -jar C:\derby_src\db-derby-10.2.1.2-bin\lib\derbyrun.jar dblook -d jdbc:derby://localhost:1527/C:\derby_s
rc\db-derby-10.2.1.2-bin\demo\databases\toursDB -z APP -t LOWER_CASE_QUOTED_WORD
-- Timestamp: 2006-09-06 12:18:00.49
-- Source database is: C:\derby_src\db-derby-10.2.1.2-bin\demo\databases\toursDB
-- Connection URL is: jdbc:derby://localhost:1527/C:\derby_src\db-derby-10.2.1.2
-bin\demo\databases\toursDB
-- The dblook utility will consider only specified tables.
-- Specified schema is: APP
-- appendLogs: false
5) create table "lower_case quoted three_words"(id integer);
This does not work whether the argument is in lower case or upper case and double quoted:
java -jar C:\derby_src\db-derby-10.2.1.2-bin\lib\derbyrun.jar dblook -d jdbc:derby://localhost:1527/C:\derby_s
rc\db-derby-10.2.1.2-bin\demo\databases\toursDB -z APP -t "lower_case quoted three_words"
-- Timestamp: 2006-09-06 11:09:11.352
-- Source database is: C:\derby_src\db-derby-10.2.1.2-bin\demo\databases\toursDB
-- Connection URL is: jdbc:derby://localhost:1527/C:\derby_src\db-derby-10.2.1.2
-bin\demo\databases\toursDB
-- The dblook utility will consider only specified tables.
-- Specified schema is: APP
-- appendLogs: false
java -jar C:\derby_src\db-derby-10.2.1.2-bin\lib\derbyrun.jar dblook -d jdbc:derby://localhost:1527/C:\derby_s
rc\db-derby-10.2.1.2-bin\demo\databases\toursDB -z APP -t "LOWER_CASE QUOTED THREE_WORDS"
-- Timestamp: 2006-09-06 12:20:42.553
-- Source database is: C:\derby_src\db-derby-10.2.1.2-bin\demo\databases\toursDB
-- Connection URL is: jdbc:derby://localhost:1527/C:\derby_src\db-derby-10.2.1.2
-bin\demo\databases\toursDB
-- The dblook utility will consider only specified tables.
-- Specified schema is: APP
-- appendLogs: false
Is this a doc bug or a bug in the code?
Thanks,
Susan
Re: dblook and lower-case table names created with double-quotes,
doc bug or "bug" bug?
Posted by Army <qo...@gmail.com>.
Army wrote:
>
> With K-shell on Windows the double-quotes are stripped off before before
> they ever make it to dblook. So this ends up looking for a table named
> LOWER_CASE_QUOTED_WORD, which doesn't exist.
<snip>
> but that's not all--K-shell looks at the space as an argument delimiter
> and thus the above command will look for tables named '"lower_case',
> 'quoted', and 'three_words"'--i.e. won't find any of them.
As a follow-up thought, perhaps you could file an enhancement request so that
instead of printing:
-- The dblook utility will consider only specified tables.
dblook will actually print the table names as it received them from the command
line. Then the user can see what s/he passed in and can perhaps catch cases
where the quotes were misused. I don't know know off-hand how hard that would
be, but perhaps it's worth a Jira...
Army
Re: dblook and lower-case table names created with double-quotes,
doc bug or "bug" bug?
Posted by Army <qo...@gmail.com>.
Laura Stewart wrote:
> On 9/6/06, Susan L. Cline <ho...@pacbell.net> wrote:
>
>>
>> Agreed - I think either we make a note to the effect above and give at
>> least one example, or we
>> remove the entire example that uses a table with quotes.
>
> Please open a JIRA issue for these changes :-)
This is being tracked from:
http://wiki.apache.org/db-derby/ToolsUtilitesTenTwo
in a fashion similar to the other doc review comments for other books. Is there
anything in particular about this specific change that makes it worthy of a Jira
issue? I think there are a lot of doc review comments on the Wiki that do not
have corresponding Jira entries, and several link to email threads like this
one. In fact, I (perhaps naively) thought that's what the Wiki page was for...
Ex. see http://wiki.apache.org/db-derby/ReferenceManualTenTwo
Should all of the doc review comments have corresponding Jira issues? Or is
this just a special case?
My apologies if I've misunderstood how the Wiki is being used here...
Army
Re: dblook and lower-case table names created with double-quotes, doc bug or "bug" bug?
Posted by Laura Stewart <sc...@gmail.com>.
On 9/6/06, Susan L. Cline <ho...@pacbell.net> wrote:
>
> Agreed - I think either we make a note to the effect above and give at least one example, or we
> remove the entire example that uses a table with quotes.
>
Please open a JIRA issue for these changes :-)
--
Laura Stewart
Re: dblook and lower-case table names created with double-quotes, doc bug or "bug" bug?
Posted by "Susan L. Cline" <ho...@pacbell.net>.
--- "Susan L. Cline" <ho...@pacbell.net> wrote:
> --- Army <qo...@gmail.com> wrote:
> > Susan Cline wrote:
> > > In reviewing the dblook examples in the Tools and Utilities Guide:
> > >
> > > http://db.apache.org/derby/docs/dev/tools/rtoolsdblookexamples.html
> > >
> > > I noticed the output from using the -t flag with dblook to specify
> > > a particular table created using lower case names and double-quotes
> > > is inconsistent when creating tablenames in upper case and double-
> > > quoting the name.
> >
[ snip ]
> > If you think specific examples of using quotes/spaces would be more helpful than
> > confusing, you should certainly feel free to add them!
>
> Thanks for the demonstration Army, and the history. I can see why this would be confusing to
> document.
>
> > > Is this a doc bug or a bug in the code?
> >
> > I would say "doc bug", but that does't mean the examples are wrong. Instead, we
> > should probably add a note to the documentation explaining that the quotes shown
> > in the examples are *part* of the argument and need to be passed to dblook; how
> > that happens depends on the command-line being used. Then, as mentioned above,
> > if anyone thinks some specific examples would be helpful, then s/he/they should
> > definitely follow-up to get some examples into the doc...
>
> Agreed - I think either we make a note to the effect above and give at least one example, or we
> remove the entire example that uses a table with quotes.
>
How do you think this sounds to replace the two existing examples where the two -t "My Table"
examples are shown?
Replace this:
Dump the DDL for all objects with schema 'SAMP' in database 'sample' that are related to the table
name 'My Table' to the console.
java org.apache.derby.tools.dblook -d jdbc:derby:sample -z samp -t "My Table".
With this:
Dump the DDL for all objects with schema 'SAMP' in database 'sample' that are related to the table
name 'My Table' to the console.
The quotes shown for the table argument are part of the argument and need to be passed to dblook.
Escaping these quotes depends on the command line being used.
For instance on a Windows command line the command make take this form:
java org.apache.derby.tools.dblook -d jdbc:derby:sample -z samp -t "\"My Table\"".
Using the C-shell on a Linux platform may require this command:
java org.apache.derby.tools.dblook -d jdbc:derby:sample -z samp -t '"My Table"'.
---------------------------------------------------------------------------------
For the second example, replace this:
Dump the DDL for all objects in database 'sample' that are related
to either of the table names 'STAFF' or 'My Table' to the console.
java org.apache.derby.tools.dblook -d jdbc:derby:sample -t "My Table" staff
With this:
Dump the DDL for all objects in database 'sample' that are related
to either of the table names 'STAFF' or 'My Table' to the console.
The quotes shown for the table argument are part of the argument and need to be passed to dblook.
Escaping these quotes depends on the command-line being used.
For instance on a Windows command line the command make take this form:
java org.apache.derby.tools.dblook -d jdbc:derby:sample -z samp -t "\"My Table\"" staff
Using the C-shell on a Linux platform may require this command:
java org.apache.derby.tools.dblook -d jdbc:derby:sample -z samp -t '"My Table"' staff
Thanks,
Susan
Re: dblook and lower-case table names created with double-quotes, doc bug or "bug" bug?
Posted by "Susan L. Cline" <ho...@pacbell.net>.
--- Army <qo...@gmail.com> wrote:
> Susan Cline wrote:
> > In reviewing the dblook examples in the Tools and Utilities Guide:
> >
> > http://db.apache.org/derby/docs/dev/tools/rtoolsdblookexamples.html
> >
> > I noticed the output from using the -t flag with dblook to specify
> > a particular table created using lower case names and double-quotes
> > is inconsistent when creating tablenames in upper case and double-
> > quoting the name.
>
> I think the issue here is the way the command-line handles quotes. Different
> command lines handle quotes differently. When the documentation for dblook was
> first being written, there were all kinds of notes and explanations and
> exceptions in the documentation about how and when to use single vs double vs
> escaped quotes, and they became more and more complex with every draft. It was
> eventually decided that proper use of the quotes for a specific command line was
> the responsibility of the user--trying to give examples of how to use quotes
> seemed like it could cause more confusion than anything because the examples
> would inevitably work for one command-line but not another.
[ snip ]
> And that's just one way to do it; I'm sure there are others. But to try to
> document this just seems like it's asking for user confusion, so I think the
> assumption is that the user will figure out how his/her command-line deals with
> quotes (and spaces).
>
> If you think specific examples of using quotes/spaces would be more helpful than
> confusing, you should certainly feel free to add them!
Thanks for the demonstration Army, and the history. I can see why this would be confusing to
document.
> > Is this a doc bug or a bug in the code?
>
> I would say "doc bug", but that does't mean the examples are wrong. Instead, we
> should probably add a note to the documentation explaining that the quotes shown
> in the examples are *part* of the argument and need to be passed to dblook; how
> that happens depends on the command-line being used. Then, as mentioned above,
> if anyone thinks some specific examples would be helpful, then s/he/they should
> definitely follow-up to get some examples into the doc...
Agreed - I think either we make a note to the effect above and give at least one example, or we
remove the entire example that uses a table with quotes.
Re: dblook and lower-case table names created with double-quotes,
doc bug or "bug" bug?
Posted by Army <qo...@gmail.com>.
Susan Cline wrote:
> In reviewing the dblook examples in the Tools and Utilities Guide:
>
> http://db.apache.org/derby/docs/dev/tools/rtoolsdblookexamples.html
>
> I noticed the output from using the -t flag with dblook to specify
> a particular table created using lower case names and double-quotes
> is inconsistent when creating tablenames in upper case and double-
> quoting the name.
I think the issue here is the way the command-line handles quotes. Different
command lines handle quotes differently. When the documentation for dblook was
first being written, there were all kinds of notes and explanations and
exceptions in the documentation about how and when to use single vs double vs
escaped quotes, and they became more and more complex with every draft. It was
eventually decided that proper use of the quotes for a specific command line was
the responsibility of the user--trying to give examples of how to use quotes
seemed like it could cause more confusion than anything because the examples
would inevitably work for one command-line but not another.
> Testing these combinations, case 3 and 5 do not work as expected.
>
> 3) create table "lower_case_quoted_word"(id integer);
java -jar ... dblook -d myDB -z APP -t "lower_case_quoted_word"
With K-shell on Windows the double-quotes are stripped off before before they
ever make it to dblook. So this ends up looking for a table named
LOWER_CASE_QUOTED_WORD, which doesn't exist. In order for this to work you have
to ensure that the quotes actually make it to dblook--i.e. that the command-line
doesn't strip them off. One way to do this is to escape them:
java -jar ... dblook -d myDB -z APP -t \"lower_case_quoted_word\"
> 5) create table "lower_case quoted three_words"(id integer);
In this you again need to escape the quotes:
java -jar ... dblook -d myDB -z APP -t \"lower_case quoted three_words\"
but that's not all--K-shell looks at the space as an argument delimiter and thus
the above command will look for tables named '"lower_case', 'quoted', and
'three_words"'--i.e. won't find any of them. So you have to tell K-shell to
treat the whole thing as a single argument, which you do by putting ADDITIONAL
quotes around the whole thing:
java -jar ... dblook -d myDB -z APP -t "\"lower_case quoted three_words\""
And that's just one way to do it; I'm sure there are others. But to try to
document this just seems like it's asking for user confusion, so I think the
assumption is that the user will figure out how his/her command-line deals with
quotes (and spaces).
If you think specific examples of using quotes/spaces would be more helpful than
confusing, you should certainly feel free to add them!
> Is this a doc bug or a bug in the code?
I would say "doc bug", but that does't mean the examples are wrong. Instead, we
should probably add a note to the documentation explaining that the quotes shown
in the examples are *part* of the argument and need to be passed to dblook; how
that happens depends on the command-line being used. Then, as mentioned above,
if anyone thinks some specific examples would be helpful, then s/he/they should
definitely follow-up to get some examples into the doc...
Army