|
FrontBase Documentation |
|
|
|
FrontBase Documentation |
|
|
Backtrack: Welcome! 6. Original Documentation 6.7. FBAccess API |
Updated:
20-Nov-2000
prev — next Table of Contents |
This class is available by including FBAccess/FBDatabaseConnection.h.
Class Methods
connectToDatabaseNamed:onHost:password:
+ (FBDatabaseConnection *) connectToDatabaseNamed :(NSString *) dbName onHost:(NSString *) host password:(NSString *) password
connectToDatabaseNamed creates a so-called agent object which controls the access to the actual FrontBase server. An agent can have many so-called connections or sessions, of which only one can be active at a given time. Agent objects are cached by FBDatabaseConnection, i.e. multiple calls to connectToDatabaseNamed will return the same agent object (no need to do retain/release).
connectToDatabaseNamed:onHost:
+ (FBDatabaseConnection *) connectToDatabaseNamed :(NSString *) dbName onHost:(NSString *) host
Invokes connectToDatabaseNamed:onHost:password with @"" as password.
errorMessage
+ (NSString *) errorMessage
errorMessage may provide an explanation for why a connectToDatabaseNamed:: failed, i.e. nil was returned.
FBDCConnectionWillTerminate
+ (NSString *) FBDCConnectionWillTerminate
Use this when adding observers for connection termination.
setRollbackAfterError:
+ (void) setRollbackAfterError:(BOOL) flag
Sets the value that will be used for all future CONNECTions (in this application), no matter the database and host. The default is YES.
setShareDatabaseConnections:
+ (void) setShareDatabaseConnections:(BOOL) aFlag
If YES, connections to the same database on the same host will be shared, i.e. you don't need to worry about retain/release. If NO, the connections will not be shared, i.e. you need to retain/release the connections. The default is to shared connections.
Instance Methods
buildDecimalNumber:
- (NSDecimalNumber *) buildDecimalNumber:(int) dataSize :(unsigned char *) rawPtr
Transforms the raw data into a decimal number. Please note that BLOB and CLOB column values are returned in one of two ways depending on their size:
A given column value can be tested upon like: [columnValue class] == [FBBlobHandle class].
Size < "a given threshold value" => NSData for BLOB and NSString for CLOB T => FBBlobHandle
Use readBLOB: respectively readCLOB: to read the actual content that a blob handle represents.
buildDoubleFromDecimalNumber:
- (double) buildDoubleFromDecimalNumber:(int) dataSize :(unsigned char *) rawPtr
Transforms the raw data into a double.
buildRowsFrom:
- (NSArray *) buildRowsFrom:(NSData *) rawData
Transforms the raw data into an array of array, i.e. an array of rows. Please note that BLOB and CLOB column values are returned in one of two ways depending on their size:
A given column value can be tested upon like: [columnValue class] == [FBBlobHandle class].
Size < "a given threshold value" => NSData for BLOB and NSString for CLOB T => FBBlobHandle
Use readBLOB: respectively readCLOB: to read the actual content that a blob handle represents.
cancelFetch:
- (FBMetaData *) cancelFetch:(NSString *) handleID
To free up resources on the server side, cancelFetch is to be called as soon as possible. An easy way to get meta data about a table is actually to do a SELECT:
FBMetaData *md;
md = [connection executeDirectSQL:@"TABLE aTable"]; ..., use of [md columnCount], [md rowCount], .. md = [connection cancelFetch:[md fetchHandle]];
close
- (void) close
The proper way to close a connection to a server.
commit
- (FBMetaData *) commit
Shorthand for [connection executeDirectSQL:@"COMMIT;]";
connected
- (BOOL) connected
Returns YES if this agent is properly connected to a FrontBase server.
createSession:sessionUser:password:systemUser:
- (FBMetaData *) createSession:(NSString *) sessionId sessionUser:(NSString *) sessionUser password:(NSString *) password systemUser:(NSString *) systemUser
Creates a new session/connection (within this current agent). This implements the CONNECT TO <str1> AS <str2> USER <str3> statement (part of SQL 92).
databaseName
- (NSString *) databaseName
Returns the name of the database.
disconnect:
- (FBMetaData *) disconnect:(NSString *) sessionId
disconnectAll
- (FBMetaData *) disconnectAll
disconnectDefault
- (FBMetaData *) disconnectDefault
disconnectCurrent
- (FBMetaData *) disconnectCurrent
errorMessage
- (NSString *) errorMessage
Whenever a method doesn't return what you expected, this method may give an explanation.
errorMetaData
- (FBErrorMetaData *) errorMetaData
If an SQL statement caused some errors, this is the way to get at them.
executeDirectSQL:preFetch:into:
- (FBMetaData *) executeDirectSQL:(NSString *) sql preFetch:(unsigned) rowCount into:(NSData **) rawData
Effectively an efficient shorthand for executeDirectSQL: followed by fetch:handle: (saves one round-trip to the server). Instead of:
meta = [connection executeDirectSQL:@"SELECT ..."]; data = [connection fetch:rowCount handle:[meta fetchHandle]];Do:meta = [connection executeDirectSQL:@"SELECT ..." preFetch:rowCount into:&data];
Please note that the NSData object returned is autoreleased, i.e. you have to consider retaining it.
In both cases, data will be nil if errors were detected during execution of the SQL or if no rows can be fetched.
executeDirectSQL:
- (FBMetaData *) executeDirectSQL:(NSString *) sql
Sends the SQL command to the FrontBase server for execution. An autoreleased FBMetaData object is always returned. Via the FBMetaData object information relating to the execution of the SQL statement (error count, row count, column count etc.) can be obtained.
fetch:handle:
- (NSData *) fetch:(unsigned) rowCount handle:(NSString *) handleID
Fetching a number of rows, assuming that a SELECT of some sort has been executed successfully prior to this. The rows are returned in a very compact binary format, which can be unpacked by buildRowsFrom: (see below). fetch: can return less rows than asked for because of two reasons: 1) there are no more rows in the fetch data set, or 2) no more space in the buffer used when building the fetch result on the server side. fetch: can be called as many times as needed and will return nil when no more rows are available.
hostName
- (NSString *) hostName
Returns the name of the host.
newestMetaData
- (FBMetaData *) newestMetaData
If the reference to the meta data object from the last method that generated some meta data was lost, newestMetaData returns the newest generated meta data.
readBLOB:
- (NSData *) readBLOB:(FBBlobHandle *) aHandle
Read a BLOB. Example:
if ([value class] == [FBBlobHandle class]) data = [connection readBLOB:[value blobHandle]];
readCLOB:
- (NSString *) readCLOB:(FBBlobHandle *) aHandle
Read a CLOB. Example:
if ([value class] == [FBClobHandle class]) data = [connection readCLOB:[value blobHandle]];
rollback
- (FBMetaData *) rollback
Shorthand for [connection executeDirectSQL:@"ROLLBACK;"];
sessionID
- (NSString *) sessionID
Returns the current session id.
setConnection:
- (FBMetaData *) setConnection:(NSString *) sessionId Assigns a session id to a connection.
setConnectionToDefault
- (FBMetaData *) setConnectionToDefault
setDatabasePassword:
- (FBMetaData *) setDatabasePassword:(NSString *) newPassword
setDatabasePassword sets the database password. This requires that a connection/session has been established with _SYSTEM as the session user.
setPasswordForUser:to:old:
- (FBMetaData *) setPasswordForUser:(NSString *) userName to:(NSString *) newPassword old:(NSString *) oldPassword
Sets the password for the given user. If the session user is _SYSTEM, the old password is ignored.
setRollbackAfterError:
- (BOOL) setRollbackAfterError:(BOOL) flag
Sets the value that will be used for the current CONNECTion until changed. The default value is set via +setRollbackAfterError (which has YES as default).
setSessionID:
- (void) setSessionID:(NSString *) anID
Sets the default session id to be used when creating new sessions (within this agent), default is @"SessionID".
setSessionUser:password:systemUser:
- (FBMetaData *) setSessionUser:(NSString *) sessionUser password:(NSString *) password systemUser:(NSString *) systemUser
setSessionUser:systemUser:
- (FBMetaData *) setSessionUser:(NSString *) sessionUser systemUser:(NSString *) systemUser
Shorthand for -createSession:sessionUser:password:systemUser where the default session id is used.
stopDatabase
- (FBMetaData *) stopDatabase:
An effective way to stop a server:
connection = [FBDatabaseConnection connectToDatabaseNamed :@"DB0" onHost:@"tuborg"]; [connection stopDatabase];
writeBLOB:
- (FBBlobHandle *) writeBLOB:(NSData *) blobData
Write a BLOB to the database. The returned handle is to be used in the SQL in place of the actual BLOB value. Example:
bhandle = [connection writeBLOB:someData]; ... sql = [NSString stringWithFormat: @"INSERT INTO T0 VALUES(%@,...)", [bhandle handle], ...];
writeCHARACTER:
- (FBBlobHandle *) writeCHARACTER:(NSString *) aString
Write a string to the database. The returned handle is to be used in the SQL in place of the actual BLOB value. Example:
bhandle = [connection writeCHARACTER:aString]; ... sql = [NSString stringWithFormat: @"INSERT INTO T0 VALUES(%@,...)", [bhandle handle], ...];
writeCLOB:
- (FBBlobHandle *) writeCLOB:(NSString *) aString
Write a CLOB to the database. The returned handle is to be used in the SQL in place of the actual CLOB value. Example:
bhandle = [connection writeCLOB:someData]; ... sql = [NSString stringWithFormat: @"INSERT INTO T0 VALUES(%@,...)", [bhandle handle], ...];
If you have feedback or questions on this document, please send e-mail to doc-feedback@frontbase.com. Please reference the section number and topic. Thanks!!
©2000 FrontBase, Inc. All rights reserved.