You are viewing a plain text version of this content. The canonical link for it is here.
Posted to derby-commits@db.apache.org by jt...@apache.org on 2006/10/17 04:35:34 UTC
svn commit: r464772 - in /db/derby/docs/trunk/src/ref:
rrefbuiltsmallint.dita rrefkeywords29722.dita rrefsecondfunc.dita
rrefsqlj29930.dita rrefsqlj93082.dita rreftimestampfunc.dita
Author: jta
Date: Mon Oct 16 19:35:33 2006
New Revision: 464772
URL: http://svn.apache.org/viewvc?view=rev&rev=464772
Log:
DERBY-1839 Updates to the Reference Guide based on 10.2 doc review comments.
Patch derby1839_functions3.diff contributed by Laura Stewart <sc...@gmail.com>
Modified:
db/derby/docs/trunk/src/ref/rrefbuiltsmallint.dita
db/derby/docs/trunk/src/ref/rrefkeywords29722.dita
db/derby/docs/trunk/src/ref/rrefsecondfunc.dita
db/derby/docs/trunk/src/ref/rrefsqlj29930.dita
db/derby/docs/trunk/src/ref/rrefsqlj93082.dita
db/derby/docs/trunk/src/ref/rreftimestampfunc.dita
Modified: db/derby/docs/trunk/src/ref/rrefbuiltsmallint.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefbuiltsmallint.dita?view=diff&rev=464772&r1=464771&r2=464772
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefbuiltsmallint.dita (original)
+++ db/derby/docs/trunk/src/ref/rrefbuiltsmallint.dita Mon Oct 16 19:35:33 2006
@@ -1,4 +1,7 @@
<?xml version="1.0" encoding="utf-8"?>
+
+<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN"
+ "../dtd/reference.dtd">
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
@@ -15,26 +18,25 @@
See the License for the specific language governing permissions and
limitations under the License.
-->
-<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "../dtd/reference.dtd">
-<reference xml:lang="en-us" id="rrefbuiltsmallint">
+<reference id="rrefbuiltsmallint" xml:lang="en-us">
<title>SMALLINT</title>
<prolog><metadata>
-<keywords><indexterm>SMALLINT function</indexterm>
-</keywords>
-</metadata>
-</prolog><refbody>
+<keywords><indexterm>functions<indexterm>SMALLINT</indexterm></indexterm>
+<indexterm>SMALLINT function</indexterm></keywords>
+</metadata></prolog>
+<refbody>
<section>The SMALLINT function returns a small integer representation of a
number or character string in the form of a small integer constant.</section>
-<refsyn><title>Syntax</title>
-<codeblock><b>SMALLINT (<i>NumericExpression</i> | <i>CharacterExpression</i> ) </b></codeblock>
-<dl>
-<dlentry><dt>NumericExpression</dt>
+<refsyn><title>Syntax</title> <codeblock>SMALLINT ( <i>NumericExpression</i> | <i>CharacterExpression</i> )</codeblock> <dl>
+<dlentry>
+<dt>NumericExpression</dt>
<dd>An expression that returns a value of any built-in numeric data type.
If the argument is a NumericExpression, the result is the same number that
would occur if the argument were assigned to a small integer column or variable.
If the whole part of the argument is not within the range of small integers,
-an error occurs. The decimal part of the argument is truncated if present.</dd></dlentry>
-<dlentry><dt>CharacterExpression</dt>
+an error occurs. The decimal part of the argument is truncated if present.</dd>
+</dlentry><dlentry>
+<dt>CharacterExpression</dt>
<dd>An expression that returns a character string value of length not greater
than the maximum length of a character constant. Leading and trailing blanks
are eliminated and the resulting string must conform to the rules for forming
@@ -42,8 +44,14 @@
range of small integers. The character string cannot be a long string. If
the argument is a CharacterExpression, the result is the same number that
would occur if the corresponding integer constant were assigned to a small
-integer column or variable.</dd></dlentry>
-</dl>
-<p>The result of the function is a small integer. If the argument can be null,
-the result can be null; if the argument is null, the result is the null value. </p>
-</refsyn></refbody></reference>
+integer column or variable.</dd>
+</dlentry></dl> <p>The result of the function is a small integer. If the argument
+can be null, the result can be null. If the argument is null, the result is
+the null value.</p> </refsyn>
+<example><title>Example</title><p>To determine the small integer representation
+of the number 32767.99, use this clause:<codeblock>VALUES SMALLINT (32767.99)</codeblock>The
+result is 32767. </p><p>To determine the small integer representation of the
+number 1, use this clause: <codeblock>VALUES SMALLINT (1)</codeblock>The result
+is 1. </p></example>
+</refbody>
+</reference>
Modified: db/derby/docs/trunk/src/ref/rrefkeywords29722.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefkeywords29722.dita?view=diff&rev=464772&r1=464771&r2=464772
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefkeywords29722.dita (original)
+++ db/derby/docs/trunk/src/ref/rrefkeywords29722.dita Mon Oct 16 19:35:33 2006
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="utf-8"?>
-
+
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN"
"../dtd/reference.dtd">
<!--
@@ -21,7 +21,7 @@
<reference id="rrefkeywords29722" xml:lang="en-us">
<title>SQL reserved words</title>
<prolog><metadata>
-<keywords><indexterm>Reserved words</indexterm><indexterm>Keywords</indexterm>
+<keywords><indexterm>reserved words</indexterm><indexterm>keywords</indexterm>
</keywords>
</metadata></prolog>
<refbody>
@@ -234,6 +234,7 @@
<sli>XML</sli>
<sli>XMLEXISTS</sli>
<sli>XMLPARSE</sli>
+<sli>XMLQUERY</sli>
<sli>XMLSERIALIZE</sli>
<sli>YEAR</sli>
</sl></p></section>
Modified: db/derby/docs/trunk/src/ref/rrefsecondfunc.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefsecondfunc.dita?view=diff&rev=464772&r1=464771&r2=464772
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefsecondfunc.dita (original)
+++ db/derby/docs/trunk/src/ref/rrefsecondfunc.dita Mon Oct 16 19:35:33 2006
@@ -22,15 +22,16 @@
<title>SECOND</title>
<shortdesc>The SECOND function returns the seconds part of a value.</shortdesc>
<prolog><metadata>
-<keywords><indexterm>SECOND function</indexterm></keywords>
+<keywords><indexterm>functions<indexterm>SECOND</indexterm></indexterm><indexterm>SECOND
+function</indexterm></keywords>
</metadata></prolog>
<refbody>
<section> <p>The argument must be a time, timestamp, or a valid character
string representation of a time 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.</p> <p>The other rules depend on the data type of the argument
-specified: <ul>
+can be null, the result can be null. If the argument is null, the result is
+0.</p> <p>The other rules depend on the data type of the argument specified:
+ <ul>
<li>If the argument is a date, timestamp, or valid string representation of
a date or timestamp: The result is the seconds part of the value, which is
an integer between 0 and 59.</li>
@@ -38,9 +39,10 @@
the seconds part of the value, which is an integer between -99 and 99. A nonzero
result has the same sign as the argument.</li>
</ul></p></section>
-<refsyn><title>Syntax</title> <codeblock><b>SECOND ( <i>expression</i> )</b></codeblock> </refsyn>
-<example> <p>Assume that the column RECEIVED (timestamp) has an internal value
-equivalent to 1988-12-25-17.12.30.000000.</p> <codeblock><b>SECOND(RECEIVED)</b></codeblock> <p>Returns
-the value 30.</p> </example>
+<refsyn><title>Syntax</title><codeblock>SECOND ( <i>expression</i> )</codeblock> </refsyn>
+<example> <title>Example</title><p>The column RECEIVED (timestamp) has an
+internal value equivalent to 2005-12-25-17.12.30.000000. To determine return
+only the seconds part of the timestamp, use the following syntax:<codeblock>SECOND(RECEIVED)</codeblock>The
+value 30 is returned.</p></example>
</refbody>
</reference>
Modified: db/derby/docs/trunk/src/ref/rrefsqlj29930.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefsqlj29930.dita?view=diff&rev=464772&r1=464771&r2=464772
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefsqlj29930.dita (original)
+++ db/derby/docs/trunk/src/ref/rrefsqlj29930.dita Mon Oct 16 19:35:33 2006
@@ -1,4 +1,7 @@
<?xml version="1.0" encoding="utf-8"?>
+
+<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN"
+ "../dtd/reference.dtd">
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
@@ -15,27 +18,24 @@
See the License for the specific language governing permissions and
limitations under the License.
-->
-
-<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN"
- "../dtd/reference.dtd">
<reference id="rrefsqlj29930.dita" xml:lang="en-us">
<title>UCASE or UPPER</title>
<prolog><metadata>
-<keywords><indexterm>UPPER function</indexterm><indexterm>UCASE function</indexterm>
+<keywords><indexterm>functions<indexterm>UPPER</indexterm></indexterm><indexterm>functions<indexterm>UCASE</indexterm></indexterm>
+<indexterm>UPPER function</indexterm><indexterm>UCASE function</indexterm>
</keywords>
</metadata></prolog>
<refbody>
<section> <p>UCASE or UPPER takes a character expression as a parameter and
returns a string in which all alpha characters have been converted to uppercase.</p></section>
-<refsyn><title>Format</title><codeblock><b>UCASE or UPPER ( <i>CharacterExpression</i> ) </b></codeblock><p>If
+<refsyn><title>Syntax</title><codeblock>UCASE or UPPER ( <i>CharacterExpression</i> ) </codeblock><p>If
the parameter type is CHAR , the return type is CHAR. Otherwise, the return
type is VARCHAR. <note>UPPER and LOWER follow the database locale. See <i><xref
-href="rrefattrib56769.dita#rrefattrib56769"></xref></i> for more
-information about specifying locale.</note></p><p>The length and maximum length
-of the returned value are the same as the length and maximum length of the
-parameter. </p> </refsyn>
-<example><codeblock><b><ph>-- returns 'ASD1#W'</ph>
-VALUES UPPER('aSD1#w')</b></codeblock> </example>
+href="rrefattrib56769.dita#rrefattrib56769"></xref></i> for more information
+about specifying locale.</note></p><p>The length and maximum length of the
+returned value are the same as the length and maximum length of the parameter. </p> </refsyn>
+<example><title>Example</title><p>To return the string <codeph>aSD1#w</codeph> in
+uppercase, use the following clause:<codeblock>VALUES UPPER('aSD1#w')</codeblock>The
+value returned is <codeph>ASD1#W</codeph>.</p> </example>
</refbody>
</reference>
-
Modified: db/derby/docs/trunk/src/ref/rrefsqlj93082.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefsqlj93082.dita?view=diff&rev=464772&r1=464771&r2=464772
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefsqlj93082.dita (original)
+++ db/derby/docs/trunk/src/ref/rrefsqlj93082.dita Mon Oct 16 19:35:33 2006
@@ -1,4 +1,7 @@
<?xml version="1.0" encoding="utf-8"?>
+
+<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN"
+ "../dtd/reference.dtd">
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
@@ -15,36 +18,41 @@
See the License for the specific language governing permissions and
limitations under the License.
-->
-
-<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN"
- "../dtd/reference.dtd">
<reference id="rrefsqlj93082" xml:lang="en-us">
<title>SUBSTR</title>
<prolog><metadata>
-<keywords><indexterm>SUBSTR (function)</indexterm></keywords>
+<keywords><indexterm>functions<indexterm>SUBSTR</indexterm></indexterm><indexterm>SUBSTR
+function</indexterm></keywords>
</metadata></prolog>
<refbody>
<section> <p>The SUBSTR function acts on a character string expression or
a bit string expression. The type of the result is a <xref href="rrefsqlj41207.dita#rrefsqlj41207">VARCHAR</xref> in
-the first case and <xref href="rrefsqlj32714.dita#rrefsqlj32714">VARCHAR FOR BIT DATA</xref> in
-the second case. The length of the result is the maximum length of the source
-type.</p></section>
-<refsyn><title>Syntax</title> <codeblock><b>SUBSTR({ <i>CharacterExpression</i> },
- <i>StartPosition</i> [, <i>LengthOfString</i> ] )</b></codeblock> <p><i>startPosition</i> and
-the optional <i>lengthOfString</i> are both integer expressions. (The first
-character or bit has a <i>startPosition</i> of 1; if you specify 0, <ph conref="refconrefs.dita#prod/productshortname"></ph> assumes
-that you mean 1.) </p> <p>A <i>characterExpression</i> is a CHAR, VARCHAR,
+the first case and <xref href="rrefsqlj32714.dita#rrefsqlj32714">VARCHAR FOR
+BIT DATA</xref> in the second case. The length of the result is the maximum
+length of the source type.</p></section>
+<refsyn><title>Syntax</title><codeblock>SUBSTR({ <i>CharacterExpression</i> },
+ <i>StartPosition</i> [, <i>LengthOfString</i> ] )</codeblock><p>The parameter <i>startPosition</i> and
+the optional parameter <i>lengthOfString</i> are both integer expressions.
+The first character or bit has a <i>startPosition</i> of 1. If you specify
+0, <ph conref="refconrefs.dita#prod/productshortname"></ph> assumes that you
+mean 1.</p><p>The parameter <i>characterExpression</i> is a CHAR, VARCHAR,
or LONG VARCHAR data type or any built-in type that is implicitly converted
-to a string (except a bit expression).</p> <p>For character expressions, both <i>startPosition</i> and <i>lengthOfString</i> refer
-to characters. For bit expressions, both <i>startPosition</i> and <i>lengthOfString</i> refer
-to bits. </p> <p>SUBSTR returns NULL if <i>lengthOfString</i> is specified
-and it is less than zero. </p> <p>If <i>startPosition</i> is positive, it
-refers to position from the start of the source expression (counting the first
-character as 1). If <i>startPosition</i> is negative, it is the position from
-the end of the source. </p> <p>If <i>lengthOfString</i> is not specified,
-SUBSTR returns the substring of the expression from the <i>startPosition</i> to
+to a string (except a bit expression).</p><p>For character expressions, the <i>startPosition</i> and <i>lengthOfString</i> parameters
+refer to characters. For bit expressions, the <i>startPosition</i> and <i>lengthOfString</i> parameters
+refer to bits. </p><p>If the <i>startPosition</i> is positive, it refers to
+position from the start of the source expression (counting the first character
+as 1). The <i>startPosition</i> cannot be a negative number. </p><p>If the <i>lengthOfString</i> is
+not specified, SUBSTR returns the substring of the expression from the <i>startPosition</i> to
the end of the source expression. If <i>lengthOfString</i> is specified, SUBSTR
-returns a VARCHAR or VARBIT of length <i>lengthOfString</i> starting at the <i>startPosition</i>. </p> </refsyn>
+returns a VARCHAR or VARBIT of length <i>lengthOfString</i> starting at the <i>startPosition</i>.
+The SUBSTR function returns an error if you specify a negative number for
+the parameter <i>lengthOfString</i>.</p> </refsyn>
+<example><title>Examples</title><p>To return a substring of the word <codeph>hello</codeph>,
+starting at the second character and continuing until the end of the word,
+use the following clause:<codeblock>VALUES SUBSTR('hello', 2)</codeblock>The
+result is '<codeph>ello</codeph>'.</p><p>To return a substring of the word <codeph>hello</codeph>,
+starting at the first character and continuing for two characters, use the
+following clause:<codeblock>VALUES SUBSTR('hello',1,2)</codeblock>The result
+is '<codeph>he</codeph>'.</p></example>
</refbody>
</reference>
-
Modified: db/derby/docs/trunk/src/ref/rreftimestampfunc.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rreftimestampfunc.dita?view=diff&rev=464772&r1=464771&r2=464772
==============================================================================
--- db/derby/docs/trunk/src/ref/rreftimestampfunc.dita (original)
+++ db/derby/docs/trunk/src/ref/rreftimestampfunc.dita Mon Oct 16 19:35:33 2006
@@ -23,7 +23,8 @@
<shortdesc>The TIMESTAMP function returns a timestamp from a value or a pair
of values.</shortdesc>
<prolog><metadata>
-<keywords><indexterm>TIMESTAMP function</indexterm></keywords>
+<keywords><indexterm>functions<indexterm>TIMESTAMP</indexterm></indexterm>
+<indexterm>TIMESTAMP function</indexterm></keywords>
</metadata></prolog>
<refbody>
<section> <p>The rules for the arguments depend on whether the second argument
@@ -47,9 +48,14 @@
timestamp represented by that string. If the argument is a string of length
14, the timestamp has a microsecond part of zero. </li>
</ul></p></section>
-<refsyn><title>Syntax</title> <codeblock><b>TIMESTAMP ( <i>expression</i> [, <i>expression</i> ] )</b></codeblock> </refsyn>
-<example> <p>Assume the column START_DATE (date) has a value equivalent to
-1998-12-25, and the column START_TIME (time) has a value equivalent to 17.12.30.</p> <codeblock><b>TIMESTAMP(START_DATE, START_TIME)</b></codeblock
-> <p>Returns the value '1998-12-25-17.12.30.000000'.</p> </example>
+<refsyn><title>Syntax</title><codeblock>TIMESTAMP ( <i>expression</i> [, <i>expression</i> ] )</codeblock> </refsyn>
+<example><title>Examples</title><p>The second column in table <codeph>records_table</codeph> contains
+dates (such as 1998-12-25) and the third column contains times of day (such
+as 17:12:30). You can return the timestamp with this statement:<codeblock>SELECT TIMESTAMP(col2, col3) FROM records_table</codeblock></p><p>The
+following clause returns the value <codeph>1998-12-25-17:12:30.0</codeph>:<codeblock>VALUES TIMESTAMP('1998-12-25', '17.12.30');
+1
+--------------------------
+1998-12-25 17:12:30.0
+</codeblock></p> </example>
</refbody>
</reference>