RJCallableStatementInterface


1   
2   /**
3    * RmiJdbc client/server JDBC Driver
4    * (C) GIE Dyade (Groupe BULL / INRIA Research Center) 1997
5    *
6    * @version     1.0
7    * @author      Pierre-Yves Gibello (pierreyves.gibello@experlog.com)
8    */
9   
10  package org.objectweb.rmijdbc;
11  
12  import java.sql.*;
13  import java.math.BigDecimal  ;
14  import java.util.Calendar  ;
15  
16  /**
17   * <P>CallableStatement is used to execute SQL stored procedures.
18   *
19   * <P>JDBC provides a stored procedure SQL escape that allows stored
20   * procedures to be called in a standard way for all RDBMS's. This
21   * escape syntax has one form that includes a result parameter and one
22   * that does not. If used, the result parameter must be registered as
23   * an OUT parameter. The other parameters may be used for input,
24   * output or both. Parameters are refered to sequentially, by
25   * number. The first parameter is 1.
26   *
27   * <P><CODE>
28   * {?= call <procedure-name>[<arg1>,<arg2>, ...]}<BR>
29   * {call <procedure-name>[<arg1>,<arg2>, ...]}
30   * </CODE>
31   *    
32   * <P>IN parameter values are set using the set methods inherited from
33   * PreparedStatement. The type of all OUT parameters must be
34   * registered prior to executing the stored procedure; their values
35   * are retrieved after execution via the get methods provided here.
36   *
37   * <P>A Callable statement may return a ResultSet or multiple
38   * ResultSets. Multiple ResultSets are handled using operations
39   * inherited from Statement.
40   *
41   * <P>For maximum portability, a call's ResultSets and update counts
42   * should be processed prior to getting the values of output
43   * parameters.
44   *
45   * @see Connection#prepareCall
46   * @see ResultSet 
47   */
48  public interface RJCallableStatementInterface
49  extends RJPreparedStatementInterface {
50  
51    /**
52     * Before executing a stored procedure call, you must explicitly
53     * call registerOutParameter to register the java.sql.Type of each
54     * out parameter.
55     *
56     * <P><B>Note:</B> When reading the value of an out parameter, you
57     * must use the getXXX method whose Java type XXX corresponds to the
58     * parameter's registered SQL type.
59     *
60     * @param parameterIndex the first parameter is 1, the second is 2,...
61     * @param sqlType SQL type code defined by java.sql.Types;
62     * for parameters of type Numeric or Decimal use the version of
63     * registerOutParameter that accepts a scale value
64     * @see Type 
65     */
66    void registerOutParameter(int parameterIndex, int sqlType)
67    throws java.rmi.RemoteException  , SQLException;
68  
69    /**
70     * Use this version of registerOutParameter for registering
71     * Numeric or Decimal out parameters.
72     *
73     * <P><B>Note:</B> When reading the value of an out parameter, you
74     * must use the getXXX method whose Java type XXX corresponds to the
75     * parameter's registered SQL type.
76     *
77     * @param parameterIndex the first parameter is 1, the second is 2, ...
78     * @param sqlType use either java.sql.Type.NUMERIC or java.sql.Type.DECIMAL
79     * @param scale a value greater than or equal to zero representing the 
80     *              desired number of digits to the right of the decimal point
81     * @see Type 
82     */
83    void registerOutParameter(int parameterIndex, int sqlType, int scale)
84    throws java.rmi.RemoteException  , SQLException;
85  
86    /**
87     * An OUT parameter may have the value of SQL NULL; wasNull reports 
88     * whether the last value read has this special value.
89     *
90     * <P><B>Note:</B> You must first call getXXX on a parameter to
91     * read its value and then call wasNull() to see if the value was
92     * SQL NULL.
93     *
94     * @return true if the last parameter read was SQL NULL 
95     */
96    boolean wasNull() throws java.rmi.RemoteException  , SQLException;
97  
98    /**
99     * Get the value of a CHAR, VARCHAR, or LONGVARCHAR parameter as a Java String.
100    *
101    * @param parameterIndex the first parameter is 1, the second is 2, ...
102    * @return the parameter value; if the value is SQL NULL, the result is null
103    */
104   String   getString(int parameterIndex)
105   throws java.rmi.RemoteException  , SQLException;
106 
107   /**
108    * Get the value of a BIT parameter as a Java boolean.
109    *
110    * @param parameterIndex the first parameter is 1, the second is 2, ...
111    * @return the parameter value; if the value is SQL NULL, the result is false
112    */
113   boolean getBoolean(int parameterIndex)
114   throws java.rmi.RemoteException  , SQLException;
115 
116   /**
117    * Get the value of a TINYINT parameter as a Java byte.
118    *
119    * @param parameterIndex the first parameter is 1, the second is 2, ...
120    * @return the parameter value; if the value is SQL NULL, the result is 0
121    */
122   byte getByte(int parameterIndex)
123   throws java.rmi.RemoteException  , SQLException;
124 
125   /**
126    * Get the value of a SMALLINT parameter as a Java short.
127    *
128    * @param parameterIndex the first parameter is 1, the second is 2, ...
129    * @return the parameter value; if the value is SQL NULL, the result is 0
130    */
131   short getShort(int parameterIndex)
132   throws java.rmi.RemoteException  , SQLException;
133 
134   /**
135    * Get the value of an INTEGER parameter as a Java int.
136    *
137    * @param parameterIndex the first parameter is 1, the second is 2, ...
138    * @return the parameter value; if the value is SQL NULL, the result is 0
139    */
140   int getInt(int parameterIndex)
141   throws java.rmi.RemoteException  , SQLException;
142 
143   /**
144    * Get the value of a BIGINT parameter as a Java long.
145    *
146    * @param parameterIndex the first parameter is 1, the second is 2, ...
147    * @return the parameter value; if the value is SQL NULL, the result is 0
148    */
149   long getLong(int parameterIndex)
150   throws java.rmi.RemoteException  , SQLException;
151 
152   /**
153    * Get the value of a FLOAT parameter as a Java float.
154    *
155    * @param parameterIndex the first parameter is 1, the second is 2, ...
156    * @return the parameter value; if the value is SQL NULL, the result is 0
157    */
158   float getFloat(int parameterIndex)
159   throws java.rmi.RemoteException  , SQLException;
160 
161   /**
162    * Get the value of a DOUBLE parameter as a Java double.
163    *
164    * @param parameterIndex the first parameter is 1, the second is 2, ...
165    * @return the parameter value; if the value is SQL NULL, the result is 0
166    */
167   double getDouble(int parameterIndex)
168   throws java.rmi.RemoteException  , SQLException;
169 
170   /**
171    * Get the value of a NUMERIC parameter as a java.math.BigDecimal object.
172    *
173    * @param parameterIndex the first parameter is 1, the second is 2, ...
174    * @param scale a value greater than or equal to zero representing the 
175    *              desired number of digits to the right of the decimal point
176    * @return the parameter value; if the value is SQL NULL, the result is null
177    */
178   java.math.BigDecimal   getBigDecimal(int parameterIndex, int scale)
179   throws java.rmi.RemoteException  , SQLException;
180 
181   /**
182    * Get the value of a SQL BINARY or VARBINARY parameter as a Java byte[]
183    *
184    * @param parameterIndex the first parameter is 1, the second is 2, ...
185    * @return the parameter value; if the value is SQL NULL, the result is null
186    */
187   byte[] getBytes(int parameterIndex)
188   throws java.rmi.RemoteException  , SQLException;
189 
190   /**
191    * Get the value of a SQL DATE parameter as a java.sql.Date object
192    *
193    * @param parameterIndex the first parameter is 1, the second is 2, ...
194    * @return the parameter value; if the value is SQL NULL, the result is null
195    */
196   java.sql.Date   getDate(int parameterIndex)
197   throws java.rmi.RemoteException  , SQLException;
198 
199   /**
200    * Get the value of a SQL TIME parameter as a java.sql.Time object.
201    *
202    * @param parameterIndex the first parameter is 1, the second is 2, ...
203    * @return the parameter value; if the value is SQL NULL, the result is null
204    */
205   java.sql.Time   getTime(int parameterIndex)
206   throws java.rmi.RemoteException  , SQLException;
207 
208   /**
209    * Get the value of a SQL TIMESTAMP parameter as a java.sql.Timestamp object.
210    *
211    * @param parameterIndex the first parameter is 1, the second is 2, ...
212    * @return the parameter value; if the value is SQL NULL, the result is null
213    */
214   java.sql.Timestamp   getTimestamp(int parameterIndex)
215   throws java.rmi.RemoteException  , SQLException;
216 
217   //----------------------------------------------------------------------
218   // Advanced features:
219 
220 
221   /**
222    * Get the value of a parameter as a Java object.
223    *
224    * <p>This method returns a Java object whose type coresponds to the SQL
225    * type that was registered for this parameter using registerOutParameter.
226    *
227    * <p>Note that this method may be used to read
228    * datatabase-specific, abstract data types. This is done by
229    * specifying a targetSqlType of java.sql.types.OTHER, which
230    * allows the driver to return a database-specific Java type.
231    *
232    * @param parameterIndex The first parameter is 1, the second is 2, ...
233    * @return A java.lang.Object holding the OUT parameter value.
234    * @see Types 
235    */
236   Object   getObject(int parameterIndex)
237   throws java.rmi.RemoteException  , SQLException;
238 
239     //--------------------------JDBC 2.0-----------------------------
240 
241     /**
242      * JDBC 2.0
243      *
244      * Gets the value of a JDBC <code>NUMERIC</code> parameter as a 
245      * <code>java.math.BigDecimal</code> object with as many digits to the
246      * right of the decimal point as the value contains.
247      * @param parameterIndex the first parameter is 1, the second is 2,
248      * and so on
249      * @return the parameter value in full precision.  If the value is 
250      * SQL NULL, the result is <code>null</code>. 
251      * @exception SQLException if a database access error occurs
252      */
253     BigDecimal   getBigDecimal(int parameterIndex) throws java.rmi.RemoteException  , SQLException;
254 
255     /**
256      * JDBC 2.0
257      *
258      * Returns an object representing the value of OUT parameter 
259      * <code>i</code> and uses <code>map</code> for the custom
260      * mapping of the parameter value.
261      * <p>
262      * This method returns a Java object whose type corresponds to the
263      * JDBC type that was registered for this parameter using the method
264      * <code>registerOutParameter</code>.  By registering the target
265      * JDBC type as <code>java.sql.Types.OTHER</code>, this method can
266      * be used to read database-specific abstract data types.  
267      * @param i the first parameter is 1, the second is 2, and so on
268      * @param map the mapping from SQL type names to Java classes
269      * @return a java.lang.Object holding the OUT parameter value.
270      * @exception SQLException if a database access error occurs
271      */
272      Object    getObject (int i, java.util.Map   map) throws java.rmi.RemoteException  , SQLException;
273 
274     /**
275      * JDBC 2.0
276      *
277      * Gets the value of a JDBC <code>REF(&lt;structured-type&gt;)</code>
278      * parameter as a {@link Ref} object in the Java programming language.
279      * @param i the first parameter is 1, the second is 2, 
280      * and so on
281      * @return the parameter value as a <code>Ref</code> object in the
282      * Java programming language.  If the value was SQL NULL, the value
283      * <code>null</code> is returned.
284      * @exception SQLException if a database access error occurs
285      */
286      RJRefInterface getRef(int i)
287          throws java.rmi.RemoteException  , SQLException;
288 
289     /**
290      * JDBC 2.0
291      *
292      * Gets the value of a JDBC <code>BLOB</code> parameter as a
293      * {@link Blob} object in the Java programming language.
294      * @param i the first parameter is 1, the second is 2, and so on
295      * @return the parameter value as a <code>Blob</code> object in the
296      * Java programming language.  If the value was SQL NULL, the value
297      * <code>null</code> is returned.
298      * @exception SQLException if a database access error occurs
299      */
300      RJBlobInterface getBlob(int i)
301          throws java.rmi.RemoteException  , SQLException;
302 
303     /**
304      * JDBC 2.0
305      *
306      * Gets the value of a JDBC <code>CLOB</code> parameter as a
307      * <code>Clob</code> object in the Java programming language.
308      * @param i the first parameter is 1, the second is 2, and
309      * so on
310      * @return the parameter value as a <code>Clob</code> object in the
311      * Java programming language.  If the value was SQL NULL, the
312      * value <code>null</code> is returned.
313      * @exception SQLException if a database access error occurs
314      */
315      RJClobInterface getClob (int i)
316          throws java.rmi.RemoteException  , SQLException;
317 
318     /**
319      * JDBC 2.0
320      *
321      * Gets the value of a JDBC <code>ARRAY</code> parameter as an
322      * {@link Array} object in the Java programming language.
323      * @param i the first parameter is 1, the second is 2, and 
324      * so on
325      * @return the parameter value as an <code>Array</code> object in
326      * the Java programming language.  If the value was SQL NULL, the
327      * value <code>null</code> is returned.
328      * @exception SQLException if a database access error occurs
329      */
330      RJArrayInterface getArray (int i)
331          throws java.rmi.RemoteException  , SQLException;
332 
333     /**
334      * Gets the value of a JDBC <code>DATE</code> parameter as a 
335      * <code>java.sql.Date</code> object, using
336      * the given <code>Calendar</code> object
337      * to construct the date.
338      * With a <code>Calendar</code> object, the driver
339      * can calculate the date taking into account a custom timezone and locale.
340      * If no <code>Calendar</code> object is specified, the driver uses the
341      * default timezone and locale.
342      *
343      * @param parameterIndex the first parameter is 1, the second is 2, 
344      * and so on
345      * @param cal the <code>Calendar</code> object the driver will use
346      *            to construct the date
347      * @return the parameter value.  If the value is SQL NULL, the result is 
348      * <code>null</code>.
349      * @exception SQLException if a database access error occurs
350      */
351     java.sql.Date   getDate(int parameterIndex, Calendar   cal) 
352     throws java.rmi.RemoteException  , SQLException;
353 
354     /**
355      * Gets the value of a JDBC <code>TIME</code> parameter as a 
356      * <code>java.sql.Time</code> object, using
357      * the given <code>Calendar</code> object
358      * to construct the time.
359      * With a <code>Calendar</code> object, the driver
360      * can calculate the time taking into account a custom timezone and locale.
361      * If no <code>Calendar</code> object is specified, the driver uses the
362      * default timezone and locale.
363      *
364      * @param parameterIndex the first parameter is 1, the second is 2,
365      * and so on
366      * @param cal the <code>Calendar</code> object the driver will use
367      *            to construct the time
368      * @return the parameter value; if the value is SQL NULL, the result is 
369      * <code>null</code>.
370      * @exception SQLException if a database access error occurs
371      */
372     java.sql.Time   getTime(int parameterIndex, Calendar   cal) 
373     throws java.rmi.RemoteException  , SQLException;
374 
375     /**
376      * Gets the value of a JDBC <code>TIMESTAMP</code> parameter as a
377      * <code>java.sql.Timestamp</code> object, using
378      * the given <code>Calendar</code> object to construct
379      * the <code>Timestamp</code> object.
380      * With a <code>Calendar</code> object, the driver
381      * can calculate the timestamp taking into account a custom timezone and locale.
382      * If no <code>Calendar</code> object is specified, the driver uses the
383      * default timezone and locale.
384      *
385      *
386      * @param parameterIndex the first parameter is 1, the second is 2, 
387      * and so on
388      * @param cal the <code>Calendar</code> object the driver will use
389      *            to construct the timestamp
390      * @return the parameter value.  If the value is SQL NULL, the result is 
391      * <code>null</code>.
392      * @exception SQLException if a database access error occurs
393      */
394     java.sql.Timestamp   getTimestamp(int parameterIndex, Calendar   cal) 
395     throws java.rmi.RemoteException  , SQLException;
396 
397 
398     /**
399      * JDBC 2.0
400      *
401      * Registers the designated output parameter.  This version of 
402      * the method <code>registerOutParameter</code>
403      * should be used for a user-named or REF output parameter.  Examples
404      * of user-named types include: STRUCT, DISTINCT, JAVA_OBJECT, and
405      * named array types.
406      *
407      * Before executing a stored procedure call, you must explicitly
408      * call <code>registerOutParameter</code> to register the type from
409      * <code>java.sql.Types</code> for each
410      * OUT parameter.  For a user-named parameter the fully-qualified SQL
411      * type name of the parameter should also be given, while a REF
412      * parameter requires that the fully-qualified type name of the
413      * referenced type be given.  A JDBC driver that does not need the
414      * type code and type name information may ignore it.   To be portable,
415      * however, applications should always provide these values for
416      * user-named and REF parameters.
417      *
418      * Although it is intended for user-named and REF parameters,
419      * this method may be used to register a parameter of any JDBC type.
420      * If the parameter does not have a user-named or REF type, the
421      * typeName parameter is ignored.
422      *
423      * <P><B>Note:</B> When reading the value of an out parameter, you
424      * must use the <code>getXXX</code> method whose Java type XXX corresponds to the
425      * parameter's registered SQL type.
426      *
427      * @param parameterIndex the first parameter is 1, the second is 2,...
428      * @param sqlType a value from {@link java.sql.Types}
429      * @param typeName the fully-qualified name of an SQL structured type
430      * @exception SQLException if a database-access error occurs
431      * @see Types
432      */
433     void registerOutParameter (int paramIndex, int sqlType, String   typeName)
434     throws java.rmi.RemoteException  , SQLException;
435 
436 
437   //--------------------------JDBC 3.0-----------------------------
438 
439     /**
440      * Registers the OUT parameter named 
441      * <code>parameterName</code> to the JDBC type 
442      * <code>sqlType</code>.  All OUT parameters must be registered
443      * before a stored procedure is executed.
444      * <p>
445      * The JDBC type specified by <code>sqlType</code> for an OUT
446      * parameter determines the Java type that must be used
447      * in the <code>get</code> method to read the value of that parameter.
448      * <p>
449      * If the JDBC type expected to be returned to this output parameter
450      * is specific to this particular database, <code>sqlType</code>
451      * should be <code>java.sql.Types.OTHER</code>.  The method 
452      * {@link #getObject} retrieves the value.
453      * @param parameterName the name of the parameter
454      * @param sqlType the JDBC type code defined by <code>java.sql.Types</code>.
455      * If the parameter is of JDBC type <code>NUMERIC</code>
456      * or <code>DECIMAL</code>, the version of
457      * <code>registerOutParameter</code> that accepts a scale value 
458      * should be used.
459      * @exception SQLException if a database access error occurs
460      * @since 1.4
461      * @see Types 
462      */
463     void registerOutParameter(String   parameterName, int sqlType)
464     throws java.rmi.RemoteException  , SQLException;
465 
466     /**
467      * Registers the parameter named 
468      * <code>parameterName</code> to be of JDBC type
469      * <code>sqlType</code>.  This method must be called
470      * before a stored procedure is executed.
471      * <p>
472      * The JDBC type specified by <code>sqlType</code> for an OUT
473      * parameter determines the Java type that must be used
474      * in the <code>get</code> method to read the value of that parameter.
475      * <p>
476      * This version of <code>registerOutParameter</code> should be
477      * used when the parameter is of JDBC type <code>NUMERIC</code>
478      * or <code>DECIMAL</code>.
479      * @param parameterName the name of the parameter
480      * @param sqlType SQL type code defined by <code>java.sql.Types</code>.
481      * @param scale the desired number of digits to the right of the
482      * decimal point.  It must be greater than or equal to zero.
483      * @exception SQLException if a database access error occurs
484      * @since 1.4
485      * @see Types 
486      */
487     void registerOutParameter(String   parameterName, int sqlType, int scale)
488     throws java.rmi.RemoteException  , SQLException;
489 
490     /**
491      * Registers the designated output parameter.  This version of 
492      * the method <code>registerOutParameter</code>
493      * should be used for a user-named or REF output parameter.  Examples
494      * of user-named types include: STRUCT, DISTINCT, JAVA_OBJECT, and
495      * named array types.
496      *
497      * Before executing a stored procedure call, you must explicitly
498      * call <code>registerOutParameter</code> to register the type from
499      * <code>java.sql.Types</code> for each
500      * OUT parameter.  For a user-named parameter the fully-qualified SQL
501      * type name of the parameter should also be given, while a REF
502      * parameter requires that the fully-qualified type name of the
503      * referenced type be given.  A JDBC driver that does not need the
504      * type code and type name information may ignore it.   To be portable,
505      * however, applications should always provide these values for
506      * user-named and REF parameters.
507      *
508      * Although it is intended for user-named and REF parameters,
509      * this method may be used to register a parameter of any JDBC type.
510      * If the parameter does not have a user-named or REF type, the
511      * typeName parameter is ignored.
512      *
513      * <P><B>Note:</B> When reading the value of an out parameter, you
514      * must use the <code>getXXX</code> method whose Java type XXX corresponds to the
515      * parameter's registered SQL type.
516      *
517      * @param parameterName the name of the parameter
518      * @param sqlType a value from {@link java.sql.Types}
519      * @param typeName the fully-qualified name of an SQL structured type
520      * @exception SQLException if a database access error occurs
521      * @see Types
522      * @since 1.4
523      */
524     void registerOutParameter (String   parameterName, int sqlType, String   typeName)
525     throws java.rmi.RemoteException  , SQLException;
526 
527     /**
528      * Retrieves the value of the designated JDBC <code>DATALINK</code> parameter as a
529      * <code>java.net.URL</code> object.
530      * 
531      * @param parameterIndex the first parameter is 1, the second is 2,...
532      * @return a <code>java.net.URL</code> object that represents the 
533      *         JDBC <code>DATALINK</code> value used as the designated
534      *         parameter
535      * @exception SQLException if a database access error occurs,
536      *            or if the URL being returned is
537      *            not a valid URL on the Java platform
538      * @see #setURL
539      * @since 1.4
540      */
541     java.net.URL   getURL(int parameterIndex) throws java.rmi.RemoteException  , SQLException;
542 
543     /**
544      * Sets the designated parameter to the given <code>java.net.URL</code> object.
545      * The driver converts this to an SQL <code>DATALINK</code> value when
546      * it sends it to the database.
547      *
548      * @param parameterName the name of the parameter
549      * @param val the parameter value
550      * @exception SQLException if a database access error occurs,
551      *            or if a URL is malformed
552      * @see #getURL
553      * @since 1.4
554      */
555     void setURL(String   parameterName, java.net.URL   val) throws java.rmi.RemoteException  , SQLException;
556     
557     /**
558      * Sets the designated parameter to SQL <code>NULL</code>.
559      *
560      * <P><B>Note:</B> You must specify the parameter's SQL type.
561      *
562      * @param parameterName the name of the parameter
563      * @param sqlType the SQL type code defined in <code>java.sql.Types</code>
564      * @exception SQLException if a database access error occurs
565      * @since 1.4
566      */
567     void setNull(String   parameterName, int sqlType) throws java.rmi.RemoteException  , SQLException;
568 
569     /**
570      * Sets the designated parameter to the given Java <code>boolean</code> value.
571      * The driver converts this
572      * to an SQL <code>BIT</code> value when it sends it to the database.
573      *
574      * @param parameterName the name of the parameter
575      * @param x the parameter value
576      * @exception SQLException if a database access error occurs
577      * @see #getBoolean
578      * @since 1.4
579      */
580     void setBoolean(String   parameterName, boolean x) throws java.rmi.RemoteException  , SQLException;
581 
582     /**
583      * Sets the designated parameter to the given Java <code>byte</code> value.  
584      * The driver converts this
585      * to an SQL <code>TINYINT</code> value when it sends it to the database.
586      *
587      * @param parameterName the name of the parameter
588      * @param x the parameter value
589      * @exception SQLException if a database access error occurs
590      * @see #getByte
591      * @since 1.4
592      */
593     void setByte(String   parameterName, byte x) throws java.rmi.RemoteException  , SQLException;
594 
595     /**
596      * Sets the designated parameter to the given Java <code>short</code> value. 
597      * The driver converts this
598      * to an SQL <code>SMALLINT</code> value when it sends it to the database.
599      *
600      * @param parameterName the name of the parameter
601      * @param x the parameter value
602      * @exception SQLException if a database access error occurs
603      * @see #getShort
604      * @since 1.4
605      */
606     void setShort(String   parameterName, short x) throws java.rmi.RemoteException  , SQLException;
607 
608     /**
609      * Sets the designated parameter to the given Java <code>int</code> value.  
610      * The driver converts this
611      * to an SQL <code>INTEGER</code> value when it sends it to the database.
612      *
613      * @param parameterName the name of the parameter
614      * @param x the parameter value
615      * @exception SQLException if a database access error occurs
616      * @see #getInt
617      * @since 1.4
618      */
619     void setInt(String   parameterName, int x) throws java.rmi.RemoteException  , SQLException;
620 
621     /**
622      * Sets the designated parameter to the given Java <code>long</code> value. 
623      * The driver converts this
624      * to an SQL <code>BIGINT</code> value when it sends it to the database.
625      *
626      * @param parameterName the name of the parameter
627      * @param x the parameter value
628      * @exception SQLException if a database access error occurs
629      * @see #getLong
630      * @since 1.4
631      */
632     void setLong(String   parameterName, long x) throws java.rmi.RemoteException  , SQLException;
633 
634     /**
635      * Sets the designated parameter to the given Java <code>float</code> value. 
636      * The driver converts this
637      * to an SQL <code>FLOAT</code> value when it sends it to the database.
638      *
639      * @param parameterName the name of the parameter
640      * @param x the parameter value
641      * @exception SQLException if a database access error occurs
642      * @see #getFloat
643      * @since 1.4
644      */
645     void setFloat(String   parameterName, float x) throws java.rmi.RemoteException  , SQLException;
646 
647     /**
648      * Sets the designated parameter to the given Java <code>double</code> value.  
649      * The driver converts this
650      * to an SQL <code>DOUBLE</code> value when it sends it to the database.
651      *
652      * @param parameterName the name of the parameter
653      * @param x the parameter value
654      * @exception SQLException if a database access error occurs
655      * @see #getDouble
656      * @since 1.4
657      */
658     void setDouble(String   parameterName, double x) throws java.rmi.RemoteException  , SQLException;
659 
660     /**
661      * Sets the designated parameter to the given
662      * <code>java.math.BigDecimal</code> value.  
663      * The driver converts this to an SQL <code>NUMERIC</code> value when
664      * it sends it to the database.
665      *
666      * @param parameterName the name of the parameter
667      * @param x the parameter value
668      * @exception SQLException if a database access error occurs
669      * @see #getBigDecimal
670      * @since 1.4
671      */
672     void setBigDecimal(String   parameterName, BigDecimal   x) throws java.rmi.RemoteException  , SQLException;
673 
674     /**
675      * Sets the designated parameter to the given Java <code>String</code> value. 
676      * The driver converts this
677      * to an SQL <code>VARCHAR</code> or <code>LONGVARCHAR</code> value
678      * (depending on the argument's
679      * size relative to the driver's limits on <code>VARCHAR</code> values)
680      * when it sends it to the database.
681      *
682      * @param parameterName the name of the parameter
683      * @param x the parameter value
684      * @exception SQLException if a database access error occurs
685      * @see #getString
686      * @since 1.4
687      */
688     void setString(String   parameterName, String   x) throws java.rmi.RemoteException  , SQLException;
689 
690     /**
691      * Sets the designated parameter to the given Java array of bytes.  
692      * The driver converts this to an SQL <code>VARBINARY</code> or 
693      * <code>LONGVARBINARY</code> (depending on the argument's size relative 
694      * to the driver's limits on <code>VARBINARY</code> values) when it sends 
695      * it to the database.
696      *
697      * @param parameterName the name of the parameter
698      * @param x the parameter value 
699      * @exception SQLException if a database access error occurs
700      * @see #getBytes
701      * @since 1.4
702      */
703     void setBytes(String   parameterName, byte x[]) throws java.rmi.RemoteException  , SQLException;
704 
705     /**
706      * Sets the designated parameter to the given <code>java.sql.Date</code> value.  
707      * The driver converts this
708      * to an SQL <code>DATE</code> value when it sends it to the database.
709      *
710      * @param parameterName the name of the parameter
711      * @param x the parameter value
712      * @exception SQLException if a database access error occurs
713      * @see #getDate
714      * @since 1.4
715      */
716     void setDate(String   parameterName, java.sql.Date   x)
717     throws java.rmi.RemoteException  , SQLException;
718 
719     /**
720      * Sets the designated parameter to the given <code>java.sql.Time</code> value.  
721      * The driver converts this
722      * to an SQL <code>TIME</code> value when it sends it to the database.
723      *
724      * @param parameterName the name of the parameter
725      * @param x the parameter value
726      * @exception SQLException if a database access error occurs
727      * @see #getTime
728      * @since 1.4
729      */
730     void setTime(String   parameterName, java.sql.Time   x) 
731     throws java.rmi.RemoteException  , SQLException;
732 
733     /**
734      * Sets the designated parameter to the given <code>java.sql.Timestamp</code> value.  
735      * The driver
736      * converts this to an SQL <code>TIMESTAMP</code> value when it sends it to the
737      * database.
738      *
739      * @param parameterName the name of the parameter
740      * @param x the parameter value 
741      * @exception SQLException if a database access error occurs
742      * @see #getTimestamp
743      * @since 1.4
744      */
745     void setTimestamp(String   parameterName, java.sql.Timestamp   x)
746     throws java.rmi.RemoteException  , SQLException;
747 
748     /**
749      * Sets the designated parameter to the given input stream, which will have 
750      * the specified number of bytes.
751      * When a very large ASCII value is input to a <code>LONGVARCHAR</code>
752      * parameter, it may be more practical to send it via a
753      * <code>java.io.InputStream</code>. Data will be read from the stream
754      * as needed until end-of-file is reached.  The JDBC driver will
755      * do any necessary conversion from ASCII to the database char format.
756      * 
757      * <P><B>Note:</B> This stream object can either be a standard
758      * Java stream object or your own subclass that implements the
759      * standard interface.
760      *
761      * @param parameterName the name of the parameter
762      * @param x the Java input stream that contains the ASCII parameter value
763      * @param length the number of bytes in the stream 
764      * @exception SQLException if a database access error occurs
765      * @since 1.4
766      */
767     void setAsciiStream(String   parameterName, java.io.InputStream   x, int length)
768     throws java.rmi.RemoteException  , SQLException;
769 
770     /**
771      * Sets the designated parameter to the given input stream, which will have 
772      * the specified number of bytes.
773      * When a very large binary value is input to a <code>LONGVARBINARY</code>
774      * parameter, it may be more practical to send it via a
775      * <code>java.io.InputStream</code> object. The data will be read from the stream
776      * as needed until end-of-file is reached.
777      * 
778      * <P><B>Note:</B> This stream object can either be a standard
779      * Java stream object or your own subclass that implements the
780      * standard interface.
781      *
782      * @param parameterName the name of the parameter
783      * @param x the java input stream which contains the binary parameter value
784      * @param length the number of bytes in the stream 
785      * @exception SQLException if a database access error occurs
786      * @since 1.4
787      */
788     void setBinaryStream(String   parameterName, java.io.InputStream   x, 
789              int length) throws java.rmi.RemoteException  , SQLException;
790 
791     /**
792      * Sets the value of the designated parameter with the given object. The second
793      * argument must be an object type; for integral values, the
794      * <code>java.lang</code> equivalent objects should be used.
795      *
796      * <p>The given Java object will be converted to the given targetSqlType
797      * before being sent to the database.
798      *
799      * If the object has a custom mapping (is of a class implementing the 
800      * interface <code>SQLData</code>),
801      * the JDBC driver should call the method <code>SQLData.writeSQL</code> to write it 
802      * to the SQL data stream.
803      * If, on the other hand, the object is of a class implementing
804      * <code>Ref</code>, <code>Blob</code>, <code>Clob</code>, <code>Struct</code>, 
805      * or <code>Array</code>, the driver should pass it to the database as a 
806      * value of the corresponding SQL type.
807      * <P>
808      * Note that this method may be used to pass datatabase-
809      * specific abstract data types. 
810      *
811      * @param parameterName the name of the parameter
812      * @param x the object containing the input parameter value
813      * @param targetSqlType the SQL type (as defined in java.sql.Types) to be 
814      * sent to the database. The scale argument may further qualify this type.
815      * @param scale for java.sql.Types.DECIMAL or java.sql.Types.NUMERIC types,
816      *          this is the number of digits after the decimal point.  For all other
817      *          types, this value will be ignored.
818      * @exception SQLException if a database access error occurs
819      * @see Types
820      * @see #getObject
821      * @since 1.4 
822      */
823     void setObject(String   parameterName, Object   x, int targetSqlType, int scale)
824     throws java.rmi.RemoteException  , SQLException;
825 
826     /**
827      * Sets the value of the designated parameter with the given object.
828      * This method is like the method <code>setObject</code>
829      * above, except that it assumes a scale of zero.
830      *
831      * @param parameterName the name of the parameter
832      * @param x the object containing the input parameter value
833      * @param targetSqlType the SQL type (as defined in java.sql.Types) to be 
834      *                      sent to the database
835      * @exception SQLException if a database access error occurs
836      * @see #getObject
837      * @since 1.4
838      */
839     void setObject(String   parameterName, Object   x, int targetSqlType) 
840     throws java.rmi.RemoteException  , SQLException;
841 
842     /**
843      * Sets the value of the designated parameter with the given object. 
844      * The second parameter must be of type <code>Object</code>; therefore, the
845      * <code>java.lang</code> equivalent objects should be used for built-in types.
846      *
847      * <p>The JDBC specification specifies a standard mapping from
848      * Java <code>Object</code> types to SQL types.  The given argument 
849      * will be converted to the corresponding SQL type before being
850      * sent to the database.
851      *
852      * <p>Note that this method may be used to pass datatabase-
853      * specific abstract data types, by using a driver-specific Java
854      * type.
855      *
856      * If the object is of a class implementing the interface <code>SQLData</code>,
857      * the JDBC driver should call the method <code>SQLData.writeSQL</code>
858      * to write it to the SQL data stream.
859      * If, on the other hand, the object is of a class implementing
860      * <code>Ref</code>, <code>Blob</code>, <code>Clob</code>, <code>Struct</code>, 
861      * or <code>Array</code>, the driver should pass it to the database as a 
862      * value of the corresponding SQL type.
863      * <P>
864      * This method throws an exception if there is an ambiguity, for example, if the
865      * object is of a class implementing more than one of the interfaces named above.
866      *
867      * @param parameterName the name of the parameter
868      * @param x the object containing the input parameter value 
869      * @exception SQLException if a database access error occurs or if the given
870      *            <code>Object</code> parameter is ambiguous
871      * @see #getObject
872      * @since 1.4
873      */
874     void setObject(String   parameterName, Object   x) throws java.rmi.RemoteException  , SQLException;
875    
876 
877     /**
878      * Sets the designated parameter to the given <code>Reader</code>
879      * object, which is the given number of characters long.
880      * When a very large UNICODE value is input to a <code>LONGVARCHAR</code>
881      * parameter, it may be more practical to send it via a
882      * <code>java.io.Reader</code> object. The data will be read from the stream
883      * as needed until end-of-file is reached.  The JDBC driver will
884      * do any necessary conversion from UNICODE to the database char format.
885      * 
886      * <P><B>Note:</B> This stream object can either be a standard
887      * Java stream object or your own subclass that implements the
888      * standard interface.
889      *
890      * @param parameterName the name of the parameter
891      * @param reader the <code>java.io.Reader</code> object that
892      *        contains the UNICODE data used as the designated parameter
893      * @param length the number of characters in the stream 
894      * @exception SQLException if a database access error occurs
895      * @since 1.4
896      */
897     void setCharacterStream(String   parameterName,
898                 java.io.Reader   reader,
899                 int length) throws java.rmi.RemoteException  , SQLException;
900 
901     /**
902      * Sets the designated parameter to the given <code>java.sql.Date</code> value,
903      * using the given <code>Calendar</code> object.  The driver uses
904      * the <code>Calendar</code> object to construct an SQL <code>DATE</code> value,
905      * which the driver then sends to the database.  With a
906      * a <code>Calendar</code> object, the driver can calculate the date
907      * taking into account a custom timezone.  If no
908      * <code>Calendar</code> object is specified, the driver uses the default
909      * timezone, which is that of the virtual machine running the application.
910      *
911      * @param parameterName the name of the parameter
912      * @param x the parameter value
913      * @param cal the <code>Calendar</code> object the driver will use
914      *            to construct the date
915      * @exception SQLException if a database access error occurs
916      * @see #getDate
917      * @since 1.4
918      */
919     void setDate(String   parameterName, java.sql.Date   x, Calendar   cal)
920     throws java.rmi.RemoteException  , SQLException;
921 
922     /**
923      * Sets the designated parameter to the given <code>java.sql.Time</code> value,
924      * using the given <code>Calendar</code> object.  The driver uses
925      * the <code>Calendar</code> object to construct an SQL <code>TIME</code> value,
926      * which the driver then sends to the database.  With a
927      * a <code>Calendar</code> object, the driver can calculate the time
928      * taking into account a custom timezone.  If no
929      * <code>Calendar</code> object is specified, the driver uses the default
930      * timezone, which is that of the virtual machine running the application.
931      *
932      * @param parameterName the name of the parameter
933      * @param x the parameter value
934      * @param cal the <code>Calendar</code> object the driver will use
935      *            to construct the time
936      * @exception SQLException if a database access error occurs
937      * @see #getTime
938      * @since 1.4
939      */
940     void setTime(String   parameterName, java.sql.Time   x, Calendar   cal) 
941     throws