IBM DB2 Information Integrator
Java API Reference
for Developing Wrappers

com.ibm.db2.wrapper
Class RemoteQuery

java.lang.Object
  extended bycom.ibm.db2.wrapper.SqlqgBaseClass
      extended bycom.ibm.db2.wrapper.RemoteOperation
          extended bycom.ibm.db2.wrapper.RemoteQuery

public class RemoteQuery
extends RemoteOperation

The RemoteQuery class represents SELECT statement operations on a remote data source. An instance of your RemoteQuery subclass is created when the federated server invokes the createRemoteQuery method on an instance of the appropriate RemoteConnection subclass. The federated server destroys the RemoteQuery object after the application that submitted the query to the federated server closes its cursor over the result set of the query.

Since:
IBM DB2 Information Integrator Version 8.2

Field Summary
static byte CLOSE_EOA
          Status constant used in close method to indicate that the wrapper is to finish necessary cleanup and that the RemoteQuery object is destroyed after the close method returns.
static byte CLOSE_EOS
          Status constant used in close method to indicate that the wrapper must leave the RemoteQuery in a state so that the reopen or reopenInputLob methods can be invoked.
static byte EOF
          Status constant to be used with getStatus and setStatus methods to indicate that the RemoteQuery object finished fetching all the rows of the result set.
static int FETCH_LOB_LAST
          LOB fetching status constant: indicate that the last buffer of data for the current LOB column has been fetched.
static int FETCH_LOB_MORE
          LOB fetching status constant: indicate that more data is available for the current LOB column.
static int FETCH_LOB_NEXT
          LOB fetching status constant: indicate that another LOB column is to be fetched next.
static int FETCH_NON_LOB_NEXT
          LOB fetching status constant: indicate that a non-LOB column is to be fetched next.
static int FETCH_ROW_DONE
          LOB fetching status constant: indicate that all the values for the current row have been fetched.
static byte OPEN
          Status constant to be used with getStatus and setStatus methods to indicate that the RemoteQuery object is in open state.
static int OPEN_LOB_INIT
          LOB input status constant: indicate the start of processing for the input LOB values.
static int OPEN_LOB_LAST
          LOB input status constant: indicate that this is the last fragment for the current input LOB value.
static int OPEN_LOB_MORE
          LOB input status constant: indicate that more fragments are available for the current input LOB value.
static int OPEN_LOB_NEW
          LOB input status constant: indicate that the wrapper expects data fragments for a new input LOB value.
static int OPEN_NON_LOB_NEXT
          LOB input status constant: indicate that only input non-LOB values are to be processed.
static int OPEN_ROW_DONE
          LOB input status constant: indicate that all the input values have been processed.
static byte READY
          Status constant to be used with getStatus and setStatus methods to indicate that the RemoteQuery object is ready to fetch the next row.
static byte UNREADY
          Status constant to be used with getStatus and setStatus methods to indicate that the RemoteQuery object is not yet ready to fetch the next row.
 
Constructor Summary
protected RemoteQuery(RemoteConnection activeConnection, long id)
          Construct a new query object for the specified connection.
 
Method Summary
protected  void close(short status)
          Allow the wrapper and the data source to clean up after query statement processing.
protected  void fetch()
          Fetch (retrieve) a single-result row from the remote data source into the output data buffers.
protected  java.lang.Object fetchLob(int bufferSize, int bytesWritten)
          Retrieve a large object (LOB) fragment from the remote source.
protected  int getRowStatus()
          Retrieve the current row status.
protected  byte getStatus()
          Retrieve the status of the query.
protected  void lobDataReady(int columnNumber, int bytesReady, int status, int intent)
          Notify the federated server that a fragment of data from a LOB column is fetched (retrieved).
protected  void open()
          Allow the wrapper to prepare the remote data source to return the first result row for the query.
protected  int openInputLob(int columnNumber, int matSize, int xferBytes, java.lang.Object buffer)
          Allow the wrapper to prepare the remote data source to return the first result row for the query that contains input large object (LOB) parameters.
protected  void reopen(short action)
          Reset a previously opened result stream and prepares the data source to return more result sets, possibly based on different parameter bindings.
protected  int reopenInputLob(short action, int columnNumber, int matSize, int xferBytes, java.lang.Object buffer)
          Reset a previously opened result stream and prepares the data source to return more result sets, possibly based on different parameter bindings for queries with input large object (LOB) parameters.
protected  void reportEof()
          Report an end-of-file condition during a fetch operation.
protected  void setLobNext()
          Notify the federated server when a current fetched row contains large object (LOB) values and that the fetchLob method is to be invoked.
protected  void setRowStatus(int status)
          Set the current row status.
protected  void setStatus(byte status)
          Set the query status.
 
Methods inherited from class com.ibm.db2.wrapper.RemoteOperation
getConnection, getExecDesc, getInputData, getOutputData, getServer, getWrapper
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

CLOSE_EOA

public static final byte CLOSE_EOA
Status constant used in close method to indicate that the wrapper is to finish necessary cleanup and that the RemoteQuery object is destroyed after the close method returns.

Since:
IBM DB2 Information Integrator Version 8.2
See Also:
Constant Field Values

CLOSE_EOS

public static final byte CLOSE_EOS
Status constant used in close method to indicate that the wrapper must leave the RemoteQuery in a state so that the reopen or reopenInputLob methods can be invoked.

Since:
IBM DB2 Information Integrator Version 8.2
See Also:
Constant Field Values

EOF

public static final byte EOF
Status constant to be used with getStatus and setStatus methods to indicate that the RemoteQuery object finished fetching all the rows of the result set.

Since:
IBM DB2 Information Integrator Version 8.2
See Also:
Constant Field Values

FETCH_LOB_LAST

public static final int FETCH_LOB_LAST
LOB fetching status constant: indicate that the last buffer of data for the current LOB column has been fetched.

Since:
IBM DB2 Information Integrator Version 8.2
See Also:
Constant Field Values

FETCH_LOB_MORE

public static final int FETCH_LOB_MORE
LOB fetching status constant: indicate that more data is available for the current LOB column.

Since:
IBM DB2 Information Integrator Version 8.2
See Also:
Constant Field Values

FETCH_LOB_NEXT

public static final int FETCH_LOB_NEXT
LOB fetching status constant: indicate that another LOB column is to be fetched next.

Since:
IBM DB2 Information Integrator Version 8.2
See Also:
Constant Field Values

FETCH_NON_LOB_NEXT

public static final int FETCH_NON_LOB_NEXT
LOB fetching status constant: indicate that a non-LOB column is to be fetched next.

Since:
IBM DB2 Information Integrator Version 8.2
See Also:
Constant Field Values

FETCH_ROW_DONE

public static final int FETCH_ROW_DONE
LOB fetching status constant: indicate that all the values for the current row have been fetched.

Since:
IBM DB2 Information Integrator Version 8.2
See Also:
Constant Field Values

OPEN

public static final byte OPEN
Status constant to be used with getStatus and setStatus methods to indicate that the RemoteQuery object is in open state.

Since:
IBM DB2 Information Integrator Version 8.2
See Also:
Constant Field Values

OPEN_LOB_INIT

public static final int OPEN_LOB_INIT
LOB input status constant: indicate the start of processing for the input LOB values.

Since:
IBM DB2 Information Integrator Version 8.2
See Also:
Constant Field Values

OPEN_LOB_LAST

public static final int OPEN_LOB_LAST
LOB input status constant: indicate that this is the last fragment for the current input LOB value.

Since:
IBM DB2 Information Integrator Version 8.2
See Also:
Constant Field Values

OPEN_LOB_MORE

public static final int OPEN_LOB_MORE
LOB input status constant: indicate that more fragments are available for the current input LOB value.

Since:
IBM DB2 Information Integrator Version 8.2
See Also:
Constant Field Values

OPEN_LOB_NEW

public static final int OPEN_LOB_NEW
LOB input status constant: indicate that the wrapper expects data fragments for a new input LOB value.

Since:
IBM DB2 Information Integrator Version 8.2
See Also:
Constant Field Values

OPEN_NON_LOB_NEXT

public static final int OPEN_NON_LOB_NEXT
LOB input status constant: indicate that only input non-LOB values are to be processed.

Since:
IBM DB2 Information Integrator Version 8.2
See Also:
Constant Field Values

OPEN_ROW_DONE

public static final int OPEN_ROW_DONE
LOB input status constant: indicate that all the input values have been processed.

Since:
IBM DB2 Information Integrator Version 8.2
See Also:
Constant Field Values

READY

public static final byte READY
Status constant to be used with getStatus and setStatus methods to indicate that the RemoteQuery object is ready to fetch the next row.

Since:
IBM DB2 Information Integrator Version 8.2
See Also:
Constant Field Values

UNREADY

public static final byte UNREADY
Status constant to be used with getStatus and setStatus methods to indicate that the RemoteQuery object is not yet ready to fetch the next row.

Since:
IBM DB2 Information Integrator Version 8.2
See Also:
Constant Field Values
Constructor Detail

RemoteQuery

protected RemoteQuery(RemoteConnection activeConnection,
                      long id)
Construct a new query object for the specified connection.

Parameters:
activeConnection - The connection through which the query is executed.
id - An integer value that represents the RemoteQuery object.
Since:
IBM DB2 Information Integrator Version 8.2
See Also:
RemoteConnection
Method Detail

close

protected void close(short status)
              throws java.lang.Exception
Allow the wrapper and the data source to clean up after query statement processing. The wrapper must implement this method in the wrapper specific RemoteQuery subclass. A single SQL statement that is submitted to the federated server can result in multiple query requests to a wrapper. So that wrappers can more easily optimize the translation and submission of queries to the data source, the close method receives a status flag that indicates whether the close represents an end-of-query (CLOSE_EOS) or an end-of-statement (CLOSE_EOA) status. If the close method is called with an end-of-query status, the RemoteQuery object can execute the reopen method successfully. If the close method is called with an end-of-statement status, the federated server destroys the RemoteQuery object after the close method completes.

Parameters:
status - the status of the operation.
Throws:
java.lang.Exception - if the close operation fails.
Since:
IBM DB2 Information Integrator Version 8.2

fetch

protected void fetch()
              throws java.lang.Exception
Fetch (retrieve) a single-result row from the remote data source into the output data buffers. The wrapper must implement this method in the wrapper-specific RemoteQuery subclass.

Throws:
java.lang.Exception - if the fetch operation fails.
Since:
IBM DB2 Information Integrator Version 8.2

fetchLob

protected java.lang.Object fetchLob(int bufferSize,
                                    int bytesWritten)
                             throws java.lang.Exception
Retrieve a large object (LOB) fragment from the remote source. The wrapper must implement this method in the wrapper-specific RemoteQuery subclass if the wrapper transfers large objects (LOB). The fetchLob method includes a function argument that specifies the maximum size of the fetched (retrieved) data fragment. The fetchLob method must call the lobDataReady method to inform the federated server of the fetch status.

Parameters:
bufferSize - The maximum size of the data fragment to be fetched.
bytesWritten - The number of bytes already fetched for the current LOB.
Returns:
A data fragment in the form of a string for Clob data and a byte array for Blob data.
Throws:
java.lang.Exception - if the fetchLob operation fails.
Since:
IBM DB2 Information Integrator Version 8.2

getRowStatus

protected final int getRowStatus()
Retrieve the current row status.

Returns:
The current row status.
Since:
IBM DB2 Information Integrator Version 8.2

getStatus

protected final byte getStatus()
Retrieve the status of the query.

Returns:
The status.
Since:
IBM DB2 Information Integrator Version 8.2

lobDataReady

protected final void lobDataReady(int columnNumber,
                                  int bytesReady,
                                  int status,
                                  int intent)
                           throws WrapperException
Notify the federated server that a fragment of data from a LOB column is fetched (retrieved). Call this method from the fetchLob method.

Parameters:
columnNumber - The index of the column that this data fragment belongs to.
bytesReady - The length the fragment in bytes.
status - The status of the LOB operation. The status value can be FETCH_LOB_MORE or FETCH_LOB_LAST.
intent - The flag that indicates if there are any more LOB or non-LOB columns to fetch or if the complete row was fetched.
Throws:
WrapperException - if the method fails.
Since:
IBM DB2 Information Integrator Version 8.2

open

protected void open()
             throws java.lang.Exception
Allow the wrapper to prepare the remote data source to return the first result row for the query. The wrapper must implement this method in the wrapper-specific RemoteQuery subclass.

Throws:
java.lang.Exception - if the open operation fails.
Since:
IBM DB2 Information Integrator Version 8.2

openInputLob

protected int openInputLob(int columnNumber,
                           int matSize,
                           int xferBytes,
                           java.lang.Object buffer)
                    throws java.lang.Exception
Allow the wrapper to prepare the remote data source to return the first result row for the query that contains input large object (LOB) parameters. The wrapper must implement this method in the wrapper-specific RemoteQuery subclass if the wrapper supports input large object (LOB) parameters.
The federated server calls this method if input LOB host variables are found. Initially the openInputLob method is called with an empty buffer and the columnNumber parameter set to -1. The wrapper must return the index of the host variable that receives the next LOB fragment, then call setRowStatus to indicate that there are input LOB parameters. When the wrapper indicates that there are more LOB input parameters to process, the federated server calls this method with another LOB fragment. The LOB input value total size, in bytes, is given as the matSize parameter. The size of the current LOB fragment, in bytes, is given as the xferBytes parameter. The wrapper must use these parameter values to advance to the next input variable or to signal that the entire input values have been read.

Parameters:
columnNumber - The index of the input host variable that receives the current LOB fragment.
matSize - The materialized size of the input data, in bytes.
xferBytes - The size of the current data fragment, in bytes.
buffer - The current LOB fragment object. The object is a string for CLOB variables and a byte array for BLOB variables.
Returns:
The index of the input host variable that receives the next LOB fragment.
Throws:
java.lang.Exception - if the openInputLob process fails.
Since:
IBM DB2 Information Integrator Version 8.2

reopen

protected void reopen(short action)
               throws java.lang.Exception
Reset a previously opened result stream and prepares the data source to return more result sets, possibly based on different parameter bindings. The wrapper must implement this method in the wrapper-specific RemoteQuery subclass. This method will not be called unless the query was previously closed with an end-of-query status. See also the close method.

Parameters:
action - Unused.
Throws:
java.lang.Exception - if the reopen operation fails.
Since:
IBM DB2 Information Integrator Version 8.2

reopenInputLob

protected int reopenInputLob(short action,
                             int columnNumber,
                             int matSize,
                             int xferBytes,
                             java.lang.Object buffer)
                      throws java.lang.Exception
Reset a previously opened result stream and prepares the data source to return more result sets, possibly based on different parameter bindings for queries with input large object (LOB) parameters. The wrapper must implement this method in the wrapper-specific RemoteQuery subclass if the wrapper supports input large object (LOB) parameters. This method will not be called unless the query was previously closed with an end-of-query status. See also the close method.
The federated server calls this method if input LOB host variables are found. Initially the reopenInputLob method is called with an empty buffer and the columnNumber parameter set to -1. The wrapper must return the index of the host variable that receives the next LOB fragment, then call setRowStatus to indicate that there are input LOB parameters. When the wrapper indicates that there are more LOB input parameters to process, the federated server calls this method with another LOB fragment. The LOB input value total size, in bytes, is given as the matSize parameter. The size of the current LOB fragment, in bytes, is given as the xferBytes parameter. The wrapper must use these parameter values to advance to the next input variable or to signal that the entire input values have been read.

Parameters:
action - Unused.
columnNumber - The index of the input host variable that receives the current LOB fragment.
matSize - The materialized size of the input data, in bytes.
xferBytes - The size of the current data fragment, in bytes.
buffer - The current LOB fragment object. The object is a string for CLOB variables and a byte array for BLOB variables.
Returns:
The index of the input host variable that receives the next LOB fragment.
Throws:
java.lang.Exception - if the reopenInputLob process fails.
Since:
IBM DB2 Information Integrator Version 8.2

reportEof

protected final void reportEof()
                        throws WrapperException
Report an end-of-file condition during a fetch operation. The wrapper specific RemoteQuery subclass invokes this method during the fetch operation to indicate that the last row was fetched.

Overrides:
reportEof in class RemoteOperation
Throws:
WrapperException - if the method fails.
Since:
IBM DB2 Information Integrator Version 8.2

setLobNext

protected final void setLobNext()
Notify the federated server when a current fetched row contains large object (LOB) values and that the fetchLob method is to be invoked. Call this method from the fetch method if there is LOB data to transfer. Do not call the setLobNext method from inside the fetchLob method.
After the fetch method returns and setLobNext is called, the federated server calls fetchLob to retrieve the LOB column values.

Since:
IBM DB2 Information Integrator Version 8.2

setRowStatus

protected final void setRowStatus(int status)
Set the current row status.

Parameters:
status - The new row status to be set.
Since:
IBM DB2 Information Integrator Version 8.2

setStatus

protected final void setStatus(byte status)
Set the query status.

Parameters:
status - The new query status to be set.
Since:
IBM DB2 Information Integrator Version 8.2

IBM DB2 Information Integrator
Java API Reference
for Developing Wrappers

(C)Copyright IBM Corp. 2002. All rights reserved.

Links on this page are made available for your convenience and may take you to non-IBM sites. IBM does not warrant any sample code provided on these sites.