Statement (BlackBerry JDE 7.1.0 API Reference)

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

net.rim.device.api.database
Interface Statement

public interface Statement

The representation of a SQL statement. Here is the lifecycle of a Statement object (a prepared statement):

Creation: via Database.createStatement(java.lang.String) (unless you are executing the Statement with Database.executeStatement(java.lang.String), in which case the preparation is done for you).
Preparation: via Statement.prepare() (unless you are executing the Statement with Database.executeStatement(java.lang.String), in which case the preparation is done for you).
Binding: Optional, to increase performance when running a Statement multiple times with different values.
Execution: If the statement might return results (such as a SELECT statement), execute the Statement by calling Statement.getCursor(), which returns a Cursor. If the statement doesn't return result sets, execute by calling one of the following methods:
- Statement.executeUpdate(java.lang.Object[]) - Use when updating data (with an UPDATE statement) and running the Statement multiple times with bind parameters.
- Statement.executeInsert(java.lang.Object[]) - Use when inserting data (with an INSERT statement) and running the Statement multiple times with bind parameters.
- Statement.execute() - Use when you want to use bind parameters.

Note: If you are not using bind parameters, you do not need to create a Statement object. See Database.executeStatement(java.lang.String).

Using SQL parameters and bind

SQL parameters allow the same statement to be re-used with different literal values in each execution. There are two main ways to number the parameters:

A question mark (?) in the statement causes each parameter to be numbered sequentially, starting from 1.
A question mark followed by an integer (?NNN) in the statement provides each parameter with the number NNN.

When using the executeInsert or executeUpdate methods, you bind parameters right in the method with the bindParams parameter. bindParams takes an array of objects: any combination of null, Integer, Long, Boolean, Float, Double, String, or ByteBuffers.

Here's an example of an INSERT statement using SQL parameters:

 Statement st = d.createStatement("INSERT INTO People(Name, Age) VALUES (?, ?)");
 try
 {
     st.prepare();
     Object[] bindParams = {"John", new Integer (37)};
     long rowID = st.executeInsert(bindParams);
 }
 finally
 {
     st.close();
 }

When using the execute method or getCursor method, you can use the Statement.bind method to provide names for SQL parameters. The bind method takes the number of the parameter and the value to be bound to it. If you use a number outside of the allowed range, a DatabaseException is thrown. All bindings can be reset using Statement.reset.

For more information about the Database API, see the Data Storage Development Guide for BlackBerry Java SDK, available at www.blackberry.com/go/devguides. For more information about SQLite, see www.sqlite.org.

Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 5.0.0

Method Summary
	`void`	`bind(int index, boolean value)` Binds a `boolean` parameter in the Statement; for use with `Statement.execute()`.
	`void`	`bind(int index, byte value)` Binds a `byte` parameter in the Statement; for use with `Statement.execute()`.
	`void`	`bind(int index, byte[] value)` Binds a byte[] parameter in the Statement; for use with `Statement.execute()`.
	`void`	`bind(int index, byte[] value, int offset)` Binds a byte[] parameter in the Statement; for use with `Statement.execute()`.
	`void`	`bind(int index, byte[] value, int offset, int length)` Binds a byte[] parameter in the Statement; for use with `Statement.execute()`.
	`void`	`bind(int index, double value)` Binds a `double` parameter in the Statement; for use with `Statement.execute()`.
	`void`	`bind(int index, float value)` Binds a `float` parameter in the Statement; for use with `Statement.execute()`.
	`void`	`bind(int index, int value)` Binds an `int` parameter in the Statement; for use with `Statement.execute()`.
	`void`	`bind(int index, String value)` Binds a `String` parameter in the Statement; for use with `Statement.execute()`.
	`void`	`bind(int index, long value)` Binds a `long` parameter in the Statement; for use with `Statement.execute()`.
	`void`	`bind(int index, short value)` Binds a `short` parameter in the Statement; for use with `Statement.execute()`.
	`void`	`bindZeroBlob(int index, int length)` Binds a series of null bytes to a parameter in the Statement; for use with `Statement.execute()`.
	`void`	`close()` Closes the current Statement and releases all resources.
	`void`	`execute()` Executes a statement that does not return a result set: INSERT, UPDATE, DELETE, and similar SQL statements.
	`long`	`executeInsert(Object[] bindParams)` Executes an INSERT statement.
	`void`	`executeUpdate(Object[] bindParams)` Executes an UPDATE statement.
	`String[]`	`getColumnNames()` Gets the names of the columns of this Statement.
	`Cursor`	`getCursor()` Executes a query statement and returns a Cursor with selected rows.
	`int`	`getCursorBufferSize()` Returns the number of rows a Cursor will buffer.
	`int`	`getFormalIndex(String paramName)` Converts the named SQL parameter into a parameter index that can be used in `bind()` calls.
	`String`	`getFormalName(int index)` Converts a parameter index to a SQL parameter name.
	`int`	`getIntegers(int[] buffer, int offset, int length, int nullValue)` Copies a column of `int`s into a buffer.
	`int`	`getLongs(long[] buffer, int offset, int length, long nullValue)` Copies a column of `long`s into a buffer.
	`int`	`getParameterCount()` Returns the largest index of all SQL parameters in a Statement, or zero if there are no SQL parameters.
	`String`	`getTail()` Gets the unparsed portion of a prepared statement (the "tail").
	`void`	`prepare()` Prepares a statement for execution.
	`void`	`reset()` Resets a Statement to its state just after `Statement.prepare()` and clears all bindings.
	`void`	`rewind()` Rewinds a Statement to its state just after `Statement.prepare()` but does not clear any bindings.
	`void`	`setCursorBufferSize(int size)` Sets how many rows a Cursor will fetch at a time.

Method Detail

prepare

void prepare()
             throws DatabaseException

Prepares a statement for execution.

Here is an example:

 Statement st = d.createStatement("INSERT INTO x VALUES (1, 2)");
 try 
 {
     st.prepare();
     st.execute();
 } 
 finally 
 {
     st.close();
 }

Throws:: DatabaseException - If the database is closed or a SQL statement has already been prepared.
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 5.0.0

getTail

String getTail()
               throws DatabaseException

Gets the unparsed portion of a prepared statement (the "tail"). This method is useful for multiple statements separated by semicolons (;).

Returns:: The unparsed portion of a prepared statement (the "tail").
Throws:: DatabaseException - If the database is closed or the statement has not been prepared.
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 5.0.0

execute

void execute()
             throws DatabaseException

Executes a statement that does not return a result set: INSERT, UPDATE, DELETE, and similar SQL statements.

Here is an example:

 Statement st = d.createStatement("INSERT INTO x VALUES (1, 2)");
 try 
 {
     st.prepare();
     st.execute();
 } 
 finally 
 {
       st.close();
 }

Throws:: DatabaseException - If there is a problem executing the statement.
See Also:: Statement.getCursor()
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 5.0.0

executeInsert

long executeInsert(Object[] bindParams)
                   throws DatabaseException

Executes an INSERT statement.

The Statement must be prepared before calling this method. The number of parameter elements must match the number of bind parameters in the INSERT statement. Once complete, the ROWID of the newly inserted row is returned. In addition, on completion the bindings are cleared and the Statement is reset, which puts the statement in a state where another call to executeInsert can be made to insert another row.

The following example inserts rows:

 Statement st = d.createStatement("INSERT INTO People(Name, Age) VALUES (?, ?)");
 try
 {
     st.prepare();
     Object[] bindParams = {"John", new Integer (37)};
     long rowID = st.executeInsert(bindParams);
 }
 finally 
 {
     st.close();
 }

Parameters:: bindParams - Optional bind parameters consisting of any combination of: null, byte, short, int, long, boolean, float, double, String, or ByteBuffers
Returns:: The ROWID of the inserted row.
Throws:: DatabaseException - If this Statement hasn't been prepared, or if the number of elements in bindParams is greater than the number of bind variables in the query or there was a problem executing the Statement.
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 7.0.0

executeUpdate

void executeUpdate(Object[] bindParams)
                   throws DatabaseException

Executes an UPDATE statement.

The Statement must be prepared before calling this method. The number of parameter elements must match the number of bind parameters in the UPDATE statement. Once complete, the bindings are cleared and the Statement is reset, which puts the Statement in a state where another call to executeUpdate can be made to update another row.

This method is intended for executing UPDATE statements. If you use it to execute other types of statements, the row ID that is returned will be meaningless.

The following example updates rows:

 Statement st = d.createStatement("UPDATE Account set Balance = ? WHERE AcctNo > ?");
 try
 {
     st.prepare();
     Object[] bindParams = {new Integer (2000), new Integer (100)};
     st.executeUpdate(bindParams);
 }
 finally 
 {
     st.close();
 }

Parameters:: bindParams - Optional bind parameters consisting of any combination of: null, byte, short, int, long, boolean, float, double, String, or ByteBuffers.
Throws:: DatabaseException - If this Statement hasn't been prepared, or if the number of elements in bindParams is greater than the number of bind variables in the query or there was a problem executing the Statement.
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 7.0.0

getCursor

Cursor getCursor()
                 throws DatabaseException

Executes a query statement and returns a Cursor with selected rows.

This method should be called only with statements that return a result set, such as SELECT.

The first call to getCursor() creates a Cursor. Each subsequent call to getCursor() for the same instance of the Statement returns the same Cursor instance. Using reset() on the Statement discards all bound values, and invalidates the current Cursor. A subsequent call to getCursor() allocates a fresh Cursor for the reset Statement.

If the cursor's buffer size has been modified from the default value of 1, then the cursor will fetch size rows of the result set at a time. For large result sets, this can greatly improve performance. The following example returns a Cursor that has buffered up to five rows:

 Statement st = d.createStatement("SELECT Name FROM Account WHERE Location = 'Waterloo'");
 try
 {
     st.prepare();
     st.setCursorBufferSize(5);
     Cursor c = st.getCursor();
 }
 finally 
 {
     st.close();
 }

The returned cursor is positioned before the first row and an attempt to get the current row will fail. Navigate to the first row through the Cursor.first() or Cursor.next() methods.

Returns:: A Cursor to iterate over results from execution.
Throws:: DatabaseException - If the statement is not prepared.
See Also:: Statement.execute()
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 5.0.0

setCursorBufferSize

void setCursorBufferSize(int size)

Sets how many rows a Cursor will fetch at a time. For large result sets, this setting can greatly improve performance.

The number of rows a Cursor will fetch at a time will be at most size rows. The buffer size should be set prior to the call to getCursor(). The default buffer size is 1. Calls to set a buffer size less than 1 will be ignored. The maximum buffer size is 40,000. Calls to set a buffer size greater than 40,000 will be ignored.

The following example returns a Cursor that has buffered up to five rows:

 Statement st = d.createStatement("SELECT Name FROM Account WHERE Location = 'Waterloo'");
 try
 {
     st.prepare();
     st.setCursorBufferSize(5);
     Cursor c = st.getCursor();
 }
 finally
 {
     st.close();
 }

Parameters:: size - The number of result set rows a Cursor will buffer.
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 7.0.0

getCursorBufferSize

int getCursorBufferSize()

Returns the number of rows a Cursor will buffer.

Returns:: The number of result set rows a Cursor will buffer.
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 7.0.0

getIntegers

int getIntegers(int[] buffer,
                int offset,
                int length,
                int nullValue)
                throws DatabaseException

Copies a column of ints into a buffer.

This method is ideal for a SELECT statement where the result set is a single integer column. This method will copy results into the buffer starting at the given offset and copying at most length integers.

The nullValue will be copied into the buffer for every row that has a null integer.

The following example runs a query that returns an integer column of a result set for five rows:

 Statement st = d.createStatement("SELECT accountNumbers FROM Orders");
 try
 {
     st.prepare();
     int[] accountNumbers = new int[5];
     st.getIntegers(accountNumbers, 0, 5, -1);
 }
 finally
 {
     st.close();
 }

Parameters:: buffer - The buffer the results will be copied to.; offset - The offset into the buffer to start copying.; length - The number of records to copy into the buffer.; nullValue - What integer to copy into the buffer to represent null.
Returns:: The number of records copied into the buffer.
Throws:: DatabaseException - If the statement hasn't been prepared; if the result set contains more than a single column; or if there was a problem executing the statement.
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 7.0.0

getLongs

int getLongs(long[] buffer,
             int offset,
             int length,
             long nullValue)
             throws DatabaseException

Copies a column of longs into a buffer.

This method functions like getIntegers() except it works on longs.

The following example runs a query that returns a long column of a result set for five rows:

 Statement st = d.createStatement("SELECT Shares FROM Stocks");
 try
 {
     st.prepare();
     long[] shares = new long[5];
     st.getLongs(shares, 0, 5, -1);
 }
 finally
 {
     st.close();
 }

Parameters:: buffer - The buffer the results will be copied into.; offset - Offset into the buffer to start copying.; length - The number of records to copy into the buffer.; nullValue - What long value to copy into the buffer to represent null in the results.
Returns:: The number of records copied into the buffer.
Throws:: DatabaseException - If this statement hasn't been prepared; if the result set contains more than a single column; or if there was a problem executing the statement.
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 7.0.0

bind

void bind(int index,
          int value)
          throws DatabaseBindingException,
                 DatabaseException

Binds an int parameter in the Statement; for use with Statement.execute().

The bind method is not used with Statement.executeUpdate(java.lang.Object[]) or Statement.executeInsert(java.lang.Object[]).

Parameters:: index - The index of the parameter.; value - The value to bind.
Throws:: DatabaseBindingException - If binding failed.; DatabaseException - If a Statement has not been prepared or is closed, or if the database is closed.
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 5.0.0

bind

void bind(int index,
          long value)
          throws DatabaseBindingException,
                 DatabaseException

Binds a long parameter in the Statement; for use with Statement.execute().

The bind method is not used with Statement.executeUpdate(java.lang.Object[]) or Statement.executeInsert(java.lang.Object[]).

Parameters:: index - Index of the parameter.; value - The value to bind.
Throws:: DatabaseBindingException - If binding failed.; DatabaseException - If a statement has not been prepared or is closed, or if the database is closed.
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 5.0.0

bind

void bind(int index,
          float value)
          throws DatabaseBindingException,
                 DatabaseException

Binds a float parameter in the Statement; for use with Statement.execute().

The bind method is not used with Statement.executeUpdate(java.lang.Object[]) or Statement.executeInsert(java.lang.Object[]).

Parameters:: index - Index of the parameter.; value - The value to bind.
Throws:: DatabaseBindingException - If binding failed.; DatabaseException - If a statement has not been prepared or is closed, or if the database is closed.
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 5.0.0

bind

void bind(int index,
          double value)
          throws DatabaseBindingException,
                 DatabaseException

Binds a double parameter in the Statement; for use with Statement.execute().

The bind method is not used with Statement.executeUpdate(java.lang.Object[]) or Statement.executeInsert(java.lang.Object[]).

Parameters:: index - Index of the parameter.; value - The value to bind.
Throws:: DatabaseBindingException - If binding failed.; DatabaseException - If a Statement has not been prepared or is closed, or if the database is closed.
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 5.0.0

bind

void bind(int index,
          short value)
          throws DatabaseBindingException,
                 DatabaseException

Binds a short parameter in the Statement; for use with Statement.execute().

The bind method is not used with Statement.executeUpdate(java.lang.Object[]) or Statement.executeInsert(java.lang.Object[]).

Parameters:: index - Index of the parameter.; value - The value to bind.
Throws:: DatabaseBindingException - If binding failed.; DatabaseException - If a Statement has not been prepared or is closed, or if the database is closed.
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 5.0.0

bind

void bind(int index,
          byte value)
          throws DatabaseBindingException,
                 DatabaseException

Binds a byte parameter in the Statement; for use with Statement.execute().

The bind method is not used with Statement.executeUpdate(java.lang.Object[]) or Statement.executeInsert(java.lang.Object[]).

Parameters:: index - Index of the parameter.; value - The value to bind.
Throws:: DatabaseBindingException - If binding failed.; DatabaseException - If a Statement has not been prepared or is closed, or if the database is closed.
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 5.0.0

bind

void bind(int index,
          boolean value)
          throws DatabaseBindingException,
                 DatabaseException

Binds a boolean parameter in the Statement; for use with Statement.execute().

The bind method is not used with Statement.executeUpdate(java.lang.Object[]) or Statement.executeInsert(java.lang.Object[]).

true is bound as 1, and false is bound as 0.

Parameters:: index - Index of the parameter.; value - The value to bind.
Throws:: DatabaseBindingException - If binding failed.; DatabaseException - If a Statement has not been prepared or is closed, or if the database is closed.
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 5.0.0

bind

void bind(int index,
          String value)
          throws DatabaseBindingException,
                 DatabaseException

Binds a String parameter in the Statement; for use with Statement.execute().

The bind method is not used with Statement.executeUpdate(java.lang.Object[]) or Statement.executeInsert(java.lang.Object[]).

Parameters:: index - Index of the parameter.; value - The value to bind. null is also allowed.
Throws:: DatabaseBindingException - If binding failed.; DatabaseException - If a Statement has not been prepared or is closed, or if the database is closed.
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 5.0.0

bindZeroBlob

void bindZeroBlob(int index,
                  int length)
                  throws DatabaseBindingException,
                         DatabaseException

Binds a series of null bytes to a parameter in the Statement; for use with Statement.execute().

This method is generally used to reserve space for a blob that is represented by an OutputStream object.

The bindZeroBlob method is not used with Statement.executeUpdate(java.lang.Object[]) or Statement.executeInsert(java.lang.Object[]).

Parameters:: index - Index of the parameter.; length - The number of null bytes to bind.
Throws:: DatabaseBindingException - If binding failed.; DatabaseException - If a statement has not been prepared or is closed, or if the database is closed.
See Also:: Database.createBlobOutputStream(java.lang.String, java.lang.String, long)
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 7.0.0

bind

void bind(int index,
          byte[] value)
          throws DatabaseBindingException,
                 DatabaseException

Binds a byte[] parameter in the Statement; for use with Statement.execute().

The bind method is not used with Statement.executeUpdate(java.lang.Object[]) or Statement.executeInsert(java.lang.Object[]).

Parameters:: index - Index of the parameter.; value - The value to bind. null can also be bound.
Throws:: DatabaseBindingException - If binding failed.; DatabaseException - If a Statement has not been prepared or is closed, or if the database is closed.
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 5.0.0

bind

void bind(int index,
          byte[] value,
          int offset)
          throws DatabaseBindingException,
                 DatabaseException

Binds a byte[] parameter in the Statement; for use with Statement.execute().

The bind method is not used with Statement.executeUpdate(java.lang.Object[]) or Statement.executeInsert(java.lang.Object[]).

Parameters:: index - Index of the parameter.; value - The value to bind. null can also be bound.; offset - The offset from which to bind value[].
Throws:: DatabaseBindingException - If binding failed.; DatabaseException - If a Statement has not been prepared or is closed, or if the database is closed.
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 5.0.0

bind

void bind(int index,
          byte[] value,
          int offset,
          int length)
          throws DatabaseBindingException,
                 DatabaseException

Binds a byte[] parameter in the Statement; for use with Statement.execute().

The bind method is not used with Statement.executeUpdate(java.lang.Object[]) or Statement.executeInsert(java.lang.Object[]).

Parameters:: index - Index of the parameter.; value - The value to bind. null can also be bound.; offset - The offset from which to bind value[].; length - The number of bytes to take from value[].
Throws:: DatabaseBindingException - If binding failed.; DatabaseException - If a Statement has not been prepared or is closed, or if the database is closed.
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 5.0.0

reset

void reset()
           throws DatabaseException

Resets a Statement to its state just after Statement.prepare() and clears all bindings. After a reset, Statement.getCursor() must be called to get a new Cursor.

Throws:: DatabaseException - If the reset does not succeed.
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 5.0.0

rewind

void rewind()
            throws DatabaseException

Rewinds a Statement to its state just after Statement.prepare() but does not clear any bindings.

After a rewind, Statement.getCursor() must be called to get a new Cursor.

Throws:: DatabaseException - If the rewind fails.
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 5.0.0

close

void close()
           throws DatabaseException

Closes the current Statement and releases all resources. After a call to close(), any cursors based on this Statement will fail.

Statements should be closed explicitly to free up resources. It is recommended you close statements in a finally block.

You should close Statements in a way that detects errors. This is recommended because SQLite sometimes does not commit a Statement until the Statement is closed.

The following example closes a Statement so that exceptions are reported.

 Statement st = d.createStatement("INSERT INTO x VALUES (1, 2)");
 try 
 {
     st.prepare();
     st.execute();
 } 
 finally 
 {
     st.close();
 }

Throws:: DatabaseException - Never thrown but is kept for backwards compatibility.
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 5.0.0

getFormalIndex

int getFormalIndex(String paramName)
                   throws DatabaseBindingException,
                          DatabaseException

Converts the named SQL parameter into a parameter index that can be used in bind() calls.

Parameters:: paramName - The name of a SQL parameter.
Returns:: The index of the named SQL parameter.
Throws:: DatabaseBindingException - If no matching parameter is found.; DatabaseException - If a statement has not been prepared or is closed.
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 5.0.0

getFormalName

String getFormalName(int index)
                     throws DatabaseBindingException,
                            DatabaseException

Converts a parameter index to a SQL parameter name.

For getFormalName() to return the parameter name, you must provide a name in the query. For example, when you call getFormalName, the statement "SELECT * FROM T WHERE a = :a" will return :a. When parameters such as a question mark (?) are used as placeholders, the getFormalName() method will not return a parameter name. For example, getFormalName will not return the name for the parameter in this statement: "SELECT * FROM T WHERE a = ?"

Parameters:: index - The index for a SQL parameter.
Returns:: The SQL parameter name for the given index.
Throws:: DatabaseBindingException - If no matching parameter is found, or if the parameter with the given index is an anonymous parameter.; DatabaseException - If a Statement has not been prepared or is closed.
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 5.0.0

getColumnNames

String[] getColumnNames()
                        throws DatabaseException

Gets the names of the columns of this Statement.

Returns:: The column names for the result of the executed SELECT statement.
Throws:: DatabaseException - If a Statement has not been prepared or is closed.
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 5.0.0

getParameterCount

int getParameterCount()
                      throws DatabaseException

Returns the largest index of all SQL parameters in a Statement, or zero if there are no SQL parameters.

The SQL parameters can be numbered arbitrarily if the ?NNN notation is used, in which case gaps might exist in the parameter list.

Returns:: The largest index of all SQL parameters in a Statement, or zero if there are no SQL parameters.
Throws:: DatabaseException - If a Statement has not been prepared or is closed.
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 5.0.0

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

Copyright 1999-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.
Legal

net.rim.device.api.database Interface Statement

Using SQL parameters and bind

prepare

getTail

execute

executeInsert

executeUpdate

getCursor

setCursorBufferSize

getCursorBufferSize

getIntegers

getLongs

bind

bind

bind

bind

bind

bind

bind

bind

bindZeroBlob

bind

bind

bind

reset

rewind

close

getFormalIndex

getFormalName

getColumnNames

getParameterCount

net.rim.device.api.database
Interface Statement