db-derby-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From chaa...@apache.org
Subject svn commit: r1428414 - in /db/derby/docs/trunk/src/ref: rrefcreatefunctionstatement.dita rrefcreateprocedurestatement.dita
Date Thu, 03 Jan 2013 15:50:31 GMT
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>



Mime
View raw message