Class com.ibm.db.CallableStatement
java.lang.Object
|
+----com.ibm.db.Statement
|
+----com.ibm.db.SelectStatement
|
+----com.ibm.db.CallableStatement
- public class CallableStatement
- extends SelectStatement
CallableStatement represents an SQL statement that can be used to execute a stored procedure.
- See Also:
- Statement
Constructor Index
- CallableStatement()
- Constructs a new CallableStatement.
- CallableStatement(boolean)
- Constructs a new CallableStatement.
Method Index
- addPropertyChangeListener(PropertyChangeListener)
- Adds a listener to the PropertyChange event set.
- cancelExecution()
- Cancels execution of the SQL statement which is associated with
this CallableStatement.
- close()
- Applies any changes in the current row of the current Select Result to the
database, and then closes the result set and the statement.
- execute()
- Executes the SQL CALL statement and, if any result sets were produced, positions to the
first row in the first result set.
- firstResult()
- Applies any changes in the current row of the current result set to the database,
and then positions to the first result set (if any result sets were returned).
- getCacheResultAt(int)
- Returns the SelectResult at the specified index.
- getCurrentResult()
- Returns the index of the current result set.
- getCurrentResultInCache()
- Returns the index in the cache of the current result set.
- getMaximumResultsInCache()
- Returns the maximum number of result sets the cache can contain at one time.
- getMetaData()
- Returns the StatementMetaData associated with the Statement.
- getNumResults()
- Returns the number of result sets fetched so far.
- getNumResultsInCache()
- Returns the number of result sets currently in the cache.
- getParameter(int)
- Returns the value of the parameter at the specified index.
- getResult()
- Returns the current SelectResult for this CallableStatement (if the stored procedure
returned any result sets).
- getRootMetaData()
- Returns the root StatementMetaData associated with the Statement.
- isFillResultCacheOnExecute()
- Returns true if as many result sets as allowed are fetched into the cache
when
execute
is invoked.
- isLastResult()
- Returns true if the currentResult is the last one fetched and either
there are known to be no more result sets or the statement has been closed.
- lastResult()
- Applies any changes in the current row of the current result set to the database,
and then positions to the last result set.
- nextResult()
- Applies any changes in the current row of the current result set to the database,
and then positions to the next result set.
- previousResult()
- Applies any changes in the current row of the current result set to the database,
and then positions to the previous result set.
- refresh()
- Re-executes the SQL statement, refreshing any result sets it returned.
- removePropertyChangeListener(PropertyChangeListener)
- Removes a listener to the PropertyChange event set.
- setCurrentResult(int)
- Applies any changes in the current row to the database, and then positions to the
specified result set.
- setFillResultCacheOnExecute(boolean)
- If true, as many result sets as allowed are fetched into the cache when
execute
is invoked.
- setMaximumResultsInCache(int)
- Sets the maximum number of result sets the cache can contain at one time.
- setMetaData(StatementMetaData)
- Associates the a chain of StatementMetaData objects with the Statement.
- setParameter(int, Object)
- Sets the parameter at the specified index to the specified value.
Constructors
CallableStatement
public CallableStatement()
- Constructs a new CallableStatement.
CallableStatement
public CallableStatement(boolean forVAJava)
- Constructs a new CallableStatement. If
forVAJava
is true,
messages that refer to a row number, a column number, or the current row will
be reported in VisualAge for Java Select bean terms (zero-based),
instead of one-based.
This constructor only be used by classes in com.ibm.ivj.db.uibeans package.
- Parameters:
- forVAJava - if true report row, column and currentRow in VisualAge
terms.
Methods
addPropertyChangeListener
public synchronized void addPropertyChangeListener(PropertyChangeListener listener)
- Adds a listener to the PropertyChange event set. PropertyChange events occur
when the bound properties, currentRow, currentRowInCache, currentResult and
currentResultInCache are changed.
- Parameters:
- listener - PropertyChangeListener
- See Also:
- removePropertyChangeListener
cancelExecution
public void cancelExecution() throws DataException
- Cancels execution of the SQL statement which is associated with
this CallableStatement. In order to use this method, it must be invoked
from a thread different from the one in which the SQL statement is running.
The SQL statement is either the one that executes the stored procedure, or
the one associated with a subsequent request to insert, update, or delete
a row in the result set.
- Throws: DataException
- noConnection
- if no associated DatabaseConnection
- Throws: DataException
- notExecuting
- if the statement is not currently being executed
- Throws: DataException
- sqlException
- if an SQLException occurred
- Overrides:
- cancelExecution in class SelectStatement
close
public void close() throws DataException
- Applies any changes in the current row of the current Select Result to the
database, and then closes the result set and the statement.
JDBC resources associated with the statement and the result set are
released. After the statement is closed, no more rows can be fetched into
any result set, but you can still use the associated SelectResults to update the
database, and you can re-execute the statement.
Even if you do not explicitly call close()
,
JDBC resources are automatically freed when your CallableStatement is garbage collected,
However, changes to the current row are not automatically applied in that case.
The events aboutToClose
and closed
are
triggered by this method.
- Throws: DataException
- noActiveConnection
- if no active connection exists
- Throws: DataException
- rowChanged
- if the current row cannot be updated because it cannot be found in the database
- Throws: DataException
- sqlException
- if an SQLException occurred
- Overrides:
- close in class SelectStatement
execute
public synchronized void execute() throws DataException
- Executes the SQL CALL statement and, if any result sets were produced, positions to the
first row in the first result set.
If needed, a connection is made to the database prior to executing the
SQL statement, using the associated DatabaseConnection. The SQL statement is
obtained from the StatementMetaData associated with this CallableStatement.
Any result sets returned can be accessed through SelectResult objects associated
with this CallableStatement.
The events aboutToExecute
and executed
are
triggered by this method.
The event cacheRowsChanged
of any associated SelectResults is triggered
by this method.
The event propertyChange
is triggered by this method for the
bound properties currentRow, currentRowInCache, currentResult, and currentResultInCache.
- Throws: DataException
- noConnection
- if no associated DatabaseConnection
- Throws: DataException
- noGui
- if no GUI available and logon prompt requested
- Throws: DataException
- badUidPwd
- if incorrect Userid or password specified
- Throws: DataException
- noSQL
- if the SQL statement is null
- Throws: DataException
- notCall
- if SQL statement is not a CALL statement
- Throws: DataException
- noTransactions
- if database does not support transactions and autoCommit set to false
- Throws: DataException
- sqlException
- if an SQLException occurred
- Overrides:
- execute in class SelectStatement
- See Also:
- DatabaseConnection
- StatementMetaData
- SelectResult
firstResult
public void firstResult() throws DataException
- Applies any changes in the current row of the current result set to the database,
and then positions to the first result set (if any result sets were returned).
If the first result set has been displaced from the cache, you are positioned to
the first result set still in the cache, and an exception is thrown to indicate
that the request could not be satisfied.
If the current row should be locked ( isLockRows
returns true),
the current row of the new current result set is locked in the database.
The event propertyChange
is triggered by this method for the
bound properties currentResultSet and currentResultSetInCache.
- Throws: DataException
- notExecuted
- if statement has not been executed
- Throws: DataException
- noResultSets
- if no result sets were produced
- Throws: DataException
- rowChanged
- if the current row cannot be updated because it cannot be found in the database
- Throws: DataException
- rowNotFound
- if the lockRows property is true and the new current row cannot be locked
- Throws: DataException
- beforeResultCacheStart
- if the requested result set is before the start of the cache
- Throws: DataException
- sqlException
- if an SQLException occurred
- See Also:
- setCurrentResult
getCacheResultAt
public SelectResult getCacheResultAt(int resultNumber)
- Returns the SelectResult at the specified index.
if there is no result set at the specified index, a null is returned.
The index of the first result set is 1.
- Returns:
- the specified SelectResult
getCurrentResult
public int getCurrentResult()
- Returns the index of the current result set. Returns 0 if there is no current result set.
The index of the first result set is 1.
Certain methods on CallableStatement, such as getResult
and
isLastResult
, apply to the current result set.
- Returns:
- index of the current result set
- See Also:
- setCurrentResult
getCurrentResultInCache
public int getCurrentResultInCache()
- Returns the index in the cache of the current result set.
Returns 0 if there is no current result set.
The index of the first result set in the cache is 1.
The value of currentResultInCache and currentResult will be the same unless
you have set maximumResultsInCache to a value other than 0, and a result set has been
displaced from the cache.
For example, if one result set has been displaced from the cache and
currentResult is 2, currentResultInCache would be 1.
- Returns:
- index in the cache of the current result set
getMaximumResultsInCache
public int getMaximumResultsInCache()
- Returns the maximum number of result sets the cache can contain at one time.
If there is no limit to the number of result sets, the value is 0.
- Returns:
- the maximum number of result sets in the cache
- See Also:
- setMaximumResultsInCache
getMetaData
public StatementMetaData getMetaData()
- Returns the StatementMetaData associated with the Statement.
- Returns:
- the associated StatementMetaData
- Overrides:
- getMetaData in class Statement
- See Also:
- setMetaData
getNumResults
public int getNumResults()
- Returns the number of result sets fetched so far. (This may be less than the number of
result sets returned by the stored procedure.)
- Returns:
- number of result sets fetched
getNumResultsInCache
public int getNumResultsInCache()
- Returns the number of result sets currently in the cache.
- Returns:
- the number of result sets in cache
getParameter
public Object getParameter(int parameterNumber) throws DataException
- Returns the value of the parameter at the specified index.
If the parameter value is null, a null is returned.
The index of the first parameter is 1.
After you execute a stored procedure, its output parameter values are not retrieved
from the database until you request them via this method. When you first request
these values, your statement must still be open. The reason for deferring the retrieval
of these output values from the database is to allow you to first obtain any of the
result sets returned by the stored procedure. Some database products may have problems
if you get output parameter values before you obtain the result sets.
- Parameters:
- parameterNumber - index of the parameter
- Returns:
- the parameter value
- Throws: IndexOutOfBoundsException
- - if the parameter index is not defined
- Throws: DataException
- notOpen
- if the output parameter has not been read after execution and the statement is not open
- Throws: DataException
- noActiveConnection
- if the output parameter has not been read after execution and no active connection exists
- Throws: DataException
- sqlException
- if the output parameter has not been read after execution and an SQLException occurred
- Overrides:
- getParameter in class Statement
- See Also:
- setParameter
getResult
public SelectResult getResult()
- Returns the current SelectResult for this CallableStatement (if the stored procedure
returned any result sets).
You can access the result set through the SelectResult object.
Returns a null if there is no current result set.
A CallableStatement can have more than one SelectResult associated with it, one
of which is considered the current result.
- Returns:
- the current SelectResult
- Overrides:
- getResult in class SelectStatement
- See Also:
- getCurrentResult
- setCurrentResult
getRootMetaData
public StatementMetaData getRootMetaData()
- Returns the root StatementMetaData associated with the Statement.
The root StatementMetaData associated with a CallableStatement describes the
call statement itself, including any parameters. If the CallableStatement can
return result sets, additional StatementMetaData objects for the result sets
are chained off of the root. The StatementMetaData object returned by the
getMetaData method depends on the value of the currentResult property,
while the StatementMetaData object returned by this method is always the first.
- Returns:
- the first associated StatementMetaData
- See Also:
- getMetaData
- setMetaData
isFillResultCacheOnExecute
public boolean isFillResultCacheOnExecute()
- Returns true if as many result sets as allowed are fetched into the cache
when
execute
is invoked.
Returns false if result sets are fetched into the cache only as needed to satisfy
a request to set the current result set position.
The number of result sets you are allowed to fetch into the cache is limited by the
maximumResultsInCache property.
If more than one result set is fetched on execute
, all result sets
before the last one fetched are closed. You will not be able to fetch any additional rows
into the closed result sets beyond what was initially fetched when
execute
was invoked. The number of rows initially fetched for each
result set is governed by the fillCacheOnExecute property.
- Returns:
- true if as many result sets as allowed are fetched into the cache on
execute
, else false.
- See Also:
- setFillResultCacheOnExecute
- getMaximumResultsInCache
- isFillCacheOnExecute
isLastResult
public boolean isLastResult()
- Returns true if the currentResult is the last one fetched and either
there are known to be no more result sets or the statement has been closed. It cannot
be known that there are no more result sets until you have tried to go past the last
result set. Therefore, if you are on the last result set and have not tried to go past it,
this method will return false.
- Returns:
- true if the currentResult is the last one fetched and no
more result sets can be fetched.
lastResult
public synchronized void lastResult() throws DataException
- Applies any changes in the current row of the current result set to the database,
and then positions to the last result set.
If more result sets can be fetched from the database
they are fetched before positioning to the last result set.
The database operation which tells us that there are no more result sets has the
effect of closing the last result set. Therefore, after you use the lastResult
method, no more rows can be fetched in any of the result sets. Because of this, you
should generally avoid the method unless you are not limiting the cache size for
each result set, and the fillCacheOnExecute property is set to true,
causing all rows in each result set to be fetched as soon as the result set is opened.
If the current row should be locked ( isLockRows
returns true),
the current row of the new current result set is locked in the database.
The event propertyChange
is triggered by this method for the
bound properties currentResultSet and currentResultSetInCache.
- Throws: DataException
- notExecuted
- if associated statement has not been executed
- Throws: DataException
- noResultSets
- if no result sets were produced
- Throws: DataException
- rowChanged
- if the current row cannot be updated because it cannot be found in the database
- Throws: DataException
- rowNotFound
- if the lockRows property is true and the new current row cannot be locked
- Throws: DataException
- sqlException
- if an SQLException occurred
- See Also:
- setCurrentResult
- setFillCacheOnExecute
nextResult
public void nextResult() throws DataException
- Applies any changes in the current row of the current result set to the database,
and then positions to the next result set.
If the next result set has not already been fetched from the database, it is fetched.
If no more result sets can be fetched, your position does not change, and
no exception is thrown. Thus, if you are on the last result set, repeatedly invoking
this method has no effect. For a discussion of when no more result sets can be fetched,
see the isLastResult
method.
If the current row should be locked ( isLockRows
returns true),
the current row of the new current result set is locked in the database.
The event propertyChange
is triggered by this method for the
bound properties currentResultSet and currentResultSetInCache.
- Throws: DataException
- notExecuted
- if statement has not been executed
- Throws: DataException
- noResultSets
- if no result sets were produced
- Throws: DataException
- rowChanged
- if the current row cannot be updated because it cannot be found in the database
- Throws: DataException
- rowNotFound
- if the lockRows property is true and the new current row cannot be locked
- Throws: DataException
- sqlException
- if an SQLException occurred
- See Also:
- setCurrentResult
previousResult
public void previousResult() throws DataException
- Applies any changes in the current row of the current result set to the database,
and then positions to the previous result set.
If you are already on the first result set, your position does not change, and no exception
is thrown. Thus, if you are on the first result set, repeatedly invoking this method has
no effect.
If the previous result set has been displaced from the cache, your position does not change,
and an exception is thrown to indicate that the request could not be satisfied.
If the current row should be locked ( isLockRows
returns true),
the current row of the new current result set is locked in the database.
The event propertyChange
is triggered by this method for the
bound properties currentResultSet and currentResultSetInCache.
- Throws: DataException
- notExecuted
- if statement has not been executed
- Throws: DataException
- noResultSets
- if no result sets were produced
- Throws: DataException
- rowChanged
- if the current row cannot be updated because it cannot be found in the database
- Throws: DataException
- rowNotFound
- if the lockRows property is true and the new current row cannot be locked
- Throws: DataException
- beforeResultCacheStart
- if the requested result set is before the start of the cache
- Throws: DataException
- sqlException
- if an SQLException occurred
- See Also:
- setCurrentResult
refresh
public synchronized void refresh() throws DataException
- Re-executes the SQL statement, refreshing any result sets it returned.
The statement must currently be open.
Any changes you have made to statement input parameters will take effect when the
statement is re-executed. If you have changed the SQL CALL statement itself in the
StatementMetaData, that change will not take effect. (To make the latter change take
effect, use the
execute
method.
The events aboutToExecute
and executed
are
triggered by this method.
The event cacheRowsChanged
of any associated SelectResults
is triggered by this method.
The event propertyChange
is triggered by this method for the
bound properties currentRow, currentRowInCache, currentResult, and currentResultInCache.
- Throws: DataException
- noActiveConnection
- if no active connection exists
- Throws: DataException
- notOpen
- if the statement is not open
- Throws: DataException
- sqlException
- if an SQLException occurred
- Overrides:
- refresh in class SelectStatement
- See Also:
- execute
removePropertyChangeListener
public synchronized void removePropertyChangeListener(PropertyChangeListener listener)
- Removes a listener to the PropertyChange event set. PropertyChange events occur
when the bound properties, currentRow, currentRowInCache, currentResult and
currentResultInCache are changed.
- Parameters:
- listener - PropertyChangeListener
- See Also:
- addPropertyChangeListener
setCurrentResult
public synchronized void setCurrentResult(int resultNumber) throws DataException
- Applies any changes in the current row to the database, and then positions to the
specified result set.
If the specified result set has not yet been fetched, result sets are fetched until the
specified result set is in the cache or no more result sets can be fetched.
If no more result sets can be fetched, and the specified result set was not reached,
you are positioned to the last result set, and an exception is thrown to indicate
that the request could not be satisfied.
If the specified result set has been displaced from the cache, you are positioned to
the first result set in the cache, and an exception is thrown to indicate
that the request could not be satisfied.
If the current row should be locked ( isLockRows
returns true),
the current row of the new current result set is locked in the database.
The event propertyChange
is triggered by this method for the
bound properties currentResultSet and currentResultSetInCache.
- Parameters:
- resultNumber - index of the result set
- Throws: DataException
- notExecuted
- if associated statement has not been executed
- Throws: DataException
- noResultSets
- if no result sets were produced
- Throws: DataException
- rowChanged
- if the current row cannot be updated because it cannot be found in the database
- Throws: DataException
- rowNotFound
- if the lockRows property is true and the new current row cannot be locked
- Throws: DataException
- beforeResultCacheStart
- if the requested result set is before the start of the cache
- Throws: DataException
- resultIndexTooLarge
- if the requested result set is after the last result set
- Throws: DataException
- sqlException
- if an SQLException occurred
- See Also:
- getCurrentResult
setFillResultCacheOnExecute
public void setFillResultCacheOnExecute(boolean fillResultCacheOnExecute)
- If true, as many result sets as allowed are fetched into the cache when
execute
is invoked.
Otherwise, result sets are fetched into the cache as needed to satisfy
a request to set the current result set position.
The number of result sets you are allowed to fetch into the cache is limited by the
maximumResultsInCache property.
If more than one result set is fetched on execute
, all result sets
before the last one fetched are closed. You will not be able to fetch any additional rows
into the closed result sets beyond what was initially fetched when
execute
was invoked. The number of rows initially fetched for each
result set is governed by the fillCacheOnExecute property.
If you never execute this method for a CallableStatement, the value defaults to true.
- Parameters:
- fillResultCacheOnExecute - true, fetch as many result sets as allowed on
execute
; false fetch result sets only as needed
- See Also:
- isFillResultCacheOnExecute
- setMaximumResultsInCache
- setFillCacheOnExecute
setMaximumResultsInCache
public void setMaximumResultsInCache(int maximumResultsInCache)
- Sets the maximum number of result sets the cache can contain at one time. Set the value
to 0 if there is no limit on the number of result sets in the cache.
If you never execute this method, the value defaults to 0.
- Parameters:
- maximumResultsInCache - the maximum number of result sets in cache
- See Also:
- getMaximumResultsInCache
setMetaData
public synchronized void setMetaData(StatementMetaData metaData)
- Associates the a chain of StatementMetaData objects with the Statement.
The first StatementMetaData should specify the SQL for calling the stored procedure,
including any stored procedure parameters.
Any additional chained StatementMetaData objects specify result sets returned by the
stored procedure.
If the stored procedure returns no result sets, do not chain any
StatementMetaData objects after the first one. If the stored procedure returns one
result set, or returns multiple result sets which can all be described by the same
meta data, chain only one StatementMetaData after the first one. If the stored procedure
returns multiple result sets which cannot all be described by the same meta data,
chain one StatementMetaData for each result set after the first one.
To chain StatementMetaData objects, use the setNextMetaData
method of
StatementMetaData.
- Parameters:
- metaData - the first associated StatementMetaData
- Overrides:
- setMetaData in class SelectStatement
- See Also:
- getMetaData
- getRootMetaData
- setNextMetaData
setParameter
public void setParameter(int parameterNumber,
Object aValue) throws DataException
- Sets the parameter at the specified index to the specified value.
The index of the first parameter is 1.
- Parameters:
- parameterNumber - index of the parameter
- aValue - parameter value
- Throws: IndexOutOfBoundsException
- if the parameter index is not
defined
- Throws: DataException
- if the value does not match the object type
of the parameter
- Overrides:
- setParameter in class Statement
- See Also:
- getParameter
