Derby
  1. Derby
  2. DERBY-4568

Documentation needed for sequence generators

    Details

    • Type: Task Task
    • Status: Closed
    • Priority: Major 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
          Kim Haase added a comment -

          Closing, since documentation appears in Latest Alpha Manuals.

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

          Thanks very much, Rick!

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

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

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

          +1

          Show
          Rick Hillegas added a comment - Thanks, Kim. The revised patch looks great. I agree with your treatment of SYSPERMS.ISGRANTABLE. +1
          Hide
          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
          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
          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
          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
          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
          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:
              Kim Haase
              Reporter:
              Kim Haase
            • Votes:
              0 Vote for this issue
              Watchers:
              0 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved:

                Development