Overview | Package | Class | Tree | Deprecated | Index | Help

2.01.05
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## interbase.interclient
Class Statement

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

All Implemented Interfaces:
  Statement

Direct Known Subclasses:
  PreparedStatement

public class Statement
extends Object
implements Statement

A SQL container used for executing SQL, and a factory for result sets.

A Statement object is used for executing a static SQL statement and obtaining the results produced by it.

Only one ResultSet per Statement can be open at any point in time. Therefore, if the reading of one ResultSet is interleaved with the reading of another, each must have been generated by different Statements. All statement execute methods implicitly close a statment's current ResultSet if an open one exists.

Since:
  JDBC 1, with extended behavior in JDBC 2
See Also:
  `Connection.createStatement()`, `ResultSet`

Method Summary
`void` | `addBatch(String sql)` Adds a SQL command to the current batch of commmands for the statement.
`void` | `cancel()` Cancel can be used by one thread to cancel a statement that is being executed by another thread.
`void` | `clearBatch()` Make the set of commands in the current batch empty.
`void` | `clearWarnings()` After this call, getWarnings returns null until a new warning is reported for this Statement.
`void` | `close()` In many cases, it is desirable to immediately release a Statement's database and JDBC resources instead of waiting for this to happen when it is automatically closed; the close method provides this immediate release.
`boolean` | `execute(String sql)` Execute a SQL statement that may return multiple results.
`int[]` | `executeBatch()` Submit a batch of commands to the database for execution.
`ResultSet` | `executeQuery(String sql)` Execute a SQL statement that returns a single ResultSet.
`int` | `executeUpdate(String sql)` Execute a SQL INSERT, UPDATE or DELETE statement.
`protected void` | `finalize()` A statement will be closed when its finalizer is called by the garbage collector.
`Connection` | `getConnection()` Returns the Connection that produced this Statement.
`int` | `getFetchDirection()` Determine the fetch direction.
`int` | `getFetchSize()` Determine the default fetch size.
`int` | `getMaxFieldSize()` The maxFieldSize limit (in bytes) is the maximum amount of data returned for any column value; it only applies to BINARY, VARBINARY, LONGVARBINARY, CHAR, VARCHAR, and LONGVARCHAR columns.
`int` | `getMaxRows()` The maxRows limit is the maximum number of rows that a ResultSet can contain.
`boolean` | `getMoreResults()` getMoreResults moves to a Statement's next result.
`int` | `getQueryTimeout()` The queryTimeout limit is the number of seconds the driver will wait for a Statement to execute.
`ResultSet` | `getResultSet()` getResultSet returns the current result as a ResultSet.
`int` | `getResultSetConcurrency()` Determine the result set concurrency.
`int` | `getResultSetType()` Determine the result set type.
`int` | `getUpdateCount()` getUpdateCount returns the current result as an update count; if the result is a ResultSet or there are no more results, -1 is returned.
`SQLWarning` | `getWarnings()` The first warning reported by calls on this Statement is returned.
`void` | `setCursorName(String cursorName)` setCursorname defines the SQL cursor name that will be used by subsequent Statement execute methods.
`void` | `setEscapeProcessing(boolean enable)` If escape scanning is on (the default), the driver will do escape substitution before sending the SQL to the database.
`void` | `setFetchDirection(int direction)` Give a hint as to the direction in which the rows in a result set will be processed.
`void` | `setFetchSize(int rows)` Give the JDBC driver a hint as to the number of rows that should be fetched from the database when more rows are needed.
`void` | `setMaxFieldSize(int maxFieldSize)` The maxFieldSize limit (in bytes) is set to limit the size of data that can be returned for any column value; it only applies to BINARY, VARBINARY, LONGVARBINARY, CHAR, VARCHAR, and LONGVARCHAR fields.
`void` | `setMaxRows(int maxRows)` The maxRows limit is set to limit the number of rows that any ResultSet can contain.
`void` | `setQueryTimeout(int seconds)` The queryTimeout limit is the number of seconds the driver will wait for a Statement to execute.

Methods inherited from class java.lang.Object
`clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Method Detail

### finalize

    protected void finalize()
                     throws Throwable

  A statement will be closed when its finalizer is called by the garbage collector. However, there is no guarantee that the garbage collector will ever run, and in general will not run when an application terminates abruptly without closing its resources.

  Therefore, it is recommended that prepared statements be explicitly closed even if your application throws an exception. This can be achieved by placing a call to close() in a finally clause of your application as follows

       try {
         ...
       }
       finally {
         if (statement != null)
           try { statement.close (); } catch (SQLException e) {}
         if (connection != null)
           try { connection.close (); } catch (SQLException e) {}
       }

  Or alternatively, use the System.runFinalizersOnExit () method.

  Overrides:
    `finalize` in class `Object`
  Since:
    Extension

### executeQuery

    public ResultSet executeQuery(String sql)
                           throws SQLException

  Execute a SQL statement that returns a single ResultSet.
  Specified by:
    `executeQuery` in interface `Statement`
  Parameters:
    `sql` - typically this is a static SQL SELECT statement
  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(String sql)
                      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 `Statement`
  Parameters:
    `sql` - a SQL INSERT, UPDATE or DELETE statement or a SQL statement that returns nothing
  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

### close

    public void close()
               throws SQLException

  In many cases, it is desirable to immediately release a Statement's database and JDBC resources instead of waiting for this to happen when it is automatically closed; the close method provides this immediate release.

  Note: A Statement is automatically closed when it is garbage collected. When a Statement is closed, its current ResultSet, if one exists, is also closed.

  Specified by:
    `close` in interface `Statement`
  Throws:
    `SQLException` - if a database access error occurs.
  Since:
    JDBC 1

### getMaxFieldSize

    public int getMaxFieldSize()
                        throws SQLException

  The maxFieldSize limit (in bytes) is the maximum amount of data returned for any column value; it only applies to BINARY, VARBINARY, LONGVARBINARY, CHAR, VARCHAR, and LONGVARCHAR columns. If the limit is exceeded, the excess data is silently discarded.
  Specified by:
    `getMaxFieldSize` in interface `Statement`
  Returns:
    the current max column size limit; zero means unlimited
  Throws:
    `SQLException` - if a database access error occurs.
  Since:
    JDBC 1

### setMaxFieldSize

    public void setMaxFieldSize(int maxFieldSize)
                         throws SQLException

  The maxFieldSize limit (in bytes) is set to limit the size of data that can be returned for any column value; it only applies to BINARY, VARBINARY, LONGVARBINARY, CHAR, VARCHAR, and LONGVARCHAR fields. If the limit is exceeded, the excess data is silently discarded. For maximum portability use values greater than 256.
  Specified by:
    `setMaxFieldSize` in interface `Statement`
  Parameters:
    `max` - the new max column size limit; zero means unlimited
  Throws:
    `SQLException` - if a database access error occurs.
  Since:
    JDBC 1

### getMaxRows

    public int getMaxRows()
                   throws SQLException

  The maxRows limit is the maximum number of rows that a ResultSet can contain. If the limit is exceeded, the excess rows are silently dropped.
  Specified by:
    `getMaxRows` in interface `Statement`
  Returns:
    the current max row limit; zero means unlimited
  Throws:
    `SQLException` - if a database access error occurs.
  Since:
    JDBC 1

### setMaxRows

    public void setMaxRows(int maxRows)
                    throws SQLException

  The maxRows limit is set to limit the number of rows that any ResultSet can contain. If the limit is exceeded, the excess rows are silently dropped.
  Specified by:
    `setMaxRows` in interface `Statement`
  Parameters:
    `max` - the new max rows limit; zero means unlimited
  Throws:
    `SQLException` - if a database access error occurs.
  Since:
    JDBC 1

### setEscapeProcessing

    public void setEscapeProcessing(boolean enable)
                             throws SQLException

  If escape scanning is on (the default), the driver will do escape substitution before sending the SQL to the database. Note: Since prepared statements have usually been parsed prior to making this call, disabling escape processing for prepared statements will likely have no affect.
  Specified by:
    `setEscapeProcessing` in interface `Statement`
  Parameters:
    `enable` - true to enable; false to disable
  Throws:
    `SQLException` - if a database access error occurs.
  Since:
    JDBC 1

### getQueryTimeout

    public int getQueryTimeout()
                        throws SQLException

  The queryTimeout limit is the number of seconds the driver will wait for a Statement to execute. If the limit is exceeded, a SQLException is thrown.
  Specified by:
    `getQueryTimeout` in interface `Statement`
  Returns:
    the current query timeout limit in seconds; zero means unlimited
  Throws:
    `SQLException` - if a database access error occurs.
  Since:
    JDBC 1

### setQueryTimeout

    public void setQueryTimeout(int seconds)
                         throws SQLException

  The queryTimeout limit is the number of seconds the driver will wait for a Statement to execute. If the limit is exceeded, a SQLException is thrown.

  InterClient note: Throws DriverNotCapableException. InterBase does not support asynchronous query timeout or cancel.

  Specified by:
    `setQueryTimeout` in interface `Statement`
  Parameters:
    `seconds` - the new query timeout limit in seconds; zero means unlimited
  Throws:
    `SQLException` - if a database access error occurs.
  Since:
    JDBC 1, not yet supported

### cancel

    public void cancel()
                throws SQLException

  Cancel can be used by one thread to cancel a statement that is being executed by another thread.

  InterClient note: Throws DriverNotCapableException. InterBase does not support asynchronous query timeout or cancel.

  Specified by:
    `cancel` in interface `Statement`
  Throws:
    `SQLException` - if a database access error occurs.
  Since:
    JDBC 1, not yet supported

### getWarnings

    public SQLWarning getWarnings()
                           throws SQLException

  The first warning reported by calls on this Statement is returned. A Statment's execute methods clear its SQLWarning chain. Subsequent Statement warnings will be chained to this SQLWarning.

  The warning chain is automatically cleared each time a statement is (re)executed.

  Note: If you are processing a ResultSet then any warnings associated with ResultSet reads will be chained on the ResultSet object.

  Specified by:
    `getWarnings` in interface `Statement`
  Returns:
    the first SQLWarning or null
  Throws:
    `SQLException` - if a database access error occurs.
  Since:
    JDBC 1

### clearWarnings

    public void clearWarnings()
                       throws SQLException

  After this call, getWarnings returns null until a new warning is reported for this Statement.
  Specified by:
    `clearWarnings` in interface `Statement`
  Throws:
    `SQLException` - if a database access error occurs.
  Since:
    JDBC 1

### setCursorName

    public void setCursorName(String cursorName)
                       throws SQLException

  setCursorname defines the SQL cursor name that will be used by subsequent Statement execute methods. This name can then be used in SQL positioned update/delete statements to identify the current row in the ResultSet generated by this statement. If the database doesn't support positioned update/delete, this method is a noop. To insure that a cursor has the proper isolation level to support update, the cursor's select statement should be of the form 'select for update ...'. If the 'for update' clause is omitted the positioned updates may fail.

  Note: By definition, positioned update/delete execution must be done by a different Statement than the one which generated the ResultSet being used for positioning. Also, cursor names must be unique within a Connection.

  Specified by:
    `setCursorName` in interface `Statement`
  Parameters:
    `name` - the new cursor name.
  Throws:
    `SQLException` - if a database access error occurs.
  Since:
    JDBC 1

### execute

    public boolean execute(String sql)
                    throws SQLException

  Execute a SQL statement that may return multiple results. Under some (uncommon) situations a single SQL statement may return multiple result sets and/or update counts. Normally you can ignore this, unless you're executing a stored procedure that you know may return multiple results, or unless you're dynamically executing an unknown SQL string. The "execute", "getMoreResults", "getResultSet" and "getUpdateCount" methods let you navigate through multiple results. The "execute" method executes a SQL statement and indicates the form of the first result. You can then use getResultSet or getUpdateCount to retrieve the result, and getMoreResults to move to any subsequent result(s).
  Specified by:
    `execute` in interface `Statement`
  Parameters:
    `sql` - any SQL statement
  Returns:
    true if the next result is a ResultSet; false if it is an update count or there are no more results
  Throws:
    `SQLException` - if a database access error occurs.
  Since:
    JDBC 1
  See Also:
    `getResultSet()`, `getUpdateCount()`, `getMoreResults()`

### getResultSet

    public ResultSet getResultSet()
                           throws SQLException

  getResultSet returns the current result as a ResultSet. It should only be called once per result.
  Specified by:
    `getResultSet` in interface `Statement`
  Returns:
    the current result as a ResultSet; null if the result is an update count or there are no more results
  Throws:
    `SQLException` - if a database access error occurs.
  Since:
    JDBC 1
  See Also:
    `execute(java.lang.String)`

### getUpdateCount

    public int getUpdateCount()
                       throws SQLException

  getUpdateCount returns the current result as an update count; if the result is a ResultSet or there are no more results, -1 is returned. It should only be called once per result.
  Specified by:
    `getUpdateCount` in interface `Statement`
  Returns:
    the current result as an update count; -1 if it is a ResultSet or there are no more results
  Throws:
    `SQLException` - if a database access error occurs.
  Since:
    JDBC 1
  See Also:
    `execute(java.lang.String)`

### getMoreResults

    public boolean getMoreResults()
                           throws SQLException

  getMoreResults moves to a Statement's next result. It returns true if this result is a ResultSet. getMoreResults also implicitly closes any current ResultSet obtained with getResultSet. There are no more results when (!getMoreResults() && (getUpdateCount() == -1)
  Specified by:
    `getMoreResults` in interface `Statement`
  Returns:
    true if the next result is a ResultSet; false if it is an update count or there are no more results
  Throws:
    `SQLException` - if a database access error occurs.
  Since:
    JDBC 1
  See Also:
    `execute(java.lang.String)`

### setFetchDirection

    public void setFetchDirection(int direction)
                           throws SQLException

  Give a hint as to the direction in which the rows in a result set will be processed. The hint applies only to result sets created using this Statement object. The default value is ResultSet.FETCH_FORWARD.
  Specified by:
    `setFetchDirection` in interface `Statement`
  Parameters:
    `direction` - the initial direction for processing rows
  Throws:
    `SQLException` - if a database access error occurs or direction is not one of ResultSet.FETCH_FORWARD, ResultSet.FETCH_REVERSE, or ResultSet.FETCH_UNKNOWN
  Since:
    JDBC 2, not yet supported

### getFetchDirection

    public int getFetchDirection()
                          throws SQLException

  Determine the fetch direction.
  Specified by:
    `getFetchDirection` in interface `Statement`
  Returns:
    the default fetch direction
  Throws:
    `SQLException` - if a database access error occurs.
  Since:
    JDBC 2, not yet supported

### setFetchSize

    public void setFetchSize(int rows)
                      throws SQLException

  Give the JDBC driver a hint as to the number of rows that should be fetched from the database when more rows are needed. The number of rows specified only affects result sets created using this statement. If the value specified is zero, then the hint is ignored. The default value is zero.

  InterClient note: The default of zero lets the driver decide. By default, InterClient prefetches as many rows as can fill up a 128K buffer.

  Specified by:
    `setFetchSize` in interface `Statement`
  Parameters:
    `rows` - the number of rows to fetch
  Throws:
    `SQLException` - if a database access error occurs, or the condition 0 <= rows <= this.getMaxRows() is not satisfied.
  Since:
    JDBC 2, since InterClient 1.50

### getFetchSize

    public int getFetchSize()
                     throws SQLException

  Determine the default fetch size.
  Specified by:
    `getFetchSize` in interface `Statement`
  Throws:
    `SQLException` - if a database access error occurs.
  Since:
    JDBC 2, not yet supported

### getResultSetConcurrency

    public int getResultSetConcurrency()
                                throws SQLException

  Determine the result set concurrency.
  Specified by:
    `getResultSetConcurrency` in interface `Statement`
  Throws:
    `SQLException` - if a database access error occurs.
  Since:
    JDBC 2, not yet supported

### getResultSetType

    public int getResultSetType()
                         throws SQLException

  Determine the result set type.
  Specified by:
    `getResultSetType` in interface `Statement`
  Throws:
    `SQLException` - if a database access error occurs.
  Since:
    JDBC 2, not yet supported

### addBatch

    public void addBatch(String sql)
                  throws SQLException

  Adds a SQL command to the current batch of commmands for the statement. This method is optional.
  Specified by:
    `addBatch` in interface `Statement`
  Parameters:
    `sql` - typically this is a static SQL INSERT or UPDATE statement
  Throws:
    `SQLException` - if a database access error occurs, or the driver does not support batch statements
  Since:
    JDBC 2, not yet supported

### clearBatch

    public void clearBatch()
                    throws SQLException

  Make the set of commands in the current batch empty. This method is optional.
  Specified by:
    `clearBatch` in interface `Statement`
  Throws:
    `SQLException` - if a database access error occurs, or the driver does not support batch statements
  Since:
    JDBC 2, not yet supported

### executeBatch

    public int[] executeBatch()
                       throws SQLException

  Submit a batch of commands to the database for execution. This method is optional.
  Specified by:
    `executeBatch` in interface `Statement`
  Returns:
    an array of update counts containing one element for each command in the batch. The array is ordered according to the order in which commands were inserted into the batch
  Throws:
    `SQLException` - if a database access error occurs, or the driver does not support batch statements
  Since:
    JDBC 2, not yet supported

### getConnection

    public Connection getConnection()
                             throws SQLException

  Returns the Connection that produced this Statement.
  Specified by:
    `getConnection` in interface `Statement`
  Throws:
    `SQLException` - if a database access error occurs.
  Since:
    JDBC 2, since InterClient 1.50

Overview | Package | Class | Tree | Deprecated | Index | Help

2.01.05
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Send comments or suggestions to interclient@borland.com