db-derby-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From fuzzylo...@apache.org
Subject svn commit: r451045 - in /db/derby/docs/trunk/src/ref: rreffuncxmlexists.dita rreffuncxmlquery.dita rreffuncxmlserialize.dita rrefjdbc88908.dita rrefsqlj33562.dita rrefsqljtypexml.dita
Date Thu, 28 Sep 2006 22:22:09 GMT
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>



Mime
View raw message