Uploaded image for project: 'Derby'
  1. Derby
  2. DERBY-4568

Documentation needed for sequence generators

    Details

    • Type: Task
    • Status: Closed
    • Priority: Major
    • Resolution: Fixed
    • Affects Version/s: None
    • Fix Version/s: 10.6.1.0
    • Component/s: Documentation
    • Labels:
      None

      Description

      DERBY-712 provides support for sequence generators, which now need to be documented.

      1. DERBY-4568-2.zip
        21 kB
        Kim Haase
      2. DERBY-4568-2.diff
        33 kB
        Kim Haase
      3. DERBY-4568.zip
        21 kB
        Kim Haase
      4. DERBY-4568.stat
        0.3 kB
        Kim Haase
      5. DERBY-4568.diff
        33 kB
        Kim Haase

        Issue Links

          Activity

          Hide
          chaase3 Kim Haase added a comment -

          Closing, since documentation appears in Latest Alpha Manuals.

          Show
          chaase3 Kim Haase added a comment - Closing, since documentation appears in Latest Alpha Manuals.
          Hide
          chaase3 Kim Haase added a comment -

          Thanks very much, Rick!

          Committed patch DERBY-4568-2.diff to documentation trunk at revision 930287.

          Show
          chaase3 Kim Haase added a comment - Thanks very much, Rick! Committed patch DERBY-4568 -2.diff to documentation trunk at revision 930287.
          Hide
          rhillegas Rick Hillegas added a comment -

          Thanks, Kim. The revised patch looks great. I agree with your treatment of SYSPERMS.ISGRANTABLE.

          +1

          Show
          rhillegas Rick Hillegas added a comment - Thanks, Kim. The revised patch looks great. I agree with your treatment of SYSPERMS.ISGRANTABLE. +1
          Hide
          chaase3 Kim Haase added a comment -

          Attaching DERBY-4568-2.diff and DERBY-4568-2.zip.

          Thanks very much for the edits, Rick. Hope the issues are fixed in this patch. One comment:

          rrefsistabssysperms, ISGRANTABLE: No other table has an ISGRANTABLE column. The closest is GRANTOPTION in SYSROUTINEPERMS, and I don't much like that language because it is unclear: "Specifies if the GRANTEE is the owner of the routine. Valid values are Y and N." It might seem to be obvious what Y means, but it's not explicitly stated. Do you mind if I leave ISGRANTABLE as is?

          Show
          chaase3 Kim Haase added a comment - Attaching DERBY-4568 -2.diff and DERBY-4568 -2.zip. Thanks very much for the edits, Rick. Hope the issues are fixed in this patch. One comment: rrefsistabssysperms, ISGRANTABLE: No other table has an ISGRANTABLE column. The closest is GRANTOPTION in SYSROUTINEPERMS, and I don't much like that language because it is unclear: "Specifies if the GRANTEE is the owner of the routine. Valid values are Y and N." It might seem to be obvious what Y means, but it's not explicitly stated. Do you mind if I leave ISGRANTABLE as is?
          Hide
          rhillegas Rick Hillegas added a comment -

          Hi Kim. Thanks for this great documentation. I have some comments, largely related to mistakes in the spec, for which I apologize:

          rrefsistabssysperms

          o I apologize. The spec says that some of the column names have underscores in them. That is not true. There are no underscores in the names of these columns.

          o Redundant "the" in the first sentence.

          o For GRANTEE/GRANTOR/ISGRANTABLE, I think it would be better to just copy the verbiage from the GRANTEE/GRANTOR/GRANTABLE columns of SYSCOLPERMS and SYSROUTINEPERMS.

          rrefsistabssyssequences

          o I apologize. The spec says that some of the column names have underscores in them. That is not true. There are no underscores in the names of these columns.

          o SEQUENCEDATATYPE - For this row, I would just copy the verbiage from SYSCOLUMNS.COLUMNDATATYPE.

          o CURRENTVALUE - I apologize for another error in the spec. The initial value of this column is STARTVALUE. This column is NULL only if the sequence generator is exhausted and cannot issue any more numbers.

          rrefsqljcreatesequence

          o I apologize again. The grammar in the spec is too restrictive. The actual grammar is:

          CREATE SEQUENCE sequenceName [ SequenceElement ] *

          SequenceElement

          {
          AS dataType

          START WITH signedInteger
          INCREMENT BY signedInteger
          MAXVALUE signedInteger NO MAXVALUE
          MINVALUE signedInteger NO MINVALUE
          CYCLE NO CYCLE
          }

          o Examples - It's a little unclear what is the last value of these generators. The last legal value of the first generator is the largest possible INT. The last legal value of the second generator is the largest possible BIGINT. After handing out the largest value, Derby raises an exception if NEXT VALUE is invoked on the generator again.

          rrefsqljnextvaluefor

          o Again, I apologize for errors in the spec. I would reword the description of NEXT VALUE as follows:

          "If this is the first use of the sequence generator, then the generator returns its STARTVALUE. Otherwise, the INCREMENT value is added to the previous value returned by the sequence generator..."

          o Thanks for asking that question about WINDOW functions. Yes, that limitation should be "WINDOW function".

          Show
          rhillegas Rick Hillegas added a comment - Hi Kim. Thanks for this great documentation. I have some comments, largely related to mistakes in the spec, for which I apologize: rrefsistabssysperms o I apologize. The spec says that some of the column names have underscores in them. That is not true. There are no underscores in the names of these columns. o Redundant "the" in the first sentence. o For GRANTEE/GRANTOR/ISGRANTABLE, I think it would be better to just copy the verbiage from the GRANTEE/GRANTOR/GRANTABLE columns of SYSCOLPERMS and SYSROUTINEPERMS. rrefsistabssyssequences o I apologize. The spec says that some of the column names have underscores in them. That is not true. There are no underscores in the names of these columns. o SEQUENCEDATATYPE - For this row, I would just copy the verbiage from SYSCOLUMNS.COLUMNDATATYPE. o CURRENTVALUE - I apologize for another error in the spec. The initial value of this column is STARTVALUE. This column is NULL only if the sequence generator is exhausted and cannot issue any more numbers. rrefsqljcreatesequence o I apologize again. The grammar in the spec is too restrictive. The actual grammar is: CREATE SEQUENCE sequenceName [ SequenceElement ] * SequenceElement { AS dataType START WITH signedInteger INCREMENT BY signedInteger MAXVALUE signedInteger NO MAXVALUE MINVALUE signedInteger NO MINVALUE CYCLE NO CYCLE } o Examples - It's a little unclear what is the last value of these generators. The last legal value of the first generator is the largest possible INT. The last legal value of the second generator is the largest possible BIGINT. After handing out the largest value, Derby raises an exception if NEXT VALUE is invoked on the generator again. rrefsqljnextvaluefor o Again, I apologize for errors in the spec. I would reword the description of NEXT VALUE as follows: "If this is the first use of the sequence generator, then the generator returns its STARTVALUE. Otherwise, the INCREMENT value is added to the previous value returned by the sequence generator..." o Thanks for asking that question about WINDOW functions. Yes, that limitation should be "WINDOW function".
          Hide
          chaase3 Kim Haase added a comment -

          Here's a first pass at the documentation for this feature. Attaching DERBY-4568.diff, DERBY-4568.stat, and DERBY-4568.zip, with new topics on CREATE SEQUENCE, DROP SEQUENCE, NEXT VALUE FOR, and the SYSSEQUENCES and SYSPERMS tables, and additions to the GRANT and REVOKE statement topics.

          I hope I got everything, but am not sure, of course. I put a note with a question in the NEXT VALUE FOR topic. The REVOKE topic has a lot of verbiage about limitations and system tables – I wonder if anything is needed for sequence generators.

          Show
          chaase3 Kim Haase added a comment - Here's a first pass at the documentation for this feature. Attaching DERBY-4568 .diff, DERBY-4568 .stat, and DERBY-4568 .zip, with new topics on CREATE SEQUENCE, DROP SEQUENCE, NEXT VALUE FOR, and the SYSSEQUENCES and SYSPERMS tables, and additions to the GRANT and REVOKE statement topics. I hope I got everything, but am not sure, of course. I put a note with a question in the NEXT VALUE FOR topic. The REVOKE topic has a lot of verbiage about limitations and system tables – I wonder if anything is needed for sequence generators.

            People

            • Assignee:
              chaase3 Kim Haase
              Reporter:
              chaase3 Kim Haase
            • Votes:
              0 Vote for this issue
              Watchers:
              0 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved:

                Development