Class Hierarchy All Classes All Fields and Methods

 

Class com.ibm.db.beans.DBProcedureCall 

java.lang.Object
        com.ibm.db.beans.DBStatement
                com.ibm.db.beans.DBSelect
                        com.ibm.db.beans.DBProcedureCall

public class DBProcedureCall
extends DBSelect

This class allows you to call a stored procedure and use any parameters or result sets it returns in a bean which exposes JDBC 2.0 RowSet functionality and adds its own useful functions for managing stored procedure results.

The JDBC RowSet "wraps" a connection, a statement, and a result set as a bean, and provides properties, methods, and events for using them. It does not currently define interfaces for getting output parameters or multiple result sets from stored procedures. That function is added by this bean.

The bean does not currently support getting stored procedure results which are update counts. Only stored procedure results which are result sets are supported.

This bean also has function (some of it inherited from DBSelect) to help with managing large result sets and to make it easy to use the bean in a graphical user interface. For example, it can fire PropertyChange events for dynamically generated bound "properties" corresponding to the parameters of the stored procedure. You can also connect this bean to the utility bean DBTableModel, which adapts it for use as the model of a javax.swing.JTable.

Constructor Index
Constructor Description
DBProcedureCall() Default constructor for a DBProcedureCall bean.

Method Index
Method Description
void addPropertyChangeListener(PropertyChangeListener) Adds a listener to the PropertyChange event set.
void clearMetaData() Clears the descriptions of all result sets for this DBProcedureCall.
DBSelectMetaData createMetaData(int) Creates a new DBSelectMetaData object to describe the specified result set.
int findColumn(String) Maps the given column label to its column index.
boolean firstResult() Applies any changes in the current row of the current result set to the database, and then positions to the first result set.
DBSelectMetaData getMetaData(int) Gets the meta data describing the result set at the specified position.
Object getParameter(int) Gets the value of the parameter at the specified position.
int getResult() Gets the number of the result set to which you are currently positioned.
int getResultCount() Gets the number of result sets.
boolean hasResult() Returns true if the store procedure returns at least one result set; returns false otherwise.
boolean isFetchAllResultsOnExecute() Returns true if all result sets produced by this procedure call will be obtained immediately during the execute method.
boolean isLastResult() Returns true if the current result set is the last one fetched and either there are known to be no more result sets or the statement has been closed.
boolean isOpen() Returns true if the underlying RowSet is open, otherwise returns false.
boolean lastResult() Applies any changes in the current row of the current result set to the database, and then positions to the last result set.
boolean nextResult() Applies any changes in the current row of the current result set to the database, and then positions to the next result set.
boolean previousResult() Applies any changes in the current row of the current result set to the database, and then positions to the previous result set.
void removePropertyChangeListener(PropertyChangeListener) Removes a listener to the PropertyChange event set.
void setFetchAllResultsOnExecute(boolean) If true, all result sets produced by this procedure call will be obtained immediately during the execute method.
boolean setResult(int) Applies any changes in the current row of the current result set to the database, and then positions to the specified result set.

 

Constructors

 

DBProcedureCall

public DBProcedureCall()

Default constructor for a DBProcedureCall bean. This constructor also creates associated bean of type DBParameterMetaData.

 

Methods

 

addPropertyChangeListener

public synchronized void addPropertyChangeListener(PropertyChangeListener listener)

Adds a listener to the PropertyChange event set.

 

clearMetaData

public void clearMetaData() throws SQLException

Clears the descriptions of all result sets for this DBProcedureCall.

 

createMetaData

public DBSelectMetaData createMetaData(int position) throws DBException, SQLException

Creates a new DBSelectMetaData object to describe the specified result set. The index of the first result set is 1.

If there was already a result set described at this position, its description is replaced with a new (empty) one.

There is no public constructor for a DBSelectMetaData object. This method is the only way to create one.

 

findColumn

public int findColumn(String columnName) throws DBException, SQLException

Maps the given column label to its column index. The index of the first column is 1.

 

firstResult

public synchronized boolean firstResult() throws DBException, SQLException

Applies any changes in the current row of the current result set to the database, and then positions to the first result set.

If there are no result sets, a false is returned.

If the current row should be locked ( isLockRows returns true), the current row of the new current result set is locked in the database.

 

getMetaData

public DBSelectMetaData getMetaData(int position) throws DBException, SQLException

Gets the meta data describing the result set at the specified position. The position of the first result set is 1.

 

getParameter

public synchronized Object getParameter(int position) throws DBException, SQLException

Gets the value of the parameter at the specified position. If the parameter value is null, a null is returned. The position of the first parameter is 1.

If the parameter is an output or inout parameter, then the first time you use this method after executing the stored procedure, its value will be retrieved from the database. Both the JDBC Statement and Connection must be open for this to succeed. Otherwise an exception will occur. Before executing, or after executing and using this method once, the Statement and Connection need not be open, and the exception will not occur.

 

getResult

public int getResult()

Gets the number of the result set to which you are currently positioned. The number of the first result is 1.

 

getResultCount

public int getResultCount()

Gets the number of result sets.

If you use this method before executing the stored procedure, it reflects only the meta data you have provided about the stored procedure. If you use it after executing, the number returned will be the greater of the number before executing and the number of result sets actually fetched so far. (There could be additional result sets not yet fetched.)

 

hasResult

public boolean hasResult()

Returns true if the store procedure returns at least one result set; returns false otherwise.

If you use this method before executing the stored procedure, it reflects only the meta data you have provided about the stored procedure.

 

isFetchAllResultsOnExecute

public boolean isFetchAllResultsOnExecute()

Returns true if all result sets produced by this procedure call will be obtained immediately during the execute method. Otherwise, only the first result set will be obtained at that time, and additional result sets will be obtained upon request.

Once all result sets have been obtained, it is not possible to fetch additional rows in any result set. Therefore, if your procedure produces multiple result sets, and you used the cacheLimit property to limit the number of rows initially fetched, you should set this property to false in order to fetch additional rows.

If you do not execute this method, the value defaults to true.

 

isLastResult

public boolean isLastResult()

Returns true if the current result set 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.

If there are no result sets, the method will return false. If you wish to test whether any result sets were obtained by executing the stored procedure, use hasResult() or getResultCount().

 

isOpen

public boolean isOpen() throws SQLException

Returns true if the underlying RowSet is open, otherwise returns false.

If you are positioned to a result set returned by the stored procedure, this method reports the status of that result set. Otherwise it reports the status of the JDBC Statement.

When isOpen returns true, the database Connection, Statement, and current ResultSet (if any) are all open, and the RowSet is fully functional.

When isOpen returns false, it may be because the statement has not been executed, the result set you are positioned to has been closed, or the DBProcedureCall bean has been serialized and then de-serialized.

If you are positioned to a result set which is closed, you can scroll among any rows currently in the cache and you can even perform inserts, updates, and deletes, but you cannot fetch any additional rows.

 

lastResult

public synchronized boolean lastResult() throws DBException, SQLException

Applies any changes in the current row of the current result set to the database, and then positions to the last result set.

If there are no result sets, a false is returned.

If the current row should be locked ( isLockRows returns true), the current row of the new current result set is locked in the database.

 

nextResult

public synchronized boolean nextResult() throws DBException, SQLException

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 there is no next result set, a false is returned. Your position does not change, and no exception is thrown. Thus, if there are no result sets, or 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.

 

previousResult

public synchronized boolean previousResult() throws DBException, SQLException

Applies any changes in the current row of the current result set to the database, and then positions to the previous result set.

If there is no previous result set, a false is returned. Your position does not change, and no exception is thrown. Thus, if there are no result sets, or you are on the first result set, repeatedly invoking this method has no effect.

If the current row should be locked ( isLockRows returns true), the current row of the new current result set is locked in the database.

 

removePropertyChangeListener

public synchronized void removePropertyChangeListener(PropertyChangeListener listener)

Removes a listener to the PropertyChange event set.

 

setFetchAllResultsOnExecute

public void setFetchAllResultsOnExecute(boolean fetchAll)

If true, all result sets produced by this procedure call will be obtained immediately during the execute method. Otherwise, only the first result set will be obtained at that time, and additional result sets will be obtained upon request.

Once all result sets have been obtained, it is not possible to fetch additional rows in any result set. Therefore, if your procedure produces multiple result sets, and you have limited the cache size of result sets via the cacheLimit property, you should set this property to false in order to fetch additional rows.

If you do not execute this method, the value defaults to true.

 

setResult

public synchronized boolean setResult(int resultNumber) throws DBException, SQLException

Applies any changes in the current row of the current result set to the database, and then positions to the specified result set. The index of the first result set is 1.

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, a false is returned 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.

Class Hierarchy All Classes All Fields and Methods