Author: fuzzylogic
Date: Thu Sep 28 15:22:05 2006
New Revision: 451045
URL: http://svn.apache.org/viewvc?view=rev&rev=451045
Log:
DERBY-1839: Comments from Doc Review related to XML functions.
Committed for Laura Stewart <scotsmatrix@gmail.com>
Modified:
db/derby/docs/trunk/src/ref/rreffuncxmlexists.dita
db/derby/docs/trunk/src/ref/rreffuncxmlquery.dita
db/derby/docs/trunk/src/ref/rreffuncxmlserialize.dita
db/derby/docs/trunk/src/ref/rrefjdbc88908.dita
db/derby/docs/trunk/src/ref/rrefsqlj33562.dita
db/derby/docs/trunk/src/ref/rrefsqljtypexml.dita
Modified: db/derby/docs/trunk/src/ref/rreffuncxmlexists.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rreffuncxmlexists.dita?view=diff&rev=451045&r1=451044&r2=451045
==============================================================================
--- db/derby/docs/trunk/src/ref/rreffuncxmlexists.dita (original)
+++ db/derby/docs/trunk/src/ref/rreffuncxmlexists.dita Thu Sep 28 15:22:05 2006
@@ -35,34 +35,34 @@
<dt><codeph>xquery-string-literal</codeph></dt>
<dd>Must be specified as a string literal. If this argument is specified as
a parameter, an expression that is not a literal, or a literal that is not
-a string (for example an integer), <ph conref="refconrefs.dita#prod/productshortname"></ph>
returns
+a string (for example an integer), <ph conref="refconrefs.dita#prod/productshortname"></ph>
throws
an error. The <codeph>xquery-string-literal</codeph> argument must also be
an XPath expression that is supported by Apache Xalan. <ph conref="refconrefs.dita#prod/productshortname"></ph>
uses
Apache Xalan to evaluate all XML query expressions. Because Xalan does not
support full XQuery, neither does <ph conref="refconrefs.dita#prod/productshortname"></ph>.
If Xalan is unable to compile or execute the query argument, <ph conref="refconrefs.dita#prod/productshortname"></ph>
catches
the error that is thrown by Xalan and throws the error as a SQLException.
-For more on XPath and XQuery expressions, see the these Web sites: <xref format="html"
+For more on XPath and XQuery expressions, see these Web sites: <xref format="html"
href="http://www.w3.org/TR/xpath">http://www.w3.org/TR/xpath</xref> and <xref
format="html" href="http://www.w3.org/TR/xquery/">http://www.w3.org/TR/xquery/</xref>.</dd>
</dlentry><dlentry>
<dt><codeph>xml-value-expression</codeph></dt>
-<dd>Must be an XML data type and must constitute a valid SQL/XML document.
+<dd>Must be an XML data value and must constitute a well-formed SQL/XML document.
The <codeph>xml-value-expression</codeph> argument cannot be a parameter.
<ph conref="refconrefs.dita#prod/productshortname"></ph> does not perform
implicit parsing nor casting of XML values, so use of strings or any other
data type results in an error. If the argument is a sequence that is returned
by the <ph conref="refconrefs.dita#prod/productshortname"></ph> <xref href="rreffuncxmlquery.dita#rreffuncxmlquery"></xref>,
the argument is accepted if it is a sequence of exactly one node that is a
-document node. Otherwise <ph conref="refconrefs.dita#prod/productshortname"></ph>
returns
+document node. Otherwise <ph conref="refconrefs.dita#prod/productshortname"></ph>
throws
an error.</dd>
</dlentry><dlentry>
<dt>BY REF</dt>
<dd>Optional keywords that describe the only value passing mechanism supported
-by <ph conref="refconrefs.dita#prod/productshortname"></ph>. Since the BY
-REF clause is also the default passing mechanism, the XMLEXISTS operator behaves
-the same whether the keywords are present or not. For more information on
-passing mechanisms, see the SQL/XML specification.</dd>
+by <ph conref="refconrefs.dita#prod/productshortname"></ph>. Since BY REF
+is also the default passing mechanism, the XMLEXISTS operator behaves the
+same whether the keywords are present or not. For more information on passing
+mechanisms, see the SQL/XML specification.</dd>
</dlentry></dl></refsyn>
<section><title>Operator results and combining with other operators</title><p>The
result of the XMLEXISTS operator is a SQL boolean value that is based on the
@@ -94,8 +94,8 @@
and contains the element <codeph>/roster/student</codeph>, use this statement:<codeblock>SELECT
id FROM <varname>x_table</varname> WHERE XMLEXISTS('<varname
>/roster/student</varname>' PASSING BY REF <varname>xcol</varname>)</codeblock></p><p>You
can create the <codeph>x_table</codeph> table with a check constraint that
-allows an XML value to be inserted into the <codeph>xcol</codeph> XML column.
-The constraint is that the column has at least one <codeph>student</codeph> element
+limits which XML values can be inserted into the <codeph>xcol</codeph> XML
+column. In this example, the constraint is that the column has at least one <codeph>student</codeph>
element
with an <codeph>age</codeph> attribute with a value that is less than 25.
To create the table, use this statement:<codeblock>CREATE TABLE <varname>x_table</varname>
( id INT, <varname>xcol</varname> XML CHECK (XMLEXISTS ('<varname
>//student[@age &lt; 25]</varname>' PASSING BY REF <varname>xcol</varname>))
)</codeblock></p></section>
Modified: db/derby/docs/trunk/src/ref/rreffuncxmlquery.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rreffuncxmlquery.dita?view=diff&rev=451045&r1=451044&r2=451045
==============================================================================
--- db/derby/docs/trunk/src/ref/rreffuncxmlquery.dita (original)
+++ db/derby/docs/trunk/src/ref/rreffuncxmlquery.dita Thu Sep 28 15:22:05 2006
@@ -37,41 +37,41 @@
<dt><codeph>xquery-string-literal</codeph></dt>
<dd>Must be specified as a string literal. If this argument is specified as
a parameter, an expression that is not a literal, or a literal that is not
-a string (for example an integer), <ph conref="refconrefs.dita#prod/productshortname"></ph>
returns
+a string (for example an integer),<ph conref="refconrefs.dita#prod/productshortname"></ph>
throws
an error. The <codeph>xquery-string-literal</codeph> argument must also be
an XPath expression that is supported by Apache Xalan. <ph conref="refconrefs.dita#prod/productshortname"></ph>
uses
Apache Xalan to evaluate all XML query expressions. Because Xalan does not
support full XQuery, neither does <ph conref="refconrefs.dita#prod/productshortname"></ph>.
If Xalan is unable to compile or execute the query argument, <ph conref="refconrefs.dita#prod/productshortname"></ph>
catches
the error that is thrown by Xalan and throws the error as a SQLException.
-For more on XPath and XQuery expressions, see the these Web sites: <xref format="html"
+For more on XPath and XQuery expressions, see these Web sites: <xref format="html"
href="http://www.w3.org/TR/xpath">http://www.w3.org/TR/xpath</xref> and <xref
format="html" href="http://www.w3.org/TR/xquery/">http://www.w3.org/TR/xquery/</xref>.</dd>
</dlentry><dlentry>
<dt><codeph>xml-value-expression</codeph></dt>
-<dd>Must be an XML data type and must constitute a valid SQL/XML document.
+<dd>Must be an XML data value and must constitute a well-formed SQL/XML document.
The <codeph>xml-value-expression</codeph> argument cannot be a parameter.
<ph conref="refconrefs.dita#prod/productshortname"></ph> does not perform
implicit parsing nor casting of XML values, so use of strings or any other
data type results in an error. If the argument is a sequence that is returned
by a <ph conref="refconrefs.dita#prod/productshortname"></ph> XMLQUERY operation,
the argument is accepted if it is a sequence of exactly one node that is a
-document node. Otherwise <ph conref="refconrefs.dita#prod/productshortname"></ph>
returns
-an error.</dd>
+document node. Otherwise <ph conref="refconrefs.dita#prod/productshortname"></ph>
throws
+an error. </dd>
</dlentry><dlentry>
<dt>BY REF</dt>
<dd>Optional keywords that describe the only value passing mechanism supported
-by <ph conref="refconrefs.dita#prod/productshortname"></ph>. Since the BY
-REF clause is also the default passing mechanism, the XMLQUERY operator behaves
-the same whether the keywords are present or not. For more information on
-passing mechanisms, see the SQL/XML specification.</dd>
+by <ph conref="refconrefs.dita#prod/productshortname"></ph>. Since BY REF
+is also the default passing mechanism, the XMLQUERY operator behaves the same
+whether the keywords are present or not. For more information on passing mechanisms,
+see the SQL/XML specification.</dd>
</dlentry><dlentry>
<dt>RETURNING SEQUENCE</dt>
<dd>Optional keywords that describe the only XML type returned by the <ph
conref="refconrefs.dita#prod/productshortname"></ph> XMLQUERY operator. Since
-the RETURNING SEQUENCE clause is also the default return type, the XMLQUERY
-operator behaves the same whether the keywords are present or not. For more
-information on the different XML return types, see the SQL/XML specification.</dd>
+SEQUENCE is also the default return type, the XMLQUERY operator behaves the
+same whether the keywords are present or not. For more information on the
+different XML return types, see the SQL/XML specification.</dd>
</dlentry><dlentry>
<dt>EMPTY ON EMPTY</dt>
<dd>Required keywords that describe the way in which XMLQUERY handles an empty
@@ -80,15 +80,15 @@
to a null value. When an empty result sequence is serialized, the result
is an empty string. <ph conref="refconrefs.dita#prod/productshortname"></ph>
does
not consider an empty result sequence to be a well-formed XML document.</dd>
-</dlentry></dl><p>The result of the XMLQUERY operator is another Derby
XML
-value. Unlike other XML values, the result might represent an empty sequence
-of XML nodes or values. Atomic values, such as strings, can be part of the
-result sequence. The result of an XMLQUERY operator is not guaranteed to represent
-a valid XML document and it might not be possible to insert the result of
-an XMLQUERY operator into a Derby XML column. To store the result in a Derby
-XML column, the result must be a sequence with exactly one item in the sequence
-and the item must be a well-formed document node. The result can be viewed
-only in serialized form by explicitly using the <xref href="rreffuncxmlserialize.dita#rreffuncxmlserialize"></xref>.
</p></refsyn>
+</dlentry></dl><p>The result of the XMLQUERY operator is a value of type
XML.
+The result represents a sequence of XML nodes or values. Atomic values, such
+as strings, can be part of the result sequence. The result of an XMLQUERY
+operator is not guaranteed to represent a well-formed XML document and it
+might not be possible to insert the result of an XMLQUERY operator into an
+XML column. To store the result in an XML column, the result must be a sequence
+with exactly one item in the sequence and the item must be a well-formed document
+node. The result can be viewed only in serialized form by explicitly using
+the <xref href="rreffuncxmlserialize.dita#rreffuncxmlserialize"></xref>. </p></refsyn>
<section><title>Examples</title><p>In the <codeph>x_table</codeph>
table,
to search the XML column <codeph>xcol</codeph> and return the students that
have an age attribute that is greater than 20, use the following statement:<codeblock>SELECT
ID,
@@ -102,13 +102,13 @@
the <codeph>x_table</codeph> table, to search the XML column <codeph>xcol</codeph>
and
return the ages for any students named BC, use the following statement:<codeblock>SELECT
ID,
XMLSERIALIZE(
- XMLQUERY('<varname>//student[text() = "BC"]/@age</varname>' PASSING BY
REF <varname>xcol</varname> EMPTY ON EMPTY)
+ XMLQUERY('<varname>string(//student[text() = "BC"]/@age</varname>)' PASSING
BY REF <varname>xcol</varname> EMPTY ON EMPTY)
AS VARCHAR(50))
FROM <varname>x_table</varname>
WHERE
XMLEXISTS('<varname>//student[text() = "BC"]</varname>' PASSING BY REF <varname>xcol</varname>)
</codeblock> The result set for this query contains a row for only the rows
-in <codeph>x_table</codeph> that has a student name of BC.</p></section>
+in <codeph>x_table</codeph> that have a student whose name is BC.</p></section>
<section><title>Usage note</title><p><ph conref="refconrefs.dita#prod/productshortname"></ph>
requires
that a JAXP parser, such as Apache Xerces, and that Apache Xalan are listed
in the Java classpath for the XML functions to work. If either the JAXP parser
Modified: db/derby/docs/trunk/src/ref/rreffuncxmlserialize.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rreffuncxmlserialize.dita?view=diff&rev=451045&r1=451044&r2=451045
==============================================================================
--- db/derby/docs/trunk/src/ref/rreffuncxmlserialize.dita (original)
+++ db/derby/docs/trunk/src/ref/rreffuncxmlserialize.dita Thu Sep 28 15:22:05 2006
@@ -20,26 +20,25 @@
-->
<reference id="rreffuncxmlserialize" xml:lang="en-us">
<title>XMLSERIALIZE operator</title>
-<shortdesc>XMLSERIALIZE is a SQL/XML operator that you can use to view the
-serialized contents of an XML value in <ph conref="refconrefs.dita#prod/productshortname"></ph>.</shortdesc>
+<shortdesc>XMLSERIALIZE is a SQL/XML operator that you can use to convert
+an XML type to a character type. There is no other way to convert the type
+of a <ph conref="refconrefs.dita#prod/productshortname"></ph> XML value.</shortdesc>
<prolog><metadata>
<keywords><indexterm>XMLSERIALIZE operator</indexterm><indexterm>operators<indexterm>XMLSERIALIZE</indexterm></indexterm>
<indexterm>XML<indexterm>operators, XMLSERIALIZE</indexterm></indexterm></keywords>
</metadata></prolog>
<refbody>
-<section> <p> Using the XMLSERIALIZE operator is the only way that you can
-view serialized contents. </p><note type="attention">Serialization is performed
-based on the SQL/XML serialization rules. These rules, combined with the fact
-that <ph conref="refconrefs.dita#prod/productshortname"></ph> supports only
-a subset of the XMLSERIALIZE syntax, dictate that the results of an XMLSERIALIZE
+<section> <note type="attention">Serialization is performed based on the SQL/XML
+serialization rules. These rules, combined with the fact that <ph conref="refconrefs.dita#prod/productshortname"></ph>
supports
+only a subset of the XMLSERIALIZE syntax, dictate that the results of an XMLSERIALIZE
operation are not guaranteed to be in-tact copies of the original XML text.
For example, assume that <codeph>[xString]</codeph> is a textual representation
-of a well-formed XML document. You issue the following statements:<codeblock>INSERT
INTO <varname>xTable</varname> (<varname>id</varname>, <varname
+of a well-formed XML document. You issue the following statements:<codeblock>INSERT
INTO <varname>x_table</varname> (<varname>id</varname>, <varname
>xcol</varname>)
VALUES (3, XMLPARSE(DOCUMENT '<varname>[xString]</varname>' PRESERVE WHITESPACE));
SELECT id, XMLSERIALIZE(<varname>xcol</varname> AS VARCHAR(100))
- FROM <varname>xTable</varname> WHERE id = 3;
+ FROM <varname>x_table</varname> WHERE id = 3;
</codeblock><p>There is no guarantee that the result of the XMLSERIALIZE operator
will be identical to the original <codeph>[xString]</codeph> representation.
Certain transformations can occur as part of XMLSERIALIZE processing, and
Modified: db/derby/docs/trunk/src/ref/rrefjdbc88908.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefjdbc88908.dita?view=diff&rev=451045&r1=451044&r2=451045
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefjdbc88908.dita (original)
+++ db/derby/docs/trunk/src/ref/rrefjdbc88908.dita Thu Sep 28 15:22:05 2006
@@ -1,4 +1,5 @@
<?xml version="1.0" encoding="utf-8"?>
+
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN"
"../dtd/reference.dtd">
<!--
@@ -127,7 +128,7 @@
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
+<dd>Returns a 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>
Modified: db/derby/docs/trunk/src/ref/rrefsqlj33562.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefsqlj33562.dita?view=diff&rev=451045&r1=451044&r2=451045
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefsqlj33562.dita (original)
+++ db/derby/docs/trunk/src/ref/rrefsqlj33562.dita Thu Sep 28 15:22:05 2006
@@ -692,7 +692,8 @@
-- cast a SMALLINT to a BIGINT
VALUES CAST (CAST (12 as SMALLINT) as BIGINT)</b></codeblock> </example>
<section><title>Conversions of XML values</title><p>An XML value
cannot be
-converted to a non-XML type. To convert an XML value to a string, you must
-use the SQL/XML serialization operator XMLSERIALIZE.</p> </section>
+converted to any non-XML type using an explicit or implicit CAST. Use the <xref
+href="rreffuncxmlserialize.dita#rreffuncxmlserialize"></xref> to convert an
+XML type to a character type.</p> </section>
</refbody>
</reference>
Modified: db/derby/docs/trunk/src/ref/rrefsqljtypexml.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefsqljtypexml.dita?view=diff&rev=451045&r1=451044&r2=451045
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefsqljtypexml.dita (original)
+++ db/derby/docs/trunk/src/ref/rrefsqljtypexml.dita Thu Sep 28 15:22:05 2006
@@ -20,17 +20,20 @@
-->
<reference id="rrefsqljtypexml" xml:lang="en-us">
<title>XML data type</title>
-<shortdesc>An XML column is used to store Unicode character-based data, such
-as large documents in any character set, that conform to the SQL/XML definition
-of a well-formed XML(DOCUMENT(ANY)) value. </shortdesc>
+<shortdesc>The XML data type is used for Extensible Markup Language (XML)
+documents.</shortdesc>
<prolog><metadata>
<keywords><indexterm>XML data type</indexterm></keywords>
</metadata></prolog>
<refbody>
-<section> <p>An XML value can be up to 2,147,483,647 characters long. </p><note>For
-an application to retrieve, update, query, or otherwise access an XML data
-value, the application must have classes for a JAXP parser and for Xalan in
-the classpath. <ph conref="refconrefs.dita#prod/productshortname"></ph> issues
+<section> <p>The XML data type is used: <ul>
+<li>To store XML documents that conform to the SQL/XML definition of a well-formed
+XML(DOCUMENT(ANY)) value.</li>
+<li>Transiently for XML(SEQUENCE) values, that might not be well-formed XML(DOCUMENT(ANY))
+values.</li>
+</ul></p><note>For an application to retrieve, update, query, or otherwise
+access an XML data value, the application must have classes for a JAXP parser
+and for Xalan in the classpath. <ph conref="refconrefs.dita#prod/productshortname"></ph>
issues
an error if either the parser or Xalan is not found.<p>Because none of the
JDBC-side support for SQL/XML is implemented in <ph conref="refconrefs.dita#prod/productshortname"></ph>,
it is not possible to bind directly into an XML value or to retrieve an XML
@@ -53,7 +56,7 @@
using JDBC, use the XMLPARSE operator in the SQL statement. For example: <codeblock>INSERT
INTO myXmlTable(xcol) VALUES XMLPARSE(
DOCUMENT CAST (? AS CLOB) PRESERVE WHITESPACE)
</codeblock>Then use any of the setXXX methods that are compatible with String
-types, in this example use the PreparedStatement.setString or PreparedStatementsetCharacterStream
+types, in this example use the PreparedStatement.setString or PreparedStatement.setCharacterStream
method calls to bind the operator.</p> </section>
</refbody>
</reference>