Interface GDS

public BlobParameterBuffer createBlobParameterBuffer()

Create a new BlobParameterBuffer instance for setting blob parameters in the current GDS implementation.

Returns:

A new BlobParameterBuffer

public DatabaseParameterBuffer createDatabaseParameterBuffer()

Create a new DatabaseParameterBuffer instance for setting database parameters in the current GDS implementation.

Returns:

A new DatabaseParameterBuffer

public EventHandle createEventHandle(String eventName)

Create a new EventHandle specific to a given GDS implementation.

Returns:

The newly created EventHandle

public IscBlobHandle createIscBlobHandle()

Factory method to create a new IscBlobHandle instance specific to the implementation of this interface.

Returns:

A new IscBlobHandle instance

public IscDbHandle createIscDbHandle()

Factory method to create a new IscDbHandle instance specific to the implementation of this interface.

Returns:

instance of IscDbHandle

public IscStmtHandle createIscStmtHandle()

Factory method to create a new IscStmtHandle instance specific to the implementation of this interface.

Returns:

A new IscStmtHandle instance

public IscSvcHandle createIscSvcHandle()

Factory method to create a new IscSvcHandle instance that is linked to the current GDS implemenation.

Returns:

A new IscSvcHandle instance

public IscTrHandle createIscTrHandle()

Factory method to create a new IscTrHandle instance that is linked to the current GDS implementation.

Returns:

A new IscTrHandle instance

public ServiceParameterBuffer createServiceParameterBuffer()

Create a new ServiceParameterBuffer instance for setting service parameters in the current GDS implementation.

Returns:

a new ServiceParameterBuffer

public ServiceRequestBuffer createServiceRequestBuffer(int taskIdentifier)

Create a new ServiceRequestBuffer instance for setting service request parameters in the current GDS implementation. The returned ServiceRequestBuffer is linked to a specific Services API task, and must be one of the isc_info_svc_* or isc_action_svc constants from ISCConstants.

Parameters:

taskIdentifier - The specific Services API task for which the ServiceRequestBuffer is created

Returns:

A new ServiceRequestBuffer

public void getSqlCounts(IscStmtHandle stmt)
            throws GDSException

Fetch count information for a statement. The count information that is retrieved includes counts for all CRUD operations, and is set in the handle itself.

Parameters:

stmt - Handle to the statement for which count data is to be retrieved

Throws:

GDSException - if an error occurs while retrieving the count data

public void iscAttachDatabase(String fileName,
                              IscDbHandle dbHandle,
                              DatabaseParameterBuffer databaseParameterBuffer)
            throws GDSException

Attach to an existing database via a filename.

Parameters:

fileName - The filename for the database, including host and port. The expected format is <host name>/<port>:<file path>. The value for host is localhost if not supplied. The value for port is 3050 if not supplied.

dbHandle - The handle to attach to the database

databaseParameterBuffer - parameters for the database attachment

Throws:

GDSException - if an error occurs while attaching to the database

public byte[] iscBlobInfo(IscBlobHandle handle,
                          byte[] items,
                          int bufferLength)
            throws GDSException

Retrieve data about an existing blob. The parameters to be retrieved are placed in items, and the corresponding values are returned. The values in items should be isc_info_blob_* constants from ISCConstants.

Parameters:

handle - Handle to the blob for which data is to be retrieved

items - Parameters to be fetched about the blob

bufferLength - Length of the byte array to be returned

Returns:

Data corresponding to the parameters requested in items

Throws:

GDSException - if an error occurs while fetching data about the blob

public void iscCancelEvents(IscDbHandle dbHandle,
                            EventHandle eventHandle)
            throws GDSException

Cancel event listening based on an EventHandle.

Parameters:

dbHandle - Handle to the database where events are being listened for

eventHandle - Datastructure for handling event data

Throws:

GDSException - If a database communication error occurs

public void iscCloseBlob(IscBlobHandle blob)
            throws GDSException

Close an open blob.

Parameters:

blob - Handle to the blob to be closed

Throws:

GDSException - if an error occurs while closing the blob

public void iscCommitRetaining(IscTrHandle trHandle)
            throws GDSException

public void iscCommitTransaction(IscTrHandle trHandle)
            throws GDSException

Commit a transaction.

Parameters:

trHandle - Handle to the transaction to be committed.

Throws:

GDSException - if an error occurs while committing the transaction

See Also:

iscRollbackTransaction(IscTrHandle)

public void iscCreateBlob2(IscDbHandle db,
                           IscTrHandle tr,
                           IscBlobHandle blob,
                           BlobParameterBuffer blobParameterBuffer)
            throws GDSException

Create a new blob within a given transaction.

Parameters:

db - Handle to the database in which the blob will be created

tr - Handle to the transaction in which the blob will be created

blob - Handle to be attached to the newly created blob

blobParameterBuffer - contains parameters for creation of the new blob, can be null

Throws:

GDSException - if an error occurs while creating the blob

public void iscCreateDatabase(String fileName,
                              IscDbHandle dbHandle,
                              DatabaseParameterBuffer databaseParameterBuffer)
            throws GDSException

Create a database based on the supplied filename and database parameters. The supplied IscDbHandle is attached to the newly created database.

Parameters:

fileName - The filename for the new database, including host and port. The expected format is host:port:filepath. The value for host is localhost if not supplied. The value for port is 3050 if not supplied.

dbHandle - The handle to attach to the new database

databaseParameterBuffer - The parameters for the new database and attachment to it

Throws:

GDSException - if an error occurs while creating the database

public byte[] iscDatabaseInfo(IscDbHandle dbHandle,
                              byte[] items,
                              int bufferLength)
            throws GDSException

Get information about the database to which IscDbHandle is attached. The requested parameters are values set in items, and the values in the returned byte-array correspond to the requested parameters in items

Parameters:

dbHandle - Handle to the database for which info is to be retrieved

items - An array of values from the isc_info_* constant fields from ISCConstants

bufferLength - The size of the byte array that is to be returned

Returns:

array of bytes whose values correspond the requested parameters in items

Throws:

GDSException - if an error occurs while retrieving database info

public void iscDetachDatabase(IscDbHandle dbHandle)
            throws GDSException

Detach the given database handle from its database. This effectively closes the connection to the database.

Parameters:

dbHandle - The handle to be detached

Throws:

GDSException - if an error occurs while detaching from the database

public void iscDropDatabase(IscDbHandle dbHandle)
            throws GDSException

Drop (delete) the database to which IscDbHandle is attached.

Parameters:

dbHandle - Handle to the database to be dropped

Throws:

GDSException - if an error occurs while dropping the database

public void iscDsqlAllocateStatement(IscDbHandle dbHandle,
                                     IscStmtHandle stmtHandle)
            throws GDSException

Allocate a dynamic SQL (DSQL) statement on the database to which IscDbHandle is attached.

Parameters:

dbHandle - Handle to the database where the statement is to be allocated

stmtHandle - Handle to attach to the newly allocated statement

Throws:

GDSException - if an error occurs while allocating the statement

public XSQLDA iscDsqlDescribe(IscStmtHandle stmtHandle,
                              int daVersion)
            throws GDSException

Retrieve data for a statement.

Parameters:

stmtHandle - Handle to the statement about which data is to be retrieved

daVersion - Version of the XSQLDA to be retrieved

Returns:

data for the given statement

Throws:

GDSException - if an error occurs while retrieving statement data

public XSQLDA iscDsqlDescribeBind(IscStmtHandle stmtHandle,
                                  int daVersion)
            throws GDSException

Retrieve data for a bind statement.

Parameters:

stmtHandle - Handle to the bind statement about which bind data is to be retrieved

daVersion - Version of the XSQLDA to be retrieved

Returns:

data for the given bind statement

Throws:

GDSException - if an error occurs while retrieving statement data

public void iscDsqlExecImmed2(IscDbHandle dbHandle,
                              IscTrHandle trHandle,
                              String statement,
                              String encoding,
                              int dialect,
                              XSQLDA inXSQLDA,
                              XSQLDA outXSQLDA)
            throws GDSException

Deprecated. use iscDsqlExecImmed2(IscDbHandle,IscTrHandle,byte[],int,XSQLDA,XSQLDA)

public void iscDsqlExecImmed2(IscDbHandle dbHandle,
                              IscTrHandle trHandle,
                              String statement,
                              int dialect,
                              XSQLDA inXSQLDA,
                              XSQLDA outXSQLDA)
            throws GDSException

Execute a string SQL statement directly, without first allocating a statement handle. Data is retrieved using this method.

Parameters:

dbHandle - Handle to the database where the statement is to be executed

trHandle - Handle to the transaction in which the statement is to be executed

statement - byte array holding the SQL to be executed

dialect - Interbase dialect for the SQL, should be one of the SQL_DIALECT_* constants from ISCConstants

inXSQLDA - Data to be sent to the database for the statement

outXSQLDA - Placeholder for data retrieved from executing the SQL statement

Throws:

GDSException - if an error occurs while executing the statement

public void iscDsqlExecImmed2(IscDbHandle dbHandle,
                              IscTrHandle trHandle,
                              byte[] statement,
                              int dialect,
                              XSQLDA inXSQLDA,
                              XSQLDA outXSQLDA)
            throws GDSException

Execute a string SQL statement directly, without first allocating a statement handle. Output data from executing the statement is stored in outXSQLDA.

Parameters:

dbHandle - Handle to the database where the statement is to be executed

trHandle - Handle to the transaction in which the statement is to be executed

statement - byte array holding the SQL to be executed

dialect - Interbase dialect for the SQL, should be one of the SQL_DIALECT_* constants from ISCConstants

inXSQLDA - Data to be sent to the database for the statement

outXSQLDA - Holder for data retrieved from the database

Throws:

GDSException - if an error occurs while executing the statement

public void iscDsqlExecute(IscTrHandle trHandle,
                           IscStmtHandle stmtHandle,
                           int daVersion,
                           XSQLDA xsqlda)
            throws GDSException

Execute a statement with only outgoing data.

Parameters:

trHandle - Handle to the transaction in which the statement is to be executed

stmtHandle - Handle to the statement to be executed

daVersion - Version of XSQLDA to be used

xsqlda - Input data for executing the statement

Throws:

GDSException - if an error occurs while executing the statement

public void iscDsqlExecute2(IscTrHandle trHandle,
                            IscStmtHandle stmtHandle,
                            int daVersion,
                            XSQLDA inXSQLDA,
                            XSQLDA outXSQLDA)
            throws GDSException

Execute a statement with outgoing and incoming data.

Parameters:

trHandle - Handle to the transaction in which the statement is to be executed

stmtHandle - Handle to the statement to be executed

daVersion - Version of XSQLDA to be used

inXSQLDA - Data to be sent to the database for the statement

outXSQLDA - Holder for data to be received from executing the statement

Throws:

GDSException - if an error occurs while executing the statement

public void iscDsqlExecuteImmediate(IscDbHandle dbHandle,
                                    IscTrHandle trHandle,
                                    String statement,
                                    String encoding,
                                    int dialect,
                                    XSQLDA xsqlda)
            throws GDSException

Deprecated. use iscDsqlExecuteImmediate(IscDbHandle,IscTrHandle,byte[],int,XSQLDA)

public void iscDsqlExecuteImmediate(IscDbHandle dbHandle,
                                    IscTrHandle trHandle,
                                    String statement,
                                    int dialect,
                                    XSQLDA xsqlda)
            throws GDSException

Execute a string SQL statement directly, without first allocating a statement handle. No data is retrieved using this method.

Parameters:

dbHandle - Handle to the database where the statement is to be executed

trHandle - Handle to the transaction in which the statement is to be executed

statement - SQL command to be executed

dialect - Interbase dialect for the SQL, should be one of the SQL_DIALECT_* constants from ISCConstants

xsqlda - Data to be sent to the database for the statement

Throws:

GDSException - if an error occurs while executing the statement

public void iscDsqlExecuteImmediate(IscDbHandle dbHandle,
                                    IscTrHandle trHandle,
                                    byte[] statement,
                                    int dialect,
                                    XSQLDA xsqlda)
            throws GDSException

Execute a string SQL statement directly, without first allocating a statement handle. No data is retrieved using this method.

Parameters:

dbHandle - Handle to the database where the statement is to be executed

trHandle - Handle to the transaction in which the statement is to be executed

statement - byte array holding the SQL to be executed

dialect - Interbase dialect for the SQL, should be one of the SQL_DIALECT_* constants from ISCConstants

xsqlda - Data to be sent to the database for the statement

Throws:

GDSException - if an error occurs while executing the statement

public void iscDsqlFetch(IscStmtHandle stmt_handle,
                         int daVersion,
                         XSQLDA xsqlda,
                         int fetchSize)
            throws GDSException

Retrieve record data from a statement. A maximum of fetchSize records will be fetched.

Parameters:

stmt_handle - Handle to the statement for which records are to be fetched

daVersion - Version of XSQLDA to be used

xsqlda - Holder for records that are fetched

fetchSize - The maximum number of records to be fetched

Throws:

GDSException - if an error occurs while fetching the records

public void iscDsqlFreeStatement(IscStmtHandle stmtHandle,
                                 int option)
            throws GDSException

Free a statement in the database that is pointed to by a valid handle. The statement can be closed or fully deallocated, depending on the value of option. option should be one of ISCConstants.DSQL_drop or ISCConstants.DSQL_close.

Parameters:

stmtHandle - Handle to the statement to be freed

option - Option to be used when freeing the statement. If the value is ISCConstants.DSQL_drop, the statement will be deallocated, if the value is ISCConstants.DSQL_close, the statement will only be closed

public XSQLDA iscDsqlPrepare(IscTrHandle trHandle,
                             IscStmtHandle stmtHandle,
                             String statement,
                             String encoding,
                             int dialect)
            throws GDSException

Deprecated. use iscDsqlPrepare(IscTrHandle,IscStmtHandle,byte[],int)

public XSQLDA iscDsqlPrepare(IscTrHandle trHandle,
                             IscStmtHandle stmtHandle,
                             String statement,
                             int dialect)
            throws GDSException

Prepare a string SQL statement for execution in the database.

Parameters:

trHandle - Handle to the transaction in which the SQL statement is to be prepared

stmtHandle - Handle to the statement for which the SQL is to be prepared

statement - The SQL statement to be prepared

dialect - Interbase dialect for the SQL, should be one of the SQL_DIALECT_* constants from ISCConstants

Returns:

A datastructure with data about the prepared statement

Throws:

GDSException - if an error occurs while preparing the SQL

public XSQLDA iscDsqlPrepare(IscTrHandle trHandle,
                             IscStmtHandle stmtHandle,
                             byte[] statement,
                             int dialect)
            throws GDSException

Prepare a string SQL statement for execution in the database.

Parameters:

trHandle - Handle to the transaction in which the SQL statement is to be prepared

stmtHandle - Handle to the statement for which the SQL is to be prepared

statement - byte-array with containing the SQL to be prepared

dialect - Interbase dialect for the SQL, should be one of the SQL_DIALECT_* constants from ISCConstants

Returns:

A datastructure with data about the prepared statement

Throws:

GDSException - if an error occurs while preparing the SQL

public void iscDsqlSetCursorName(IscStmtHandle stmtHandle,
                                 String cursorName,
                                 int type)
            throws GDSException

Set the name to be used for a given statement.

Parameters:

stmtHandle - Handle to the statement for which the cursor name is to be set

cursorName - Name to set for the cursor

type - Reserved for future use

Throws:

GDSException - if an error occurs while setting the cursor name

public byte[] iscDsqlSqlInfo(IscStmtHandle stmtHandle,
                             byte[] items,
                             int bufferLength)
            throws GDSException

Retrieve data about a statement. The parameters that are requested are defined by the isc_info_sql_* constants defined in ISCConstants. An array with corresponding values for the requested parameters is returned.

Parameters:

stmtHandle - Handle to the statement about which data is to be retrieved

items - Array of parameters whose values are to be retrieved

bufferLength - The length of the byte-array to be returned

Returns:

An array of values corresponding to the requested parameters

Throws:

GDSException - if an error occurs while retrieving the statement info

public void iscEventBlock(EventHandle eventHandle)
            throws GDSException

Initialize the internal databastructures for an EventHandle.

Parameters:

eventHandle - The event handle to be initialized

Throws:

GDSException - If a database communication error occurs

public void iscEventCounts(EventHandle eventHandle)
            throws GDSException

Retrieve count information after an event has occurred.

Parameters:

eventHandle - The handle containing event data

Throws:

GDSException - If a database communication error occurs

public byte[] iscGetSegment(IscBlobHandle blob,
                            int maxread)
            throws GDSException

Fetch a segment of a blob.

Parameters:

blob - Handle to the blob from which a segment is to be fetched

maxread - The maximum number of bytes to attempt to fetch

Returns:

A segment of data from the blob, with maximum length of maxread

Throws:

GDSException - if an error occurs while fetching the blob segment

public void iscOpenBlob2(IscDbHandle db,
                         IscTrHandle tr,
                         IscBlobHandle blob,
                         BlobParameterBuffer blobParameterBuffer)
            throws GDSException

Open a blob within a given transaction.

Parameters:

db - Handle to the database in which the blob will be opened

tr - Handle to the transaction in which the blob will be opened

blob - Handle to the blob to be opened

blobParameterBuffer - Contains parameters for the blob

Throws:

GDSException - if an error occurs while opening the blob

public void iscPrepareTransaction(IscTrHandle trHandle)
            throws GDSException

public void iscPrepareTransaction2(IscTrHandle trHandle,
                                   byte[] bytes)
            throws GDSException

public void iscPutSegment(IscBlobHandle blob_handle,
                          byte[] buffer)
            throws GDSException

Write a segment of data to a blob.

Parameters:

blob_handle - Handle to the blob to which data is to be written

buffer - Data to be written to the blob

Throws:

GDSException - if an error occurs while writing to the blob

public int iscQueueEvents(IscDbHandle dbHandle,
                          EventHandle eventHandle,
                          EventHandler eventHandler)
            throws GDSException

Queue an EventHandler.

Parameters:

dbHandle - Handle to the database where events are to be listened for

eventHandle - Handle for event management

eventHandler - Callback to be called when an event occurs

Throws:

GDSException - If a database communication error occurs

public void iscReconnectTransaction(IscTrHandle trHandle,
                                    IscDbHandle dbHandle,
                                    long transactionId)
            throws GDSException

Reconnect "in limbo" transaction using new database handle.

Parameters:

trHandle - transaction handle that will be reconnected.

dbHandle - database handle in which "in limbo" transaction will be reconnected.

transactionId - ID of the transaction to reconnect.

Throws:

GDSException - if something went wrong.

public void iscRollbackRetaining(IscTrHandle trHandle)
            throws GDSException

public void iscRollbackTransaction(IscTrHandle trHandle)
            throws GDSException

Rollback a transaction.

Parameters:

trHandle - Handle to the transaction that is to be rolled back

Throws:

GDSException - if an error occurs while rolling back

See Also:

iscCommitTransaction(IscTrHandle)

public void iscSeekBlob(IscBlobHandle handle,
                        int position,
                        int seekMode)
            throws GDSException

Seek to a given position in a blob. seekMode is used in the same way as the system fseek call, i.e.:

• 0 - seek relative to the start of the blob
• 1 - seek relative to the current position in the blob
• 2 - seek relative to the end of the blob

position is the offset number of bytes to seek to, relative to the position described by seekMode. Seeking can only be done in a forward direction.

Parameters:

handle - Handle to the blob for which seeking will be done

position - The offset number of bytes to seek to

seekMode - Describes the base point to be used in seeking, should be negative if seekMode is equal to 2

Throws:

GDSException - if an error occurs while seeking

public void iscServiceAttach(String service,
                             IscSvcHandle serviceHandle,
                             ServiceParameterBuffer serviceParameterBuffer)
            throws GDSException

Attach to a Service Manager.

Parameters:

service - The name/path to the service manager

serviceHandle - Handle to be linked to the attached service manager

serviceParameterBuffer - Contains parameters for attaching to the service manager

Throws:

GDSException - if an error occurs while attaching

public void iscServiceDetach(IscSvcHandle serviceHandle)
            throws GDSException

Detach from a Service Manager.

Parameters:

serviceHandle - Handle to the service manager that is to be detached

Throws:

GDSException - if an error occurs while detaching

public void iscServiceQuery(IscSvcHandle serviceHandle,
                            ServiceParameterBuffer serviceParameterBuffer,
                            ServiceRequestBuffer serviceRequestBuffer,
                            byte[] resultBuffer)
            throws GDSException

Query a service manager

Parameters:

serviceHandle - Handle to the service manager to be queried

serviceParameterBuffer - parameters about the service

serviceRequestBuffer - parameters requested in the query

resultBuffer - buffer to hold the query results

Throws:

GDSException - if an error occurs while querying

public void iscServiceStart(IscSvcHandle serviceHandle,
                            ServiceRequestBuffer serviceRequestBuffer)
            throws GDSException

Start a service operation.

Parameters:

serviceHandle - Handle to the service manager where the operation is to be started

serviceRequestBuffer - parameters about the service to be started

public void iscStartTransaction(IscTrHandle trHandle,
                                IscDbHandle dbHandle,
                                TransactionParameterBuffer tpb)
            throws GDSException

Start a transaction based on a handle to a transaction.

Parameters:

trHandle - Handle to the transaction that is to be started

dbHandle - Handle to the database in which the transaction is to be started

tpb - Transaction Parameter Block in the form of a byte array, contains parameter data for the transaction attributes

Throws:

GDSException - if an error occurs while starting the transaction

See Also:

createIscTrHandle()

public byte[] iscTransactionInformation(IscTrHandle trHandle,
                                        byte[] requestBuffer,
                                        int bufferLen)
            throws GDSException

public TransactionParameterBuffer newTransactionParameterBuffer()

Create new TransactionParameterBuffer instance for setting transaction parameters in the current GDS implementation.

Returns:

A new TransactionParameterBuffer.