svn commit: r431991 - /db/derby/docs/trunk/src/ref/rrefjdbc88908.dita

[dj...@apache.org]

Author: djd
Date: Wed Aug 16 12:05:00 2006
New Revision: 431991

URL: http://svn.apache.org/viewvc?rev=431991&view=rev
Log:
DERBY-1549 Added documentation for the new JDBC escape functions ACOS,ASIN, etc.

Modified:
    db/derby/docs/trunk/src/ref/rrefjdbc88908.dita

Modified: db/derby/docs/trunk/src/ref/rrefjdbc88908.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefjdbc88908.dita?rev=431991&r1=431990&r2=431991&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefjdbc88908.dita (original)
+++ db/derby/docs/trunk/src/ref/rrefjdbc88908.dita Wed Aug 16 12:05:00 2006
@@ -20,67 +20,173 @@
 <reference id="rrefjdbc88908" xml:lang="en-us">
 <title>JDBC escape syntax for fn keyword</title>
 <prolog><metadata>
-<keywords><indexterm>fn (JDBC escape keyword)</indexterm><indexterm>substring
-(JDBC scalar function)</indexterm><indexterm>mod (JDBC scalar function)</indexterm>
-<indexterm>locate (JDBC scalar function)</indexterm><indexterm>abs (JDBC scalar
-function)</indexterm><indexterm>sqrt (JDBC scalar function)</indexterm><indexterm>concat
-(JDBC scalar function)</indexterm><indexterm>TIMESTAMPADD function</indexterm>
-<indexterm>TIMESTAMPDIFF function</indexterm></keywords>
+<keywords><indexterm>fn<indexterm>JDBC escape keyword</indexterm><indexterm>JDBC <indexterm>escape
+keyword</indexterm></indexterm><indexterm>escape keyword<indexterm>JDBC </indexterm></indexterm></indexterm>
+<indexterm>JDBC<indexterm>escape functions</indexterm></indexterm><indexterm>substring<indexterm>JDBC
+scalar function</indexterm></indexterm><indexterm>mod<indexterm>JDBC scalar
+function</indexterm></indexterm><indexterm>locate<indexterm>JDBC scalar function</indexterm></indexterm>
+<indexterm>abs<indexterm>JDBC scalar function</indexterm></indexterm><indexterm>sqrt<indexterm>JDBC
+scalar function</indexterm></indexterm><indexterm>concat<indexterm>JDBC scalar
+function</indexterm></indexterm><indexterm>TIMESTAMPADD function<indexterm>JDBC
+scalar function</indexterm></indexterm><indexterm>TIMESTAMPDIFF function<indexterm>JDBC
+scalar function</indexterm></indexterm><indexterm>acos<indexterm>JDBC scalar
+function</indexterm></indexterm><indexterm>asin<indexterm>JDBC scalar function</indexterm></indexterm>
+<indexterm>atan<indexterm>JDBC scalar function</indexterm></indexterm><indexterm>ceiling<indexterm>JDBC
+scalar function</indexterm></indexterm><indexterm>cos<indexterm>JDBC scalar
+function</indexterm></indexterm><indexterm>degrees<indexterm>JDBC scalar function</indexterm></indexterm>
+<indexterm>exp<indexterm>JDBC scalar function</indexterm></indexterm><indexterm>floor<indexterm>JDBC
+scalar function</indexterm><indexterm>log<indexterm>JDBC scalar function</indexterm></indexterm><indexterm>log10<indexterm>JDBC
+scalar function</indexterm></indexterm><indexterm>pi<indexterm>JDBC scalar
+function</indexterm></indexterm><indexterm>radians<indexterm>JDBC scalar function</indexterm></indexterm><indexterm>sin<indexterm>JDBC
+scalar function</indexterm></indexterm></indexterm><indexterm>tan<indexterm>JDBC
+scalar function</indexterm></indexterm></keywords>
 </metadata></prolog>
 <refbody>
-<section> <p>The fn keyword allows the use of several scalar functions. The
-function name follows the keyword fn.</p></section>
+<section> <p>You can specify functions in JDBC escape syntax, by using the <parmname>fn</parmname> keyword.</p></section>
 <refsyn><title>Syntax</title><codeblock><b>{fn <i>functionCall</i>}</b></codeblock><p>where <i>functionCall</i> is
-one of the following functions:</p><codeblock><b>concat (<b><i>CharacterExpression</i></b>, <b><i>CharacterExpression</i></b>)</b></codeblock><p>Character
-string formed by appending the second string to the first; if either string
-is null, the result is NULL. {fn concat (<i>CharacterExpression</i>, <i>CharacterExpression</i>)
-is equivalent to built-in syntax { CharacterExpression || CharacterExpression
-}. For more details, see <xref href="rrefsqlj40899.dita#rrefsqlj40899"></xref>.</p><codeblock><b><i>sqrt (<b><i>FloatingPointExpression</i></b>)</i
-></b></codeblock><p>Square root of floating point number.</p><p>{fn sqrt (<i>FloatingPointExpression</i>)}
-is equivalent to built-in syntax  <xref href="rrefsqlj73147.dita#rrefsqlj73147/i1195048">SQRT(FloatingPointExpression)</xref>.
-For more details see <xref href="rrefsqlj73147.dita#rrefsqlj73147"></xref>.</p><codeblock><b>abs (<b><i>NumericExpression</i></b>)</b></codeblock
-><p>Absolute value of number. {fn abs(<i>NumericExpression</i>)} is equivalent
-to built-in syntax <xref href="rrefsqlj98067.dita#rrefsqlj98067/i1195049">ABSOLUTE(NumericExpression)</xref>.
-For more details see <xref href="rrefsqlj98067.dita#rrefsqlj98067"></xref>.</p><codeblock><b>locate(<b><i>CharacterExpression</i></b>,<b><i>CharacterExpression</i
-></b> [, <b><i>startIndex</i></b>] )</b></codeblock><p>Position in the second <i>CharacterExpression</i> of
-the first occurrence of the first <i>CharacterExpression</i>, searching from
-the beginning of the second character expression, unless <i>startIndex</i> is
-specified. {fn locate(<i>CharacterExpression</i>,<i>CharacterExpression</i> [, <i>startIndex</i>]
+the name of one of the following scalar functions:</p><dl><dlentry>
+<dt>abs</dt>
+<dd>Returns the absolute value of a number.<codeblock><b>abs(<i>NumericExpression</i>)</b></codeblock><p>The
+JDBC escape syntax {fn abs(<i>NumericExpression</i>)} is equivalent to the
+built-in syntax <xref href="rrefsqlj98067.dita#rrefsqlj98067/i1195049">ABSOLUTE(NumericExpression)</xref>.
+For more information, see the <xref href="rrefsqlj98067.dita#rrefsqlj98067"></xref> function.</p></dd>
+</dlentry><dlentry>
+<dt>acos</dt>
+<dd>Returns the arc cosine of a specified number.<codeblock><b>acos(<i>number</i>)</b></codeblock><p>The
+JDBC escape syntax {fn acos(<i>number</i>)} is equivalent to the built-in
+syntax ACOS(number). For more information, see the <xref href="rreffuncacos.dita#rreffuncacos">ACOS</xref> function.</p></dd>
+</dlentry><dlentry>
+<dt>asin</dt>
+<dd>Returns the arc sine of a specified number.<codeblock><b>asin(<i>number</i>)</b></codeblock><p>The
+JDBC escape syntax {fn asin(<i>number</i>)} is equivalent to the built-in
+syntax ASIN(number). For more information, see the <xref href="rreffuncasin.dita#rreffuncasin">ASIN</xref> function.</p></dd>
+</dlentry><dlentry>
+<dt>atan</dt>
+<dd>Returns the arc tangent of a specified number.<codeblock><b>atan(<i>number</i>)</b></codeblock><p>The
+JDBC escape syntax {fn atan(<i>number</i>)} is equivalent to the built-in
+syntax ATAN(number). For more information, see the <xref href="rreffuncatan.dita#rreffuncatan">ATAN</xref> function.</p></dd>
+</dlentry><dlentry>
+<dt>ceiling</dt>
+<dd>Rounds the specified number up, and returns the smallest number that is
+greater than or equal to the specified number.<codeblock><b>ceiling(<i>number</i>)</b></codeblock><p>The
+JDBC escape syntax {fn ceiling(<i>number</i>)} is equivalent to the built-in
+syntax CEILING(number). For more information, see the <xref href="rreffuncceil.dita#rreffuncceil"></xref> function.</p></dd>
+</dlentry><dlentry>
+<dt>concat</dt>
+<dd>Returns the concatenation of character strings.<codeblock><b>concat(<i>CharacterExpression</i>, <i>CharacterExpression</i>)</b></codeblock><p
+>Character string formed by appending the second string to the first string.
+If either string is null, the result is NULL. The JDBC escape syntax {fn concat
+(<i>CharacterExpression</i>, <i>CharacterExpression</i>) is equivalent to
+the built-in syntax { CharacterExpression || CharacterExpression }. For more
+information, see the <xref href="rrefsqlj40899.dita#rrefsqlj40899"></xref> function.</p></dd>
+</dlentry><dlentry>
+<dt>cos</dt>
+<dd>Returns the cosine of a specified number.<codeblock><b>cos(<i>number</i>)</b></codeblock><p>The
+JDBC escape syntax {fn cos(<i>number</i>)} is equivalent to the built-in syntax
+COS(number). For more information, see the <xref href="rreffunccos.dita#rreffunccos"></xref> function.</p></dd>
+</dlentry><dlentry>
+<dt>degrees</dt>
+<dd>Converts a specified number from radians to degrees.<codeblock><b>degrees(<i>number</i>)</b></codeblock><p>The
+JDBC escape syntax {fn degrees(<i>number</i>)} is equivalent to the built-in
+syntax DEGREES(number). For more information, see the <xref href="rreffuncdegrees.dita#rreffuncdegrees"></xref> function.</p></dd>
+</dlentry><dlentry>
+<dt>exp</dt>
+<dd>Returns <term>e</term> raised to the power of the specified number.<codeblock><b>exp(<i>number</i>)</b></codeblock><p>The
+JDBC escape syntax {fn exp(<i>number</i>)} is equivalent to the built-in syntax
+EXP(number). For more information, see the <xref href="rreffuncexp.dita#rreffuncexp"></xref> function.</p></dd>
+</dlentry><dlentry>
+<dt>floor</dt>
+<dd>Rounds the specified number down, and returns the largest number that
+is less than or equal to the specified number.<codeblock><b>floor(<i>number</i>)</b></codeblock><p>The
+JDBC escape syntax {fn floor(<i>number</i>)} is equivalent to the built-in
+syntax FLOOR(number). For more information, see the <xref href="rreffuncfloor.dita#rreffuncfloor"></xref> function.</p></dd>
+</dlentry><dlentry>
+<dt>locate</dt>
+<dd>Returns the position in the second <i>CharacterExpression</i> of the first
+occurrence of the first <i>CharacterExpression</i>. Searches from the beginning
+of the second <i>CharacterExpression</i>, unless the <i>startIndex</i> parameter
+is specified.<codeblock><b>locate(<i>CharacterExpression</i>,<i>CharacterExpression</i> [, <i>startIndex</i>] )</b></codeblock><p> The
+JDBC escape syntax {fn locate(<i>CharacterExpression</i>,<i>CharacterExpression</i> [, <i>startIndex</i>]
 )} is equivalent to the built-in syntax <xref href="rrefsqlj61998.dita#rrefsqlj61998/i1195050">LOCATE(CharacterExpression,
-CharacterExpression [, StartPosition] )</xref>. For more details see <xref
-href="rrefsqlj61998.dita#rrefsqlj61998"></xref>.</p><codeblock><b>substring(<b><i>CharacterExpression</i></b>, <b><i>startIndex</i></b>, <b><i>length</i
-></b>)</b></codeblock><p>A character string formed by extracting <i>length</i> characters
-from the CharacterExpression beginning at <i>startIndex</i>; the index starts
-with 1.</p><codeblock><b>mod(<b><i>integer_type</i></b>, <b><i>integer_type</i></b>)</b></codeblock><p>MOD
-returns the remainder (modulus) of argument 1 divided by argument 2. The result
-is negative only if argument 1 is negative. For more details, see <xref href="rrefsqljmod.dita#rrefsqljmod"></xref>.</p><note>Any <ph
-conref="refconrefs.dita#prod/productshortname"></ph> built-in function is
-allowed in this syntax, not just those listed in this section.</note><codeblock><b>TIMESTAMPADD( <i>interval</i>, <i>integerExpression</i>, <i>timestampExpression</i
-> )</b></codeblock><p>Use the <codeph>TIMESTAMPADD</codeph> function to add
-the value of an interval to a timestamp. The function applies the integer
-to the specified timestamp based on the interval type and returns the sum
-as a new timestamp. You can subtract from the timestamp by using negative
-integers.</p><p>Note that <codeph>TIMESTAMPADD</codeph> is a JDBC escaped
-function, and is only accessible using the JDBC escape function syntax.</p><p>To
+CharacterExpression [, StartPosition] )</xref>. For more information, see
+the <xref href="rrefsqlj61998.dita#rrefsqlj61998"></xref>. function</p></dd>
+</dlentry><dlentry>
+<dt>log</dt>
+<dd>Returns the natural logarithm (base <term>e</term>) of the specified number.<codeblock><b>log(<i>number</i>)</b> </codeblock><p>The
+JDBC escape syntax {fn log(<i>number</i>)} is equivalent to the built-in syntax
+LOG(number). For more information, see the <xref href="rreffunclog.dita#rreffunclog"></xref> function.</p></dd>
+</dlentry><dlentry>
+<dt>log10</dt>
+<dd>Returns the base-10 logarithm of the specified number.<codeblock><b>log10(<i>number</i>)</b></codeblock><p>The
+JDBC escape syntax {fn log10(<i>number</i>)} is equivalent to the built-in
+syntax LOG10(number). For more information, see the <xref href="rreffunclog10.dita#rreffunclog10"></xref> function.</p></dd>
+</dlentry><dlentry>
+<dt>mod</dt>
+<dd> Returns the remainder (modulus) of argument 1 divided by argument 2.
+The result is negative only if argument 1 is negative.<codeblock><b>mod(<i>integer_type</i>, <i>integer_type</i>)</b></codeblock><p>For
+more information, see the <xref href="rrefsqljmod.dita#rrefsqljmod"></xref> function.</p></dd>
+</dlentry><dlentry>
+<dt>pi</dt>
+<dd>Returns an value that is closer than any other value to <term>pi</term>.<codeblock><b>pi()</b></codeblock><p>The
+JDBC escape syntax {fn pi()} is equivalent to the built-in syntax PI(). For
+more information, see the <xref href="rreffuncpi.dita#rreffuncpi"></xref> function.</p></dd>
+</dlentry><dlentry>
+<dt>radians</dt>
+<dd>Converts a specified number from degrees to radians.<codeblock><b>radians(<i>number</i>)</b></codeblock><p>The
+JDBC escape syntax {fn radians(<i>number</i>)} is equivalent to the built-in
+syntax RADIANS(number). For more information, see the <xref href="rreffuncradians.dita#rreffuncradians"></xref> function.</p></dd>
+</dlentry><dlentry>
+<dt>sin</dt>
+<dd>Returns the sine of a specified number.<codeblock><b>sin(<i>number</i>)</b></codeblock><p>The
+JDBC escape syntax {fn sin(<i>number</i>)} is equivalent to the built-in syntax
+SIN(number). For more information, see the <xref href="rreffuncsin.dita#rreffuncsin">SIN</xref> function.</p></dd>
+</dlentry><dlentry>
+<dt>sqrt</dt>
+<dd>Returns the square root of floating point number.<codeblock><b>sqrt(<i>FloatingPointExpression</i>)</b></codeblock><p>The
+JDBC escape syntax {fn sqrt (<i>FloatingPointExpression</i>)} is equivalent
+to the built-in syntax  <xref href="rrefsqlj73147.dita#rrefsqlj73147/i1195048">SQRT(FloatingPointExpression)</xref>.
+For more information, see the <xref href="rrefsqlj73147.dita#rrefsqlj73147"></xref> function.</p></dd>
+</dlentry><dlentry>
+<dt>substring</dt>
+<dd>Forms a character string by extracting <i>length</i> characters from the <i>CharacterExpression</i> beginning
+at <i>startIndex</i>. The index of the first character in the <i>CharacterExpression</i> is
+1.<codeblock><b>substring(<i>CharacterExpression</i>, <i>startIndex</i>, <i>length</i>)</b></codeblock></dd>
+</dlentry><dlentry>
+<dt>tan</dt>
+<dd>Returns the tangent of a specified number.<codeblock><b>tan(<i>number</i>)</b></codeblock><p>The
+JDBC escape syntax {fn tan(<i>number</i>)} is equivalent to the built-in syntax
+TAN(number). For more information, see the <xref href="rreffunctan.dita#rreffunctan">TAN</xref> function.</p></dd>
+</dlentry><dlentry>
+<dt>TIMESTAMPADD</dt>
+<dd>Use the <codeph>TIMESTAMPADD</codeph> function to add the value of an
+interval to a timestamp. The function applies the integer to the specified
+timestamp based on the interval type and returns the sum as a new timestamp.
+You can subtract from the timestamp by using negative integers.<p>The <codeph>TIMESTAMPADD</codeph> is
+a JDBC escaped function, and is only accessible by using the JDBC escape function
+syntax.</p><codeblock><b>TIMESTAMPADD( <i>interval</i>, <i>integerExpression</i>, <i>timestampExpression</i> )</b></codeblock><p>To
 perform <codeph>TIMESTAMPADD</codeph> on dates and times, it is necessary
-to convert them to timestamps. Dates are converted to timestamps by putting
-00:00:00.0 in the time-of-day fields. Times are converted to timestamps by
-putting the current date in the date fields.</p><p>Note that you should not
-put a datetime column inside a timestamp arithmetic function in WHERE clauses
-because the optimizer will not use any index on the column.</p><codeblock><b>TIMESTAMPDIFF( interval, timestampExpression1, timestampExpression2 )</b
-></codeblock><p>Use the <codeph>TIMESTAMPDIFF</codeph> function to find the
-difference between two timestamp values at a specified interval. For example,
-the function can return the number of minutes between two specified timestamps.</p><p>Note
-that <codeph>TIMESTAMPDIFF</codeph> is a JDBC escaped function, and is only
-accessible using the JDBC escape function syntax.</p><p>To perform <codeph>TIMESTAMPDIFF</codeph> on
-dates and times, it is necessary to convert them to timestamps. Dates are
-converted to timestamps by putting 00:00:00.0 in the time-of-day fields. Times
-are converted to timestamps by putting the current date in the date fields.</p><p>Note
-that you should not put a datetime column inside a timestamp arithmetic function
-in WHERE clauses because the optimizer will not use any index on the column.</p></refsyn>
+to convert the dates and times to timestamps. Dates are converted to timestamps
+by putting 00:00:00.0 in the time-of-day fields. Times are converted to timestamps
+by putting the current date in the date fields.</p><p>You should not put a
+datetime column inside of a timestamp arithmetic function in WHERE clauses
+because the optimizer will not use any index on the column.</p></dd>
+</dlentry><dlentry>
+<dt>TIMESTAMPDIFF</dt>
+<dd>Use the <codeph>TIMESTAMPDIFF</codeph> function to find the difference
+between two timestamp values at a specified interval. For example, the function
+can return the number of minutes between two specified timestamps.<p>The <codeph>TIMESTAMPDIFF</codeph> is
+a JDBC escaped function, and is only accessible by using the JDBC escape function
+syntax.</p><codeblock><b>TIMESTAMPDIFF( <i>interval</i>, <i>timestampExpression1</i>, <i>timestampExpression2</i> )</b></codeblock><p>To
+perform <codeph>TIMESTAMPDIFF</codeph> on dates and times, it is necessary
+to convert the dates and times to timestamps. Dates are converted to timestamps
+by putting 00:00:00.0 in the time-of-day fields. Times are converted to timestamps
+by putting the current date in the date fields.</p><p>You should not put a
+datetime column inside of a timestamp arithmetic function in WHERE clauses
+because the optimizer will not use any index on the column.</p></dd>
+</dlentry></dl></refsyn>
 <section><title>Valid intervals for TIMESTAMPADD and TIMESTAMPDIFF</title>The <codeph>TIMESTAMPADD</codeph> and <codeph>TIMESTAMPDIFF</codeph> functions
-can be used to perform arithmetic with timestamps. These two functions use
-the following valid intervals for arithmetic operations:<ul>
+are used to perform arithmetic with timestamps. These two functions use the
+following valid intervals for arithmetic operations:<ul>
 <li>SQL_TSI_DAY</li>
 <li>SQL_TSI_FRAC_SECOND</li>
 <li>SQL_TSI_HOUR</li>
@@ -91,10 +197,11 @@
 <li>SQL_TSI_WEEK</li>
 <li>SQL_TSI_YEAR</li>
 </ul></section>
-<example><title>Examples of TIMESTAMPADD and TIMESTAMPDIFF</title><codeblock><b>{fn TIMESTAMPADD( SQL_TSI_MONTH, 1, CURRENT_TIMESTAMP)}</b></codeblock
-><p>Returns a timestamp value one month later than the current timestamp.</p><codeblock><b>{fn TIMESTAMPDIFF(SQL_TSI_WEEK, CURRENT_TIMESTAMP, 
-  timestamp('2001-01-01-12.00.00.000000'))}</b
-></codeblock><p>Returns the number of weeks between now and the specified
-time on January 1, 2001.</p></example>
+<example><title>Examples for the TIMESTAMPADD and TIMESTAMPDIFF escape functions </title><p>To
+return a timestamp value one month later than the current timestamp, use the
+following syntax:</p><codeblock><b>{fn TIMESTAMPADD( SQL_TSI_MONTH, 1, CURRENT_TIMESTAMP)}</b></codeblock><p>To
+return the number of weeks between now and the specified time on January 1,
+2008, use the following syntax:</p><codeblock><b>{fn TIMESTAMPDIFF(SQL_TSI_WEEK, CURRENT_TIMESTAMP, 
+  timestamp('2008-01-01-12.00.00.000000'))}</b></codeblock></example>
 </refbody>
 </reference>