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 "Satheesh Bandaram (JIRA)" <de...@db.apache.org> on 2005/05/12 02:29:04 UTC
[jira] Created: (DERBY-275) Add documentation support for BY DEFAULT option, once code changes are made.
Add documentation support for BY DEFAULT option, once code changes are made.
----------------------------------------------------------------------------
Key: DERBY-275
URL: http://issues.apache.org/jira/browse/DERBY-275
Project: Derby
Type: Sub-task
Components: Documentation
Versions: 10.0.2.1
Reporter: Satheesh Bandaram
Fix For: 10.1.0.0
Once a patch is accepted, new syntax needs to be documented.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see:
http://www.atlassian.com/software/jira
[jira] Updated: (DERBY-275) Add documentation support for BY DEFAULT option, once code changes are made.
Posted by "Jeff Levitt (JIRA)" <de...@db.apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-275?page=all ]
Jeff Levitt updated DERBY-275:
------------------------------
Attachment: derby275finaldraftmodified.zip
Attached is a new patch fixing the problems requested by Army in:
http://mail-archives.apache.org/mod_mbox/db-derby-dev/200506.mbox/%3c42B83585.3020708@sbcglobal.net%3e
Army, I think your points are valid, and no one else had any objections, so I made the changes. The column default link was bad because when we moved it to the other file, the pointer to it wasn't changed to point to the new file, but it should look fine now.
> Add documentation support for BY DEFAULT option, once code changes are made.
> ----------------------------------------------------------------------------
>
> Key: DERBY-275
> URL: http://issues.apache.org/jira/browse/DERBY-275
> Project: Derby
> Type: Sub-task
> Components: Documentation
> Versions: 10.0.2.1
> Reporter: Satheesh Bandaram
> Fix For: 10.1.1.0
> Attachments: derby275finaldraftmodified.zip
>
> Once a patch is accepted, new syntax needs to be documented.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see:
http://www.atlassian.com/software/jira
[jira] Commented: (DERBY-275) Add documentation support for BY DEFAULT option, once code changes are made.
Posted by "Satheesh Bandaram (JIRA)" <de...@db.apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-275?page=comments#action_12314361 ]
Satheesh Bandaram commented on DERBY-275:
-----------------------------------------
I did a quick review... This looks good and can be committed.
> Add documentation support for BY DEFAULT option, once code changes are made.
> ----------------------------------------------------------------------------
>
> Key: DERBY-275
> URL: http://issues.apache.org/jira/browse/DERBY-275
> Project: Derby
> Type: Sub-task
> Components: Documentation
> Versions: 10.0.2.1
> Reporter: Satheesh Bandaram
> Fix For: 10.1.1.0
> Attachments: derby275finaldraftmodified.zip
>
> Once a patch is accepted, new syntax needs to be documented.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see:
http://www.atlassian.com/software/jira
Re: [jira] Commented: (DERBY-275) Add documentation support for BY DEFAULT option, once code changes are made.
Posted by Jeff Levitt <de...@mylevita.com>.
--- Army <qo...@sbcglobal.net> wrote:
> This probably goes without saying, but of course
> you'd have to include an
> explanation of what BY DEFAULT means, in addition to
> changing the syntax diagram :)
>
Yes, thats the plan...could someone provide me with a
good synopsis of why you'd use ALWAYS or BY DEFAULT
over each other? Whats the advantage and disadvantage
of both?
>
> Note, though, that a slight dblook modification
> should be made for DERBY-337;
> I'll post a comment to that issue and that can serve
> as the start of a new thread...
Yes, I'd be happy to do that as well, I'll make the
changes in that jira issue...
Re: [jira] Commented: (DERBY-275) Add documentation support for BY
DEFAULT option, once code changes are made.
Posted by Army <qo...@sbcglobal.net>.
Jeff Levitt (JIRA) wrote:
> [ http://issues.apache.org/jira/browse/DERBY-275?page=comments#action_12313327 ]
>
> Jeff Levitt commented on DERBY-275:
> -----------------------------------
>
> I was going to try to make a pass at a patch for the docs for
> this issue. It seems to me the only place that needs a change
> is in the Reference Manual, to change the syntax for generated
> column spec for Create Table to allow the option of either
> ALWAYS or BY DEFAULT. Is that the only place that needs
> changing?
This probably goes without saying, but of course you'd have to include an
explanation of what BY DEFAULT means, in addition to changing the syntax diagram :)
> It didn't look to me like there needed to be any changes to
> anything about dblook, because that change was under the covers...?
Yes, that's correct--i.e. no changes to the dblook documentation should be required.
Note, though, that a slight dblook modification should be made for DERBY-337;
I'll post a comment to that issue and that can serve as the start of a new thread...
Army
[jira] Commented: (DERBY-275) Add documentation support for BY DEFAULT option, once code changes are made.
Posted by "Jeff Levitt (JIRA)" <de...@db.apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-275?page=comments#action_12313327 ]
Jeff Levitt commented on DERBY-275:
-----------------------------------
I was going to try to make a pass at a patch for the docs for this issue. It seems to me the only place that needs a change is in the Reference Manual, to change the syntax for generated column spec for Create Table to allow the option of either ALWAYS or BY DEFAULT. Is that the only place that needs changing? It didn't look to me like there needed to be any changes to anything about dblook, because that change was under the covers...?
If someone can enlighten me, I could submit a patch very soon...Thanks!
> Add documentation support for BY DEFAULT option, once code changes are made.
> ----------------------------------------------------------------------------
>
> Key: DERBY-275
> URL: http://issues.apache.org/jira/browse/DERBY-275
> Project: Derby
> Type: Sub-task
> Components: Documentation
> Versions: 10.0.2.1
> Reporter: Satheesh Bandaram
> Fix For: 10.1.0.0
>
> Once a patch is accepted, new syntax needs to be documented.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see:
http://www.atlassian.com/software/jira
[jira] Updated: (DERBY-275) Add documentation support for BY DEFAULT option, once code changes are made.
Posted by "Jeff Levitt (JIRA)" <de...@db.apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-275?page=all ]
Jeff Levitt updated DERBY-275:
------------------------------
Attachment: derby275modified.zip
Attached patch add Army's feedback as requested in:
http://article.gmane.org/gmane.comp.apache.db.derby.devel/5792
Please verify that all looks good. Thanks!
> Add documentation support for BY DEFAULT option, once code changes are made.
> ----------------------------------------------------------------------------
>
> Key: DERBY-275
> URL: http://issues.apache.org/jira/browse/DERBY-275
> Project: Derby
> Type: Sub-task
> Components: Documentation
> Versions: 10.0.2.1
> Reporter: Satheesh Bandaram
> Fix For: 10.1.1.0
> Attachments: derby275modified.zip
>
> Once a patch is accepted, new syntax needs to be documented.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see:
http://www.atlassian.com/software/jira
Re: [jira] Commented: (DERBY-275) Add documentation support for BY DEFAULT option, once code changes are made.
Posted by Jeff Levitt <de...@mylevita.com>.
--- "Kathey Marsden (JIRA)" <de...@db.apache.org>
wrote:
> [
>
http://issues.apache.org/jira/browse/DERBY-275?page=comments#action_12314405
> ]
>
Hi Kathey,
This issue was committed and closed I think yesterday,
so it is already part of the DITA source. What I
would suggest is to just copy and paste your entire
comment into the Doc Review bug for this manual. That
way it will get fixed when the comments from that bug
get committed.
[jira] Commented: (DERBY-275) Add documentation support for BY DEFAULT option, once code changes are made.
Posted by "Kathey Marsden (JIRA)" <de...@db.apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-275?page=comments#action_12314405 ]
Kathey Marsden commented on DERBY-275:
--------------------------------------
REGARDING THIS PARAGRAPH:
Note that unlike a GENERATED ALWAYS column, a GENERATED BY DEFAULT column does not guarantee uniqueness. Thus, in the above example, the hi and salut rows will both have an identity value of "1", because the generated column starts at "1" and the user-specified value was also "1". To prevent this, you can use the "STARTS WITH" keyword described below. To check for this condition and disallow it, you can use a primary key or unique constraint on the GENERATED BY DEFAULT identity column.
In the paragraph STARTS WITH should be START WITH and loading or importing data should be covered.
CHANGE:
To prevent this, you can use the "STARTS WITH" keyword described below.
TO:
To prevent duplication especially when loading or importing data, create the table using a "START WITH" value which corresponds to the first
identity value that the system should assign.
ADD AN EXAMPLE:
create table greetings
(i int generated by default as identity (START WITH 2, INCREMENT BY 1),
ch char(50));
-- specify value "1":
insert into greetings values (1, 'hi');
-- use generated default
insert into greetings values (DEFAULT, 'salut');
-- use generated default
insert into greetings(ch) values ('bonjour');
> Add documentation support for BY DEFAULT option, once code changes are made.
> ----------------------------------------------------------------------------
>
> Key: DERBY-275
> URL: http://issues.apache.org/jira/browse/DERBY-275
> Project: Derby
> Type: Sub-task
> Components: Documentation
> Versions: 10.0.2.1
> Reporter: Satheesh Bandaram
> Fix For: 10.1.1.0
> Attachments: derby275finaldraftmodified.zip
>
> Once a patch is accepted, new syntax needs to be documented.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see:
http://www.atlassian.com/software/jira
[jira] Closed: (DERBY-275) Add documentation support for BY DEFAULT option, once code changes are made.
Posted by "Jean T. Anderson (JIRA)" <de...@db.apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-275?page=all ]
Jean T. Anderson closed DERBY-275:
----------------------------------
Resolution: Fixed
Committed, revision 201514, Jeff Levitt's patch that documents the BY DEFAULT option. Modified files:
$ svn status src
M src/ref/rrefsqlj24513.dita
M src/ref/rrefsqlj37836.dita
M src/ref/rrefsqlj30540.dita
> Add documentation support for BY DEFAULT option, once code changes are made.
> ----------------------------------------------------------------------------
>
> Key: DERBY-275
> URL: http://issues.apache.org/jira/browse/DERBY-275
> Project: Derby
> Type: Sub-task
> Components: Documentation
> Versions: 10.0.2.1
> Reporter: Satheesh Bandaram
> Fix For: 10.1.1.0
> Attachments: derby275finaldraftmodified.zip
>
> Once a patch is accepted, new syntax needs to be documented.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see:
http://www.atlassian.com/software/jira
Re: [jira] Updated: (DERBY-275) Add documentation support for BY
DEFAULT option, once code changes are made.
Posted by Army <qo...@sbcglobal.net>.
Jeff Levitt (JIRA) wrote:
> [ http://issues.apache.org/jira/browse/DERBY-275?page=all ]
>
> Jeff Levitt updated DERBY-275:
> ------------------------------
>
> Attachment: derby275finaldraft.zip
>
> Attached is the new patch.
1) The "CREATE TABLE" section with this new patch has the following:
"See rrefsqlj24513.html#rrefsqlj24513__sqlj64478."
I think that's supposed to be "See Column Default" (looks like maybe the name of
the link has been lost/invalidated?)
2) There should be some kind of header/separation between the CREATE TABLE
syntax and the subsequent examples (even something as simple "Examples:" would
be fine). That, and/or move the CREATE TABLE syntax up so that it's just under
the header (and would then be followed by the description, which seems more
clear to me).
3) In the "column-definition" section, I think the syntax should be changed to
distinguish a "normal" column default from a generated column default. I.e.
Simple-column-Name DataType
[ Column-level-constraint ]*
[ [ WITH ] DEFAULT {ConstantExpression | NULL }
| generated-column-spec ]
[ Column-level-constraint ]*
That way it's more clear what the "Column default" paragraph in the
"column-definition" section is referring to. And of course, if you do this,
then you'd want to remove the "[ WITH ] DEFAULT {ConstantExpression | NULL }"
from the syntax in the "generated-column-spec" section.
Also, this may not be related at all to this patch, but as of this morning when
I try to open the PDF version of the Reference manual on the Apache website, I'm
getting an error saying "The file is damaged and could not be repaired." This
worked fine yesterday...
Hopefully these are the last changes required to complete this patch. And
please note that this is all just according to my own personal opinion; I'm
hoping that if anyone out there disagrees with any of this feedback (including
you, Jeff :), s/he will speak up...
Army
[jira] Updated: (DERBY-275) Add documentation support for BY DEFAULT option, once code changes are made.
Posted by "Jeff Levitt (JIRA)" <de...@db.apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-275?page=all ]
Jeff Levitt updated DERBY-275:
------------------------------
Attachment: derby275finaldraft.zip
Attached is the new patch. I just made all the changes you requested, it was easy to just make the changes in this issue, since they are all related. Please let me know if all looks good. Thanks!
> Add documentation support for BY DEFAULT option, once code changes are made.
> ----------------------------------------------------------------------------
>
> Key: DERBY-275
> URL: http://issues.apache.org/jira/browse/DERBY-275
> Project: Derby
> Type: Sub-task
> Components: Documentation
> Versions: 10.0.2.1
> Reporter: Satheesh Bandaram
> Fix For: 10.1.1.0
> Attachments: derby275finaldraft.zip
>
> Once a patch is accepted, new syntax needs to be documented.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see:
http://www.atlassian.com/software/jira
[jira] Commented: (DERBY-275) Add documentation support for BY DEFAULT option, once code changes are made.
Posted by "A B (JIRA)" <de...@db.apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-275?page=comments#action_12314356 ]
A B commented on DERBY-275:
---------------------------
This looks okay to me. I think Satheesh and/or Tomohito should look it over to make sure, but if they have no comments, then I say commit it...
> Add documentation support for BY DEFAULT option, once code changes are made.
> ----------------------------------------------------------------------------
>
> Key: DERBY-275
> URL: http://issues.apache.org/jira/browse/DERBY-275
> Project: Derby
> Type: Sub-task
> Components: Documentation
> Versions: 10.0.2.1
> Reporter: Satheesh Bandaram
> Fix For: 10.1.1.0
> Attachments: derby275finaldraftmodified.zip
>
> Once a patch is accepted, new syntax needs to be documented.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see:
http://www.atlassian.com/software/jira
[jira] Updated: (DERBY-275) Add documentation support for BY DEFAULT option, once code changes are made.
Posted by "Jeff Levitt (JIRA)" <de...@db.apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-275?page=all ]
Jeff Levitt updated DERBY-275:
------------------------------
Attachment: derby275.zip
Attached zip includes a patch that attempts to document this in the generated-column-spec topic. HTML output is included for review.
> Add documentation support for BY DEFAULT option, once code changes are made.
> ----------------------------------------------------------------------------
>
> Key: DERBY-275
> URL: http://issues.apache.org/jira/browse/DERBY-275
> Project: Derby
> Type: Sub-task
> Components: Documentation
> Versions: 10.0.2.1
> Reporter: Satheesh Bandaram
> Fix For: 10.1.0.0
> Attachments: derby275.zip
>
> Once a patch is accepted, new syntax needs to be documented.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see:
http://www.atlassian.com/software/jira
[jira] Commented: (DERBY-275) Add documentation support for BY DEFAULT option, once code changes are made.
Posted by "A B (JIRA)" <de...@db.apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-275?page=comments#action_12314111 ]
A B commented on DERBY-275:
---------------------------
With this latest patch, it looks like some text in the "CREATE TABLE" section was orphaned. More specifically, the following lines should be moved to the "Identity column attributes" section with the rest of the related info:
----
The IDENTITY keyword can only be specified if the data type associated with the column is one of the following exact integer types.
* SMALLINT
* INT
* BIGINT
----
Actually, there seems to be a lot of column-specific information under the "CREATE TABLE" section that would be better if moved to the "Column-definition" section. For example, we talk about "Data types", "Column-level-constraints", and column defaults when none of those are used in the syntax diagram for CREATE TABLE. Wouldn't all of that make more sense under the "Column-definition" section? Of course, that's a problem that existed before this patch, so perhaps that should be a different issue to be filed against the Reference Manual later...?
In any event, the above lines (at the very least) should be moved to the same section that describes the GENERATED ALWAYS/BY DEFAULT keywords, since that's where IDENTITY columns are specified.
> Add documentation support for BY DEFAULT option, once code changes are made.
> ----------------------------------------------------------------------------
>
> Key: DERBY-275
> URL: http://issues.apache.org/jira/browse/DERBY-275
> Project: Derby
> Type: Sub-task
> Components: Documentation
> Versions: 10.0.2.1
> Reporter: Satheesh Bandaram
> Fix For: 10.1.1.0
> Attachments: derby275modified.zip
>
> Once a patch is accepted, new syntax needs to be documented.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see:
http://www.atlassian.com/software/jira