interbase.interclient
Class PreparedStatement

java.lang.Object
  |
  +--interbase.interclient.Statement
        |
        +--interbase.interclient.PreparedStatement

Direct Known Subclasses:

CallableStatement

public class PreparedStatement

extends Statement

implements PreparedStatement

Represents a precompiled SQL statement, possibly parameterized.

A SQL statement is pre-compiled and stored in a PreparedStatement object. This object can then be used to efficiently execute this statement multiple times.

Note: The setXXX methods for setting IN parameter values must specify types that are compatible with the defined SQL type of the input parameter. For instance, if the IN parameter has SQL type Integer then setInt should be used.

If arbitrary parameter type conversions are required then the setObject method should be used with a target SQL type.

Since:

JDBC 1, with extended behavior in JDBC 2

See Also:

Connection.prepareStatement(java.lang.String), ResultSet

Method Summary

void	addBatch() Add a set of parameters to the batch.
void	clearParameters() In general, parameter values remain in force for repeated use of a Statement.
boolean	execute() Some prepared statements return multiple results; the execute method handles these complex statements as well as the simpler form of statements handled by executeQuery and executeUpdate.
ResultSet	executeQuery() A prepared SQL query is executed and its ResultSet is returned.
int	executeUpdate() Execute a SQL INSERT, UPDATE or DELETE statement.
ResultSetMetaData	getMetaData() The number, types and properties of a ResultSet's columns are provided by the getMetaData method.
ParameterMetaData	getParameterMetaData() Get meta data describing the parameters to this prepared statement.
String	getPlan() If this statement was prepared with setPlan enabled then retrieve the plan.
ResultSetMetaData	getResultSetMetaData() Deprecated. deprecated since 1.50, replaced by getMetaData() in JDBC 2.
void	setArray(int i, Array x) Set an Array parameter.
void	setAsciiStream(int parameterIndex, InputStream x, int length) When a very large ASCII value is input to a LONGVARCHAR parameter, it may be more practical to send it via a java.io.InputStream.
void	setBigDecimal(int parameterIndex, BigDecimal x) Set a parameter to a java.lang.BigDecimal value.
void	setBinaryStream(int parameterIndex, InputStream x, int length) When a very large binary value is input to a LONGVARBINARY parameter, it may be more practical to send it via a java.io.InputStream.
void	setBlob(int i, Blob x) Set a BLOB parameter.
void	setBoolean(int parameterIndex, boolean x) Set a parameter to a Java boolean value.
void	setByte(int parameterIndex, byte x) Set a parameter to a Java byte value.
void	setBytes(int parameterIndex, byte[] x) Set a parameter to a Java array of bytes.
void	setCharacterStream(int parameterIndex, Reader reader, int length) When a very large UNICODE value is input to a LONGVARCHAR parameter, it may be more practical to send it via a java.io.Reader.
void	setClob(int i, Clob x) Set a CLOB parameter.
void	setDate(int parameterIndex, Date x) Set a parameter to a java.sql.Date value.
void	setDate(int parameterIndex, Date x, Calendar cal) Set a parameter to a java.sql.Date value.
void	setDouble(int parameterIndex, double x) Set a parameter to a Java double value.
void	setFloat(int parameterIndex, float x) Set a parameter to a Java float value.
void	setInt(int parameterIndex, int x) Set a parameter to a Java int value.
void	setLong(int parameterIndex, long x) Set a parameter to a Java long value.
void	setNull(int parameterIndex, int sqlType) Set a parameter to SQL NULL.
void	setObject(int parameterIndex, Object x) Set the value of a parameter using an object; use the java.lang equivalent objects for integral values.
void	setObject(int parameterIndex, Object x, int targetSQLType) This method is like setObject above, but assumes a scale of zero.
void	setObject(int parameterIndex, Object x, int targetSQLType, int scale) Set the value of a parameter using an object; use the java.lang equivalent objects for integral values.
void	setRef(int i, Ref x) Set a REF(<structured-type>) parameter.
void	setShort(int parameterIndex, short x) Set a parameter to a Java short value.
void	setString(int parameterIndex, String x) Set a parameter to a Java String value.
void	setTime(int parameterIndex, Time x) Set a parameter to a java.sql.Time value.
void	setTime(int parameterIndex, Time x, Calendar cal) Set a parameter to a java.sql.Time value.
void	setTimestamp(int parameterIndex, Timestamp x) Set a parameter to a java.sql.Timestamp value.
void	setTimestamp(int parameterIndex, Timestamp x, Calendar cal) Set a parameter to a java.sql.Timestamp value.
void	setUnicodeStream(int parameterIndex, InputStream x, int length) Deprecated. to be deprecated in future release, replaced by setCharacterStream() in JDBC 2

Methods inherited from class interbase.interclient.Statement

addBatch, cancel, clearBatch, clearWarnings, close, execute, executeBatch, executeQuery, executeUpdate, finalize, getConnection, getFetchDirection, getFetchSize, getMaxFieldSize, getMaxRows, getMoreResults, getQueryTimeout, getResultSet, getResultSetConcurrency, getResultSetType, getUpdateCount, getWarnings, setCursorName, setEscapeProcessing, setFetchDirection, setFetchSize, setMaxFieldSize, setMaxRows, setQueryTimeout

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

executeQuery

public ResultSet executeQuery()
                       throws SQLException

A prepared SQL query is executed and its ResultSet is returned.

Specified by:

executeQuery in interface PreparedStatement

Returns:

a ResultSet that contains the data produced by the query; never null

Throws:

SQLException - if a database access error occurs.

Since:

JDBC 1

executeUpdate

public int executeUpdate()
                  throws SQLException

Execute a SQL INSERT, UPDATE or DELETE statement. In addition, SQL statements that return nothing such as SQL DDL statements can be executed.

Specified by:

executeUpdate in interface PreparedStatement

Returns:

either the row count for INSERT, UPDATE or DELETE; or 0 for SQL statements that return nothing

Throws:

SQLException - if a database access error occurs.

Since:

JDBC 1

setNull

public void setNull(int parameterIndex,
                    int sqlType)
             throws SQLException

Set a parameter to SQL NULL.

Note: You must specify the parameter's SQL type.

Specified by:

setNull in interface PreparedStatement

Parameters:

parameterIndex - the first parameter is 1, the second is 2, ...

sqlType - SQL type code defined by java.sql.Types

Throws:

SQLException - if a database-access error occurs.

Since:

JDBC 1

setBoolean

public void setBoolean(int parameterIndex,
                       boolean x)
                throws SQLException

Set a parameter to a Java boolean value. The driver converts this to a SQL BIT value when it sends it to the database.

Specified by:

setBoolean in interface PreparedStatement

Parameters:

parameterIndex - the first parameter is 1, the second is 2, ...

x - the parameter value

Throws:

SQLException - if a database-access error occurs.

Since:

JDBC 1

setByte

public void setByte(int parameterIndex,
                    byte x)
             throws SQLException

Set a parameter to a Java byte value. The driver converts this to a SQL TINYINT value when it sends it to the database.

Specified by:

setByte in interface PreparedStatement

Parameters:

parameterIndex - the first parameter is 1, the second is 2, ...

x - the parameter value

Throws:

SQLException - if a database access error occurs.

Since:

JDBC 1

setShort

public void setShort(int parameterIndex,
                     short x)
              throws SQLException

Set a parameter to a Java short value. The driver converts this to a SQL SMALLINT value when it sends it to the database.

Specified by:

setShort in interface PreparedStatement

Parameters:

parameterIndex - the first parameter is 1, the second is 2, ...

x - the parameter value

Throws:

SQLException - if a database-access error occurs.

Since:

JDBC 1

setInt

public void setInt(int parameterIndex,
                   int x)
            throws SQLException

Set a parameter to a Java int value. The driver converts this to a SQL INTEGER value when it sends it to the database.

Specified by:

setInt in interface PreparedStatement

Parameters:

parameterIndex - the first parameter is 1, the second is 2, ...

x - the parameter value

Throws:

SQLException - if a database-access error occurs.

Since:

JDBC 1

setLong

public void setLong(int parameterIndex,
                    long x)
             throws SQLException

Set a parameter to a Java long value. The driver converts this to a SQL BIGINT value when it sends it to the database.

Specified by:

setLong in interface PreparedStatement

Parameters:

parameterIndex - the first parameter is 1, the second is 2, ...

x - the parameter value

Throws:

SQLException - if a database access error occurs.

Since:

JDBC 1

setFloat

public void setFloat(int parameterIndex,
                     float x)
              throws SQLException

Set a parameter to a Java float value. The driver converts this to a SQL FLOAT value when it sends it to the database.

Specified by:

setFloat in interface PreparedStatement

Parameters:

parameterIndex - the first parameter is 1, the second is 2, ...

x - the parameter value

Throws:

SQLException - if a database access error occurs.

Since:

JDBC 1

setDouble

public void setDouble(int parameterIndex,
                      double x)
               throws SQLException

Set a parameter to a Java double value. The driver converts this to a SQL DOUBLE value when it sends it to the database.

Specified by:

setDouble in interface PreparedStatement

Parameters:

parameterIndex - the first parameter is 1, the second is 2, ...

x - the parameter value

Throws:

SQLException - if a database access error occurs.

Since:

JDBC 1

setBigDecimal

public void setBigDecimal(int parameterIndex,
                          BigDecimal x)
                   throws SQLException

Set a parameter to a java.lang.BigDecimal value. The driver converts this to a SQL NUMERIC value when it sends it to the database.

Specified by:

setBigDecimal in interface PreparedStatement

Parameters:

parameterIndex - the first parameter is 1, the second is 2, ...

x - the parameter value

Throws:

SQLException - if a database access error occurs.

Since:

JDBC 1

setString

public void setString(int parameterIndex,
                      String x)
               throws SQLException

Set a parameter to a Java String value. The driver converts this to a SQL VARCHAR or LONGVARCHAR value (depending on the arguments size relative to the driver's limits on VARCHARs) when it sends it to the database.

Specified by:

setString in interface PreparedStatement

Parameters:

parameterIndex - the first parameter is 1, the second is 2, ...

x - the parameter value

Throws:

SQLException - if a database access error occurs.

Since:

JDBC 1

setBytes

public void setBytes(int parameterIndex,
                     byte[] x)
              throws SQLException

Set a parameter to a Java array of bytes. The driver converts this to a SQL VARBINARY or LONGVARBINARY (depending on the argument's size relative to the driver's limits on VARBINARYs) when it sends it to the database.

Specified by:

setBytes in interface PreparedStatement

Parameters:

parameterIndex - the first parameter is 1, the second is 2, ...

x - the parameter value

Throws:

SQLException - if a database access error occurs.

Since:

JDBC 1

setDate

public void setDate(int parameterIndex,
                    Date x)
             throws SQLException

Set a parameter to a java.sql.Date value. The driver converts this to a SQL DATE value when it sends it to the database.

Specified by:

setDate in interface PreparedStatement

Parameters:

parameterIndex - the first parameter is 1, the second is 2, ...

x - the parameter value

Throws:

SQLException - if a database access error occurs.

Since:

JDBC 1

setTime

public void setTime(int parameterIndex,
                    Time x)
             throws SQLException

Set a parameter to a java.sql.Time value. The driver converts this to a SQL TIME value when it sends it to the database.

Specified by:

setTime in interface PreparedStatement

Parameters:

parameterIndex - the first parameter is 1, the second is 2, ...

x - the parameter value

Throws:

SQLException - if a database access error occurs.

Since:

JDBC 1

setTimestamp

public void setTimestamp(int parameterIndex,
                         Timestamp x)
                  throws SQLException

Set a parameter to a java.sql.Timestamp value. The driver converts this to a SQL TIMESTAMP value when it sends it to the database.

Specified by:

setTimestamp in interface PreparedStatement

Parameters:

parameterIndex - the first parameter is 1, the second is 2, ...

x - the parameter value

Throws:

SQLException - if a database access error occurs.

Since:

JDBC 1

setAsciiStream

public void setAsciiStream(int parameterIndex,
                           InputStream x,
                           int length)
                    throws SQLException

When a very large ASCII value is input to a LONGVARCHAR parameter, it may be more practical to send it via a java.io.InputStream. JDBC will read the data from the stream as needed, until it reaches end-of-file. The JDBC driver will do any necessary conversion from ASCII to the database char format.

Note: This stream object can either be a standard Java stream object or your own subclass that implements the standard interface.

Specified by:

setAsciiStream in interface PreparedStatement

Parameters:

parameterIndex - the first parameter is 1, the second is 2, ...

x - the java input stream which contains the ASCII parameter value

length - the number of bytes in the stream

Throws:

SQLException - if a database access error occurs.

Since:

JDBC 1

setUnicodeStream

public void setUnicodeStream(int parameterIndex,
                             InputStream x,
                             int length)
                      throws SQLException

Deprecated. to be deprecated in future release, replaced by setCharacterStream() in JDBC 2

When a very large UNICODE value is input to a LONGVARCHAR parameter, it may be more practical to send it via a java.io.InputStream. JDBC will read the data from the stream as needed, until it reaches end-of-file. The JDBC driver will do any necessary conversion from UNICODE to the database char format.

Note: This stream object can either be a standard Java stream object or your own subclass that implements the standard interface.

Specified by:

setUnicodeStream in interface PreparedStatement

Parameters:

parameterIndex - the first parameter is 1, the second is 2, ...

x - the java input stream which contains the UNICODE parameter value

length - the number of bytes in the stream

Throws:

SQLException - if a database access error occurs.

Since:

JDBC 1

See Also:

setCharacterStream(int, java.io.Reader, int)

setBinaryStream

public void setBinaryStream(int parameterIndex,
                            InputStream x,
                            int length)
                     throws SQLException

When a very large binary value is input to a LONGVARBINARY parameter, it may be more practical to send it via a java.io.InputStream. JDBC will read the data from the stream as needed, until it reaches end-of-file.

Note: This stream object can either be a standard Java stream object or your own subclass that implements the standard interface.

Specified by:

setBinaryStream in interface PreparedStatement

Parameters:

parameterIndex - the first parameter is 1, the second is 2, ...

x - the java input stream which contains the binary parameter value

length - the number of bytes in the stream

Throws:

SQLException - if a database access error occurs.

Since:

JDBC 1

clearParameters

public void clearParameters()
                     throws SQLException

In general, parameter values remain in force for repeated use of a Statement. Setting a parameter value automatically clears its previous value. However, in some cases it is useful to immediately release the resources used by the current parameter values; this can be done by calling clearParameters.

Specified by:

clearParameters in interface PreparedStatement

Throws:

SQLException - if a database access error occurs.

Since:

JDBC 1

setObject

public void setObject(int parameterIndex,
                      Object x,
                      int targetSQLType,
                      int scale)
               throws SQLException

Set the value of a parameter using an object; use the java.lang equivalent objects for integral values.

The given Java object will be converted to the targetSqlType before being sent to the database.

JDBC 2 note:

Note that this method may be used to pass database specific abstract data types.

If the object is of a class implementing SQLData, the JDBC driver should call its method writeSQL() to write it to the SQL data stream, else if the object is of a class implementing Ref, Blob, Clob, Struct, or Array then pass it to the database as a value of the corresponding SQL type.

Specified by:

setObject in interface PreparedStatement

Parameters:

parameterIndex - The first parameter is 1, the second is 2, ...

x - The object containing the input parameter value

targetSqlType - The SQL type (as defined in java.sql.Types) to be sent to the database. The scale argument may further qualify this type.

scale - For java.sql.Types.DECIMAL or java.sql.Types.NUMERIC types this is the number of digits after the decimal. For all other types this value will be ignored,

Throws:

SQLException - if a database access error occurs.

Since:

JDBC 1, with extended behavior in JDBC 2

See Also:

java.sql.Types

setObject

public void setObject(int parameterIndex,
                      Object x,
                      int targetSQLType)
               throws SQLException

This method is like setObject above, but assumes a scale of zero.

Specified by:

setObject in interface PreparedStatement

Throws:

SQLException - if a database access error occurs.

Since:

JDBC 1, with extended behavior in JDBC 2

setObject

public void setObject(int parameterIndex,
                      Object x)
               throws SQLException

Set the value of a parameter using an object; use the java.lang equivalent objects for integral values.

The JDBC specification specifies a standard mapping from Java Object types to SQL types. The given argument java object will be converted to the corresponding SQL type before being sent to the database.

Note that this method may be used to pass datatabase specific abstract data types, by using a Driver specific Java type.

JDBC 2 note:

If the object is of a class implementing SQLData, the JDBC driver should call its method writeSQL() to write it to the SQL data stream, else if the object is of a class implementing Ref, Blob, Clob, Struct, or Array then pass it to the database as a value of the corresponding SQL type.

Raise an exception if there is an ambiguity, for example, if the object is of a class implementing more than one of those interfaces.

Specified by:

setObject in interface PreparedStatement

Parameters:

parameterIndex - The first parameter is 1, the second is 2, ...

x - The object containing the input parameter value

Throws:

SQLException - if a database access error occurs.

Since:

JDBC 1, with extended behavior in JDBC 2

execute

public boolean execute()
                throws SQLException

Some prepared statements return multiple results; the execute method handles these complex statements as well as the simpler form of statements handled by executeQuery and executeUpdate.

Specified by:

execute in interface PreparedStatement

Throws:

SQLException - if a database access error occurs.

Since:

JDBC 1

See Also:

Statement.execute(java.lang.String)

addBatch

public void addBatch()
              throws SQLException

Add a set of parameters to the batch.

Specified by:

addBatch in interface PreparedStatement

Throws:

SQLException - if a database access error occurs.

Since:

JDBC 2, not yet supported

See Also:

Statement.addBatch(java.lang.String)

setCharacterStream

public void setCharacterStream(int parameterIndex,
                               Reader reader,
                               int length)
                        throws SQLException

When a very large UNICODE value is input to a LONGVARCHAR parameter, it may be more practical to send it via a java.io.Reader. JDBC will read the data from the stream as needed, until it reaches end-of-file. The JDBC driver will do any necessary conversion from UNICODE to the database char format.

Note: This stream object can either be a standard Java stream object or your own subclass that implements the standard interface.

Specified by:

setCharacterStream in interface PreparedStatement

Parameters:

parameterIndex - the first parameter is 1, the second is 2, ...

x - the java reader which contains the UNICODE data

length - the number of characters in the stream

Throws:

SQLException - if a database access error occurs.

Since:

JDBC 2, not yet supported

setRef

public void setRef(int i,
                   Ref x)
            throws SQLException

Set a REF(<structured-type>) parameter.

Specified by:

setRef in interface PreparedStatement

Parameters:

i - the first parameter is 1, the second is 2, ...

x - an object representing data of an SQL REF Type

Throws:

SQLException - if a database access error occurs.

Since:

JDBC 2, not yet supported

setBlob

public void setBlob(int i,
                    Blob x)
             throws SQLException

Set a BLOB parameter.

Specified by:

setBlob in interface PreparedStatement

Parameters:

i - the first parameter is 1, the second is 2, ...

x - an object representing a BLOB

Since:

JDBC 2, not yet supported

setClob

public void setClob(int i,
                    Clob x)
             throws SQLException

Set a CLOB parameter.

Specified by:

setClob in interface PreparedStatement

Parameters:

i - the first parameter is 1, the second is 2, ...

x - an object representing a CLOB

Throws:

SQLException - if a database access error occurs.

Since:

JDBC 2, not yet supported

setArray

public void setArray(int i,
                     Array x)
              throws SQLException

Set an Array parameter.

Specified by:

setArray in interface PreparedStatement

Parameters:

i - the first parameter is 1, the second is 2, ...

x - an object representing an SQL array

Throws:

SQLException - if a database access error occurs.

Since:

JDBC 2, not yet supported

getMetaData

public ResultSetMetaData getMetaData()
                              throws SQLException

The number, types and properties of a ResultSet's columns are provided by the getMetaData method.

InterClient note: InterClient has provided the capability to get the result set meta data for a prepared statement even before the JDBC 2 specification using getResultSetMetaData(). This provides a means to access result set meta data before the prepared statement is executed (SQL DESCRIBE functionality). Unfortunately, SQL DESCRIBE INPUT functionality does not exist in JDBC 2, but does exist in InterClient using getParameterMetaData().

Specified by:

getMetaData in interface PreparedStatement

Returns:

the description of a ResultSet's columns

Throws:

SQLException - if a database access error occurs.

Since:

JDBC 2, not yet supported

See Also:

getParameterMetaData()

setDate

public void setDate(int parameterIndex,
                    Date x,
                    Calendar cal)
             throws SQLException

Set a parameter to a java.sql.Date value. The driver converts this to a SQL DATE value when it sends it to the database.

Specified by:

setDate in interface PreparedStatement

Parameters:

parameterIndex - the first parameter is 1, the second is 2, ...

x - the parameter value

Throws:

SQLException - if a database access error occurs.

Since:

JDBC 2, not yet supported

setTime

public void setTime(int parameterIndex,
                    Time x,
                    Calendar cal)
             throws SQLException

Set a parameter to a java.sql.Time value. The driver converts this to a SQL TIME value when it sends it to the database.

Specified by:

setTime in interface PreparedStatement

Parameters:

parameterIndex - the first parameter is 1, the second is 2, ...

x - the parameter value

Throws:

SQLException - if a database access error occurs.

Since:

JDBC 2, not yet supported

setTimestamp

public void setTimestamp(int parameterIndex,
                         Timestamp x,
                         Calendar cal)
                  throws SQLException

Set a parameter to a java.sql.Timestamp value. The driver converts this to a SQL TIMESTAMP value when it sends it to the database.

Specified by:

setTimestamp in interface PreparedStatement

Parameters:

parameterIndex - the first parameter is 1, the second is 2, ...

x - the parameter value

Throws:

SQLException - if a database access error occurs.

Since:

JDBC 2, not yet supported

getResultSetMetaData

public ResultSetMetaData getResultSetMetaData()
                                       throws SQLException

Deprecated. deprecated since 1.50, replaced by getMetaData() in JDBC 2.

Get the result set meta data for this prepared statement.

This method has been deprecated since this functionality is now provided by the JDBC 2 method PreparedStatement.getMetaData().

Throws:

SQLException - if a database access error occurs.

Since:

Extension

See Also:

getMetaData()

getParameterMetaData

public ParameterMetaData getParameterMetaData()
                                       throws SQLException

Get meta data describing the parameters to this prepared statement. Essentially, this represents SQL DESCRIBE INPUT functionality.

ParameterMetaData and this method were proposed for inclusion in JDBC 2.0, but not accepted due to lack of underlying support by some database vendors.

Throws:

SQLException - if a database access error occurs.

Since:

Extension

getPlan

public String getPlan()
               throws SQLException

If this statement was prepared with setPlan enabled then retrieve the plan.

The statement must be prepared with setPlan enabled.

Throws:

SQLException - if a database access error occurs.

Since:

Extension, proposed for future release, not yet supported