Derby
  1. Derby
  2. DERBY-908

YEAR,SECOND,MONTH, MINUTE, HOUR and DAY functions have incorrect information on durations.

    Details

    • Type: Bug Bug
    • Status: Closed
    • Priority: Minor Minor
    • Resolution: Fixed
    • Affects Version/s: 10.1.1.0
    • Fix Version/s: 10.3.1.4
    • Component/s: Documentation
    • Labels:
      None
    • Urgency:
      Low

      Description

      All these functions in the reference manual have a sentence like:
      (this is from DAY)

      If the argument is a time duration or timestamp duration: The result is the day part of the value, which is an integer between -99 and 99. A nonzero result has the same sign as the argument.

      This can be removed since Derby does not support durations. Then the surrounding text probably needs re-work as it leaves only a single type of argument.

      1. rrefyearfunc.html
        3 kB
        Bryan Pendleton
      2. rrefyearfunc.html
        3 kB
        Bryan Pendleton
      3. rrefyearfunc.html
        3 kB
        Bryan Pendleton
      4. rrefsecondfunc.html
        4 kB
        Bryan Pendleton
      5. rrefsecondfunc.html
        3 kB
        Bryan Pendleton
      6. rrefsecondfunc.html
        3 kB
        Bryan Pendleton
      7. rrefsecondfunc.html
        3 kB
        Bryan Pendleton
      8. rrefmonthfunc.html
        3 kB
        Bryan Pendleton
      9. rrefmonthfunc.html
        3 kB
        Bryan Pendleton
      10. rrefmonthfunc.html
        3 kB
        Bryan Pendleton
      11. rrefminutefunc.html
        3 kB
        Bryan Pendleton
      12. rrefminutefunc.html
        3 kB
        Bryan Pendleton
      13. rrefminutefunc.html
        3 kB
        Bryan Pendleton
      14. rrefminutefunc.html
        3 kB
        Bryan Pendleton
      15. rrefhourfunc.html
        3 kB
        Bryan Pendleton
      16. rrefhourfunc.html
        3 kB
        Bryan Pendleton
      17. rrefhourfunc.html
        3 kB
        Bryan Pendleton
      18. rrefdayfunc.html
        3 kB
        Bryan Pendleton
      19. rrefdayfunc.html
        3 kB
        Bryan Pendleton
      20. rrefdayfunc.html
        3 kB
        Bryan Pendleton
      21. minuteExample.diff
        0.8 kB
        Bryan Pendleton
      22. docChanges.diff
        8 kB
        Bryan Pendleton
      23. docChanges_v4.diff
        10 kB
        Bryan Pendleton
      24. docChanges_v3.diff
        9 kB
        Bryan Pendleton
      25. docChanges_v2.diff
        8 kB
        Bryan Pendleton

        Activity

        Hide
        Bryan Pendleton added a comment -

        Thank you for committing! Marked the issue resolved.

        Show
        Bryan Pendleton added a comment - Thank you for committing! Marked the issue resolved.
        Hide
        Tomohito Nakayama added a comment -

        I committed.

        Sending src/ref/rrefminutefunc.dita
        Transmitting file data .
        Committed revision 512226.

        Show
        Tomohito Nakayama added a comment - I committed. Sending src/ref/rrefminutefunc.dita Transmitting file data . Committed revision 512226.
        Hide
        Bryan Pendleton added a comment -

        It occurs to me that the "classes" example was meant to refer to an academic calendar example. For example the class schedule for the school might indicate that the first class period of the day started at 8:10 AM and ended at 9:05 AM. So the use of "classes" rather than "rows" was probably intentional.

        But I think the "flights" example is good too, and if it is clearer to readers, that's better.

        Attached is minuteExample.diff, and rrefminutefunc.html. This patch changes the example on the MINUTE page of the reference manual to correct the error of the previous example, which was that the result of the function is always less than 60, since the function's values range from 0 to 59.

        Please let me know if you think the new example is clear.

        Show
        Bryan Pendleton added a comment - It occurs to me that the "classes" example was meant to refer to an academic calendar example. For example the class schedule for the school might indicate that the first class period of the day started at 8:10 AM and ended at 9:05 AM. So the use of "classes" rather than "rows" was probably intentional. But I think the "flights" example is good too, and if it is clearer to readers, that's better. Attached is minuteExample.diff, and rrefminutefunc.html. This patch changes the example on the MINUTE page of the reference manual to correct the error of the previous example, which was that the result of the function is always less than 60, since the function's values range from 0 to 59. Please let me know if you think the new example is clear.
        Hide
        Tomohito Nakayama added a comment -

        I think your new example is better than current one.

        Show
        Tomohito Nakayama added a comment - I think your new example is better than current one.
        Hide
        Bryan Pendleton added a comment -

        I see a couple problems with the example, but I'm not sure I agree that it's clearly an example of using a duration.

        The two problems I see in the example are:
        1) It says "select all classes" where I think it should say "select all rows"
        2) Since the values of the MINUTE function range from 0 to 59, the values are always less than 60. To find rows which are not on a full hour, I think the query should look for MINUTE() > 0.

        So I suggest the following example:

        Select all rows from the "flights" table where the "departure time" is between 6:00 and 6:30 AM:

        SELECT * FROM flights WHERE HOUR(departure_time) = 6 AND MINUTE(departure_time) < 31;

        Does that example make more sense?

        Show
        Bryan Pendleton added a comment - I see a couple problems with the example, but I'm not sure I agree that it's clearly an example of using a duration. The two problems I see in the example are: 1) It says "select all classes" where I think it should say "select all rows" 2) Since the values of the MINUTE function range from 0 to 59, the values are always less than 60. To find rows which are not on a full hour, I think the query should look for MINUTE() > 0. So I suggest the following example: Select all rows from the "flights" table where the "departure time" is between 6:00 and 6:30 AM: SELECT * FROM flights WHERE HOUR(departure_time) = 6 AND MINUTE(departure_time) < 31; Does that example make more sense?
        Hide
        Tomohito Nakayama added a comment -

        I think next example in minutes page is for duration which is not supported.

        http://db.apache.org/derby/docs/dev/ref/rrefminutefunc.html
        >Select all classes that do not end on a full hour:
        >
        >SELECT * FROM table1 WHERE MINUTE(ending) < 60;

        I think this should be corrected in this issue.

        Show
        Tomohito Nakayama added a comment - I think next example in minutes page is for duration which is not supported. http://db.apache.org/derby/docs/dev/ref/rrefminutefunc.html >Select all classes that do not end on a full hour: > >SELECT * FROM table1 WHERE MINUTE(ending) < 60; I think this should be corrected in this issue.
        Hide
        Bryan Pendleton added a comment -

        Thanks Kim. I made those corrections to the pages for Second and Minute, and re-built to confirm. I think these pages are much better now; thanks to all the reviewers for comments and suggestions!

        Committed the updated pages to the docs trunk as revision 507301.

        Show
        Bryan Pendleton added a comment - Thanks Kim. I made those corrections to the pages for Second and Minute, and re-built to confirm. I think these pages are much better now; thanks to all the reviewers for comments and suggestions! Committed the updated pages to the docs trunk as revision 507301.
        Hide
        Kim Haase added a comment -

        Thanks, Bryan! Yes, those look good. There are a couple of small glitches – I don't know if they matter that much.

        rrefminutefunc has a space indent at the beginning of the example, unlike the others.

        In rrefsecondfunc, the syntax and example are not in bold, unlike those in the other files.

        This sort of thing could probably go on forever, though. Feel free to stop if you want!

        Show
        Kim Haase added a comment - Thanks, Bryan! Yes, those look good. There are a couple of small glitches – I don't know if they matter that much. rrefminutefunc has a space indent at the beginning of the example, unlike the others. In rrefsecondfunc, the syntax and example are not in bold, unlike those in the other files. This sort of thing could probably go on forever, though. Feel free to stop if you want!
        Hide
        Bryan Pendleton added a comment -

        I think the HTML looks better with the example titles and with the code blocks reformatted to avoid unnecessary line splits.

        Please have a look at the latest attached HTML pages.

        Show
        Bryan Pendleton added a comment - I think the HTML looks better with the example titles and with the code blocks reformatted to avoid unnecessary line splits. Please have a look at the latest attached HTML pages.
        Hide
        Bryan Pendleton added a comment -

        Hi Kim, those sound like fine ideas to me.

        What does that translate to in DITA terms? Is it as simple as:

        1) Add <title>Example</title> to each of the <example> blocks,

        2) Remove the extraneous newlines from the DITA source inside the <codeblock> tags?

        I'll give those changes a try, and we can see what the output looks like.

        Show
        Bryan Pendleton added a comment - Hi Kim, those sound like fine ideas to me. What does that translate to in DITA terms? Is it as simple as: 1) Add <title>Example</title> to each of the <example> blocks, 2) Remove the extraneous newlines from the DITA source inside the <codeblock> tags? I'll give those changes a try, and we can see what the output looks like.
        Hide
        Kim Haase added a comment -

        Would it make sense at this point to –

        1) Give the examples an "Example" header?

        2) Indent the second line (WHERE clause) of the two-line examples, or put the clause on the same line as SELECT?

        Show
        Kim Haase added a comment - Would it make sense at this point to – 1) Give the examples an "Example" header? 2) Indent the second line (WHERE clause) of the two-line examples, or put the clause on the same line as SELECT?
        Hide
        Bryan Pendleton added a comment -

        I'll commit this later today if there are no additional comments.

        Show
        Bryan Pendleton added a comment - I'll commit this later today if there are no additional comments.
        Hide
        Laura Stewart added a comment -

        Looks really good to me. Thanks for making that change.
        Now all we need is Dan to review

        Show
        Laura Stewart added a comment - Looks really good to me. Thanks for making that change. Now all we need is Dan to review
        Hide
        Bryan Pendleton added a comment -

        Thanks Laura, that revised example is much clearer now. Attached is docChanges_v3.diff and rrefsecondfunc.html.

        Show
        Bryan Pendleton added a comment - Thanks Laura, that revised example is much clearer now. Attached is docChanges_v3.diff and rrefsecondfunc.html.
        Hide
        Laura Stewart added a comment -

        Bryan - These updates look really good. One minor thing, if you have time to fix it...

        In the Seconds function (rrefsecondfunc.html) Example. I think it should be reworded to:

        The RECEIVED column contains a timestamp that has an internal value equivalent to 2005-12-25-17.12.30.000000. To return only the seconds part of the timestamp, use the following syntax:

        If you can't make this change, let me know and I'll add a new JIRA issue for this.

        Show
        Laura Stewart added a comment - Bryan - These updates look really good. One minor thing, if you have time to fix it... In the Seconds function (rrefsecondfunc.html) Example. I think it should be reworded to: The RECEIVED column contains a timestamp that has an internal value equivalent to 2005-12-25-17.12.30.000000. To return only the seconds part of the timestamp, use the following syntax: If you can't make this change, let me know and I'll add a new JIRA issue for this.
        Hide
        Bryan Pendleton added a comment -

        Hi Laura, thanks very much for the review! I think your proposed rewording is clearer and simpler. Attached is docChanges_v2.diff, and updated versions of the HTML output with the diff.

        Show
        Bryan Pendleton added a comment - Hi Laura, thanks very much for the review! I think your proposed rewording is clearer and simpler. Attached is docChanges_v2.diff, and updated versions of the HTML output with the diff.
        Hide
        Laura Stewart added a comment -

        There is a sentence in each of these functions which repeats some of the text in another sentence. This duplicat text should be removed.

        ORIGINAL TEXT

        The DAY function returns the day part of a value.

        The argument must be a date, timestamp, or a valid character string representation of a date or timestamp that is not a CLOB, LONG VARCHAR, or XML value. The result of the function is a large integer. If the argument can be null, the result can be null; if the argument is null, the result is the null value. If the argument is a date, timestamp, or valid string representation of a date or timestamp, the result is the day part of the value, which is an integer between 1 and 31.

        PROPOSED REWORDING

        The DAY function returns the day part of a value.

        The argument must be a date, timestamp, or a valid character string representation of a date or timestamp that is not a CLOB, LONG VARCHAR, or XML value. The result of this function is a integer between 1 and 31. If the argument can be null, the result can be null. If the argument is null, the result is the null value.

        Show
        Laura Stewart added a comment - There is a sentence in each of these functions which repeats some of the text in another sentence. This duplicat text should be removed. ORIGINAL TEXT The DAY function returns the day part of a value. The argument must be a date, timestamp, or a valid character string representation of a date or timestamp that is not a CLOB, LONG VARCHAR, or XML value. The result of the function is a large integer. If the argument can be null, the result can be null; if the argument is null, the result is the null value. If the argument is a date, timestamp, or valid string representation of a date or timestamp, the result is the day part of the value, which is an integer between 1 and 31. PROPOSED REWORDING The DAY function returns the day part of a value. The argument must be a date, timestamp, or a valid character string representation of a date or timestamp that is not a CLOB, LONG VARCHAR, or XML value. The result of this function is a integer between 1 and 31. If the argument can be null, the result can be null. If the argument is null, the result is the null value.
        Hide
        Bryan Pendleton added a comment -

        Duh. Of course there are 6 html pages, not 8 pages, attached.

        Show
        Bryan Pendleton added a comment - Duh. Of course there are 6 html pages, not 8 pages, attached.
        Hide
        Bryan Pendleton added a comment -

        Attached is a proposed patch to the doc to eliminate the text about duration arguments, since Derby doesn't support that. Also attached are the 8 resulting html pages from the reference guide. Please let me know what you think.

        Show
        Bryan Pendleton added a comment - Attached is a proposed patch to the doc to eliminate the text about duration arguments, since Derby doesn't support that. Also attached are the 8 resulting html pages from the reference guide. Please let me know what you think.
        Hide
        Andrew McIntyre added a comment -

        Unsetting Fix Version for unassigned issues.

        Show
        Andrew McIntyre added a comment - Unsetting Fix Version for unassigned issues.
        Hide
        Rick Hillegas added a comment -

        Move to 10.2.3.0.

        Show
        Rick Hillegas added a comment - Move to 10.2.3.0.
        Hide
        Rick Hillegas added a comment -

        Moving to 10.2.2.0.

        Show
        Rick Hillegas added a comment - Moving to 10.2.2.0.

          People

          • Assignee:
            Bryan Pendleton
            Reporter:
            Daniel John Debrunner
          • Votes:
            0 Vote for this issue
            Watchers:
            1 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved:

              Development