Java > Open Source Codes > org > hsqldb > jdbc > jdbcPreparedStatement


1 /* Copyright (c) 2001-2005, The HSQL Development Group
2  * All rights reserved.
3  *
4  * Redistribution and use in source and binary forms, with or without
5  * modification, are permitted provided that the following conditions are met:
6  *
7  * Redistributions of source code must retain the above copyright notice, this
8  * list of conditions and the following disclaimer.
9  *
10  * Redistributions in binary form must reproduce the above copyright notice,
11  * this list of conditions and the following disclaimer in the documentation
12  * and/or other materials provided with the distribution.
13  *
14  * Neither the name of the HSQL Development Group nor the names of its
15  * contributors may be used to endorse or promote products derived from this
16  * software without specific prior written permission.
17  *
18  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
19  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21  * ARE DISCLAIMED. IN NO EVENT SHALL HSQL DEVELOPMENT GROUP, HSQLDB.ORG,
22  * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
23  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
24  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
25  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
26  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
28  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29  */
30
31
32 package org.hsqldb.jdbc;
33
34 import java.io.IOException ;
35 import java.io.Serializable ;
36 import java.math.BigDecimal ;
37 import java.sql.Date ;
38 import java.sql.PreparedStatement ;
39 import java.sql.ResultSet ;
40 import java.sql.ResultSetMetaData ;
41 import java.sql.SQLException ;
42 import java.sql.Time ;
43 import java.sql.Timestamp ;
44 import java.util.Calendar ;
45
46 //#ifdef JAVA2
47 import java.sql.Array ;
48 import java.sql.Blob ;
49 import java.sql.Clob ;
50 import java.sql.Ref ;
51
52 //#endif JAVA2
53 //#ifdef JDBC3
54 import java.sql.ParameterMetaData ;
55
56 //#endif JDBC3
57 import org.hsqldb.Column;
58 import org.hsqldb.HsqlDateTime;
59 import org.hsqldb.HsqlException;
60 import org.hsqldb.Result;
61 import org.hsqldb.ResultConstants;
62 import org.hsqldb.Trace;
63 import org.hsqldb.Types;
64 import org.hsqldb.lib.ArrayUtil;
65 import org.hsqldb.lib.HsqlByteArrayOutputStream;
66 import org.hsqldb.lib.Iterator;
67 import org.hsqldb.lib.StringConverter;
68 import org.hsqldb.types.Binary;
69 import org.hsqldb.types.JavaObject;
70
71 // fredt@users 20020320 - patch 1.7.0 - JDBC 2 support and error trapping
72 // JDBC 2 methods can now be called from jdk 1.1.x - see javadoc comments
73 // boucherb@users 20020509 - added "throws SQLException" to all methods where
74 // it was missing here but specified in the java.sql.PreparedStatement and
75 // java.sqlCallableStatement interfaces, updated generic documentation to
76 // JDK 1.4, and added JDBC3 methods and docs
77 // boucherb@users and fredt@users 20020409/20020505 extensive review and update
78 // of docs and behaviour to comply with previous and latest java.sql specification
79 // fredt@users 20030620 - patch 1.7.2 - rewritten to support real prepared statements
80 // boucherb@users 20030801 - patch 1.7.2 - support for batch execution
81 // boucherb@users 20030801 - patch 1.7.2 - support for getMetaData and getParameterMetadata
82 // boucherb@users 20030801 - patch 1.7.2 - updated some setXXX methods
83 // boucherb@users 200403/4xx - doc 1.7.2 - javadoc updates toward 1.7.2 final
84 // boucherb@users 200403/4xx - patch 1.7.2 - eliminate eager buffer allocation from setXXXStream/Blob/Clob
85 // fredt@users 20060215 - patch 1.8.0 - check for unset parameters
86
87 /**
88  * <!-- start generic documentation -->
89  *
90  * An object that represents a precompiled SQL statement. <p>
91  *
92  * An SQL statement is precompiled and stored in a
93  * <code>PreparedStatement</code> object. This object can then be used to
94  * efficiently execute this statement multiple times.
95  *
96  * <P><B>Note:</B> The setter methods (<code>setShort</code>,
97  * <code>setString</code>, and so on) for setting IN parameter values
98  * must specify types that are compatible with the defined SQL type of
99  * the input parameter. For instance, if the IN parameter has SQL type
100  * <code>INTEGER</code>, then the method <code>setInt</code> should be
101  * used. <p>
102  *
103  * If arbitrary parameter type conversions are required, the method
104  * <code>setObject</code> should be used with a target SQL type.
105  * <P>
106  * In the following example of setting a parameter, <code>con</code>
107  * represents an active connection:
108  * <PRE>
109  * PreparedStatement pstmt = con.prepareStatement("UPDATE EMPLOYEES
110  * SET SALARY = ? WHERE ID = ?");
111  * pstmt.setBigDecimal(1, 153833.00)
112  * pstmt.setInt(2, 110592)
113  * </PRE> <p>
114  * <!-- end generic documentation -->
115  * <!-- start Release-specific documentation -->
116  * <div class="ReleaseSpecificDocumentation">
117  * <h3>HSQLDB-Specific Information:</h3> <p>
118  *
119  * Starting with HSQLDB 1.7.2, jdbcPreparedStatement objects are backed by
120  * a true compiled parameteric representation. Hence, there are now significant
121  * performance gains to be had by using a jdbcPreparedStatement object in
122  * preference to a jdbcStatement object, if a short-running SQL statement is
123  * to be executed more than a small number of times. <p>
124  *
125  * When it can be otherwise avoided, it is to be considered poor
126  * practice to fully prepare (construct), parameterize, execute, fetch and
127  * close a jdbcPreparedStatement object for each execution cycle. Indeed, under
128  * HSQLDB 1.8.0, this practice is likely to be noticably <em>less</em>
129  * performant for short-running statements than the equivalent process using
130  * jdbcStatement objects, albeit far more convenient, less error prone and
131  * certainly much less resource-intensive, especially when large binary and
132  * character values are involved, due to the optimized parameterization
133  * facility. <p>
134  *
135  * Instead, when developing an application that is not totally oriented toward
136  * the execution of ad hoc SQL, it is recommended to expend some effort toward
137  * identifing the SQL statements that are good candidates for regular reuse and
138  * adapting the structure of the application accordingly. Often, this is done
139  * by recording the text of candidate SQL statements in an application resource
140  * object (which has the nice side-benefit of isolating and hiding differences
141  * in SQL dialects across different drivers) and caching for possible reuse the
142  * PreparedStatement objects derived from the recorded text. <p>
143  *
144  * <b>Multi thread use:</b> <p>
145  *
146  * A PreparedStatement object is stateful and should not normally be shared
147  * by multiple threads. If it has to be shared, the calls to set the
148  * parameters, calls to add batch statements, the execute call and any
149  * post-execute calls should be made within a block synchronized on the
150  * PreparedStatement Object.<p>
151  *
152  * <b>JRE 1.1.x Notes:</b> <p>
153  *
154  * In general, JDBC 2 support requires Java 1.2 and above, and JDBC3 requires
155  * Java 1.4 and above. In HSQLDB, support for methods introduced in different
156  * versions of JDBC depends on the JDK version used for compiling and building
157  * HSQLDB.<p>
158  *
159  * Since 1.7.0, it is possible to build the product so that
160  * all JDBC 2 methods can be called while executing under the version 1.1.x
161  * <em>Java Runtime Environment</em><sup><font size="-2">TM</font></sup>.
162  * However, in addition to requiring explicit casts to the org.hsqldb.jdbcXXX
163  * interface implementations, some of these method calls require
164  * <code>int</code> values that are defined only in the JDBC 2 or greater
165  * version of
166  * <a HREF="http://java.sun.com/j2se/1.4/docs/api/java/sql/ResultSet.html">
167  * <code>ResultSet</code></a> interface. For this reason, when the
168  * product is compiled under JDK 1.1.x, these values are defined in
169  * {@link jdbcResultSet jdbcResultSet}.<p>
170  *
171  * In a JRE 1.1.x environment, calling JDBC 2 methods that take or return the
172  * JDBC2-only <code>ResultSet</code> values can be achieved by referring
173  * to them in parameter specifications and return value comparisons,
174  * respectively, as follows: <p>
175  *
176  * <pre class="JavaCodeExample">
177  * jdbcResultSet.FETCH_FORWARD
178  * jdbcResultSet.TYPE_FORWARD_ONLY
179  * jdbcResultSet.TYPE_SCROLL_INSENSITIVE
180  * jdbcResultSet.CONCUR_READ_ONLY
181  * // etc.
182  * </pre>
183  *
184  * However, please note that code written in such a manner will not be
185  * compatible for use with other JDBC 2 drivers, since they expect and use
186  * <code>ResultSet</code>, rather than <code>jdbcResultSet</code>. Also
187  * note, this feature is offered solely as a convenience to developers
188  * who must work under JDK 1.1.x due to operating constraints, yet wish to
189  * use some of the more advanced features available under the JDBC 2
190  * specification.<p>
191  *
192  * (fredt@users)<br>
193  * (boucherb@users)
194  * </div>
195  * <!-- end Release-specific documentation -->
196  *
197  * @author boucherb@users
198  * @author fredt@users
199  * @version 1.8.0
200  * @see jdbcConnection#prepareStatement
201  * @see jdbcResultSet
202  */
203 public class jdbcPreparedStatement extends jdbcStatement
204 implements PreparedStatement {
205
206     /** The parameter values for the next non-batch execution. */
207     protected Object [] parameterValues;
208
209     /** Flags for bound variables. */
210     protected boolean[] parameterSet;
211
212     /** Flags for bound stream variables. */
213     protected boolean[] parameterStream;
214
215     /** The SQL types of the parameters. */
216     protected int[] parameterTypes;
217
218     /** The (IN, IN OUT, or OUT) modes of parameters */
219     protected int[] parameterModes;
220
221     /** Lengths for streams. */
222     protected int[] streamLengths;
223
224     /** Has a stream or CLOB / BLOB parameter value. */
225     protected boolean hasStreams;
226
227     /**
228      * Description of result set metadata. <p>
229      */
230     protected Result rsmdDescriptor;
231
232     /** Description of parameter metadata. */
233     protected Result pmdDescriptor;
234
235     /** This object's one and one ResultSetMetaData object. */
236     protected jdbcResultSetMetaData rsmd;
237
238 // NOTE: pmd is declared as Object to avoid yet another #ifdef.
239
240     /** This object's one and only ParameterMetaData object. */
241     protected Object pmd;
242
243     /** The SQL character sequence that this object represents. */
244     protected String sql;
245
246     /**
247      * The id with which this object's corresponding
248      * {@link org.hsqldb.CompiledStatement CompiledStatement}
249      * object is registered in the engine's
250      * {@link org.hsqldb.CompiledStatementManager CompiledStatementManager}
251      * object.
252      */
253     protected int statementID;
254
255     /**
256      * Whether this statement generates only a single row update count in
257      * response to execution.
258      */
259     protected boolean isRowCount;
260
261 // fredt@users 20020215 - patch 517028 by peterhudson@users - method defined
262 // fredt@users 20020215 - patch 517028 by peterhudson@users - method defined
263 //
264 // changes by fredt
265 // SimpleDateFormat objects moved out of methods to improve performance
266 // this is safe because only one thread at a time should access a
267 // PreparedStatement object until it has finished executing the statement
268 // fredt@users 20020215 - patch 517028 by peterhudson@users - method defined
269 // minor changes by fredt
270
271     /**
272      * <!-- start generic documentation -->
273      * Sets escape processing on or off. <p>
274      * <!-- end generic documentation -->
275      *
276      * <!-- start release-specific documentation -->
277      * <div class="ReleaseSpecificDocumentation">
278      * <h3>HSQLDB-Specific Information:</h3> <p>
279      *
280      * Since 1.7.0, the implementation follows the standard
281      * behaviour by overriding the same method in jdbcStatement
282      * class. <p>
283      *
284      * In other words, calling this method has no effect.
285      * </div>
286      * <!-- end release-specific documentation -->
287      *
288      * @param enable <code>true</code> to enable escape processing;
289      * <code>false</code> to disable it
290      * @exception SQLException if a database access error occurs
291      */
292     public void setEscapeProcessing(boolean enable) throws SQLException {
293         checkClosed();
294     }
295
296     /**
297      * <!-- start generic documentation -->
298      * Executes the SQL statement in this <code>PreparedStatement</code>
299      * object, which may be any kind of SQL statement.
300      * Some prepared statements return multiple results; the
301      * <code>execute</code> method handles these complex statements as well
302      * as the simpler form of statements handled by the methods
303      * <code>executeQuery</code>and <code>executeUpdate</code>. <p>
304      *
305      * The <code>execute</code> method returns a <code>boolean</code> to
306      * indicate the form of the first result. You must call either the method
307      * <code>getResultSet</code> or <code>getUpdateCount</code>
308      * to retrieve the result; you must call <code>getMoreResults</code> to
309      * move to any subsequent result(s). <p>
310      * <!-- end generic documentation -->
311      *
312      * <!-- start release-specific documentation -->
313      * <div class="ReleaseSpecificDocumentation">
314      * <h3>HSQLDB-Specific Information:</h3> <p>
315      *
316      * Including 1.8.0, prepared statements do not generate
317      * multiple fetchable results. <p>
318      *
319      * In future versions, it will be possible that statements
320      * generate multiple fetchable results under certain conditions.
321      * </div>
322      *
323      * @return <code>true</code> if the first result is a <code>ResultSet</code>
324      * object; <code>false</code> if the first result is an update
325      * count or there is no result
326      * @exception SQLException if a database access error occurs or an argument
327      * is supplied to this method
328      * @see jdbcStatement#execute
329      * @see jdbcStatement#getResultSet
330      * @see jdbcStatement#getUpdateCount
331      * @see jdbcStatement#getMoreResults
332      */
333     public boolean execute() throws SQLException {
334
335         checkClosed();
336         connection.clearWarningsNoCheck();
337
338         resultIn = null;
339
340         try {
341             resultOut.setMaxRows(maxRows);
342             resultOut.setParameterData(parameterValues);
343
344             resultIn = connection.sessionProxy.execute(resultOut);
345         } catch (HsqlException e) {
346             throw Util.sqlException(e);
347         }
348
349         if (resultIn.isError()) {
350             Util.throwError(resultIn);
351         }
352
353         return resultIn.isData();
354     }
355
356     /**
357      * <!-- start generic documentation -->
358      * Executes the SQL query in this <code>PreparedStatement</code> object
359      * and returns the <code>ResultSet</code> object generated by the query.<p>
360      * <!-- end generic documentation -->
361      *
362      * @return a <code>ResultSet</code> object that contains the data produced
363      * by the query; never <code>null</code>
364      * @exception SQLException if a database access error occurs or the SQL
365      * statement does not return a <code>ResultSet</code> object
366      */
367     public ResultSet executeQuery() throws SQLException {
368
369         checkClosed();
370         connection.clearWarningsNoCheck();
371         checkIsRowCount(false);
372         checkParametersSet();
373
374         resultIn = null;
375
376         try {
377             resultOut.setMaxRows(maxRows);
378             resultOut.setParameterData(parameterValues);
379
380             resultIn = connection.sessionProxy.execute(resultOut);
381         } catch (HsqlException e) {
382             throw Util.sqlException(e);
383         }
384
385         if (resultIn.isError()) {
386             Util.throwError(resultIn);
387         } else if (!resultIn.isData()) {
388             String msg = "Expected but did not recieve a result set";
389
390             throw Util.sqlException(Trace.UNEXPECTED_EXCEPTION, msg);
391         }
392
393         return new jdbcResultSet(this, resultIn, connection.connProperties,
394                                  connection.isNetConn);
395     }
396
397     /**
398      * <!-- start generic documentation -->
399      * Executes the SQL statement in this <code>PreparedStatement</code>
400      * object, which must be an SQL <code>INSERT</code>,
401      * <code>UPDATE</code> or <code>DELETE</code> statement; or an SQL
402      * statement that returns nothing, such as a DDL statement.<p>
403      * <!-- end generic documentation -->
404      *
405      * @return either (1) the row count for <code>INSERT</code>,
406      * <code>UPDATE</code>, or <code>DELETE</code>
407      * statements or (2) 0 for SQL statements that
408      * return nothing
409      * @exception SQLException if a database access error occurs or the SQL
410      * statement returns a <code>ResultSet</code> object
411      */
412     public int executeUpdate() throws SQLException {
413
414         checkClosed();
415         connection.clearWarningsNoCheck();
416         checkIsRowCount(true);
417         checkParametersSet();
418
419         resultIn = null;
420
421         try {
422             resultOut.setParameterData(parameterValues);
423
424             resultIn = connection.sessionProxy.execute(resultOut);
425         } catch (HsqlException e) {
426             throw Util.sqlException(e);
427         }
428
429         if (resultIn.isError()) {
430             Util.throwError(resultIn);
431         } else if (resultIn.mode != ResultConstants.UPDATECOUNT) {
432             String msg = "Expected but did not recieve a row update count";
433
434             throw Util.sqlException(Trace.UNEXPECTED_EXCEPTION, msg);
435         }
436
437         return resultIn.getUpdateCount();
438     }
439
440     /**
441      * <!-- start generic documentation -->
442      * Submits a batch of commands to the database for execution and
443      * if all commands execute successfully, returns an array of update counts.
444      * The <code>int</code> elements of the array that is returned are ordered
445      * to correspond to the commands in the batch, which are ordered
446      * according to the order in which they were added to the batch.
447      * The elements in the array returned by the method <code>executeBatch</code>
448      * may be one of the following:
449      * <OL>
450      * <LI>A number greater than or equal to zero -- indicates that the
451      * command was processed successfully and is an update count giving the
452      * number of rows in the database that were affected by the command's
453      * execution
454      * <LI>A value of <code>SUCCESS_NO_INFO</code> -- indicates that the command was
455      * processed successfully but that the number of rows affected is
456      * unknown
457      * <P>
458      * If one of the commands in a batch update fails to execute properly,
459      * this method throws a <code>BatchUpdateException</code>, and a JDBC
460      * driver may or may not continue to process the remaining commands in
461      * the batch. However, the driver's behavior must be consistent with a
462      * particular DBMS, either always continuing to process commands or never
463      * continuing to process commands. If the driver continues processing
464      * after a failure, the array returned by the method
465      * <code>BatchUpdateException.getUpdateCounts</code>
466      * will contain as many elements as there are commands in the batch, and
467      * at least one of the elements will be the following:
468      * <P>
469      * <LI>A value of <code>EXECUTE_FAILED</code> -- indicates that the command failed
470      * to execute successfully and occurs only if a driver continues to
471      * process commands after a command fails
472      * </OL>
473      * <P>
474      * A driver is not required to implement this method.
475      * The possible implementations and return values have been modified in
476      * the Java 2 SDK, Standard Edition, version 1.3 to
477      * accommodate the option of continuing to proccess commands in a batch
478      * update after a <code>BatchUpdateException</code> obejct has been thrown. <p>
479      * <!-- end generic documentation -->
480      *
481      * <!-- start release-specific documentation -->
482      * <div class="ReleaseSpecificDocumentation">
483      * <h3>HSQLDB-Specific Information:</h3> <p>
484      *
485      * Starting with HSQLDB 1.7.2, this feature is supported. <p>
486      *
487      * HSQLDB stops execution of commands in a batch when one of the commands
488      * results in an exception. The size of the returned array equals the
489      * number of commands that were executed successfully.<p>
490      *
491      * When the product is built under the JAVA1 target, an exception
492      * is never thrown and it is the responsibility of the client software to
493      * check the size of the returned update count array to determine if any
494      * batch items failed. To build and run under the JAVA2 target, JDK/JRE
495      * 1.3 or higher must be used.
496      * </div>
497      * <!-- end release-specific documentation -->
498      *
499      * @return an array of update counts containing one element for each
500      * command in the batch. The elements of the array are ordered according
501      * to the order in which commands were added to the batch.
502      * @exception SQLException if a database access error occurs or the
503      * driver does not support batch statements. Throws
504      * {@link java.sql.BatchUpdateException}
505      * (a subclass of <code>java.sql.SQLException</code>) if one of the commands
506      * sent to the database fails to execute properly or attempts to return a
507      * result set.
508      * @since JDK 1.3 (JDK 1.1.x developers: read the new overview
509      * for jdbcStatement)
510      */
511     public int[] executeBatch() throws SQLException {
512
513         if (batchResultOut == null) {
514             batchResultOut = new Result(ResultConstants.BATCHEXECUTE,
515                                         parameterTypes, statementID);
516         }
517
518         return super.executeBatch();
519     }
520
521     /**
522      * <!-- start generic documentation -->
523      * Sets the designated parameter to SQL <code>NULL</code>. <p>
524      *
525      * <B>Note:</B> You must specify the parameter's SQL type.<p>
526      * <!-- end generic documentation -->
527      *
528      * <!-- start release-specific documentation -->
529      * <div class="ReleaseSpecificDocumentation">
530      * <h3>HSQLDB-Specific Information:</h3> <p>
531      *
532      * HSQLDB ignores the sqlType argument.
533      * </div>
534      * <!-- end release-specific documentation -->
535      *
536      * @param paramIndex the first parameter is 1, the second is 2, ...
537      * @param sqlType the SQL type code defined in <code>java.sql.Types</code>
538      * @exception SQLException if a database access error occurs
539      */
540     public void setNull(int paramIndex, int sqlType) throws SQLException {
541         setParameter(paramIndex, null);
542     }
543
544     /**
545      * <!-- start generic documentation -->
546      * Sets the designated parameter to the given Java <code>boolean</code>
547      * value. The driver converts this to an SQL <code>BIT</code> value
548      * when it sends it to the database.<p>
549      * <!-- end generic documentation -->
550      *
551      * <!-- start release-specific documentation -->
552      * <div class="ReleaseSpecificDocumentation">
553      * <h3>HSQLDB-Specific Information:</h3> <p>
554      *
555      * Since 1.7.2, HSQLDB uses the BOOLEAN type instead of BIT, as
556      * per SQL 200n (SQL 3).
557      * </div>
558      * <!-- end release-specific documentation -->
559      *
560      * @param parameterIndex the first parameter is 1, the second is 2, ...
561      * @param x the parameter value
562      * @exception SQLException if a database access error occurs
563      */
564     public void setBoolean(int parameterIndex,
565                            boolean x) throws SQLException {
566
567         Boolean b = x ? Boolean.TRUE
568                       : Boolean.FALSE;
569
570         setParameter(parameterIndex, b);
571     }
572
573     /**
574      * <!-- start generic documentation -->
575      * Sets the designated parameter to the given Java <code>byte</code> value.
576      * The driver converts this to an SQL <code>TINYINT</code> value when
577      * it sends it to the database.<p>
578      * <!-- end generic documentation -->
579      *
580      * @param parameterIndex the first parameter is 1, the second is 2, ...
581      * @param x the parameter value
582      * @exception SQLException if a database access error occurs
583      */
584     public void setByte(int parameterIndex, byte x) throws SQLException {
585         setIntParameter(parameterIndex, x);
586     }
587
588     /**
589      * <!-- start generic documentation -->
590      * Sets the designated parameter to the given Java <code>short</code>
591      * value. The driver converts this to an SQL <code>SMALLINT</code>
592      * value when it sends it to the database.<p>
593      * <!-- end generic documentation -->
594      *
595      * @param parameterIndex the first parameter is 1, the second is 2, ...
596      * @param x the parameter value
597      * @exception SQLException if a database access error occurs
598      */
599     public void setShort(int parameterIndex, short x) throws SQLException {
600         setIntParameter(parameterIndex, x);
601     }
602
603     /**
604      * <!-- start generic documentation -->
605      * Sets the designated parameter to the given Java <code>int</code> value.
606      * The driver converts this to an SQL <code>INTEGER</code> value when
607      * it sends it to the database.<p>
608      * <!-- end generic documentation -->
609      *
610      * @param parameterIndex the first parameter is 1, the second is 2, ...
611      * @param x the parameter value
612      * @exception SQLException if a database access error occurs
613      */
614     public void setInt(int parameterIndex, int x) throws SQLException {
615         setIntParameter(parameterIndex, x);
616     }
617
618     /**
619      * <!-- start generic documentation -->
620      * Sets the designated parameter to the given Java <code>long</code> value.
621      * The driver converts this to an SQL <code>BIGINT</code> value when
622      * it sends it to the database.<p>
623      * <!-- end generic documentation -->
624      *
625      * @param parameterIndex the first parameter is 1, the second is 2, ...
626      * @param x the parameter value
627      * @exception SQLException if a database access error occurs
628      */
629     public void setLong(int parameterIndex, long x) throws SQLException {
630         setLongParameter(parameterIndex, x);
631     }
632
633     /**
634      * <!-- start generic documentation -->
635      * Sets the designated parameter to the given Java <code>float</code> value.
636      * The driver converts this to an SQL <code>FLOAT</code> value when
637      * it sends it to the database.<p>
638      * <!-- end generic documentation -->
639      *
640      * <!-- start release-specific documentation -->
641      * <div class="ReleaseSpecificDocumentation">
642      * <h3>HSQLDB-Specific Information:</h3> <p>
643      *
644      * Since 1.7.1, HSQLDB handles Java positive/negative Infinity
645      * and NaN <code>float</code> values consistent with the Java Language
646      * Specification; these <em>special</em> values are now correctly stored
647      * to and retrieved from the database.
648      * </div>
649      * <!-- start release-specific documentation -->
650      *
651      * @param parameterIndex the first parameter is 1, the second is 2, ...
652      * @param x the parameter value
653      * @exception SQLException if a database access error occurs
654      */
655     public void setFloat(int parameterIndex, float x) throws SQLException {
656         setDouble(parameterIndex, (double) x);
657     }
658
659     /**
660      * <!-- start generic documentation -->
661      * Sets the designated parameter to the given Java <code>double</code> value.
662      * The driver converts this to an SQL <code>DOUBLE</code> value when it
663      * sends it to the database.<p>
664      * <!-- end generic documentation -->
665      *
666      * <!-- start release-specific documentation -->
667      * <div class="ReleaseSpecificDocumentation">
668      * <h3>HSQLDB-Specific Information:</h3> <p>
669      *
670      * Since 1.7.1, HSQLDB handles Java positive/negative Infinity
671      * and NaN <code>double</code> values consistent with the Java Language
672      * Specification; these <em>special</em> values are now correctly stored
673      * to and retrieved from the database.
674      * </div>
675      * <!-- start release-specific documentation -->
676      *
677      * @param parameterIndex the first parameter is 1, the second is 2, ...
678      * @param x the parameter value
679      * @exception SQLException if a database access error occurs
680      */
681     public void setDouble(int parameterIndex, double x) throws SQLException {
682
683         Double d = new Double (x);
684
685         setParameter(parameterIndex, d);
686     }
687
688     /**
689      * <!-- start generic documentation -->
690      * Sets the designated parameter to the given
691      * <code>java.math.BigDecimal</code> value.
692      * The driver converts this to an SQL <code>NUMERIC</code> value when
693      * it sends it to the database.<p>
694      * <!-- end generic documentation -->
695      *
696      * @param parameterIndex the first parameter is 1, the second is 2, ...
697      * @param x the parameter value
698      * @exception SQLException if a database access error occurs
699      */
700     public void setBigDecimal(int parameterIndex,
701                               BigDecimal x) throws SQLException {
702         setParameter(parameterIndex, x);
703     }
704
705     /**
706      * <!-- start generic documentation -->
707      * Sets the designated parameter to the given Java <code>String</code> value.
708      * The driver converts this
709      * to an SQL <code>VARCHAR</code> or <code>LONGVARCHAR</code> value
710      * (depending on the argument's
711      * size relative to the driver's limits on <code>VARCHAR</code> values)
712      * when it sends it to the database.<p>
713      * <!-- end generic documentation -->
714      *
715      * <!-- start release-specific documentation -->
716      * <div class="ReleaseSpecificDocumentation">
717      * <h3>HSQLDB-Specific Information:</h3> <p>
718      *
719      * Including 1.7.2, HSQLDB stores all XXXCHAR values as java.lang.String
720      * objects; there is no appreciable difference between
721      * CHAR, VARCHAR and LONGVARCHAR.
722      * </div>
723      * <!-- start release-specific documentation -->
724      *
725      * @param parameterIndex the first parameter is 1, the second is 2, ...
726      * @param x the parameter value
727      * @exception SQLException if a database access error occurs
728      */
729     public void setString(int parameterIndex, String x) throws SQLException {
730         setParameter(parameterIndex, x);
731     }
732
733     /**
734      * <!-- start generic documentation -->
735      * Sets the designated parameter to the given Java array of bytes.
736      * The driver converts this to an SQL <code>VARBINARY</code> or
737      * <code>LONGVARBINARY</code> (depending on the argument's size relative
738      * to the driver's limits on <code>VARBINARY</code> values) when it
739      * sends it to the database.<p>
740      * <!-- end generic documentation -->
741      *
742      * <!-- start release-specific documentation -->
743      * <div class="ReleaseSpecificDocumentation">
744      * <h3>HSQLDB-Specific Information:</h3> <p>
745      *
746      * Including 1.7.2, HSQLDB stores all XXXBINARY values the same way; there
747      * is no appreciable difference between BINARY, VARBINARY and
748      * LONGVARBINARY.
749      * </div>
750      * <!-- start release-specific documentation -->
751      *
752      * @param paramIndex the first parameter is 1, the second is 2, ...
753      * @param x the parameter value
754      * @exception SQLException if a database access error occurs
755      */
756     public void setBytes(int paramIndex, byte[] x) throws SQLException {
757         setParameter(paramIndex, x);
758     }
759
760     /**
761      * <!-- start generic documentation -->
762      * Sets the designated parameter to the given
763      * <code>java.sql.Date</code> value. The driver converts this
764      * to an SQL <code>DATE</code> value when it sends it to the database.<p>
765      * <!-- end generic documentation -->
766      *
767      * @param parameterIndex the first parameter is 1, the second is 2, ...
768      * @param x the parameter value
769      * @exception SQLException if a database access error occurs
770      */
771     public void setDate(int parameterIndex, Date x) throws SQLException {
772         setParameter(parameterIndex, x);
773     }
774
775     /**
776      * <!-- start generic documentation -->
777      * Sets the designated parameter to the given <code>java.sql.Time</code>
778      * value. The driver converts this to an SQL <code>TIME</code> value when it
779      * sends it to the database.<p>
780      * <!-- end generic documentation -->
781      *
782      * @param parameterIndex the first parameter is 1, the second is 2, ...
783      * @param x the parameter value
784      * @exception SQLException if a database access error occurs
785      */
786     public void setTime(int parameterIndex, Time x) throws SQLException {
787         setParameter(parameterIndex, x);
788     }
789
790     /**
791      * <!-- start generic documentation -->
792      * Sets the designated parameter to the given
793      * <code>java.sql.Timestamp</code> value. The driver converts this to
794      * an SQL <code>TIMESTAMP</code> value when it sends it to the
795      * database.<p>
796      * <!-- end generic documentation -->
797      *
798      * @param parameterIndex the first parameter is 1, the second is 2, ...
799      * @param x the parameter value
800      * @exception SQLException if a database access error occurs
801      */
802     public void setTimestamp(int parameterIndex,
803                              Timestamp x) throws SQLException {
804         setParameter(parameterIndex, x);
805     }
806
807     /**
808      * <!-- start generic documentation -->
809      * Sets the designated parameter to the given input stream, which will have
810      * the specified number of bytes.
811      * When a very large ASCII value is input to a <code>LONGVARCHAR</code>
812      * parameter, it may be more practical to send it via a
813      * <code>java.io.InputStream</code>. Data will be read from the stream
814      * as needed until end-of-file is reached. The JDBC driver will
815      * do any necessary conversion from ASCII to the database char format. <p>
816      *
817      * <b>Note:</b> This stream object can either be a standard
818      * Java stream object or your own subclass that implements the
819      * standard interface.<p>
820      * <!-- end generic documentation -->
821      * <!-- start release-specific documentation -->
822      * <div class="ReleaseSpecificDocumentation">
823      * <h3>HSQLDB-Specific Information:</h3> <p>
824      *
825      * This method uses the default platform character encoding to convert bytes
826      * from the stream into the characters of a String. In the future this is
827      * likely to change to always treat the stream as ASCII.<p>
828      *
829      * Before HSQLDB 1.7.0, <code>setAsciiStream</code> and
830      * <code>setUnicodeStream</code> were identical.
831      * </div>
832      * <!-- end release-specific documentation -->
833      *
834      * @param parameterIndex the first parameter is 1, the second is 2, ...
835      * @param x the Java input stream that contains the ASCII parameter value
836      * @param length the number of bytes in the stream
837      * @exception SQLException if a database access error occurs
838      */
839     public void setAsciiStream(int parameterIndex, java.io.InputStream x,
840                                int length) throws SQLException {
841
842         checkSetParameterIndex(parameterIndex, true);
843
844         String s;
845
846         if (x == null) {
847             s = "input stream is null";
848
849             throw Util.sqlException(Trace.INVALID_JDBC_ARGUMENT, s);
850         }
851
852         try {
853             s = StringConverter.inputStreamToString(x, length);
854
855             setParameter(parameterIndex, s);
856         } catch (IOException e) {
857             throw Util.sqlException(Trace.INVALID_CHARACTER_ENCODING);
858         }
859     }
860
861     /**
862      * <!-- start generic documentation -->
863      * Sets the designated parameter to the given input stream, which
864      * will have the specified number of bytes. A Unicode character has
865      * two bytes, with the first byte being the high byte, and the second
866      * being the low byte.
867      *
868      * When a very large Unicode value is input to a <code>LONGVARCHAR</code>
869      * parameter, it may be more practical to send it via a
870      * <code>java.io.InputStream</code> object. The data will be read from the
871      * stream as needed until end-of-file is reached. The JDBC driver will
872      * do any necessary conversion from Unicode to the database char format.
873      *
874      * <P><B>Note:</B> This stream object can either be a standard
875      * Java stream object or your own subclass that implements the
876      * standard interface.<p>
877      * <!-- end generic documentation -->
878      *
879      * <!-- start release-specific documentation -->
880      * <div class="ReleaseSpecificDocumentation">
881      * <h3>HSQLDB-Specific Information:</h3> <p>
882      *
883      * Since 1.7.0, this method complies with behavior as defined by the
884      * JDBC3 specification.
885      * </div>
886      * <!-- end release-specific documentation -->
887      *
888      * @param parameterIndex the first parameter is 1, the second is 2, ...
889      * @param x a <code>java.io.InputStream</code> object that contains the
890      * Unicode parameter value as two-byte Unicode characters
891      * @param length the number of bytes in the stream
892      * @exception SQLException if a database access error occurs
893      * @deprecated Sun does not include a reason, but presumably
894      * this is because setCharacterStream is now prefered
895      */
896
897 //#ifdef DEPRECATEDJDBC
898 public void setUnicodeStream(int parameterIndex, java.io.InputStream x,
899                                  int length) throws SQLException {
900
901         checkSetParameterIndex(parameterIndex, true);
902
903         String msg = null;
904
905         if (x == null) {
906             msg = "input stream is null";
907         } else if (length % 2 != 0) {
908             msg = "odd length argument";
909         }
910
911         if (msg != null) {
912             throw Util.sqlException(Trace.INVALID_JDBC_ARGUMENT, msg);
913         }
914
915         int chlen = length / 2;
916         int chread = 0;
917         StringBuffer sb = new StringBuffer ();
918         int hi;
919         int lo;
920
921         try {
922             for (; chread < chlen; chread++) {
923                 hi = x.read();
924
925                 if (hi == -1) {
926                     break;
927                 }
928
929                 lo = x.read();
930
931                 if (lo == -1) {
932                     break;
933                 }
934
935                 sb.append((char) (hi << 8 | lo));
936             }
937         } catch (IOException e) {
938             throw Util.sqlException(Trace.TRANSFER_CORRUPTED);
939         }
940
941         setParameter(parameterIndex, sb.toString());
942     }
943
944 //#endif
945
946     /**
947      * <!-- start generic documentation -->
948      * Sets the designated parameter to the given input stream, which will have
949      * the specified number of bytes.
950      * When a very large binary value is input to a <code>LONGVARBINARY</code>
951      * parameter, it may be more practical to send it via a
952      * <code>java.io.InputStream</code> object. The data will be read from the
953      * stream as needed until end-of-file is reached.
954      *
955      * <P><B>Note:</B> This stream object can either be a standard
956      * Java stream object or your own subclass that implements the
957      * standard interface.<p>
958      * <!-- end generic documentation -->
959      *
960      * <!-- start release-specific documentation -->
961      * <div class="ReleaseSpecificDocumentation">
962      * <h3>HSQLDB-Specific Information:</h3> <p>
963      *
964      * Since 1.7.2, this method works according to the standard.
965      * </div>
966      * <!-- end release-specific documentation -->
967      *
968      * @param parameterIndex the first parameter is 1, the second is 2, ...
969      * @param x the java input stream which contains the binary parameter value
970      * @param length the number of bytes in the stream
971      * @exception SQLException if a database access error occurs
972      */
973     public void setBinaryStream(int parameterIndex, java.io.InputStream x,
974                                 int length) throws SQLException {
975
976         checkSetParameterIndex(parameterIndex, true);
977
978         if (x == null) {
979             throw Util.sqlException(Trace.error(Trace.INVALID_JDBC_ARGUMENT,
980