You are viewing a plain text version of this content. The canonical link for it is here.
Posted to derby-commits@db.apache.org by ch...@apache.org on 2013/01/03 16:50:31 UTC
svn commit: r1428414 - in /db/derby/docs/trunk/src/ref:
rrefcreatefunctionstatement.dita rrefcreateprocedurestatement.dita
Author: chaase3
Date: Thu Jan 3 15:50:30 2013
New Revision: 1428414
URL: http://svn.apache.org/viewvc?rev=1428414&view=rev
Log:
DERBY-6018 Document varargs routines.
Modified two Reference Manual topics.
Patch: DERBY-6018.diff
Modified:
db/derby/docs/trunk/src/ref/rrefcreatefunctionstatement.dita
db/derby/docs/trunk/src/ref/rrefcreateprocedurestatement.dita
Modified: db/derby/docs/trunk/src/ref/rrefcreatefunctionstatement.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefcreatefunctionstatement.dita?rev=1428414&r1=1428413&r2=1428414&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefcreatefunctionstatement.dita (original)
+++ db/derby/docs/trunk/src/ref/rrefcreatefunctionstatement.dita Thu Jan 3 15:50:30 2013
@@ -42,10 +42,14 @@ see <xref href="rrefsqljargmatching.dita
</section>
<refsyn><title>Syntax</title> <codeblock><b>CREATE FUNCTION <i><xref href="rrefcreatefunctionstatement.dita#rrefcreatefunctionstatement/rrefcrprofunctionname"
->function-name</xref></i> ( [ <xref href="rrefcreatefunctionstatement.dita#rrefcreatefunctionstatement/rrefcrprofunctionparameter">FunctionParameter</xref
->
- [, <xref href="rrefcreatefunctionstatement.dita#rrefcreatefunctionstatement/rrefcrprofunctionparameter">FunctionParameter</xref>] ] * ) RETURNS <xref href="rrefcreatefunctionstatement.dita#rrefcreatefunctionstatement/rrefcrfunctionreturntype">ReturnDataType</xref> [ <xref
-href="rrefcreatefunctionstatement.dita#rrefcreatefunctionstatement/rrefcrprofunctionelement">FunctionElement</xref> ] *</b></codeblock></refsyn>
+>function-name</xref></i> ( [ <xref href="rrefcreatefunctionstatement.dita#rrefcreatefunctionstatement/rrefcrprofunctionparameter">FunctionParameter</xref>
+ [, <xref href="rrefcreatefunctionstatement.dita#rrefcreatefunctionstatement/rrefcrprofunctionparameter">FunctionParameter</xref>]* [...] ] ) RETURNS <xref href="rrefcreatefunctionstatement.dita#rrefcreatefunctionstatement/rrefcrfunctionreturntype">ReturnDataType</xref>
+[ <xref href="rrefcreatefunctionstatement.dita#rrefcreatefunctionstatement/rrefcrprofunctionelement">FunctionElement</xref> ]*</b></codeblock>
+<p>An ellipsis (<codeph>...</codeph>) after the last parameter indicates that
+the Java method supports trailing optional arguments, called
+<term>varargs</term>. The ellipsis indicates that the method may be invoked
+with zero or more trailing values, all having the data type of the last
+argument.</p></refsyn>
<example id="rrefcrprofunctionname"><title>function-Name</title><codeblock><b>[ <i><xref
href="rrefschemaname.dita#rrefschemaname">schemaName</xref>.</i> ] <i><xref
href="crefsqlj34834.dita#crefsqlj34834">SQL92Identifier</xref></i></b></codeblock><p>If
@@ -54,9 +58,9 @@ a qualified procedure name is specified,
SYS.</p></example>
<example id="rrefcrprofunctionparameter"><title>FunctionParameter</title><codeblock><b>[ parameter-Name ] <i>DataType</i></b></codeblock></example>
<section><p>PararameterName must be unique within a function.</p><p>The syntax
-of <i>DataType</i> is described in <xref href="crefsqlj31068.dita#crefsqlj31068"></xref>.</p><note>Data-types
-such as BLOB, CLOB, LONG VARCHAR, LONG VARCHAR FOR BIT DATA, and XML are not
-allowed as parameters in a CREATE FUNCTION statement.</note></section>
+of <i>DataType</i> is described in <xref href="crefsqlj31068.dita#crefsqlj31068"></xref>.</p>
+<note>The data types BLOB, CLOB, LONG VARCHAR, LONG VARCHAR FOR BIT DATA, and
+XML are not allowed as parameters in a CREATE FUNCTION statement.</note></section>
<example id="rrefcrfunctionreturntype"><title>ReturnDataType</title>
<codeblock><b><xref href="rrefcreatefunctionstatement.dita#rrefcreatefunctionstatement/rrefcrfunctiontabletype">TableType</xref> | <i>DataType</i></b></codeblock></example>
@@ -72,7 +76,7 @@ They are functions which return JDBC <i>
</p>
<p>
-At run-time, as values are read out of the user-supplied <i>ResultSet</i>, Derby coerces those values
+At runtime, as values are read out of the user-supplied <i>ResultSet</i>, Derby coerces those values
to the data types declared in the CREATE FUNCTION statement. This affects values typed as
CHAR, VARCHAR, LONG VARCHAR, CHAR FOR BIT DATA, VARCHAR FOR BIT DATA,
LONG VARCHAR FOR BIT DATA, and DECIMAL/NUMERIC. Values which are too long are truncated
@@ -115,21 +119,22 @@ recognize whether an operation is actual
to specify the <codeph>DeterministicCharacteristic</codeph> correctly.</p>
</section>
<example id="rrefcrfunctionparameterstyle"><title>ParameterStyle</title>
-<codeblock><b>JAVA | DERBY_JDBC_RESULT_SET</b></codeblock></example>
-<section><p>The function will
+<codeblock><b>JAVA | DERBY_JDBC_RESULT_SET | DERBY</b></codeblock></example>
+<section><p><b>JAVA</b> - The function will
use a parameter-passing convention that conforms to the Java language and
SQL Routines specification. INOUT and OUT parameters will be passed as single
entry arrays to facilitate returning values. Result sets can be returned through
-additional parameters to the Java method of type java.sql.ResultSet[] that
+additional parameters to the Java method of type <i>java.sql.ResultSet[]</i> that
are passed single entry arrays.</p><p><ph conref="../conrefs.dita#prod/productshortname"></ph> does
-not support long column types (for example Long Varchar, BLOB, and so on).
+not support long column types (for example, LONG VARCHAR, BLOB, and so on).
An error will occur if you try to use one of these long column types. </p>
-<p>The PARAMETER STYLE is DERBY_JDBC_RESULT_SET if and only if this
-is a Derby-style table function, that is, a function which returns
+<p><b>DERBY_JDBC_RESULT_SET</b> - The PARAMETER STYLE is DERBY_JDBC_RESULT_SET
+if and only if this is a Derby-style table function, that is, a function which
+returns
<xref href="rrefcreatefunctionstatement.dita#rrefcreatefunctionstatement/rrefcrfunctiontabletype">TableType</xref>
-and which is mapped to a method which returns a JDBC
-<i>ResultSet</i>. Otherwise, the PARAMETER STYLE must be JAVA.
-</p>
+and which is mapped to a method which returns a JDBC <i>ResultSet</i>.</p>
+<p><b>DERBY</b> - The parameter style must be DERBY if and only if an ellipsis
+(<codeph>...</codeph>) appears at the end of the argument list.</p>
</section>
<section id="rrefcrfunctiondefrts"><title>EXTERNAL SECURITY</title>
<p>If SQL authorization mode is enabled, a function runs by default with the
@@ -214,5 +219,16 @@ NO SQL
EXTERNAL NAME 'vtis.example.PropertyFileVTI.propertyFileVTI'
</b></codeblock>
</section>
+<section><title>Example of declaring a function that takes varargs</title>
+<codeblock><b>
+CREATE FUNCTION maximum
+( a INT ... )
+RETURNS INT
+LANGUAGE JAVA
+PARAMETER STYLE DERBY
+NO SQL
+EXTERNAL NAME 'IntFunctions.maximum'
+</b></codeblock>
+</section>
</refbody>
</reference>
Modified: db/derby/docs/trunk/src/ref/rrefcreateprocedurestatement.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefcreateprocedurestatement.dita?rev=1428414&r1=1428413&r2=1428414&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefcreateprocedurestatement.dita (original)
+++ db/derby/docs/trunk/src/ref/rrefcreateprocedurestatement.dita Thu Jan 3 15:50:30 2013
@@ -41,11 +41,14 @@ see <xref href="rrefsqljargmatching.dita
</section>
<refsyn><title>Syntax</title><codeblock><b>CREATE PROCEDURE <i><xref href="rrefcreateprocedurestatement.dita#rrefcreateprocedurestatement/rrefcrproprocedurename"
->procedure-Name</xref></i> ( [ <xref href="rrefcreateprocedurestatement.dita#rrefcreateprocedurestatement/rrefcrproprocedureparameter">ProcedureParameter</xref
->
- [, <xref href="rrefcreateprocedurestatement.dita#rrefcreateprocedurestatement/rrefcrproprocedureparameter">ProcedureParameter</xref>] ] * )
-[ <xref href="rrefcreateprocedurestatement.dita#rrefcreateprocedurestatement/rrefcrproprocedureelement">ProcedureElement</xref> ] *</b></codeblock
-></refsyn>
+>procedure-Name</xref></i> ( [ <xref href="rrefcreateprocedurestatement.dita#rrefcreateprocedurestatement/rrefcrproprocedureparameter">ProcedureParameter</xref>
+ [, <xref href="rrefcreateprocedurestatement.dita#rrefcreateprocedurestatement/rrefcrproprocedureparameter">ProcedureParameter</xref>]* [...] ] )
+[ <xref href="rrefcreateprocedurestatement.dita#rrefcreateprocedurestatement/rrefcrproprocedureelement">ProcedureElement</xref> ]*</b></codeblock>
+<p>An ellipsis (<codeph>...</codeph>) after the last parameter indicates that
+the Java method supports trailing optional arguments, called
+<term>varargs</term>. The ellipsis indicates that the method may be invoked
+with zero or more trailing values, all having the data type of the last
+argument.</p></refsyn>
<example id="rrefcrproprocedurename"><title>procedure-Name</title><codeblock><b>[ <i><xref
href="rrefschemaname.dita#rrefschemaname">schemaName</xref>.</i> ] <i><xref
href="crefsqlj34834.dita#crefsqlj34834">SQL92Identifier</xref></i></b></codeblock></example>
@@ -56,15 +59,15 @@ begin with SYS.</p></section>
></b></codeblock></example>
<section><p>The default value for a parameter is IN. ParameterName must be
unique within a procedure.</p><p>The syntax of <i>DataType</i> is described
-in <xref href="crefsqlj31068.dita#crefsqlj31068"></xref>.</p><note>Data-types
-such as BLOB, CLOB, LONG VARCHAR, LONG VARCHAR FOR BIT DATA, and XML are not
+in <xref href="crefsqlj31068.dita#crefsqlj31068"></xref>.</p><note>The data
+types BLOB, CLOB, LONG VARCHAR, LONG VARCHAR FOR BIT DATA, and XML are not
allowed as parameters in a CREATE PROCEDURE statement.</note></section>
<example id="rrefcrproprocedureelement"> <title>ProcedureElement</title><codeblock><b> {
| [ DYNAMIC ] RESULT SETS <i><xref href="rrefsqlj10696.dita#rrefsqlj10696">INTEGER</xref></i>
| LANGUAGE { JAVA }
| <xref href="rrefcreateprocedurestatement.dita#rrefcreateprocedurestatement/rrefcrproceduredetchar">DeterministicCharacteristic</xref>
| EXTERNAL NAME <i>string</i>
-| PARAMETER STYLE JAVA
+| PARAMETER STYLE { JAVA | DERBY }
| EXTERNAL SECURITY { DEFINER | INVOKER }
| { NO SQL | MODIFIES SQL DATA | CONTAINS SQL | READS SQL DATA }
}
@@ -90,10 +93,12 @@ to specify the <codeph>DeterministicChar
use a parameter-passing convention that conforms to the Java language and
SQL Routines specification. INOUT and OUT parameters will be passed as single
entry arrays to facilitate returning values. Result sets are returned through
-additional parameters to the Java method of type java.sql.ResultSet [] that
-are passed single entry arrays.</p> <p><ph conref="../conrefs.dita#prod/productshortname"></ph> does
-not support long column types (for example Long Varchar, BLOB, and so on).
-An error will occur if you try to use one of these long column types. </p></section>
+additional parameters to the Java method of type <i>java.sql.ResultSet[]</i> that are passed single entry arrays.</p> <p><ph conref="../conrefs.dita#prod/productshortname"></ph> does
+not support long column types (for example, LONG VARCHAR, BLOB, and so on).
+An error will occur if you try to use one of these long column types. </p>
+<p><b>DERBY</b> - The parameter style must be DERBY if and only if an ellipsis
+(<codeph>...</codeph>) appears at the end of the argument list.</p>
+</section>
<section id="rrefcrprodefrts"><title>EXTERNAL SECURITY</title>
<p>If SQL authorization mode is enabled, a procedure runs by default with the
privileges specified for the user who invokes the procedure (invoker's rights).
@@ -147,9 +152,19 @@ elements: <ul>
<li><b>PARAMETER STYLE</b></li>
<li><b>EXTERNAL NAME</b></li>
</ul></p></section>
-<section><title>Example</title> <codeblock><b>CREATE PROCEDURE SALES.TOTAL_REVENUE(IN S_MONTH INTEGER,
+<section><title>Examples</title> <codeblock><b>CREATE PROCEDURE SALES.TOTAL_REVENUE(IN S_MONTH INTEGER,
IN S_YEAR INTEGER, OUT TOTAL DECIMAL(10,2))
PARAMETER STYLE JAVA READS SQL DATA LANGUAGE JAVA EXTERNAL NAME
-'com.example.sales.calculateRevenueByMonth'</b></codeblock></section>
+'com.example.sales.calculateRevenueByMonth'</b></codeblock>
+
+<codeblock><b>
+CREATE PROCEDURE VARARGPROC
+( IN a INT, IN b INT, IN c BIGINT ... )
+LANGUAGE JAVA
+PARAMETER STYLE DERBY
+READS SQL DATA
+EXTERNAL NAME 'Procs.varargProc'
+</b></codeblock>
+</section>
</refbody>
</reference>