Prev Class | Next Class | Frames | No Frames |
Summary: Nested | Field | Method | Constr | Detail: Nested | Field | Method | Constr |
public interface GDS
GDS
has most of the C client interface functions
lightly mapped to java, as well as the constants returned from the server.
Method Summary | |
void |
|
BlobParameterBuffer |
|
DatabaseParameterBuffer |
|
EventHandle |
|
IscBlobHandle |
|
IscDbHandle |
|
IscStmtHandle |
|
IscSvcHandle |
|
IscTrHandle |
|
ServiceParameterBuffer |
|
ServiceRequestBuffer |
|
void |
|
void |
|
byte[] |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
byte[] |
|
void |
|
void |
|
void |
|
XSQLDA |
|
XSQLDA |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
XSQLDA |
|
XSQLDA |
|
XSQLDA |
|
void |
|
byte[] |
|
void |
|
void |
|
byte[] |
|
void |
|
void |
|
void |
|
void |
|
int |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
byte[] |
|
int |
|
TransactionParameterBuffer |
|
public void close()
Close this GDS instance.
public BlobParameterBuffer createBlobParameterBuffer()
Create a newBlobParameterBuffer
instance for setting blob parameters in the current GDS implementation.
- Returns:
- A new
BlobParameterBuffer
public DatabaseParameterBuffer createDatabaseParameterBuffer()
Create a newDatabaseParameterBuffer
instance for setting database parameters in the current GDS implementation.
- Returns:
- A new
DatabaseParameterBuffer
public EventHandle createEventHandle(String eventName)
Create a newEventHandle
specific to a givenGDS
implementation.
- Returns:
- The newly created
EventHandle
public IscBlobHandle createIscBlobHandle()
Factory method to create a newIscBlobHandle
instance specific to the implementation of this interface.
- Returns:
- A new
IscBlobHandle
instance
public IscDbHandle createIscDbHandle()
Factory method to create a newIscDbHandle
instance specific to the implementation of this interface.
- Returns:
- instance of
IscDbHandle
public IscStmtHandle createIscStmtHandle()
Factory method to create a newIscStmtHandle
instance specific to the implementation of this interface.
- Returns:
- A new
IscStmtHandle
instance
public IscSvcHandle createIscSvcHandle()
Factory method to create a newIscSvcHandle
instance that is linked to the currentGDS
implemenation.
- Returns:
- A new
IscSvcHandle
instance
public IscTrHandle createIscTrHandle()
Factory method to create a newIscTrHandle
instance that is linked to the currentGDS
implementation.
- Returns:
- A new
IscTrHandle
instance
public ServiceParameterBuffer createServiceParameterBuffer()
Create a newServiceParameterBuffer
instance for setting service parameters in the current GDS implementation.
- Returns:
- a new
ServiceParameterBuffer
public ServiceRequestBuffer createServiceRequestBuffer(int taskIdentifier)
Create a newServiceRequestBuffer
instance for setting service request parameters in the current GDS implementation. The returnedServiceRequestBuffer
is linked to a specific Services API task, and must be one of theisc_info_svc_*
orisc_action_svc
constants fromISCConstants
.
- Parameters:
taskIdentifier
- The specific Services API task for which theServiceRequestBuffer
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 databasedatabaseParameterBuffer
- 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 initems
, and the corresponding values are returned. The values initems
should beisc_info_blob_*
constants fromISCConstants
.
- Parameters:
handle
- Handle to the blob for which data is to be retrieveditems
- Parameters to be fetched about the blobbufferLength
- 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 anEventHandle
.
- Parameters:
dbHandle
- Handle to the database where events are being listened foreventHandle
- 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 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 createdtr
- Handle to the transaction in which the blob will be createdblob
- Handle to be attached to the newly created blobblobParameterBuffer
- 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 suppliedIscDbHandle
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 databasedatabaseParameterBuffer
- 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 whichIscDbHandle
is attached. The requested parameters are values set initems
, and the values in the returned byte-array correspond to the requested parameters initems
- Parameters:
dbHandle
- Handle to the database for which info is to be retrieveditems
- An array of values from theisc_info_*
constant fields fromISCConstants
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 whichIscDbHandle
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 whichIscDbHandle
is attached.
- Parameters:
dbHandle
- Handle to the database where the statement is to be allocatedstmtHandle
- 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 retrieveddaVersion
- 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 retrieveddaVersion
- 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 executedtrHandle
- Handle to the transaction in which the statement is to be executedstatement
- byte array holding the SQL to be executeddialect
- Interbase dialect for the SQL, should be one of theSQL_DIALECT_*
constants fromISCConstants
inXSQLDA
- Data to be sent to the database for the statementoutXSQLDA
- 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 executedtrHandle
- Handle to the transaction in which the statement is to be executedstatement
- byte array holding the SQL to be executeddialect
- Interbase dialect for the SQL, should be one of theSQL_DIALECT_*
constants fromISCConstants
inXSQLDA
- Data to be sent to the database for the statementoutXSQLDA
- 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 executedstmtHandle
- Handle to the statement to be executeddaVersion
- Version of XSQLDA to be usedxsqlda
- 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 executedstmtHandle
- Handle to the statement to be executeddaVersion
- Version of XSQLDA to be usedinXSQLDA
- Data to be sent to the database for the statementoutXSQLDA
- 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 executedtrHandle
- Handle to the transaction in which the statement is to be executedstatement
- SQL command to be executeddialect
- Interbase dialect for the SQL, should be one of theSQL_DIALECT_*
constants fromISCConstants
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 executedtrHandle
- Handle to the transaction in which the statement is to be executedstatement
- byte array holding the SQL to be executeddialect
- Interbase dialect for the SQL, should be one of theSQL_DIALECT_*
constants fromISCConstants
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 offetchSize
records will be fetched.
- Parameters:
stmt_handle
- Handle to the statement for which records are to be fetcheddaVersion
- Version of XSQLDA to be usedxsqlda
- Holder for records that are fetchedfetchSize
- 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 ofoption
.option
should be one ofISCConstants.DSQL_drop
orISCConstants.DSQL_close
.
- Parameters:
stmtHandle
- Handle to the statement to be freedoption
- Option to be used when freeing the statement. If the value isISCConstants.DSQL_drop
, the statement will be deallocated, if the value isISCConstants.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 preparedstmtHandle
- Handle to the statement for which the SQL is to be preparedstatement
- The SQL statement to be prepareddialect
- Interbase dialect for the SQL, should be one of theSQL_DIALECT_*
constants fromISCConstants
- 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 preparedstmtHandle
- Handle to the statement for which the SQL is to be preparedstatement
- byte-array with containing the SQL to be prepareddialect
- Interbase dialect for the SQL, should be one of theSQL_DIALECT_*
constants fromISCConstants
- 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 setcursorName
- Name to set for the cursortype
- 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 theisc_info_sql_*
constants defined inISCConstants
. An array with corresponding values for the requested parameters is returned.
- Parameters:
stmtHandle
- Handle to the statement about which data is to be retrieveditems
- Array of parameters whose values are to be retrievedbufferLength
- 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 anEventHandle
.
- 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 fetchedmaxread
- 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 openedtr
- Handle to the transaction in which the blob will be openedblob
- Handle to the blob to be openedblobParameterBuffer
- Contains parameters for the blob
- Throws:
GDSException
- if an error occurs while opening the blob
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 writtenbuffer
- 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 foreventHandle
- Handle for event managementeventHandler
- 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 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 byseekMode
. Seeking can only be done in a forward direction.
- Parameters:
handle
- Handle to the blob for which seeking will be doneposition
- The offset number of bytes to seek toseekMode
- Describes the base point to be used in seeking, should be negative ifseekMode
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 managerserviceHandle
- Handle to be linked to the attached service managerserviceParameterBuffer
- 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 queriedserviceParameterBuffer
- parameters about the serviceserviceRequestBuffer
- parameters requested in the queryresultBuffer
- 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 startedserviceRequestBuffer
- 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 starteddbHandle
- Handle to the database in which the transaction is to be startedtpb
- 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 int iscVaxInteger(byte[] buffer, int pos, int length)
Retrieve an integer value from a sequence of bytes.
- Parameters:
buffer
- The byte array from which the integer is to be retrievedpos
- The offset starting position from which to start retrieving byte valueslength
- The number of bytes to use in retrieving the integer value.
- Returns:
- The integer value retrieved from the bytes
public TransactionParameterBuffer newTransactionParameterBuffer()
Create newTransactionParameterBuffer
instance for setting transaction parameters in the current GDS implementation.
- Returns:
- A new
TransactionParameterBuffer
.