db-derby-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From chaa...@apache.org
Subject svn commit: r1609163 - /db/derby/docs/trunk/src/tuning/
Date Wed, 09 Jul 2014 14:07:47 GMT
Author: chaase3
Date: Wed Jul  9 14:07:47 2014
New Revision: 1609163

URL: http://svn.apache.org/r1609163
Log:
DERBY-6379  Manuals are inconsistent in their use of the <shortdesc> element

Modified 25 Tuning Guide topics.

Patch: DERBY-6379-tun-depth.diff

Modified:
    db/derby/docs/trunk/src/tuning/ctun_xplain_style.dita
    db/derby/docs/trunk/src/tuning/ctun_xplain_tables.dita
    db/derby/docs/trunk/src/tuning/ctundepth1002853.dita
    db/derby/docs/trunk/src/tuning/ctundepth1003116.dita
    db/derby/docs/trunk/src/tuning/ctundepth1003209.dita
    db/derby/docs/trunk/src/tuning/ctundepth1003369.dita
    db/derby/docs/trunk/src/tuning/ctundepth1003672.dita
    db/derby/docs/trunk/src/tuning/ctundepth10525.dita
    db/derby/docs/trunk/src/tuning/ctundepth13055.dita
    db/derby/docs/trunk/src/tuning/ctundepth14326.dita
    db/derby/docs/trunk/src/tuning/ctundepth21935.dita
    db/derby/docs/trunk/src/tuning/ctundepth23033.dita
    db/derby/docs/trunk/src/tuning/ctundepth26674.dita
    db/derby/docs/trunk/src/tuning/ctundepth29804.dita
    db/derby/docs/trunk/src/tuning/ctundepth32379.dita
    db/derby/docs/trunk/src/tuning/ctundepth36205.dita
    db/derby/docs/trunk/src/tuning/ctundepth37648.dita
    db/derby/docs/trunk/src/tuning/ctundepth39739.dita
    db/derby/docs/trunk/src/tuning/ctundepth853095.dita
    db/derby/docs/trunk/src/tuning/ctundepth853133.dita
    db/derby/docs/trunk/src/tuning/ctundepth853228.dita
    db/derby/docs/trunk/src/tuning/ctundepthoptover.dita
    db/derby/docs/trunk/src/tuning/ctunperf1004182.dita
    db/derby/docs/trunk/src/tuning/ttundepth33391.dita
    db/derby/docs/trunk/src/tuning/ttundepth34375.dita

Modified: db/derby/docs/trunk/src/tuning/ctun_xplain_style.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/ctun_xplain_style.dita?rev=1609163&r1=1609162&r2=1609163&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tuning/ctun_xplain_style.dita (original)
+++ db/derby/docs/trunk/src/tuning/ctun_xplain_style.dita Wed Jul  9 14:07:47 2014
@@ -5,7 +5,7 @@ contributor license agreements.  See the
 this work for additional information regarding copyright ownership.
 The ASF licenses this file to You under the Apache License, Version 2.0
 (the "License"); you may not use this file except in compliance with
-the License.  You may obtain a copy of the License at      
+the License.  You may obtain a copy of the License at  
 
 http://www.apache.org/licenses/LICENSE-2.0  
 
@@ -19,131 +19,107 @@ limitations under the License.
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "../dtd/concept.dtd">
 <concept xml:lang="en-us" id="ctun_xplain_style">
 <title>How you use the XPLAIN style</title>
+<shortdesc>XPLAIN style is an enhanced form of RUNTIMESTATISTICS processing
+which preserves captured statistics information in database tables.</shortdesc>
 <prolog><metadata>
 <keywords>
-    <indexterm>XPLAIN style<indexterm>using</indexterm></indexterm>
+<indexterm>XPLAIN style<indexterm>using</indexterm></indexterm>
 </keywords>
 </metadata>
 </prolog>
 <conbody>
-<section><title>Overview</title>
-    <p>
-        XPLAIN style is an enhanced form of RUNTIMESTATISTICS processing
-        which preserves captured statistics information in 
-        <xref href="ctun_xplain_tables.dita#ctun_xplain_tables">database 
-            tables</xref>.
-        Once the statistics have been collected and saved in the 
-        tables, they can be queried for analysis purposes.
-    </p>
-    <p>
-        Note that <ph conref="../conrefs.dita#prod/productshortname"></ph>
-        spells XPLAIN without the initial 'E'. This is done
-        to help distinguish the
-        <ph conref="../conrefs.dita#prod/productshortname"></ph>
-        functionality from the explain
-        functionality that you might be familiar with from commercial DBMS
-        products. The current XPLAIN implementation is optimized for
-        ad-hoc queries and tool support. Furthermore, the explain data
-        is quite extensive to analyze. 
-        <ph conref="../conrefs.dita#prod/productshortname"></ph>
-        tries to implement a
-        compromise between detailed explain information which is
-        almost unreadable by human users and which has to be evaluated
-        with the help of a tool, versus a compact version of explain
-        data which is only applicable for rough investigations but
-        is still browseable by human users. We feel that the information
-        in the XPLAIN system tables is sufficiently detailed to be powerful,
-        but still simple enough to provide useful information to
-        ad-hoc querying during interactive use.
-    </p>
-    <p>
-    To use XPLAIN style, first turn on RUNTIMESTATISTICS using the
-            <codeph>SYSCS_UTIL.SYSCS_SET_RUNTIMESTATISTICS()</codeph> system
-            procedure.</p>
-        <p>Optionally, turn on statistics timing using the
-            <codeph>SYSCS_UTIL.SYSCS_SET_STATISTICS_TIMING</codeph>
-            system procedure.  If you do not turn on statistics timing,
-            you will see the statement execution
-            plan only, and not the timing information.</p>
-        <p>Next, to activate XPLAIN style, use the
-            <codeph>SYSCS_UTIL.SYSCS_SET_XPLAIN_SCHEMA()</codeph> system
-        procedure:</p>
-<codeblock>-- turn on RUNTIMESTATISTICS for connection:
+<section>
+<p>Once the statistics have been collected and saved in the tables, they can be
+queried for analysis purposes. See <xref href="ctun_xplain_tables.dita"/> for
+details.</p>
+<p>Note that <ph conref="../conrefs.dita#prod/productshortname"></ph> spells
+XPLAIN without the initial 'E'. This is helps distinguish the
+<ph conref="../conrefs.dita#prod/productshortname"></ph> functionality from the
+explain functionality that you might be familiar with from commercial DBMS
+products. The current XPLAIN implementation is optimized for ad-hoc queries and
+tool support. Furthermore, the explain data is quite extensive to analyze. 
+<ph conref="../conrefs.dita#prod/productshortname"></ph> tries to implement a
+compromise between detailed explain information (which is almost unreadable by
+human users and has to be evaluated with the help of a tool) and a compact
+version of explain data which is only applicable for rough investigations but
+is still browseable by human users. The information in the XPLAIN system tables
+is sufficiently detailed to be powerful, but still simple enough to provide
+useful information to ad-hoc querying during interactive use.</p>
+<p>To use XPLAIN style, first turn on RUNTIMESTATISTICS using the
+<codeph>SYSCS_UTIL.SYSCS_SET_RUNTIMESTATISTICS()</codeph> system procedure.</p>
+<p>Optionally, turn on statistics timing using the
+<codeph>SYSCS_UTIL.SYSCS_SET_STATISTICS_TIMING</codeph> system procedure. If you
+do not turn on statistics timing, you will see the statement execution plan
+only, and not the timing information.</p>
+<p>Next, to activate XPLAIN style, use the
+<codeph>SYSCS_UTIL.SYSCS_SET_XPLAIN_SCHEMA()</codeph> system procedure:</p>
+<codeblock>-- Turn on RUNTIMESTATISTICS for connection:
 <b>CALL SYSCS_UTIL.SYSCS_SET_RUNTIMESTATISTICS(1);</b>
 <b>CALL SYSCS_UTIL.SYSCS_SET_STATISTICS_TIMING(1);</b>
 -- Indicate that statistics information should be captured into
 -- database tables in the MYSCHEMA schema:
 <b>CALL SYSCS_UTIL.SYSCS_SET_XPLAIN_SCHEMA('MYSCHEMA');</b>
---execute queries, step through result sets, perform application processing...
+-- Execute queries, step through result sets, perform application
+-- processing ...
 <b>CALL SYSCS_UTIL.SYSCS_SET_RUNTIMESTATISTICS(0);</b></codeblock>
-<p>Although the syntax is different, the basic steps for working with
-    XPLAIN style are the same in a Java program.</p>
-<p>XPLAIN style is further refined by the use of XPLAIN-only mode. By
-    default, XPLAIN-only mode is off, which means that statements are
-    compiled and executed normally. When XPLAIN-only mode is on, statements
-    are compiled, but not executed. This is useful for investigating what
-    query plan has been selected for a statement, without actually
-    executing the statement. To activate XPLAIN-only mode, use the
-    <codeph>SYSCS_UTIL.SYSCS_SET_XPLAIN_MODE()</codeph> system procedure:</p>
-<codeblock>
-    call SYSCS_UTIL.SYSCS_SET_XPLAIN_MODE(1);
-</codeblock>
+<p>Although the syntax is different, the basic steps for working with XPLAIN
+style are the same in a Java program.</p>
+<p>XPLAIN style is further refined by the use of XPLAIN-only mode. By default,
+XPLAIN-only mode is off, which means that statements are compiled and executed
+normally. When XPLAIN-only mode is on, statements are compiled, but not
+executed. This is useful for investigating what query plan has been selected for
+a statement without actually executing the statement. To activate XPLAIN-only
+mode, use the <codeph>SYSCS_UTIL.SYSCS_SET_XPLAIN_MODE()</codeph> system
+procedure:</p>
+<codeblock><b>CALL SYSCS_UTIL.SYSCS_SET_XPLAIN_MODE(1);</b></codeblock>
 </section>
-<section><title>Examples</title><p>Some examples of usage follow.</p>
-    <p>Retrieve the text of statements
-        which were captured, in order by the time when the statistics were
-    captured:</p>
-<codeblock>
-    select stmt_text, xplain_time from myschema.sysxplain_statements
-    order by xplain_time
-</codeblock>
-<p>Retrieve the text of statements which were captured, showing the
-    statements which took the longest time to execute first:</p>
-<codeblock>
-    select s.stmt_text, st.execute_time from myschema.sysxplain_statements s,
-           myschema.sysxplain_statement_timings st
-    where s.timing_id = st.timing_id
-    order by st.execute_time desc
-</codeblock>
-<p>Show the statements that were executed, together with the result sets
-    that each statement required:</p>
-<codeblock>
-    select st.stmt_text, rs.op_identifier 
-    from myschema.sysxplain_statements st
-    join myschema.sysxplain_resultsets rs
-         on st.stmt_id = rs.stmt_id
-</codeblock>
+<section><title>Examples</title>
+<p>Some examples of usage follow.</p>
+<p>Retrieve the text of statements which were captured, in order by the time
+when the statistics were captured:</p>
+<codeblock>select stmt_text, xplain_time 
+from myschema.sysxplain_statements
+order by xplain_time</codeblock>
+<p>Retrieve the text of statements which were captured, showing the statements
+which took the longest time to execute first:</p>
+<codeblock>select s.stmt_text, st.execute_time
+from myschema.sysxplain_statements s,
+     myschema.sysxplain_statement_timings st
+where s.timing_id = st.timing_id
+order by st.execute_time desc</codeblock>
+<p>Show the statements that were executed, together with the result sets that
+each statement required:</p>
+<codeblock>select st.stmt_text, rs.op_identifier 
+from myschema.sysxplain_statements st
+join myschema.sysxplain_resultsets rs
+     on st.stmt_id = rs.stmt_id</codeblock>
 <p>Find statements which resulted in an external sort being performed:</p>
-<codeblock>
-    select s.stmt_text, s.stmt_id, rs.op_identifier, srt.no_input_rows
-    from myschema.sysxplain_sort_props srt,
-         myschema.sysxplain_resultsets rs,
-         myschema.sysxplain_statements s
-    where rs.stmt_id = s.stmt_id and rs.sort_rs_id = srt.sort_rs_id
-          and srt.sort_type = 'EX'
-</codeblock>
-<p>Show statements which resulted in a sort, sorted by the number of
-    rows which were sorted by that statement.</p>
-<codeblock>
-    select s.stmt_text, s.stmt_id, rs.op_identifier, srt.no_input_rows
-    from myschema.sysxplain_sort_props srt,
-         myschema.sysxplain_resultsets rs,
-         myschema.sysxplain_statements s
-    where rs.stmt_id = s.stmt_id and rs.sort_rs_id = srt.sort_rs_id
-    order by srt.no_input_rows desc
-</codeblock>
-<p>Find statements which resulted in a tablescan of the COUNTRIES table,
-    and display the number of pages and rows that were visited by each scan:</p>
-<codeblock>
-    select st.stmt_text, sp.no_visited_pages, sp.no_visited_rows 
-    from myschema.sysxplain_scan_props sp, 
-         myschema.sysxplain_resultsets rs, 
-         myschema.sysxplain_statements st 
-    where st.stmt_id = rs.stmt_id and 
-          rs.scan_rs_id = sp.scan_rs_id and 
-          rs.op_identifier = 'TABLESCAN' and 
-          sp.scan_object_name = 'COUNTRIES'
-</codeblock>
+<codeblock>select s.stmt_text, s.stmt_id, rs.op_identifier, srt.no_input_rows
+from myschema.sysxplain_sort_props srt,
+     myschema.sysxplain_resultsets rs,
+     myschema.sysxplain_statements s
+where rs.stmt_id = s.stmt_id and
+      rs.sort_rs_id = srt.sort_rs_id and
+      srt.sort_type = 'EX'</codeblock>
+<p>Show statements which resulted in a sort, sorted by the number of rows which
+were sorted by that statement.</p>
+<codeblock>select s.stmt_text, s.stmt_id, rs.op_identifier, srt.no_input_rows
+from myschema.sysxplain_sort_props srt,
+     myschema.sysxplain_resultsets rs,
+     myschema.sysxplain_statements s
+where rs.stmt_id = s.stmt_id and
+      rs.sort_rs_id = srt.sort_rs_id
+order by srt.no_input_rows desc</codeblock>
+<p>Find statements which resulted in a table scan of the COUNTRIES table, and
+display the number of pages and rows that were visited by each scan:</p>
+<codeblock>select st.stmt_text, sp.no_visited_pages, sp.no_visited_rows 
+from myschema.sysxplain_scan_props sp, 
+     myschema.sysxplain_resultsets rs, 
+     myschema.sysxplain_statements st 
+where st.stmt_id = rs.stmt_id and 
+      rs.scan_rs_id = sp.scan_rs_id and 
+      rs.op_identifier = 'TABLESCAN' and 
+      sp.scan_object_name = 'COUNTRIES'</codeblock>
 </section>
 </conbody></concept>
 

Modified: db/derby/docs/trunk/src/tuning/ctun_xplain_tables.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/ctun_xplain_tables.dita?rev=1609163&r1=1609162&r2=1609163&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tuning/ctun_xplain_tables.dita (original)
+++ db/derby/docs/trunk/src/tuning/ctun_xplain_tables.dita Wed Jul  9 14:07:47 2014
@@ -5,7 +5,7 @@ contributor license agreements.  See the
 this work for additional information regarding copyright ownership.
 The ASF licenses this file to You under the Apache License, Version 2.0
 (the "License"); you may not use this file except in compliance with
-the License.  You may obtain a copy of the License at      
+the License.  You may obtain a copy of the License at  
 
 http://www.apache.org/licenses/LICENSE-2.0  
 
@@ -19,89 +19,67 @@ limitations under the License.
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "../dtd/concept.dtd">
 <concept xml:lang="en-us" id="ctun_xplain_tables">
 <title>Understanding XPLAIN style database tables</title>
+<shortdesc>XPLAIN style is an enhanced form of RUNTIMESTATISTICS processing
+which preserves captured statistics information in database tables. Once the
+statistics have been collected and saved in the tables, they can be queried for
+analysis purposes.</shortdesc>
 <prolog><metadata>
 <keywords>
-    <indexterm>XPLAIN style</indexterm>
+<indexterm>XPLAIN style</indexterm>
 </keywords>
 </metadata>
 </prolog>
 <conbody>
-    <p>
-        XPLAIN style is an enhanced form of RUNTIMESTATISTICS processing
-        which preserves captured statistics information in database tables.
-        Once the statistics have been collected and saved in the 
-        tables, they can be queried for analysis purposes.
-    </p>
-    <p>
-        Rows accumulate in the SYSXPLAIN_* database tables until you 
-        empty the tables by dropping them or executing DELETE FROM statements
-        against them.
-    </p>
-    <p>
-        Note that, although these tables have stylized names which all
-        start with the prefix "SYSXPLAIN_*", they are not in fact special
-        system catalogs, but are merely ordinary database tables, which
-        can be accessed in all the standard ways that any other database
-        table is accessed. The tables are automatically created if they
-        are not present when statistics are being captured. The tables
-        are all located in a particular schema which is specified by the
-        <codeph>SYSCS_UTIL.SYSCS_SET_XPLAIN_SCHEMA()</codeph> system procedure.
-    </p>
-    <p>
-        The XPLAIN style database tables are summarized here. For more
-        information about the structure and content of each table,
-        see "XPLAIN style tables" in
-        the <ph conref="../conrefs.dita#pub/citref"></ph>.
-    </p>
-    <dl>
-        <dlentry>
-        <dt>SYSXPLAIN_STATEMENTS</dt>
-        <dd>This table contains one row for each statement which
-            has had statistics captured. This row contains the text of the
-            statement, as well as identifiers which can be used to join with
-            the other tables to find more data about how this statement was
-            executed.
-        </dd>
-        </dlentry>
-        <dlentry>
-        <dt>SYSXPLAIN_RESULTSETS</dt>
-        <dd>This table contains one row for each result set which
-            was used during the execution of a particular explained statement.
-            Most queries have one or several result sets; some complex queries
-        can have many result sets.
-        </dd>
-        </dlentry>
-        <dlentry>
-        <dt>SYSXPLAIN_SCAN_PROPS</dt>
-        <dd>This table contains one row for each result set which
-            performed a scan of a table, index, or constraint. Using the
-            information in this row, you can determine how much data needed
-        to be examined by the scan.
-        </dd>
-        </dlentry>
-        <dlentry>
-        <dt>SYSXPLAIN_SORT_PROPS</dt>
-        <dd>This table contains one row for each result set which
-            performed a sort of data. Using the information in this row, you
-        can determine how much data needed to be sorted.
-        </dd>
-        </dlentry>
-        <dlentry>
-        <dt>SYSXPLAIN_STATEMENT_TIMINGS</dt>
-        <dd>This table contains timing information at the statement
-            level. Timing information is optional, but if it is captured, the
-            data in this table can be used to determine how much time each
-        statement took.
-        </dd>
-        </dlentry>
-        <dlentry>
-        <dt>SYSXPLAIN_RESULTSET_TIMINGS</dt>
-        <dd>This table contains timing information at the result set
-            level. Timing information is optional, but if it is captured, the
-            data in this table can be used to determine how much time each
-        result set took.
-        </dd>
-        </dlentry>
-    </dl>
+<p>Rows accumulate in the SYSXPLAIN_* database tables until you empty the tables
+by dropping them or executing DELETE FROM statements against them.</p>
+<p>Note that although these tables have stylized names which all start with the
+prefix "SYSXPLAIN_*", they are not in fact special system catalogs, but are
+merely ordinary database tables, which can be accessed in all the standard ways
+that any other database table is accessed. The tables are automatically created
+if they are not present when statistics are being captured. The tables are all
+located in a particular schema which is specified by the
+<codeph>SYSCS_UTIL.SYSCS_SET_XPLAIN_SCHEMA()</codeph> system procedure.</p>
+<p>The XPLAIN style database tables are summarized here. For more information
+about the structure and content of each table, see "XPLAIN style tables" in the
+<ph conref="../conrefs.dita#pub/citref"></ph>.</p>
+<dl>
+<dlentry>
+<dt>SYSXPLAIN_STATEMENTS</dt>
+<dd>This table contains one row for each statement which has had statistics
+captured. This row contains the text of the statement, as well as identifiers
+which can be used to join with the other tables to find more data about how this
+statement was executed.</dd>
+</dlentry>
+<dlentry>
+<dt>SYSXPLAIN_RESULTSETS</dt>
+<dd>This table contains one row for each result set which was used during the
+execution of a particular explained statement. Most queries have one or several
+result sets; some complex queries can have many result sets.</dd>
+</dlentry>
+<dlentry>
+<dt>SYSXPLAIN_SCAN_PROPS</dt>
+<dd>This table contains one row for each result set which performed a scan of a
+table, index, or constraint. Using the information in this row, you can
+determine how much data needed to be examined by the scan.</dd>
+</dlentry>
+<dlentry>
+<dt>SYSXPLAIN_SORT_PROPS</dt>
+<dd>This table contains one row for each result set which performed a sort of
+data. Using the information in this row, you can determine how much data needed
+to be sorted.</dd>
+</dlentry>
+<dlentry>
+<dt>SYSXPLAIN_STATEMENT_TIMINGS</dt>
+<dd>This table contains timing information at the statement level. Timing
+information is optional, but if it is captured, the data in this table can be
+used to determine how much time each statement took.</dd>
+</dlentry>
+<dlentry>
+<dt>SYSXPLAIN_RESULTSET_TIMINGS</dt>
+<dd>This table contains timing information at the result set level. Timing
+information is optional, but if it is captured, the data in this table can be
+used to determine how much time each result set took.</dd>
+</dlentry>
+</dl>
 </conbody></concept>
 

Modified: db/derby/docs/trunk/src/tuning/ctundepth1002853.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/ctundepth1002853.dita?rev=1609163&r1=1609162&r2=1609163&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tuning/ctundepth1002853.dita (original)
+++ db/derby/docs/trunk/src/tuning/ctundepth1002853.dita Wed Jul  9 14:07:47 2014
@@ -20,38 +20,47 @@ limitations under the License.
 -->
 <concept id="ctundepth1002853" xml:lang="en-us">
 <title>Create useful indexes</title>
+<shortdesc>Indexes are useful when a query contains a WHERE clause.</shortdesc>
 <prolog><metadata>
 <keywords><indexterm>indexes<indexterm>guidance, creating</indexterm></indexterm>
 </keywords>
 </metadata></prolog>
 <conbody>
-<p>Indexes are useful when a query contains a WHERE clause.</p>
-<p>Without a WHERE clause, <ph conref="../conrefs.dita#prod/productshortname"></ph> is <i>supposed</i> to
+<p>Without a WHERE clause,
+<ph conref="../conrefs.dita#prod/productshortname"></ph> is <i>supposed</i> to
 return all the data in the table, and so a table scan is the correct (if not
-desirable) behavior. (More about that in <xref href="ctundepth36205.dita#ctundepth36205"></xref>.)</p>
+desirable) behavior. (For more information, see
+<xref href="ctundepth36205.dita"/>.)</p>
 <p><ph conref="../conrefs.dita#prod/productshortname"></ph> creates indexes
-on tables in the following situations:   <ul>
+on tables in the following situations:</p>
+<ul>
 <li>When you define a primary key, unique, or foreign key constraint on a
-table. See "CONSTRAINT clause" in the <cite><ph conref="../conrefs.dita#pub/citref"></ph></cite> for
-more information.</li>
-<li>When you explicitly create an index on a table with a CREATE INDEX statement. </li>
-</ul></p>
+table. See "CONSTRAINT clause" in the
+<ph conref="../conrefs.dita#pub/citref"></ph> for more information.</li>
+<li>When you explicitly create an index on a table with a CREATE INDEX
+statement.</li>
+</ul>
 <p>For an index to be useful for a particular statement, one of the columns
-in the statement's WHERE clause must be the first column in the index's key.
-  <note>For a complete discussion of how indexes work and when they are useful,
-see <xref href="ctunoptimz33368.dita#ctunoptimz33368"></xref> and <xref href="ctunoptimz30217.dita#ctunoptimz30217"></xref>.</note></p>
-<p>Indexes provide some other benefits as well:   <ul>
-<li>If all the data requested are in the index, <ph conref="../conrefs.dita#prod/productshortname"></ph> does
-not have to go to the table at all. (See <xref href="ctunoptimz30768.dita#ctunoptimz30768"></xref>.)</li>
-<li>For operations that require a sort (ORDER BY), if <ph conref="../conrefs.dita#prod/productshortname"></ph> uses
-the index to retrieve the data, it does not have to perform a separate sorting
-step for some of these operations in some situations. (See <xref href="ctunoptimz27036.dita#ctunoptimz27036"></xref>.)</li>
+in the statement's WHERE clause must be the first column in the index's key.</p>
+<p><note>For a complete discussion of how indexes work and when they are useful,
+see <xref href="ctunoptimz33368.dita"/> and
+<xref href="ctunoptimz30217.dita"/>.</note></p>
+<p>Indexes provide some other benefits as well:</p>
+<ul>
+<li>If all the data requested are in the index,
+<ph conref="../conrefs.dita#prod/productshortname"></ph> does not have to go to
+the table at all. (See <xref href="ctunoptimz30768.dita"/>.)</li>
+<li>For operations that require a sort (ORDER BY), if
+<ph conref="../conrefs.dita#prod/productshortname"></ph> uses the index to
+retrieve the data, it does not have to perform a separate sorting step for some
+of these operations in some situations. (See
+<xref href="ctunoptimz27036.dita"/>.)</li>
 </ul>
-</p>
 <p>See "CREATE INDEX statement" in the
 <ph conref="../conrefs.dita#pub/citref"></ph> for details on creating indexes,
 including restrictions on key size.</p>
 <p><note><ph conref="../conrefs.dita#prod/productshortname"></ph> does
-not support indexing on columns with data types like BLOB, CLOB, and XML.</note></p>
+not support indexing on columns with data types like BLOB, CLOB, and
+XML.</note></p>
 </conbody>
 </concept>

Modified: db/derby/docs/trunk/src/tuning/ctundepth1003116.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/ctundepth1003116.dita?rev=1609163&r1=1609162&r2=1609163&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tuning/ctundepth1003116.dita (original)
+++ db/derby/docs/trunk/src/tuning/ctundepth1003116.dita Wed Jul  9 14:07:47 2014
@@ -18,6 +18,11 @@ limitations under the License.
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "../dtd/concept.dtd">
 <concept xml:lang="en-us" id="ctundepth1003116">
 <title>Make sure indexes are being used, and rebuild them</title>
+<shortdesc>If an index is useful for a query,
+<ph conref="../conrefs.dita#prod/productshortname"></ph> is probably using it.
+However, you need to make sure. Analyze the way
+<ph conref="../conrefs.dita#prod/productshortname"></ph> is executing your
+application's queries. </shortdesc>
 <prolog><metadata>
 <keywords>
 <indexterm>Index use<indexterm>analyzing</indexterm></indexterm>
@@ -25,10 +30,7 @@ limitations under the License.
 </metadata>
 </prolog>
 <conbody>
-<p>If an index is useful for a query, <ph conref="../conrefs.dita#prod/productshortname"></ph> is probably using it. However,
-you need to make sure. Analyze the way <ph conref="../conrefs.dita#prod/productshortname"></ph> is executing your application's
-queries. See <xref href="ttundepth33391.dita#ttundepth33391"/> for information on
-how to do this.</p>
+<p>See <xref href="ttundepth33391.dita"/> for information on how to do this.</p>
 <p>In addition, over time, index pages fragment. Rebuilding indexes improves
 performance significantly in these situations. To rebuild an index, drop it
 and then re-create it.</p>

Modified: db/derby/docs/trunk/src/tuning/ctundepth1003209.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/ctundepth1003209.dita?rev=1609163&r1=1609162&r2=1609163&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tuning/ctundepth1003209.dita (original)
+++ db/derby/docs/trunk/src/tuning/ctundepth1003209.dita Wed Jul  9 14:07:47 2014
@@ -18,6 +18,11 @@ limitations under the License.
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "../dtd/concept.dtd">
 <concept xml:lang="en-us" id="ctundepth1003209">
 <title>Think about index order</title>
+<shortdesc><ph conref="../conrefs.dita#prod/productshortname"></ph> allows you
+to create index columns in descending order in addition to creating them in
+ascending order, the default. Descending indexes provide performance benefits
+for the kinds of queries that require sorting data in descending
+order.</shortdesc>
 <prolog><metadata>
 <keywords>
 <indexterm>Descending indexes</indexterm>
@@ -26,10 +31,8 @@ limitations under the License.
 </metadata>
 </prolog>
 <conbody>
-<p><ph conref="../conrefs.dita#prod/productshortname"></ph> allows you to create index columns in descending order in addition
-to creating them in ascending order, the default. Descending indexes provide
-performance benefits for the following kinds of queries that require sorting data in descending order.</p>
+<p>See <xref href="ctundepth1003672.dita"/> for some examples.</p>
 <p>To ensure performance benefits, verify that the descending index is being
-used. See <xref href="ttundepth33391.dita#ttundepth33391"/> for
-information on how to do this. </p>
+used. See <xref href="ttundepth33391.dita"/> for information on how to do
+this.</p>
 </conbody></concept>

Modified: db/derby/docs/trunk/src/tuning/ctundepth1003369.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/ctundepth1003369.dita?rev=1609163&r1=1609162&r2=1609163&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tuning/ctundepth1003369.dita (original)
+++ db/derby/docs/trunk/src/tuning/ctundepth1003369.dita Wed Jul  9 14:07:47 2014
@@ -18,6 +18,8 @@ limitations under the License.
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "../dtd/concept.dtd">
 <concept xml:lang="en-us" id="ctundepth1003369">
 <title>Think about join order</title>
+<shortdesc>For some queries, join order can make the difference between a table
+scan (expensive) and an index scan (cheap).</shortdesc>
 <prolog><metadata>
 <keywords>
 <indexterm>Join order<indexterm>performance implications of</indexterm></indexterm>
@@ -25,27 +27,32 @@ limitations under the License.
 </metadata>
 </prolog>
 <conbody>
-<p>For some queries, join order can make the difference between a table scan
-(expensive) and an index scan (cheap). Here's an example:  
+<p>Here's an example:</p>
 <codeblock><b>select ht.hotel_id, ha.stay_date, ht.depart_time
 from hotels ht, Hotelavailability ha
 where ht.hotel_id = ha.hotel_id and 
 ht.room_number = ha.room_number
 and ht.bed_type = 'KING'
 and ht.smoking_room = 'NO'
-order by ha.stay_date</b></codeblock></p>
-<p>If <ph conref="../conrefs.dita#prod/productshortname"></ph> chooses <i>Hotels</i> as the outer table,
-it can use the index on <i>Hotels</i> to retrieve qualifying
-rows. Then it
-need only look up data in <i>HotelAvailability</i> three
-times, once for each qualifying row. And to retrieve the appropriate rows
-from <i>HotelAvailability</i>, it can use an index for <i>HotelAvailability</i>'s <i>hotel_id</i> column
-instead of scanning the entire table.</p>
-<p>If <ph conref="../conrefs.dita#prod/productshortname"></ph> chooses the other order, with <i>HotelAvailability</i> as the outer table, it will have to probe the <i>Hotels</i> table for <i>every row</i>, not just three rows, because
-there are no qualifications on the <i>HotelAvailability</i> table.</p>
-<p>For more information about join order, see <xref href="ctunoptimz12168.dita#ctunoptimz12168"/>.</p>
-<p><ph conref="../conrefs.dita#prod/productshortname"></ph> usually chooses a good join order. However, as with index use,
-you should make sure. Analyze the way <ph conref="../conrefs.dita#prod/productshortname"></ph> is executing your application's
-queries. See <xref href="ttundepth33391.dita#ttundepth33391"/> for information on
+order by ha.stay_date</b></codeblock>
+<p>If <ph conref="../conrefs.dita#prod/productshortname"></ph> chooses
+<codeph>Hotels</codeph> as the outer table, it can use the index on
+<codeph>Hotels</codeph> to retrieve qualifying rows. Then it need only look up
+data in <codeph>HotelAvailability</codeph> three times, once for each qualifying
+row. And to retrieve the appropriate rows from
+<codeph>HotelAvailability</codeph>, it can use an index for
+<codeph>HotelAvailability</codeph>'s <codeph>hotel_id</codeph> column instead of
+scanning the entire table.</p>
+<p>If <ph conref="../conrefs.dita#prod/productshortname"></ph> chooses the other
+order, with <codeph>HotelAvailability</codeph> as the outer table, it will have
+to probe the <codeph>Hotels</codeph> table for <i>every row</i>, not just three
+rows, because there are no qualifications on the
+<codeph>HotelAvailability</codeph> table.</p>
+<p>For more information about join order, see
+<xref href="ctunoptimz12168.dita"/>.</p>
+<p><ph conref="../conrefs.dita#prod/productshortname"></ph> usually chooses a
+good join order. However, as with index use, you should make sure. Analyze the
+way <ph conref="../conrefs.dita#prod/productshortname"></ph> is executing your
+application's queries. See <xref href="ttundepth33391.dita"/> for information on
 how to do this.</p>
 </conbody></concept>

Modified: db/derby/docs/trunk/src/tuning/ctundepth1003672.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/ctundepth1003672.dita?rev=1609163&r1=1609162&r2=1609163&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tuning/ctundepth1003672.dita (original)
+++ db/derby/docs/trunk/src/tuning/ctundepth1003672.dita Wed Jul  9 14:07:47 2014
@@ -18,21 +18,22 @@ limitations under the License.
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "../dtd/concept.dtd">
 <concept xml:lang="en-us" id="ctundepth1003672">
 <title>Decide whether a descending index would be useful</title>
+<shortdesc><ph conref="../conrefs.dita#prod/productshortname"></ph> allows you
+to create an index that uses the descending order for a column. Such indexes
+improve the performance of queries that order results in descending order or
+that search for the minimum or maximum value of an indexed column.</shortdesc>
 <prolog><metadata>
 <keywords>
-<indexterm>Indexes with Descending Ordering<indexterm>performance
+<indexterm>Indexes with descending ordering<indexterm>performance
 benefits of</indexterm></indexterm>
 </keywords>
 </metadata>
 </prolog>
 <conbody>
-<p><ph conref="../conrefs.dita#prod/productshortname"></ph> allows you to create an index that uses the descending order
-for a column. Such indexes improve the performance of queries that order results
-in descending order or that search for the minimum or maximum value of an
-indexed column. For example, both of the following queries could benefit from
-indexes that use descending ordering:  
+<p>For example, both of the following queries could benefit from indexes that
+use descending ordering:</p>
 <codeblock><b><ph>-- would benefit from an index like this:
--- CREATE INDEX c_id_desc ON Citites(city_id DESC)</ph>
+-- CREATE INDEX c_id_desc ON Cities(city_id DESC)</ph>
 SELECT * FROM Cities ORDER BY city_id DESC
 <ph>-- would benefit from an index like this:
 -- CREATE INDEX f_miles_desc on Flights(miles DESC)</ph>
@@ -40,5 +41,5 @@ SELECT MAX(miles) FROM Flight
 <ph>-- would benefit from an index like this:
 -- CREATE INDEX arrival_time_desc ON Flights(dest_airport, arrive_time DESC)
 SELECT * FROM Flights WHERE dest_airport = 'LAX'</ph>
-ORDER BY ARRIVAL DESC</b></codeblock></p>
+ORDER BY ARRIVAL DESC</b></codeblock>
 </conbody></concept>

Modified: db/derby/docs/trunk/src/tuning/ctundepth10525.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/ctundepth10525.dita?rev=1609163&r1=1609162&r2=1609163&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tuning/ctundepth10525.dita (original)
+++ db/derby/docs/trunk/src/tuning/ctundepth10525.dita Wed Jul  9 14:07:47 2014
@@ -18,11 +18,13 @@ limitations under the License.
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "../dtd/concept.dtd">
 <concept xml:lang="en-us" id="ctundepth10525">
 <title>Avoiding table scans of large tables</title>
+<shortdesc><ph conref="../conrefs.dita#prod/productshortname"></ph> is fast and
+efficient, but when tables are huge, scanning tables might take longer than a
+user would expect. It's even worse if you then ask
+<ph conref="../conrefs.dita#prod/productshortname"></ph> to sort this
+data.</shortdesc>
 <prolog>
 </prolog>
 <conbody>
-<p><ph conref="../conrefs.dita#prod/productshortname"></ph> is fast and efficient, but when tables are huge, scanning tables
-might take longer than a user would expect. It's even worse if you then
-ask <ph conref="../conrefs.dita#prod/productshortname"></ph> to sort this data.</p>
 <p>Things that you can do to avoid table scans fall into two categories.</p>
 </conbody></concept>

Modified: db/derby/docs/trunk/src/tuning/ctundepth13055.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/ctundepth13055.dita?rev=1609163&r1=1609162&r2=1609163&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tuning/ctundepth13055.dita (original)
+++ db/derby/docs/trunk/src/tuning/ctundepth13055.dita Wed Jul  9 14:07:47 2014
@@ -18,6 +18,9 @@ limitations under the License.
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "../dtd/concept.dtd">
 <concept xml:lang="en-us" id="ctundepth13055">
 <title>Working with RunTimeStatistics</title>
+<shortdesc><ph conref="../conrefs.dita#prod/productshortname"></ph> provides a
+language-level tool for evaluating the performance and the execution plans of
+statements, the RUNTIMESTATISTICS attribute.</shortdesc>
 <prolog><metadata>
 <keywords>
 <indexterm>Performance of statements<indexterm>analyzing</indexterm></indexterm>
@@ -25,7 +28,4 @@ limitations under the License.
 </metadata>
 </prolog>
 <conbody>
-<p><ph conref="../conrefs.dita#prod/productshortname"></ph> provides a language-level tool for evaluating the performance
-and the execution plans of statements, the RUNTIMESTATISTICS attribute.  
-</p>
 </conbody></concept>

Modified: db/derby/docs/trunk/src/tuning/ctundepth14326.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/ctundepth14326.dita?rev=1609163&r1=1609162&r2=1609163&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tuning/ctundepth14326.dita (original)
+++ db/derby/docs/trunk/src/tuning/ctundepth14326.dita Wed Jul  9 14:07:47 2014
@@ -18,32 +18,39 @@ See the License for the specific languag
 limitations under the License.
 -->
 <concept id="ctundepth14326" xml:lang="en-us">
-<title>Shielding users from Derby class-loading events</title>
+<title>Shielding users from
+<ph conref="../conrefs.dita#prod/productshortname"></ph> class-loading
+events</title>
+<shortdesc>JVMs tend to load classes as they are needed, which means that the
+first time you need a class in a piece of software, it takes longer to
+use.</shortdesc>
 <prolog><metadata>
-<keywords><indexterm>Class loading<indexterm>when it occurs in Derby</indexterm><indexterm>how
-to minimize impact of</indexterm></indexterm></keywords>
+<keywords><indexterm>Class loading<indexterm>when it occurs in Derby</indexterm>
+<indexterm>how to minimize impact of</indexterm></indexterm></keywords>
 </metadata></prolog>
 <conbody>
-<p>JVMs tend to load classes as they are needed, which means the first time
-you need a class in a piece of software, it takes longer to use.</p>
 <p><ph conref="../conrefs.dita#prod/productshortname"></ph> has three clear
-cases when a lot of class loading occurs:   <ul>
-<li><i>When the system boots</i>   <p>The system boots when you load the embedded
-driver, <i>org.apache.derby.</i><i>jdbc.EmbeddedDriver</i>. In a server framework,
-the system boots when you start the server framework. Booting <ph conref="../conrefs.dita#prod/productshortname"></ph> loads
-basic <ph conref="../conrefs.dita#prod/productshortname"></ph> classes.</p></li>
-<li><i>When the first database boots</i>   <p>Booting the first database loads
-some more <ph conref="../conrefs.dita#prod/productshortname"></ph> classes.
-The default behavior is that the first database boots when the first connection
-is made to it. You can also configure the system to boot databases at startup.
-Depending on your application, one or the other might be preferable. </p></li>
-<li><i>When you compile the first query</i>   <p>Compiling the first query
-loads additional classes.</p></li>
-</ul></p>
-<p>For any of these events, you can control the impact they have on users
-by starting them in separate threads while other tasks are occurring.</p>
-<p>In addition, if you are using <i>PreparedStatements</i>, prepare them in
-a separate thread in the background while other tasks are occurring.</p>
+cases when a lot of class loading occurs:</p>
+<ul>
+<li><i>When the system boots</i>
+<p>The system boots when you load the embedded driver,
+<i>org.apache.derby.jdbc.EmbeddedDriver</i>. In a server framework, the system
+boots when you start the server framework. Booting
+<ph conref="../conrefs.dita#prod/productshortname"></ph> loads basic
+<ph conref="../conrefs.dita#prod/productshortname"></ph> classes.</p></li>
+<li><i>When the first database boots</i>
+<p>Booting the first database loads some more
+<ph conref="../conrefs.dita#prod/productshortname"></ph> classes. The default
+behavior is that the first database boots when the first connection is made to
+it. You can also configure the system to boot databases at startup. Depending on
+your application, one or the other might be preferable.</p></li>
+<li><i>When you compile the first query</i>
+<p>Compiling the first query loads additional classes.</p></li>
+</ul>
+<p>For any of these events, you can control the impact they have on users by
+starting them in separate threads while other tasks are occurring.</p>
+<p>In addition, if you are using <i>PreparedStatements</i>, prepare them in a
+separate thread in the background while other tasks are occurring.</p>
 <section><title>Tuning tips for multi-user systems</title>
 <ul>
 <li>For concurrency, use row-level locking and the READ_COMMITTED isolation
@@ -56,13 +63,14 @@ isolation level.</li>
 <section><title>Tuning tips for single-user systems</title>
 <ul>
 <li><ph conref="../conrefs.dita#prod/productshortname"></ph> boots when you
-first load the embedded JDBC driver (<i>org.apache.derby.</i><i>jdbc.EmbeddedDriver</i>).
-Load this driver during the least time-sensitive portion of your program,
-such as when it is booting or when you are waiting for user input. For server
-frameworks, the driver is loaded automatically when the server boots.</li>
+first load the embedded JDBC driver
+(<i>org.apache.derby.jdbc.EmbeddedDriver</i>). Load this driver during the least
+time-sensitive portion of your program, such as when it is booting or when you
+are waiting for user input. For server frameworks, the driver is loaded
+automatically when the server boots.</li>
 <li>Boot the database at connection (the default behavior), not at startup.
 Connect in a background thread if possible.</li>
-<li>Turn off row-level locking and use READ_COMMITTED isolation level.</li>
+<li>Turn off row-level locking and use the READ_COMMITTED isolation level.</li>
 </ul>
 </section>
 </conbody>

Modified: db/derby/docs/trunk/src/tuning/ctundepth21935.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/ctundepth21935.dita?rev=1609163&r1=1609162&r2=1609163&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tuning/ctundepth21935.dita (original)
+++ db/derby/docs/trunk/src/tuning/ctundepth21935.dita Wed Jul  9 14:07:47 2014
@@ -18,6 +18,9 @@ limitations under the License.
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "../dtd/concept.dtd">
 <concept xml:lang="en-us" id="ctundepth21935">
 <title>Application and database design issues</title>
+<shortdesc>Things that you can do to improve the performance of
+<ph conref="../conrefs.dita#prod/productshortname"></ph> applications fall into
+three categories.</shortdesc>
 <prolog><metadata>
 <keywords>
 <indexterm>Database design<indexterm>performance implications</indexterm></indexterm>
@@ -27,7 +30,4 @@ limitations under the License.
 </metadata>
 </prolog>
 <conbody>
-<p>Things that you can do to improve the performance of <ph conref="../conrefs.dita#prod/productshortname"></ph> applications
-fall into three categories.
-</p>
 </conbody></concept>

Modified: db/derby/docs/trunk/src/tuning/ctundepth23033.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/ctundepth23033.dita?rev=1609163&r1=1609162&r2=1609163&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tuning/ctundepth23033.dita (original)
+++ db/derby/docs/trunk/src/tuning/ctundepth23033.dita Wed Jul  9 14:07:47 2014
@@ -18,6 +18,9 @@ limitations under the License.
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "../dtd/concept.dtd">
 <concept xml:lang="en-us" id="ctundepth23033">
 <title>Always create indexes</title>
+<shortdesc>Useful indexes prevent
+<ph conref="../conrefs.dita#prod/productshortname"></ph> from having to read an
+entire table to retrieve the data you need.</shortdesc>
 <prolog><metadata>
 <keywords>
 <indexterm>Indexes<indexterm>performance benefits of</indexterm></indexterm>
@@ -25,11 +28,11 @@ limitations under the License.
 </metadata>
 </prolog>
 <conbody>
-<p>Have you ever thought what it would be like to look up a phone number in
-the phone book of a major metropolitan city if the book were not indexed by
-name? For example, to look up the phone number for John Jones, you could not
-go straight to the <i>J</i> page. You would have to read
-the entire book. That is what a table scan is like. <ph conref="../conrefs.dita#prod/productshortname"></ph> has to read
-the entire table to retrieve what you are looking for unless you create useful
-indexes on your table.</p>
+<p>Have you ever thought what it would be like to look up a phone number in the
+phone book of a major metropolitan city if the book were not indexed by name?
+For example, to look up the phone number for John Jones, you could not go
+straight to the "J" page. You would have to read the entire book. That is what a
+table scan is like. <ph conref="../conrefs.dita#prod/productshortname"></ph> has
+to read the entire table to retrieve what you are looking for unless you create
+useful indexes on your table.</p>
 </conbody></concept>

Modified: db/derby/docs/trunk/src/tuning/ctundepth26674.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/ctundepth26674.dita?rev=1609163&r1=1609162&r2=1609163&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tuning/ctundepth26674.dita (original)
+++ db/derby/docs/trunk/src/tuning/ctundepth26674.dita Wed Jul  9 14:07:47 2014
@@ -17,7 +17,11 @@ limitations under the License.
 -->
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "../dtd/concept.dtd">
 <concept xml:lang="en-us" id="ctundepth26674">
-<title>Overview</title>
+<title>Overview of RunTimeStatistics</title>
+<shortdesc>When RUNTIMESTATISTICS is turned on for a connection,
+<ph conref="../conrefs.dita#prod/productshortname"></ph> maintains information
+about the execution plan for each statement executed within the connection
+(except for COMMIT) until the attribute is turned off.</shortdesc>
 <prolog><metadata>
 <keywords>
 <indexterm>RunTimeStatistics<indexterm>overview</indexterm></indexterm>
@@ -25,32 +29,27 @@ limitations under the License.
 </metadata>
 </prolog>
 <conbody>
-<p>When RUNTIMESTATISTICS is turned on for a connection, <ph conref="../conrefs.dita#prod/productshortname"></ph> maintains
-information about the execution plan for each statement executed within the
-connection (except for COMMIT) until the attribute is turned off.</p>
 <p>For the most recently executed query, RUNTIMESTATISTICS returns information
 about:  
 <ul>
-<li><i>the length of the compile time and the execute time.</i>  
+<li><i>The length of the compile time and the execute time</i>  
 <p>This can help in benchmarking queries.</p></li>
-<li><i>the statement execution plan.</i>  
-<p>This is a description
-of result set nodes, whether an index was used, what the join order was, how
-many rows qualified at each node, and how much time was spent in each node.
-This information can help you determine whether you need to add indexes or
-rewrite queries.</p></li>
+<li><i>The statement execution plan</i>  
+<p>This is a description of result set nodes, whether an index was used, what
+the join order was, how many rows qualified at each node, and how much time was
+spent in each node. This information can help you determine whether you need to
+add indexes or rewrite queries.</p></li>
 </ul></p>
 <p>The exact details presented, as well as the format of presentation, can
-    change. There are two techniques for retrieving the RUNTIMESTATISTICS
-    information:
-    <ul>
-        <li>call SYSCS_UTIL.SYSCS_GET_RUNTIMESTATISTICS, which retrieves
-            the RUNTIMESTATISTICS information as formatted text</li>
-        <li>call SYSCS_UTIL.SYSCS_SET_XPLAIN_SCHEMA before executing your
-            statements, which causes 
-            <ph conref="../conrefs.dita#prod/productshortname"></ph>
-            to store the RUNTIMESTATISTICS information in the SYSXPLAIN 
-            database tables, which can then be queried 
-            later to retrieve the data.</li>
-</ul></p>
+change. There are two techniques for retrieving the RUNTIMESTATISTICS
+information:</p>
+<ul>
+<li>Call <codeph>SYSCS_UTIL.SYSCS_GET_RUNTIMESTATISTICS</codeph>, which
+retrieves the RUNTIMESTATISTICS information as formatted text.</li>
+<li>Before executing your statements, call
+<codeph>SYSCS_UTIL.SYSCS_SET_XPLAIN_SCHEMA</codeph>, which causes
+<ph conref="../conrefs.dita#prod/productshortname"></ph> to store the
+RUNTIMESTATISTICS information in the SYSXPLAIN database tables. These tables can
+be queried later to retrieve the data.</li>
+</ul>
 </conbody></concept>

Modified: db/derby/docs/trunk/src/tuning/ctundepth29804.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/ctundepth29804.dita?rev=1609163&r1=1609162&r2=1609163&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tuning/ctundepth29804.dita (original)
+++ db/derby/docs/trunk/src/tuning/ctundepth29804.dita Wed Jul  9 14:07:47 2014
@@ -18,6 +18,14 @@ limitations under the License.
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "../dtd/concept.dtd">
 <concept xml:lang="en-us" id="ctundepth29804">
 <title>Avoiding compiling SQL statements</title>
+<shortdesc>When you submit an SQL statement to
+<ph conref="../conrefs.dita#prod/productshortname"></ph>,
+<ph conref="../conrefs.dita#prod/productshortname"></ph> compiles and then
+executes the statement. <i>Compilation</i> is a time-consuming process that
+involves several steps, including optimization, the stage in which
+<ph conref="../conrefs.dita#prod/productshortname"></ph> makes its statement
+execution plan. A statement execution plan includes whether to use an index,
+the join order, and so on.</shortdesc>
 <prolog><metadata>
 <keywords>
 <indexterm>Compilation<indexterm>performance hit</indexterm></indexterm>
@@ -25,15 +33,12 @@ limitations under the License.
 </metadata>
 </prolog>
 <conbody>
-<p>When you submit an SQL statement to <ph conref="../conrefs.dita#prod/productshortname"></ph>, <ph conref="../conrefs.dita#prod/productshortname"></ph> compiles
-and then executes the statement. <i>Compilation</i> is a
-time-consuming process that involves several steps, including optimization,
-the stage in which <ph conref="../conrefs.dita#prod/productshortname"></ph> makes its statement execution plan. A statement
-execution plan includes whether to use an index, the join order, and so on.</p>
-<p>Unless there are significant changes in the amount of data in a table or
-new or deleted indexes, <ph conref="../conrefs.dita#prod/productshortname"></ph> will probably come up with the same statement
-execution plan for the same statement if you submit it more than once. This
-means that the same statements should share the same plan, and <ph conref="../conrefs.dita#prod/productshortname"></ph> should
-not recompile them. <ph conref="../conrefs.dita#prod/productshortname"></ph> allows you to ensure this in the following
-ways (in order of importance):  </p>
+<p>Unless there are significant changes in the amount of data in a table or new
+or deleted indexes, <ph conref="../conrefs.dita#prod/productshortname"></ph>
+will probably come up with the same statement execution plan for the same
+statement if you submit it more than once. This means that the same statements
+should share the same plan, and
+<ph conref="../conrefs.dita#prod/productshortname"></ph> should not recompile
+them. <ph conref="../conrefs.dita#prod/productshortname"></ph> allows you to
+ensure this by using the statement cache.</p>
 </conbody></concept>

Modified: db/derby/docs/trunk/src/tuning/ctundepth32379.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/ctundepth32379.dita?rev=1609163&r1=1609162&r2=1609163&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tuning/ctundepth32379.dita (original)
+++ db/derby/docs/trunk/src/tuning/ctundepth32379.dita Wed Jul  9 14:07:47 2014
@@ -20,6 +20,8 @@ limitations under the License.
 -->
 <concept id="ctundepth32379" xml:lang="en-us">
 <title>Using the statement cache</title>
+<shortdesc>The statement cache is enabled by default. You can use it to avoid
+extra compilation overhead.</shortdesc>
 <prolog><metadata>
 <keywords><indexterm>Compilation<indexterm>avoiding by using PreparedStatements</indexterm></indexterm>
 <indexterm>Prepared statements<indexterm>performance benefits of</indexterm></indexterm>
@@ -27,20 +29,19 @@ limitations under the License.
 </keywords>
 </metadata></prolog>
 <conbody>
-<p>The statement cache is enabled by default. You can use it to avoid extra
-compilation overhead:   <ul>
-<li>Your application can use <i>PreparedStatements</i> instead of <i>Statements</i>.
-  <p><i>PreparedStatements</i> are JDBC objects that you prepare (compile)
-once and execute multiple times. See the figure below. If your application
-executes statements that are almost but not exactly alike, use <i>PreparedStatements</i>,
-which can contain dynamic or IN parameters. Instead of using the literals
-for changing parameters, use question marks (?) as placeholders for such parameters.
-Provide the values when you execute the statement.</p></li>
-</ul></p>
+<ul>
+<li>Your application can use <i>PreparedStatements</i> instead of
+<i>Statements</i>.
+<p><i>PreparedStatements</i> are JDBC objects that you prepare (compile) once
+and execute multiple times. See the figure below. If your application executes
+statements that are almost but not exactly alike, use <i>PreparedStatements</i>,
+which can contain dynamic or IN parameters. Instead of using the literals for
+changing parameters, use question marks (<codeph>?</codeph>) as placeholders for
+such parameters. Provide the values when you execute the statement.</p>
 <p><ph conref="../conrefs.dita#prod/productshortname"></ph> supports the
-<i>ParameterMetaData</i> interface. This interface describes the number, type, and properties
-of prepared statement parameters. See the <cite><ph conref="../conrefs.dita#pub/citdevelop"></ph></cite> for
-more information.</p>
+<i>ParameterMetaData</i> interface. This interface describes the number, type,
+and properties of prepared statement parameters. See the
+<ph conref="../conrefs.dita#pub/citdevelop"></ph> for more information.</p>
 <p>A connection need only compile a <i>PreparedStatement</i> once. Subsequent
 executions can use the same statement execution plan even if the parameter
 values are different, as shown in the following figure.
@@ -48,28 +49,32 @@ values are different, as shown in the fo
 <fig expanse="column" id="ctundepth42475"><title>Prepared statements and the
 statement cache</title>
 <image href="pstmt_os.gif" placement="break"><alt>This figure shows multiple executions of the same PreparedStatement over a single connection. The single PreparedStatement object uses the same statement execution plan and statement cache.</alt></image>
-</fig><ul>
-<li>Even if your statement uses <i>Statements</i> instead of <i>PreparedStatements</i>, <ph
-conref="../conrefs.dita#prod/productshortname"></ph> can reuse the statement
+</fig></li>
+<li>Even if your statement uses <i>Statements</i> instead of
+<i>PreparedStatements</i>,
+<ph conref="../conrefs.dita#prod/productshortname"></ph> can reuse the statement
 execution plan for the statements from the statement cache. Statements from
 any connection can share the same statement execution plan, avoiding compilation,
 by using the single-statement cache. The statement cache maintains statement
 plans across connections. It does not, however, maintain them across reboots.
-See the figure below. <p>When, in the same database, an application submits
-an SQL <i>Statement</i> that exactly matches one already in the cache, <ph
-conref="../conrefs.dita#prod/productshortname"></ph> grabs the statement from
-the cache, even if the <i>Statement</i> has already been closed by the application.</p> <p>To
-match exactly with a statement already in the cache, the SQL <i>Statement</i> must
-meet the following requirements:</p> <ul>
+See the figure below.
+<p>When, in the same database, an application submits an SQL <i>Statement</i>
+that exactly matches one already in the cache,
+<ph conref="../conrefs.dita#prod/productshortname"></ph> grabs the statement
+from the cache, even if the <i>Statement</i> has already been closed by the
+application.</p>
+<p>To match exactly with a statement already in the cache, the SQL
+<i>Statement</i> must meet the following requirements:</p>
+<ul>
 <li>The text must match exactly</li>
 <li>The current schema must match</li>
 <li>The Unicode flag that the statement was compiled under must match the
 current connection's flag</li>
 </ul></li>
 </ul>
-<note type="remember">If your application executes statements that are almost
-but not exactly alike, it is more efficient to use <i>PreparedStatements</i> with
-dynamic or IN parameters.  </note>
+<p><note type="remember">If your application executes statements that are almost
+but not exactly alike, it is more efficient to use <i>PreparedStatements</i>
+with dynamic or IN parameters.</note></p>
 <p>The following figure shows how
 <ph conref="../conrefs.dita#prod/productshortname"></ph> can reuse a statement
 execution plan that is already in the statement cache when the SQL text matches

Modified: db/derby/docs/trunk/src/tuning/ctundepth36205.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/ctundepth36205.dita?rev=1609163&r1=1609162&r2=1609163&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tuning/ctundepth36205.dita (original)
+++ db/derby/docs/trunk/src/tuning/ctundepth36205.dita Wed Jul  9 14:07:47 2014
@@ -18,6 +18,9 @@ limitations under the License.
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "../dtd/concept.dtd">
 <concept xml:lang="en-us" id="ctundepth36205">
 <title>Prevent the user from issuing expensive queries </title>
+<shortdesc>Some applications have complete control over the queries that they
+issue; the queries are built into the applications. Other applications allow
+users to construct queries by filling in fields on a form.</shortdesc>
 <prolog><metadata>
 <keywords>
 <indexterm>Expensive queries<indexterm>importance of avoiding</indexterm></indexterm>
@@ -26,31 +29,29 @@ limitations under the License.
 </metadata>
 </prolog>
 <conbody>
-<p>Some applications have complete control over the queries that they issue;
-the queries are built into the applications. Other applications allow users
-to construct queries by filling in fields on a form. Any time you let users
-construct ad-hoc queries, you risk the possibility that the query a user constructs
-will be one like the following:   
+<p>Any time you let users construct ad-hoc queries, you risk the possibility
+that the query a user constructs will be one like the following:</p>
 <codeblock><b>SELECT * FROM ExtremelyHugeTable
-ORDER BY unIndexedColumn</b></codeblock></p>
-<p>This statement has no WHERE clause. It will require a full table scan.
-To make matters worse, <ph conref="../conrefs.dita#prod/productshortname"></ph> will then have to order the data. Most
-likely, the user does not want to browse through all 100,000 rows, and does
-not care whether the rows are all in order.</p>
-<p>Do everything you can to avoid table scans and sorting of large results
-(such as table scans).</p>
-<p>Some things you can do to disallow such runaway queries:  
+ORDER BY unIndexedColumn</b></codeblock>
+<p>This statement has no WHERE clause. It will require a full table scan. To
+make matters worse, <ph conref="../conrefs.dita#prod/productshortname"></ph>
+will then have to order the data. Most likely, the user does not want to browse
+through all 100,000 rows, and does not care whether the rows are all in
+order.</p>
+<p>Do everything you can to avoid table scans and sorting of large results (such
+as table scans).</p>
+<p>You can do the following to prevent such runaway queries:</p> 
 <ul>
 <li>Use client-side checking to make sure some minimal fields are always filled
-in. Eliminate or disallow queries that cannot use indexes and are not optimizable.
-In other words, force an optimizable WHERE clause by making sure that the
-columns on which an index is built are included in the WHERE clause of the
-query. Reduce or disallow DISTINCT clauses (which often require sorting) on
+in. Eliminate or disallow queries that cannot use indexes and are not
+optimizable. In other words, force an optimizable WHERE clause by making sure
+that the columns on which an index is built are included in the WHERE clause of
+the query. Reduce or disallow DISTINCT clauses (which often require sorting) on
 large tables.</li>
 <li>For queries with large results, do not let the database do the ordering.
-Retrieve data in chunks (provide a Next button to allow the user to retrieve
-the next chunk, if desired), and order the data in the application.</li>
+Retrieve data in chunks (provide a Next button to allow the user to retrieve the
+next chunk, if desired), and order the data in the application.</li>
 <li>Do not use SELECT DISTINCT to populate lists; instead, maintain a separate
 table of the unique items.</li>
-</ul></p>
+</ul>
 </conbody></concept>

Modified: db/derby/docs/trunk/src/tuning/ctundepth37648.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/ctundepth37648.dita?rev=1609163&r1=1609162&r2=1609163&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tuning/ctundepth37648.dita (original)
+++ db/derby/docs/trunk/src/tuning/ctundepth37648.dita Wed Jul  9 14:07:47 2014
@@ -18,6 +18,8 @@ limitations under the License.
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "../dtd/concept.dtd">
 <concept xml:lang="en-us" id="ctundepth37648">
 <title>Analyzing the information</title>
+<shortdesc>RUNTIMESTATISTICS provides several kinds of information that you can
+analyze.</shortdesc>
 <prolog>
 </prolog>
 <conbody>

Modified: db/derby/docs/trunk/src/tuning/ctundepth39739.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/ctundepth39739.dita?rev=1609163&r1=1609162&r2=1609163&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tuning/ctundepth39739.dita (original)
+++ db/derby/docs/trunk/src/tuning/ctundepth39739.dita Wed Jul  9 14:07:47 2014
@@ -18,11 +18,11 @@ limitations under the License.
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "../dtd/concept.dtd">
 <concept xml:lang="en-us" id="ctundepth39739">
 <title>Tuning databases and applications</title>
+<shortdesc>The previous section provided some quick tips for improving
+performance. This section, while covering some of the same ground, provides more
+background on the basic design issues for improving performance.</shortdesc>
 <prolog>
 </prolog>
 <conbody>
-<p><xref href="ctunperf22457.dita#ctunperf22457"/>, provided some quick tips for
-improving performance. This chapter, while covering some of the same ground,
-provides more background on the basic design issues for improving performance.
-It also explains how to work with RunTimeStatistics.</p>
+<p>This section also explains how to work with RunTimeStatistics.</p>
 </conbody></concept>

Modified: db/derby/docs/trunk/src/tuning/ctundepth853095.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/ctundepth853095.dita?rev=1609163&r1=1609162&r2=1609163&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tuning/ctundepth853095.dita (original)
+++ db/derby/docs/trunk/src/tuning/ctundepth853095.dita Wed Jul  9 14:07:47 2014
@@ -18,6 +18,8 @@ limitations under the License.
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "../dtd/concept.dtd">
 <concept xml:lang="en-us" id="ctundepth853095">
 <title>Statistics timing</title>
+<shortdesc>If you are using statistics timing, RUNTIMESTATISTICS provides
+information about how long each stage of the statement took.</shortdesc>
 <prolog><metadata>
 <keywords>
 <indexterm>Statistics timing<indexterm>use of</indexterm></indexterm>
@@ -25,10 +27,11 @@ limitations under the License.
 </metadata>
 </prolog>
 <conbody>
-<p>If you are using statistics timing, RUNTIMESTATISTICS provides information
-about how long each stage of the statement took. An SQL statement has
-two basic stages within <ph conref="../conrefs.dita#prod/productshortname"></ph>: compilation and execution. Compilation
-is the work done while the statement is prepared. Compilation is composed
-of the following stages: parsing, binding, optimization, and code generation.
-Execution is the actual evaluation of the statement.</p>
+<p>An SQL statement has two basic stages within
+<ph conref="../conrefs.dita#prod/productshortname"></ph>: compilation and
+execution.</p>
+<p>Compilation is the work done while the statement is prepared. Compilation is
+composed of the following stages: parsing, binding, optimization, and code
+generation.</p>
+<p>Execution is the actual evaluation of the statement.</p>
 </conbody></concept>

Modified: db/derby/docs/trunk/src/tuning/ctundepth853133.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/ctundepth853133.dita?rev=1609163&r1=1609162&r2=1609163&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tuning/ctundepth853133.dita (original)
+++ db/derby/docs/trunk/src/tuning/ctundepth853133.dita Wed Jul  9 14:07:47 2014
@@ -20,29 +20,31 @@ limitations under the License.
  "../dtd/concept.dtd">
 <concept id="ctundepth853133" xml:lang="en-us">
 <title>Statement execution plan</title>
+<shortdesc>RUNTIMESTATISTICS also provides information about the <i>statement
+execution plan</i>.</shortdesc>
 <prolog><metadata>
 <keywords><indexterm>Statement execution plan</indexterm></keywords>
 </metadata></prolog>
 <conbody>
-<p>RUNTIMESTATISTICS also provides information about the <i>statement execution
-plan</i>. The statement execution plan shows how long each node took to evaluate,
-how many rows were retrieved, whether an index was used, and so on. If an
-index was used, it shows the start and stop positions for the matching index
-scan. Looking at the plan can help you determine whether to add an index or
-to rewrite the query.</p>
+<p>The statement execution plan shows how long each node took to evaluate, how
+many rows were retrieved, whether an index was used, and so on. If an index was
+used, it shows the start and stop positions for the matching index scan. Looking
+at the plan can help you determine whether to add an index or to rewrite the
+query.</p>
 <p>A statement execution plan is composed of a tree of result set nodes. A
-result set node represents the evaluation of one portion of the statement;
-it returns rows to a calling (or parent) node and can receive rows from a
-child node. A node can have one or more children. Starting from the top, if
-a node has children, it requests rows from the children. Usually only the
-execution plans of DML statements (queries, inserts, updates, and deletes,
-not dictionary object creation) are composed of more than one node.</p>
-<p>For example, consider the following query:   <codeblock><b>SELECT * FROM Countries</b></codeblock></p>
-<p>This simple query involves one node only-reading all the data out of the <i>Countries</i> table.
-It involves a single node with no children. This result set node is called
-a <i>Table Scan ResultSet</i>. RUNTIMESTATISTICS text for this node looks
-something like this:   <codeblock>
-Statement Name:
+result set node represents the evaluation of one portion of the statement; it
+returns rows to a calling (or parent) node and can receive rows from a child
+node. A node can have one or more children. Starting from the top, if a node has
+children, it requests rows from the children. Usually only the execution plans
+of DML statements (queries, inserts, updates, and deletes, not dictionary
+object creation) are composed of more than one node.</p>
+<p>For example, consider the following query:</p>
+<codeblock><b>SELECT * FROM Countries</b></codeblock>
+<p>This simple query involves one node only: reading all the data out of the
+<codeph>Countries</codeph> table. It involves a single node with no children.
+This result set node is called a <i>Table Scan ResultSet</i>. RUNTIMESTATISTICS
+text for this node looks something like this:</p>
+<codeblock>Statement Name:
         null
 Statement Text:
         select * from countries
@@ -83,18 +85,20 @@ null    qualifiers:
 None
         optimizer estimated row count:          119.00
         optimizer estimated cost:           69.35
-</codeblock></p>
-<p>Consider this second, more complex query:   <codeblock><b><ph></ph>SELECT Country
+</codeblock>
+<p>Consider this second, more complex query:</p>
+<codeblock><b><ph></ph>SELECT Country
 FROM Countries
-WHERE Region = 'Central America'</b></codeblock></p>
-<p>When executed, this query involves two nodes- one to retrieve
-qualifying rows (the restriction is done at this node) and one to project
-the requested columns. So, at bottom, there is a <i>TableScanResultSet</i> for
-scanning the table. The qualifier (Region = 'Central America') is evaluated
-in this node. These data are passed up to the parent node, called a <i>Project-Restrict
-ResultSet</i>, in which the rows are projected-only the <i>country</i> column
-is needed (the first column in the table). RUNTIMESTATISTICS text for these
-two nodes looks something like this:   <codeblock>Statement Name:
+WHERE Region = 'Central America'</b></codeblock>
+<p>When executed, this query involves two nodes: one to retrieve qualifying rows
+(the restriction is done at this node) and one to project the requested columns.
+So, at bottom, there is a <i>Table Scan ResultSet</i> for scanning the table.
+The qualifier (<codeph>Region = 'Central America'</codeph>) is evaluated in this
+node. These data are passed up to the parent node, called a
+<i>Project-Restrict ResultSet</i>, in which the rows are projected; only the
+<codeph>country</codeph> column is needed (the first column in the table).
+RUNTIMESTATISTICS text for these two nodes looks something like this:</p>
+<codeblock>Statement Name:
         null
 Statement Text:
         SELECT Country FROM Countries WHERE Region = 'Central America'
@@ -155,16 +159,18 @@ Negate comparison result: false
 
                 optimizer estimated row count:           11.90
                 optimizer estimated cost:           69.35
-</codeblock></p>
+</codeblock>
 <p>Other, more complex queries such as joins and unions have other types of
 result set nodes.</p>
-<p>For inserts, updates, and deletes, rows flow out of the top, where they
-are inserted, updated, or deleted. For selects (queries), rows flow out of
-the top into a result set that is returned to the user.</p>
-<p>The <cite><ph conref="../conrefs.dita#pub/citref"></ph></cite> shows the
-many possible <i>ResultSet</i> nodes that might appear in an execution plan. </p>
-<p>In addition, read <xref href="ctunoptimz39739.dita#ctunoptimz39739"></xref>,
-for more information about some of the ways in which <ph conref="../conrefs.dita#prod/productshortname"></ph> executes statements.</p>
+<p>For inserts, updates, and deletes, rows flow out of the top, where they are
+inserted, updated, or deleted. For selects (queries), rows flow out of the top
+into a result set that is returned to the user.</p>
+<p>The <ph conref="../conrefs.dita#pub/citref"></ph> shows the many possible
+<i>ResultSet</i> nodes that might appear in an execution plan.</p>
+<p>In addition, read <xref href="ctunoptimz39739.dita"/> for more information
+about some of the ways in which
+<ph conref="../conrefs.dita#prod/productshortname"></ph> executes
+statements.</p>
 </conbody>
 </concept>
 

Modified: db/derby/docs/trunk/src/tuning/ctundepth853228.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/ctundepth853228.dita?rev=1609163&r1=1609162&r2=1609163&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tuning/ctundepth853228.dita (original)
+++ db/derby/docs/trunk/src/tuning/ctundepth853228.dita Wed Jul  9 14:07:47 2014
@@ -18,20 +18,19 @@ limitations under the License.
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "../dtd/concept.dtd">
 <concept xml:lang="en-us" id="ctundepth853228">
 <title>Optimizer estimates</title>
+<shortdesc>RUNTIMESTATISTICS shows the optimizer estimates for a particular
+node. It shows the optimizer's estimated row count and the optimizer's
+"estimated cost."</shortdesc>
 <prolog>
 </prolog>
 <conbody>
-<p>RUNTIMESTATISTICS show the optimizer estimates for a particular node. They
-show the optimizer's estimated row count and the optimizer's "estimated
-cost."</p>
-<p>The <i>estimated row count</i> is the query optimizer's
-estimate of the number of qualifying rows for the table or index for the entire
-life of the query. If the table is the inner table of a join, the estimated
-row count will be for all the scans of the table, not just for a single scan
-of the table.  </p>
-<p>The <i>estimated cost</i> consists of a number, which
-is a relative number; it does not correspond directly to any time estimate.
-It is not, for example, the number of milliseconds or rows. Instead, the optimizer
-constructs this number for each possible access path. It compares the numbers
-and chooses the access path with the smallest number.</p>
+<p>The <i>estimated row count</i> is the query optimizer's estimate of the
+number of qualifying rows for the table or index for the entire life of the
+query. If the table is the inner table of a join, the estimated row count will
+be for all the scans of the table, not just for a single scan of the table.</p>
+<p>The <i>estimated cost</i> consists of a number, which is a relative number;
+it does not correspond directly to any time estimate. It is not, for example,
+the number of milliseconds or rows. Instead, the optimizer constructs this
+number for each possible access path. It compares the numbers and chooses the
+access path with the smallest number.</p>
 </conbody></concept>

Modified: db/derby/docs/trunk/src/tuning/ctundepthoptover.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/ctundepthoptover.dita?rev=1609163&r1=1609162&r2=1609163&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tuning/ctundepthoptover.dita (original)
+++ db/derby/docs/trunk/src/tuning/ctundepthoptover.dita Wed Jul  9 14:07:47 2014
@@ -20,15 +20,18 @@
  "../dtd/concept.dtd">
 <concept id="ctundepthoptover" xml:lang="en-us">
 <title>Optimizer overrides</title>
+<shortdesc>RUNTIMESTATISTICS provides information about user-specified optimizer
+hints that were specified by using a <codeph>--DERBY-PROPERTIES</codeph>
+clause.</shortdesc>
 <conbody>
-<p>RUNTIMESTATISTICS provides information about user-specified optimizer hints
-that were specified by using a -- DERBY-PROPERTIES clause.
-(See <xref href="ctunoptimzoverride.dita#ctunoptimzoverride"></xref> for details
-about how to use this clause.)</p>
+<p>See <xref href="ctunoptimzoverride.dita"/> for details about how to use this
+clause.</p>
 <p>The following example shows a SELECT statement in which the optimizer was
-forced to use a particular index:<codeblock><b>SELECT * FROM t1 -- DERBY-PROPERTIES index = t1_c1 
-FOR UPDATE OF c2, c1</b></codeblock></p>
-<p>RUNTIMESTATISTICS returns the following information about this statement:<codeblock>Statement Name: 
+forced to use a particular index:</p>
+<codeblock><b>SELECT * FROM t1 -- DERBY-PROPERTIES index = t1_c1 
+FOR UPDATE OF c2, c1</b></codeblock>
+<p>RUNTIMESTATISTICS returns the following information about this statement:</p>
+<codeblock>Statement Name: 
 		 null
 Statement Text: select * from t1 --DERBY-PROPERTIES index = t1_c1 
 for update of c2, c1
@@ -79,8 +82,6 @@ Columns accessed from heap = {0, 1, 2}
 		 		 stop position: 
 		 None
 		 		 qualifiers:
-None
-
-</codeblock></p>
+                 None</codeblock>
 </conbody>
 </concept>

Modified: db/derby/docs/trunk/src/tuning/ctunperf1004182.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/ctunperf1004182.dita?rev=1609163&r1=1609162&r2=1609163&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tuning/ctunperf1004182.dita (original)
+++ db/derby/docs/trunk/src/tuning/ctunperf1004182.dita Wed Jul  9 14:07:47 2014
@@ -32,13 +32,10 @@ with fewer I/Os. However, large pages re
 <ph conref="../conrefs.dita#prod/productshortname"></ph> allocates a bulk number
 of database pages in its page cache by default. If the page size is large, the
 system might run out of memory.</p>
-<p>Here's a rough guideline: If the system is running Windows 95 and has more
-than 32 MB (or Windows NT and has more than 64 MB), it is probably beneficial to
-use 8K rather than 4K as the default page size.</p>
-<p>Use the <i>-mx</i> flag as an optional parameter to the JVM to give the JVM
+<p>Use the <i>-Xmx</i> flag as an optional parameter to the JVM to give the JVM
 more memory upon startup.</p>
 <p>For example:</p>
-<codeblock><b>java -mx64 myApp</b></codeblock>
+<codeblock><b>java -Xmx64M myApp</b></codeblock>
 <p>If you have limited disk space and cannot afford the overhead of the minimum
 two pages per table, keep your page sizes small.</p>
 </conbody></concept>

Modified: db/derby/docs/trunk/src/tuning/ttundepth33391.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/ttundepth33391.dita?rev=1609163&r1=1609162&r2=1609163&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tuning/ttundepth33391.dita (original)
+++ db/derby/docs/trunk/src/tuning/ttundepth33391.dita Wed Jul  9 14:07:47 2014
@@ -19,48 +19,58 @@ limitations under the License.
 -->
 <task id="ttundepth33391" xml:lang="en-us">
 <title>Analyzing statement execution</title>
+<shortdesc>After you create indexes, make sure that
+<ph conref="../conrefs.dita#prod/productshortname"></ph> is using them. In
+addition, you might also want to find out the join order that
+<ph conref="../conrefs.dita#prod/productshortname"></ph> is
+choosing.</shortdesc>
 <prolog><metadata>
 <keywords><indexterm>Statement execution<indexterm>analyzing</indexterm></indexterm>
-<indexterm>Index use<indexterm>analyzing</indexterm></indexterm><indexterm>Join
-order<indexterm>analyzing</indexterm></indexterm><indexterm>Application performance<indexterm>analyzing</indexterm></indexterm>
-<indexterm>Checkpoint</indexterm></keywords>
+<indexterm>Index use<indexterm>analyzing</indexterm></indexterm>
+<indexterm>Join order<indexterm>analyzing</indexterm></indexterm>
+<indexterm>Application performance<indexterm>analyzing</indexterm></indexterm>
+<indexterm>Checkpoints</indexterm></keywords>
 </metadata></prolog>
 <taskbody>
-<context> After you create indexes, make sure that <ph conref="../conrefs.dita#prod/productshortname"></ph> is
-using them. In addition, you might also want to find out the join order <ph
-conref="../conrefs.dita#prod/productshortname"></ph> is choosing.<p>A general
-plan of attack for analyzing your application's SQL statements:</p></context>
+<context><p>Use this general plan of attack for analyzing your application's SQL
+statements:</p>
+</context>
 <steps>
-<step><cmd>Collect your application's most frequently used SQL statements
-and transactions into a single test.</cmd></step>
-<step><cmd>Create a benchmark test suite against which to run the sample queries.
-The first thing the test suite should do is checkpoint data (force <ph conref="../conrefs.dita#prod/productshortname"></ph> to
-flush data to disk). You can do that with the following JDBC code: </cmd>
+<step><cmd>Collect your application's most frequently used SQL statements and
+transactions into a single test.</cmd></step>
+<step><cmd>Create a benchmark test suite against which to run the sample
+queries.</cmd>
+<info>The first thing the test suite should do is to checkpoint data (force
+<ph conref="../conrefs.dita#prod/productshortname"></ph> to flush data to disk).
+You can do that with the following JDBC code:</info>
 <stepxmp><codeblock>CallableStatement cs = conn.prepareCall
 ("CALL SYSCS_UTIL.SYSCS_CHECKPOINT_DATABASE()");
 cs.execute();
 cs.close();</codeblock></stepxmp></step>
-<step><cmd>Use performance timings to identify poorly performing queries.
-Try to distinguish between cached and uncached data. Focus on measuring operations
-on uncached data (data not already in memory). For example, the first time
-you run a query, <ph conref="../conrefs.dita#prod/productshortname"></ph> returns
-uncached data. If you run the same query immediately afterward, <ph conref="../conrefs.dita#prod/productshortname"></ph> is
-probably returning cached data. The performance of these two otherwise identical
-statements varies significantly and skews results.</cmd></step>
-<step><cmd>Use RunTimeStatistics to identify tables that are scanned excessively.
-Check that the appropriate indexes are being used to satisfy the query and
-that <ph conref="../conrefs.dita#prod/productshortname"></ph> is choosing
-the best join order.  You can also set <i>derby.language.logQueryPlan</i> to true
-to check whether indexes are being used or not. This property will  is print
-query plans in the <i>derby.log</i> file. See the
+<step><cmd>Use performance timings to identify poorly performing queries. Try to
+distinguish between cached and uncached data. Focus on measuring operations on
+uncached data (data not already in memory).</cmd>
+<info>For example, the first time you run a query,
+<ph conref="../conrefs.dita#prod/productshortname"></ph> returns uncached data.
+If you run the same query immediately afterwards,
+<ph conref="../conrefs.dita#prod/productshortname"></ph> is probably returning
+cached data. The performance of these two otherwise identical statements varies
+significantly and skews results.</info></step>
+<step><cmd>Use RunTimeStatistics to identify tables that are scanned
+excessively.</cmd>
+<info>Check that the appropriate indexes are being used to satisfy the query and
+that <ph conref="../conrefs.dita#prod/productshortname"></ph> is choosing the
+best join order.  You can also set the <i>derby.language.logQueryPlan</i>
+property to true to check whether indexes are being used or not. This property
+prints query plans in the <codeph>derby.log</codeph> file. See the
 "<ph conref="../conrefs.dita#prod/productshortname"></ph> properties" section of
 the <ph conref="../conrefs.dita#pub/citref"></ph> for details on this property.
-See <xref href="ctundepth13055.dita#ctundepth13055"></xref> for more
-information.</cmd></step>
+See <xref href="ctundepth13055.dita"/> for more information.</info></step>
 <step><cmd>Make any necessary changes and then repeat.</cmd></step>
 <step><cmd>If changing data access does not create significant improvements,
-consider other database design changes, such as denormalizing data to reduce
-the number of joins required. Then review the tips in <xref href="ctundepth21935.dita#ctundepth21935"></xref>.</cmd>
+consider other database design changes, such as denormalizing data to reduce the
+number of joins required. Then review the tips in
+<xref href="ctundepth21935.dita"/>.</cmd>
 </step>
 </steps>
 </taskbody>

Modified: db/derby/docs/trunk/src/tuning/ttundepth34375.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/ttundepth34375.dita?rev=1609163&r1=1609162&r2=1609163&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tuning/ttundepth34375.dita (original)
+++ db/derby/docs/trunk/src/tuning/ttundepth34375.dita Wed Jul  9 14:07:47 2014
@@ -20,15 +20,18 @@ limitations under the License.
  "../dtd/task.dtd">
 <task id="ttundepth34375" xml:lang="en-us">
 <title>How you use the RUNTIMESTATISTICS attribute</title>
+<shortdesc>You can use the RUNTIMESTATISTICS attribute either with or without
+statistics timing.</shortdesc>
 <prolog><metadata>
 <keywords><indexterm>RunTimeStatistics<indexterm>using</indexterm></indexterm>
 </keywords>
 </metadata></prolog>
 <taskbody>
 <steps-unordered>
-<step><cmd>To use the RUNTIMESTATISTICS attribute in <codeph>ij</codeph>,
-turn on and off RUNTIMESTATISTICS using the <codeph>SYSCS_UTIL.SYSCS_SET_RUNTIMESTATISTICS()</codeph> system
-procedure (see the <cite><ph conref="../conrefs.dita#pub/citref"></ph></cite> for more information):</cmd>
+<step><cmd>To use the RUNTIMESTATISTICS attribute in <codeph>ij</codeph>, turn
+RUNTIMESTATISTICS on and off using the
+<codeph>SYSCS_UTIL.SYSCS_SET_RUNTIMESTATISTICS()</codeph> system procedure (see
+the <ph conref="../conrefs.dita#pub/citref"></ph> for more information):</cmd>
 <stepxmp><codeblock>-- turn on RUNTIMESTATISTICS for connection:
 <b>CALL SYSCS_UTIL.SYSCS_SET_RUNTIMESTATISTICS(1);</b>
 -- execute complex query here -- step through the result set
@@ -36,16 +39,18 @@ procedure (see the <cite><ph conref="../
 <b>VALUES SYSCS_UTIL.SYSCS_GET_RUNTIMESTATISTICS();</b>
 <b>CALL SYSCS_UTIL.SYSCS_SET_RUNTIMESTATISTICS(0);</b></codeblock></stepxmp>
 </step>
-<step><cmd>Turn on statistics timing using the <codeph>SYSCS_UTIL.SYSCS_SET_STATISTICS_TIMING</codeph> system
-procedure (see the <cite><ph conref="../conrefs.dita#pub/citref"></ph></cite> for more information).
-If you do not turn on statistics timing, you will see the statement execution
-plan only, and not the timing information.</cmd><stepxmp><codeblock>CALL SYSCS_UTIL.SYSCS_SET_RUNTIMESTATISTICS(1);
-CALL SYSCS_UTIL.SYSCS_SET_STATISTICS_TIMING(1);</codeblock></stepxmp></step>
+<step><cmd>Turn on statistics timing using the
+<codeph>SYSCS_UTIL.SYSCS_SET_STATISTICS_TIMING</codeph> system procedure (see
+the <ph conref="../conrefs.dita#pub/citref"></ph> for more information). If you
+do not turn on statistics timing, you will see the statement execution plan
+only, and not the timing information.</cmd>
+<stepxmp><codeblock><b>CALL SYSCS_UTIL.SYSCS_SET_RUNTIMESTATISTICS(1);
+CALL SYSCS_UTIL.SYSCS_SET_STATISTICS_TIMING(1);</b></codeblock></stepxmp></step>
 </steps-unordered>
 <result>Although the syntax is different, the basic steps for working with
 RUNTIMESTATISTICS are the same in a Java program.</result>
 <postreq>If you are working in <codeph>ij</codeph>, set the display
-width to 5000 or another high number:<codeblock><b>MaximumDisplayWidth 5000</b></codeblock></postreq>
+width to 5000 or another high number:
+<codeblock><b>MaximumDisplayWidth 5000</b></codeblock></postreq>
 </taskbody>
 </task>
-



Mime
View raw message