db-derby-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From chaa...@apache.org
Subject svn commit: r1437218 - in /db/derby/docs/trunk/src: ref/refderby.ditamap ref/rrefregistertoolproc.dita tools/ctoolsopttools.dita tools/derbytools.ditamap tools/rtoolsoptdbmetadata.dita tools/rtoolsoptforeignviews.dita
Date Tue, 22 Jan 2013 22:24:06 GMT
Author: chaase3
Date: Tue Jan 22 22:24:06 2013
New Revision: 1437218

URL: http://svn.apache.org/viewvc?rev=1437218&view=rev
Log:
DERBY-6042  Document the syscs_util.syscs_register_tool procedure added by DERBY-6022.

Added one new Reference Manual topic and three new Tools Guide topics.

Patch: DERBY-6042-2.diff

Added:
    db/derby/docs/trunk/src/ref/rrefregistertoolproc.dita   (with props)
    db/derby/docs/trunk/src/tools/ctoolsopttools.dita   (with props)
    db/derby/docs/trunk/src/tools/rtoolsoptdbmetadata.dita   (with props)
    db/derby/docs/trunk/src/tools/rtoolsoptforeignviews.dita   (with props)
Modified:
    db/derby/docs/trunk/src/ref/refderby.ditamap
    db/derby/docs/trunk/src/tools/derbytools.ditamap

Modified: db/derby/docs/trunk/src/ref/refderby.ditamap
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/refderby.ditamap?rev=1437218&r1=1437217&r2=1437218&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/refderby.ditamap (original)
+++ db/derby/docs/trunk/src/ref/refderby.ditamap Tue Jan 22 22:24:06 2013
@@ -884,6 +884,8 @@ limitations under the License.
 </topicref>
 <topicref href="rrefnativemodifypasswordproc.dita" navtitle="SYSCS_UTIL.SYSCS_MODIFY_PASSWORD
system procedure">
 </topicref>
+<topicref href="rrefregistertoolproc.dita" navtitle="SYSCS_UTIL.SYSCS_REGISTER_TOOL system
procedure">
+</topicref>
 <topicref href="rrefreloadpolicyproc.dita" navtitle="SYSCS_UTIL.SYSCS_RELOAD_SECURITY_POLICY
system procedure">
 </topicref>
 <topicref href="rrefnativeresetpasswordproc.dita" navtitle="SYSCS_UTIL.SYSCS_RESET_PASSWORD
system procedure">

Added: db/derby/docs/trunk/src/ref/rrefregistertoolproc.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefregistertoolproc.dita?rev=1437218&view=auto
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefregistertoolproc.dita (added)
+++ db/derby/docs/trunk/src/ref/rrefregistertoolproc.dita Tue Jan 22 22:24:06 2013
@@ -0,0 +1,115 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- 
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements.  See the NOTICE file distributed with
+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      
+
+http://www.apache.org/licenses/LICENSE-2.0  
+
+Unless required by applicable law or agreed to in writing, software  
+distributed under the License is distributed on an "AS IS" BASIS,  
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  
+See the License for the specific language governing permissions and  
+limitations under the License.
+-->
+
+<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN"
+ "../dtd/reference.dtd">
+<reference id="rrefregistertoolproc" xml:lang="en-us">
+<title>SYSCS_UTIL.SYSCS_REGISTER_TOOL system procedure</title>
+<shortdesc>The <codeph>SYSCS_UTIL.SYSCS_REGISTER_TOOL</codeph> system procedure
+loads and unloads optional tools packages.</shortdesc>
+<prolog><metadata>
+<keywords>
+<indexterm>system procedures<indexterm>SYSCS_UTIL.SYSCS_REGISTER_TOOL</indexterm></indexterm>
+<indexterm>SYSCS_UTIL.SYSCS_REGISTER_TOOL system procedure</indexterm>
+<indexterm>tools<indexterm>SYSCS_UTIL.SYSCS_REGISTER_TOOL
+system procedure</indexterm></indexterm>
+<indexterm>registering tools<indexterm>SYSCS_UTIL.SYSCS_REGISTER_TOOL
+system procedure</indexterm></indexterm>
+</keywords>
+</metadata></prolog>
+<refbody>
+<section><title>Syntax</title>
+<codeblock>SYSCS_UTIL.SYSCS_REGISTER_TOOL(IN TOOLNAME VARCHAR(128), 
+                               IN REGISTER BOOLEAN, 
+                               IN OPTIONALARGS VARCHAR(128) ... )</codeblock>
+<p>No result set is returned by this procedure.</p>
+<dl><dlentry>
+<dt>TOOLNAME</dt>
+<dd>The name of the optional tool. Must be either
+<codeph>'databaseMetaData'</codeph> or <codeph>'foreignViews'</codeph>.</dd>
+</dlentry>
+<dlentry>
+<dt>REGISTER</dt>
+<dd>A value of true tells
+<ph conref="../conrefs.dita#prod/productshortname"></ph> to load the tool. A

+value of false tells <ph conref="../conrefs.dita#prod/productshortname"></ph>
to
+unload the tool.</dd>
+</dlentry>
+<dlentry>
+<dt>OPTIONALARGS</dt>
+<dd>Optional arguments specific to each tool.</dd>
+</dlentry></dl>
+</section>
+<section><title>Execute privileges</title>
+<p>If authentication and SQL authorization are both enabled, only the
+<xref href="rrefattrib26867.dita#rrefattrib26867">database owner</xref> has
+execute privileges on this procedure by default. See "Enabling user
+authentication" and "Setting the SQL standard authorization mode" in the
+<ph conref="../conrefs.dita#pub/citdevelop"></ph> for more information. The
+database owner can grant access to other users.</p>
+</section>
+<section><title>Usage</title>
+<p>The following optional tools are supported:</p>
+<ul>
+<li><codeph>databaseMetaData</codeph>
+<p>This optional tool creates functions and table functions to wrap the methods
+in <i>java.sql.DatabaseMetaData</i>, allowing you to use <i>DatabaseMetaData</i>
+methods in queries. For example, you can join and filter the <i>ResultSet</i>s
+returned by <i>DatabaseMetaData</i> methods. This tool does not require any
+optional arguments. To create the metadata functions and table functions, do the
+following:</p>
+<codeblock><b>call syscs_util.syscs_register_tool( 'databaseMetaData', true )
+</b></codeblock>
+<p>To drop the functions and table functions, do the following:</p>
+<codeblock><b>call syscs_util.syscs_register_tool( 'databaseMetaData', false
)
+</b></codeblock>
+<p>See the <ph conref="../conrefs.dita#pub/citutilities"></ph> for more
+information on how to use this tool.</p>
+</li>
+<li><codeph>foreignViews</codeph>
+<p>This optional tool creates schemas, table functions, and convenience views
+for all user tables in a foreign database. The table functions and views are
+useful for bulk-importing foreign data into
+<ph conref="../conrefs.dita#prod/productshortname"></ph>. This tool takes two
+additional arguments:</p>
+<dl><dlentry>
+<dt>CONNECTION_URL</dt>
+<dd>This is a connection URL string suitable for creating a connection to the
+foreign database by calling <i>DriverManager.getConnection()</i>.</dd>
+</dlentry><dlentry>
+<dt>SCHEMA_PREFIX</dt>
+<dd>This is an optional string prefixed to all of the schema names which the
+tool creates. This argument may be omitted. If it is omitted, then the tool will
+create schemas which have the same names as the schemas in the foreign
+database.</dd>
+</dlentry></dl>
+<p>To create views on the foreign data, do the following:</p>
+<codeblock><b>call syscs_util.syscs_register_tool( 'foreignViews', true,
+    'foreignDatabaseURL', 'XYZ_' )
+</b></codeblock>
+<p>To drop the views on the foreign data, do the following:</p>
+<codeblock><b>call syscs_util.syscs_register_tool( 'foreignViews', false,
+    'foreignDatabaseURL', 'XYZ_' )
+</b></codeblock>
+<p>See the <ph conref="../conrefs.dita#pub/citutilities"></ph> for more
+information on how to use this tool.</p>
+</li>
+</ul>
+</section>
+</refbody>
+</reference>

Propchange: db/derby/docs/trunk/src/ref/rrefregistertoolproc.dita
------------------------------------------------------------------------------
    svn:eol-style = native

Added: db/derby/docs/trunk/src/tools/ctoolsopttools.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tools/ctoolsopttools.dita?rev=1437218&view=auto
==============================================================================
--- db/derby/docs/trunk/src/tools/ctoolsopttools.dita (added)
+++ db/derby/docs/trunk/src/tools/ctoolsopttools.dita Tue Jan 22 22:24:06 2013
@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- 
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements.  See the NOTICE file distributed with
+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      
+
+http://www.apache.org/licenses/LICENSE-2.0  
+
+Unless required by applicable law or agreed to in writing, software  
+distributed under the License is distributed on an "AS IS" BASIS,  
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  
+See the License for the specific language governing permissions and  
+limitations under the License.
+-->
+<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "../dtd/concept.dtd">
+<concept xml:lang="en-us" id="ctoolsopttools">
+<title>Optional tools</title>
+<prolog><metadata>
+<keywords>
+</keywords>
+</metadata>
+</prolog>
+<conbody>
+<p><ph conref="../conrefs.dita#prod/productshortname"></ph> supports optional
+tools, which you can load and unload by using the
+<codeph>SYSCS_UTIL.SYSCS_REGISTER_TOOL</codeph> system procedure as described
in
+the <ph conref="../conrefs.dita#pub/citref"></ph>.</p>
+</conbody>
+</concept>

Propchange: db/derby/docs/trunk/src/tools/ctoolsopttools.dita
------------------------------------------------------------------------------
    svn:eol-style = native

Modified: db/derby/docs/trunk/src/tools/derbytools.ditamap
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tools/derbytools.ditamap?rev=1437218&r1=1437217&r2=1437218&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tools/derbytools.ditamap (original)
+++ db/derby/docs/trunk/src/tools/derbytools.ditamap Tue Jan 22 22:24:06 2013
@@ -198,5 +198,9 @@ limitations under the License.
 <topicref href="rtoolsplanexpxmlformat.dita" navtitle="PlanExporter XML format"></topicref>
 <topicref href="rtoolsplanexpexamples.dita" navtitle="PlanExporter example"></topicref>
 </topicref>
+<topicref collection-type="family" href="ctoolsopttools.dita" navtitle="Optional tools">
+<topicref href="rtoolsoptdbmetadata.dita" navtitle="Using the databaseMetaData optional
tool"></topicref>
+<topicref href="rtoolsoptforeignviews.dita" navtitle="Using the foreignViews optional
tool"></topicref>
+</topicref>
 <topicref href="rtoolstrademderby.dita" navtitle="Trademarks"></topicref>
 </map>

Added: db/derby/docs/trunk/src/tools/rtoolsoptdbmetadata.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tools/rtoolsoptdbmetadata.dita?rev=1437218&view=auto
==============================================================================
--- db/derby/docs/trunk/src/tools/rtoolsoptdbmetadata.dita (added)
+++ db/derby/docs/trunk/src/tools/rtoolsoptdbmetadata.dita Tue Jan 22 22:24:06 2013
@@ -0,0 +1,81 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- 
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements.  See the NOTICE file distributed with
+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      
+
+http://www.apache.org/licenses/LICENSE-2.0  
+
+Unless required by applicable law or agreed to in writing, software  
+distributed under the License is distributed on an "AS IS" BASIS,  
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  
+See the License for the specific language governing permissions and  
+limitations under the License.
+-->
+<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN"
+ "../dtd/reference.dtd">
+<reference id="rtoolsoptdbmetadata" xml:lang="en-us">
+<title>Using the databaseMetaData optional tool</title>
+<shortdesc>The <codeph>databaseMetaData</codeph> optional tool creates
functions
+and table functions corresponding to most of the methods in the
+<i>java.sql.DatabaseMetaData</i> interface.</shortdesc>
+<prolog><metadata>
+<keywords>
+<indexterm>optional tools<indexterm>databaseMetaData</indexterm></indexterm>
+<indexterm>databaseMetaData optional tool</indexterm>
+<indexterm>tools<indexterm>databaseMetaData optional tool</indexterm></indexterm>
+</keywords>
+</metadata></prolog>
+<refbody>
+<section>
+<p>You can load and unload the <codeph>databaseMetaData</codeph> tool by
using
+the <codeph>SYSCS_UTIL.SYSCS_REGISTER_TOOL</codeph> system procedure. See the
+<ph conref="../conrefs.dita#pub/citref"></ph> for information about this
+procedure.</p>
+<p>To load the <codeph>databaseMetaData</codeph> tool, use the following
+statement:</p>
+<codeblock><b>call syscs_util.syscs_register_tool( 'databaseMetaData', true )
+</b></codeblock>
+<p>This command creates metadata functions and table functions in the current
+schema. The functions and table functions have the same names as the
+corresponding <i>java.sql.DatabaseMetaData</i> methods which they wrap. Once
you
+have loaded this tool, you can filter and join these functions to create
+powerful metadata queries. For instance, the following query lists the column
+names and datatypes for all columns in tables created by users:</p>
+<codeblock><b>select t.table_schem, t.table_name, c.column_name, c.type_name
+from table( getTables( null, '%', '%' ) ) t,
+     table( getColumns( null, '%', '%', '%') ) c
+where c.table_schem = t.table_schem
+and c.table_name = t.table_name
+and t.table_type = 'TABLE'
+order by table_schem, table_name, column_name
+</b></codeblock>
+<p>A few <i>DatabaseMetaData</i> methods take array arguments. Because
those
+arguments cannot be represented as
+<ph conref="../conrefs.dita#prod/productshortname"></ph> types, the arguments
+are eliminated. This means that the trailing <i>types</i> arguments to
+<i>getTables()</i> and <i>getUDTs()</i> have been eliminated. In
addition, the
+following <i>DatabaseMetaData</i> methods do not have corresponding metadata
+routines:</p>
+<ul>
+<li><i>getRowIdLifetime()</i> is eliminated because
+<ph conref="../conrefs.dita#prod/productshortname"></ph> does not provide an
+implementation of <i>java.sql.RowIdLifetime</i>.</li>
+<li><i>getSchemas()</i> is eliminated because
+<ph conref="../conrefs.dita#prod/productshortname"></ph> does not support
+overloads. The more general <i>getSchemas( String, String )</i> method is
+included.</li>
+<li><i>supportsConvert()</i> is eliminated because
+<ph conref="../conrefs.dita#prod/productshortname"></ph> does not support
+overloads. The more general <i>supportsConvert( int, int )</i> is included.</li>
+</ul>
+<p>When you have finished joining metadata results, you can drop this package of
+functions and table functions as follows:</p>
+<codeblock><b>call syscs_util.syscs_register_tool( 'databaseMetaData', false
)
+</b></codeblock>
+</section>
+</refbody>
+</reference>

Propchange: db/derby/docs/trunk/src/tools/rtoolsoptdbmetadata.dita
------------------------------------------------------------------------------
    svn:eol-style = native

Added: db/derby/docs/trunk/src/tools/rtoolsoptforeignviews.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tools/rtoolsoptforeignviews.dita?rev=1437218&view=auto
==============================================================================
--- db/derby/docs/trunk/src/tools/rtoolsoptforeignviews.dita (added)
+++ db/derby/docs/trunk/src/tools/rtoolsoptforeignviews.dita Tue Jan 22 22:24:06 2013
@@ -0,0 +1,96 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- 
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements.  See the NOTICE file distributed with
+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      
+
+http://www.apache.org/licenses/LICENSE-2.0  
+
+Unless required by applicable law or agreed to in writing, software  
+distributed under the License is distributed on an "AS IS" BASIS,  
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  
+See the License for the specific language governing permissions and  
+limitations under the License.
+-->
+<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN"
+ "../dtd/reference.dtd">
+<reference id="rtoolsoptforeignviews" xml:lang="en-us">
+<title>Using the foreignViews optional tool</title>
+<shortdesc>The <codeph>foreignViews</codeph> optional tool creates schemas,
+table functions, and convenience views for all user tables in a foreign
+database. This can be useful for bulk-importing foreign data.</shortdesc>
+<prolog><metadata>
+<keywords>
+<indexterm>optional tools<indexterm>foreignViews</indexterm></indexterm>
+<indexterm>foreignViews optional tool</indexterm>
+<indexterm>tools<indexterm>foreignViews optional tool</indexterm></indexterm>
+</keywords>
+</metadata></prolog>
+<refbody>
+<section>
+<p>You can load and unload the <codeph>foreignViews</codeph> tool by using
+the <codeph>SYSCS_UTIL.SYSCS_REGISTER_TOOL</codeph> system procedure. See the
+<ph conref="../conrefs.dita#pub/citref"></ph> for information about this
+procedure.</p>
+<p>To load the <codeph>foreignViews</codeph> tool, use a statement like
the
+following:</p>
+<codeblock><b>call syscs_util.syscs_register_tool( 'foreignViews', true,
+    '<i>foreignDatabaseURL</i>', 'XYZ_' )
+</b></codeblock>
+<p>The two trailing arguments have the following meanings:</p>
+<ul>
+<li><i>foreignDatabaseURL</i> is a URL suitable for creating a connection
to
+the foreign database by calling <i>java.sql.DriverManager.getConnection()</i>.
+For example: 
+<codeblock><b>'jdbc:derby:db3;user=fred;password=fredpassword'</b></codeblock>
+</li>
+<li><codeph>'XYZ_'</codeph> is a string prefixed to the names of all schemas
+created by this tool. This argument may be omitted. If it is omitted, the tool
+will create schemas which have the same names as the schemas in the foreign
+database.</li>
+</ul>
+<p>For example, suppose that the foreign database has two schemas,
+<codeph>S1</codeph> and <codeph>S2</codeph>. <codeph>S1</codeph>
contains two
+user tables, <codeph>T1</codeph> and <codeph>T2</codeph>. <codeph>S2</codeph>
+contains two user tables, <codeph>U1</codeph> and <codeph>U2</codeph>.
Loading
+the tool as shown above will create the following objects in your
+<ph conref="../conrefs.dita#prod/productshortname"></ph> database:</p>
+<sl>
+<sli>schema <codeph>XYZ_S1</codeph></sli>
+<sli>table function <codeph>XYZ_S1.T1</codeph>, which reads
+<codeph>S1.T1</codeph> from the foreign database</sli>
+<sli>table function <codeph>XYZ_S1.T2</codeph>, which reads
+<codeph>S1.T2</codeph> from the foreign database</sli>
+<sli>view <codeph>XYZ_S1.T1</codeph>, which wraps the corresponding table
+function</sli>
+<sli>view <codeph>XYZ_S1.T2</codeph>, which wraps the corresponding table
+function</sli>
+</sl><sl>
+<sli>schema <codeph>XYZ_S2</codeph></sli>
+<sli>table function<codeph> XYZ_S2.U1</codeph>, which reads
+<codeph>S2.U1</codeph> from the foreign database</sli>
+<sli>table function <codeph>XYZ_S2.U2</codeph>, which reads
+<codeph>S2.U2</codeph> from the foreign database</sli>
+<sli>view <codeph>XYZ_S2.U1</codeph>, which wraps the corresponding table
+function</sli>
+<sli>view <codeph>XYZ_S2.U2</codeph>, which wraps the corresponding table
+function</sli>
+</sl>
+<p>The views hide the arguments to the table functions. You can then populate
+your local schema by using the following SELECT statements:</p>
+<codeblock><b>insert into S1.T1 select * from XYZ_S1.T1
+insert into S1.T2 select * from XYZ_S1.T2
+insert into S2.U1 select * from XYZ_S2.U1
+insert into S2.U2 select * from XYZ_S2.U2 
+</b></codeblock>
+<p>When you have finished bulk-importing the foreign data, you can drop this
+package of schemas, table functions and views as follows:</p>
+<codeblock><b>call syscs_util.syscs_register_tool( 'foreignViews', false,
+    'foreignDatabaseURL', 'XYZ_' )
+</b></codeblock>
+</section>
+</refbody>
+</reference>

Propchange: db/derby/docs/trunk/src/tools/rtoolsoptforeignviews.dita
------------------------------------------------------------------------------
    svn:eol-style = native



Mime
View raw message