Objective-C API Reference

This section focuses on the low-level OpenBase Objective-C interface through the OpenBase object. The OpenBase object provides the basis for all communication to OpenBase databases and is complementary to the Espresso interface which is built on top of it.

To use the OpenBase-SQL Objective-C library, you will need to include the OpenBaseAPI.framework in the frameworks section of your project. The OpenBase header file may be included in your program source by importing <OpenBaseAPI/OpenBase.h>.

beginTransaction:

Defined in <OpenBaseAPI/OpenBase.h>

- (BOOL)beginTransaction

Returns TRUE if the transaction started correctly. If an error is detected, FALSE is returned.
Objective-C Example:

OpenBase *connection;
...
if ([connection beginTransaction]) return SUCCEED;

ANSI C Example:

OpenBase *connection;
...
if (ob_beginTransaction(connection)) return SUCCEED;

See Also:
commitTransaction
rollback Transaction

bindDouble:

Defined in <OpenBaseAPI/OpenBase.h>

bindDouble:(double *)var
bindDouble:(double *)var column:(int)col;

bindDouble: binds the double variable var to the next result column. Each time a call to bindString:, bindInt:, bindDouble:, bindLong:, or bindLongLong: is made, the column pointer is incremented to the next column. You should make as many calls as needed to bind your program variables to all the columns in your query result.

bindDouble:column: binds the double variable var to the specific column col. col is an integer which counts from column 0.

These methods should be used after a query has been executed and results have been returned. Column values will automatically be converted to the target variable's type.

Objective-C Example:

OpenBase *connection;
double doubleValue;
...
[connection bindDouble:&doubleValue];

ANSI C Example:

OpenBase *connection;
double doubleValue;
...
ob_bindDouble(connection, &doubleValue);

C++ Example:

OpenBase *connection;
double doubleValue;
...
ob_bindDouble(connection, &doubleValue);

bindInt:

Defined in <OpenBaseAPI/OpenBase.h>

bindInt:(int *)var
bindInt:(int *)var column:(int)col;

bindInt: binds the integer variable var to the next result column. Each time a call to bindString:, bindInt:, bindDouble:, bindLong:, or bindLongLong: is made, the column pointer is incremented to the next column. You should make as many calls as needed to bind your program variables to all the columns in your query result.

bindInt:column: binds the character string variable var to the specific column col. col is an integer which counts from column 0.

These methods should be used after a query has been executed and results have been returned. Column values will automatically be converted to the target variable's type.

Objective-C Example:

OpenBase *connection;
int intValue;
...
[openbase bindInt:&intValue];

ANSI C Example:

OpenBase *connection;
int intValue;
...
ob_bindInt(connection, &intValue);

bindLong:

Defined in <OpenBaseAPI/OpenBase.h>

bindLong:(long *)var;
bindLong:(long *)var column:(int)col;

bindLong: binds the long integer variable var to the next result column. Each time a call to bindString:, bindInt:, bindDouble:, bindLong:, or bindLongLong: is made, the column pointer is incremented to the next column. You should make as many calls as needed to bind your program variables to all the columns in your query result.

bindLong:column: binds the long integer variable var to the specific column col. col is an integer which counts from column 0.

These methods should be used after a query has been executed and results have been returned. Column values will automatically be converted to the target variable's type.

Objective-C Example:

OpenBase *connection;
long longValue;
...
[connection bindLong:&longValue];

ANSI C Example:

OpenBase *connection;
long longValue;
...
ob_bindLong(connection, &longValue);

bindLongLong:

Defined in <OpenBaseAPI/OpenBase.h>

bindLongLong:(long long *)var;
bindLongLong:(long long *)var column:(int)col;

bindLongLong: binds the long long integer (64 bit) variable var to the next result column. Each time a call to bindString:, bindInt:, bindDouble:, bindLong:, or bindLongLong: is made, the column pointer is incremented to the next column. You should make as many calls as needed to bind your program variables to all the columns in your query result.

bindLongLong:column: binds the long long integer variable var to the specific column col. col is an integer which counts from column 0.

These methods should be used after a query has been executed and results have been returned. Column values will automatically be converted to the target variable's type.

Objective-C Example:

OpenBase *connection;
long long longlongValue;
...
[connection bindLongLong:&longlongValue];

ANSI C Example:

OpenBase *connection;
long long longlongValue;
...
    ob_bindLongLong(connection, &longlongValue);

bindString:

Defined in <OpenBaseAPI/OpenBase.h>

bindString:(const char *)var
bindString:(const char *)var column:(int)col;

bindString: binds the character string variable var to the next result column. Calls to bindString:, bindInt:, bindDouble:, bindLong:, or bindLongLong: causes the column pointer to increment to the next column. Make as many calls as needed to bind the program variables to all columns in the query result.

bindString:column: binds the character string variable var to the specific column col. col is an integer which counts from column 0.

Use these methods after a query has been executed with returned results. Column values will automatically be converted to the target variable's type.

Objective-C Example:

OpenBase *connection;
char firstname[ 256] , lastname[ 256] ;
[connection makeCommand: "select FIRST_NAME, LAST_NAME
from EMPLOYEE order by LAST_NAME"];
if (![ connection executeCommand] ) return; if (![ connection resultReturned] ) return;
[connection bindString:firstname]; [connection bindString:lastname];
while ([ connection nextRow] ) {
printf("%s, %s\n",lastname,firstname); }

ANSI C Example:

OpenBase *connection;
char firstname[ 256] , lastname[ 256] ;
ob_makeCommand(connection, "select FIRST_NAME, LAST_NAME
from EMPLOYEE order by LAST_NAME");
if (!ob_executeCommand(connection)) return; if (!ob_resultReturned(connection)) return;
ob_bindString(connection, firstname); ob_bindString(connection, lastname);
while (ob_nextRow(connection)) { printf("%s, %s\n",lastname,firstname); }

bufferHasCommands

Defined in <OpenBaseAPI/OpenBase.h>

- (BOOL)bufferHasCommands

Returns TRUE if unexecuted commands are in the command buffer, FALSE otherwise.

Objective-C Example:

OpenBase *connection;
...
if ([ connection bufferHasCommands] ) return SUCCEED;

ANSI C Example:

OpenBase *connection;
...
if (ob_bufferHasCommands(connection)) return SUCCEED;

clearCommands

Defined in <OpenBaseAPI/OpenBase.h>

- clearCommands;

Clears the command buffer. This method removes any unexecuted commands from the command buffer.

Objective-C Example:

OpenBase *connection; ...
[ connection clearCommands] ;

ANSI C Example:

OpenBase *connection; ...
ob_clearCommands(connection);

commandBuffer

Defined in <OpenBaseAPI/OpenBase.h>

- (const char *)commandBuffer;

This method is used to look at SQL commands in the command buffer. The buffer will return the most current SQL command.

Returns the contents of the command buffer.

Objective-C Example:

OpenBase *connection; ...
prinf (" %s\ n", [ connection commandBuffer] );

ANSI C Example:

OpenBase *connection; ...
printf (" %s\ n", ob_commandBuffer (connection) );

commitTransaction

Defined in <OpenBaseAPI/OpenBase.h>

- (BOOL)commitTransaction;

Returns TRUE if the transaction committed to the database. If an error is detected, FALSE is returned.

Objective-C Example:

OpenBase *connection; ...
if ([connection commitTransaction]) return SUCCEED;

ANSI C Example:

OpenBase *connection;
...
if (ob_commitTransaction(connection)) return SUCCEED;

connectErrorMessage:

Defined in <OpenBaseAPI/OpenBase.h>

- (const char *)connectErrorMessage:(int)errorCode

Returns an error message corresponding to the error code errorCode set by connectToDatabase:onHost:login:password:return:.

Objective-C Example:

OpenBase *connection;
int errorNum;
...
prinf (" %s\ n", [ connection
connectErrorMessage:errorNum]);

ANSI C Example:

OpenBase *connection;
...
printf("%s\n", ob_connectErrorMessage(connection, errorNum));

connectToDatabase: onHost: login : password:return:

Defined in <OpenBaseAPI/OpenBase.h>

- (BOOL)connectToDatabase:(const char *)dbName
onHost:(const char *)hostName login:(const char *)loginName
password:(const char*)password return:(int*)returnCode;

This method initializes a program's connection to a OpenBase database. Upon success, this method returns TRUE. Otherwise it returns FALSE. The parameters are described as follows:

dbName the name of the database that you would like to connect to.

• hostName the host name of the computer where the database resides. A “*”; may be substituted to search the network for the designed database. An empty string specifies that the database is on the local computer.

• loginName the name that the user uses to log into the database. In order for the initialization to be successful, this login name must correspond to an entry in the user table.

password the password corresponding to the login name.

returnCode one of the following values:

ERR_SFTUSRLIM means that the software license limit has been reached.

ERR_DBSUSRLIM means that the OpenBase licensed user limit has been reached.

ERR_NOSERVER means that the server is not running.

ERR_INCORRECT_LOGIN means that the user login and password were not correct.

This method performs the initialization necessary to work with the database. You can not use the OpenBase object before it has been initialized using this method.

- (BOOL)connectToDatabase:(const char *)dbName
onHost:(const char *)hostName login:(const char *)loginName password:(const char *)password return:(int *)returnCode;

Objective-C Example:

OpenBase *connection; char dbase[ 50] ; char host[ 50] ;
char login[ 50] ; char passwd[ 50] ; int errorNum;
...
if ([connection connectToDatabase:dbase
onHost:host login:login password:passwd
return:&errorNum]) {
return SUCCEED; } else {
printf (" %s\ n", [ connection
connectErrorMessage:errorNum]);
}

ANSI C Example:

OpenBase *connection;
char dbase[ 50] ; char host[ 50] ; char login[ 50] ; char passwd[ 50] ; int errorNum; ...
if (ob_connectToDatabase(connection, dbase,
host,login,passwd, &errorNum)) {
return SUCCEED;
} else {
printf (" %s\ n", ob_connectErrorMessage(connection,errorNum));

databaseName

Defined in <OpenBaseAPI/OpenBase.h>

- (const char *)databaseName;

Returns the name of the database.

Objective-C Example:

OpenBase *connection; ...
prinf (" %s\ n", [ connection databaseName] );

ANSI C Example:

OpenBase *connection; ...
printf (" %s\ n", ob_databaseName (connection) );

executeCommand

Defined in <OpenBaseAPI/OpenBase.h>

- (BOOL)executeCommand;

Executes the SQL commands in the command buffer.

Returns TRUE if the SQL was executed. If an error is detected FALSE is returned and the server message is set with the error message (see serverMessage).

Objective-C Example:

OpenBase *connection; ...
if ([connection executeCommand]) return SUCCEED;

ANSI C Example:

OpenBase *connection; ...
if (ob_executeCommand(connection) return SUCCEED;

hostName

Defined in <OpenBaseAPI/OpenBase.h>

- (const char *)hostName

Returns the name of the host where the OpenBase server is running.

Objective-C Example:

OpenBase *connection; ...
prinf (" %s\ n", [ connection hostName] );

ANSI C Example:

OpenBase *connection; ...
printf("%s\n", ob_hostName(connection));

isColumnNULL:

Defined in <OpenBaseAPI/OpenBase.h>

- (BOOL)isColumnNULL:(int)col;

Checks to see if a returned column has a NULL value. col specifies the column position where position 0 is the first column. This method must be used in conjunction with nextRow.

Returns TRUE if the column specified by col is NULL. Otherwise FALSE is returned.

Objective-C Example:

OpenBase *connection;
int colNum;
...
if ([connection isColumnNULL:colNum]) return SUCCEED;

ANSI C Example:

OpenBase *connection;
int colNum;
...
if (ob_isColumnNULL(connection, colNum)) return SUCCEED;

loginName

Defined in <OpenBaseAPI/OpenBase.h>

- (const char *)loginName

Returns the current database login.

Objective-C Example:

OpenBase *connection; ...
prinf (" %s\ n", [ connection loginName] );

ANSI C Example:

OpenBase *connection; ...
printf("%s\n", ob_loginName(connection));

makeCommand:

Defined in <OpenBaseAPI/OpenBase.h>

- makeCommand: (char * ) cmd;

This method allows you to build an SQL statement. Each time you call this method, the content of cmd is appended to the end of an SQL buffer. When the SQL query is completely constructed, the executeCommand method will send the query to the database.

Objective-C Example:

OpenBase *connection;
...
[connection makeCommand:"insert into EMPLOYEE "]; [ connection makeCommand:" (FIRST_NAME) values "] ; [ connection makeCommand: " ( `John Smith' ) "] ;
if ([connection executeCommand]) return SUCCEED;

ANSI C Example:

OpenBase *connection;
...
ob_makeCommand(connection,"insert into EMPLOYEE "); ob_makeCommand(connection, "(FIRST_NAME) values "); ob_makeCommand(connection, "(`John Smith')");
if (ob_executeCommand(connection)) return SUCCEED;

markRow:ofTable:alreadyMarkedByUser:

Defined in <OpenBaseAPI/OpenBase.h>

- (int)markRow:(const char *)anId ofTable:(const char *)tableName alreadyMarkedByUser:(char *)userName;

These methods attempt to mark a row in table tableName where _rowid equals anId. These methods are useful for managing a pessimistic locking strategy.

Marking records before being edited will enable your programs to coordinate database changes between multiple users. If a record has been marked by another user, we recommend that the record be displayed in read-only mode. Marks are only flags to other programs. They do not block SQL from updating the records in question.

Marks are automatically released if the database is restarted or if the communication link goes down between the server and client.

Returns TRUE if the database row is marked successfully. These methods return FALSE if the record was already marked by another user. userName is set to the user who owns the mark if the attempt fails.

Objective-C Example:

OpenBase *connection;
char rowId[ 30] ; char table[ 50] ; ...
if ([connection markRow:rowId ofTable:table])
return SUCCEED;

ANSI C Example:

OpenBase *connection;
...
if (ob_markRow(connection, rowId, table)) return SUCCEED;

nextRow

Defined in <OpenBaseAPI/OpenBase.h>

- (BOOL)nextRow;

This method retrieves the next row in a search result. Each time a database row (or record) is processed using nextRow, column values are placed in Objective-C variables previously bound to each column.

If nextRow successfully processes a result row it returns TRUE. If there are no more result rows to process it returns FALSE.

Objective-C Example:

OpenBase *connection; ...
if ([connection nextRow]) return SUCCEED;

ANSI C Example:

OpenBase *connection; ...
if (ob_nextRow(connection)) return SUCCEED;

password

Defined in <OpenBaseAPI/OpenBase.h>

- (const char *)password

Returns the password used to login to the database.

Objective-C Example:

OpenBase *connection;
...
prinf (" %s\ n", [ connection password] );

ANSI C Example:

OpenBase *connection; ...
printf("%s\n", ob_password(connection));

removeMarkOnRow: ofTable:

Defined in <OpenBaseAPI/OpenBase.h>

- (int)removeMarkOnRow:(const char *)anId ofTable:(const char *)tableName;

removeMarkOnRow:ofTable: releases a previously marked record, where an Id maps to the record's _rowid column in the table tableName.

Returns TRUE if it succeeds. Otherwise FALSE is returned.

Objective-C Example:

OpenBase *connection;
char rowId[ 30] ; char table[ 50] ; ...
if ([connection removeMarkOnRow:rowId ofTable:table])
return SUCCEED;

ANSI C Example:

OpenBase *connection;
...
if (ob_removeMarkOnRow(connection, rowId, table)) return SUCCEED;

removeNotification For:

Defined in <OpenBaseAPI/OpenBase.h>

- removeNotificationFor:notificationDelegate;

Removes the notificationDelegate from the notification list.

Objective-C Example:

OpenBase *connection;
id notify;
...
[connection removeNotificationFor:notify];

resultColumnCount

Defined in <OpenBaseAPI/OpenBase.h>

- (int)resultColumnCount;

This method may be used to get the number of columns in a result.

Returns the number of columns returned by a query result.

Objective-C Example:

OpenBase *connection;
   ...
prinf (" %d\ n", [ connection resultColumnCount] );

ANSI C Example:

OpenBase *connection;
...
printf("%d\n", ob_resultColumnCount(connection));

resultColumnName:

Defined in <OpenBaseAPI/OpenBase.h>

-(const char *)resultColumnName:(int)col;

This method is used to get the column name of the result column specified by col. col specifies the column position where position 0 is the first column. This method should only be called after executing a query.

Returns the column name of the column specified by col.

Objective-C Example:

OpenBase *connection;
int colNum;
...
prinf (" %s\ n", [ connection resultColumnName; colNum] );

ANSI C Example:

OpenBase *connection;
int colNum;
...
printf("%s\n", ob_resultColumnName(connection, colNum));

resultColumnType

Defined in <OpenBaseAPI/OpenBase.h>

- (int)resultColumnType:(int)col;

This method may be used after results have been detected to get the natural type of the result columns. col specifies the column position where position 0 is the first column.

The types are defined as follows:

Type
Definition
OBTYPE_CHAR
Character String
OBTYPE_INT
Integer
OBTYPE_DOUBLE
Double
OBTYPE_LONG
Long
OBTYPE_LONGLONG
Long Long
OBTYPE_MONEY
Money
OBTYPE_DATE
Date
OBTYPE_TIME
Time
OBTYPE_DATETIME
Date-time
OBTYPE_OBJECT
Object / BLOB

Returns the natural type of the column col.

Objective-C Example:

OpenBase *connection;
int colNum;
...
if([connection resultColumnType:colNum] == OBTYPE_MONEY)
printf("MONEY!!!!!!!");

ANSI C Example:

OpenBase *connection;
int colNum;
...
if(ob_resultColumnType(connection, colNum) == OBTYPE_MONEY) printf("MONEY!!!!!!!");

resultReturned

Defined in <OpenBaseAPI/OpenBase.h>

- (BOOL)resultReturned;

Checks to see if results need to be processed by nextRow.

Returns TRUE if there are results that need to be processed. Otherwise FALSE is returned.

Objective-C Example:

OpenBase *connection;
...
if ([connection resultReturned]) return SUCCEED;

ANSI C Example:

OpenBase *connection;
...
if (ob_resultReturned(connection)) return SUCCEED;

resultTableName:

Defined in <OpenBaseAPI/OpenBase.h>

- (const char *)resultTableName:(int)col;

This method is used to get the table name of the result column specified by col. col specifies the column position where position 0 is the first column. This method should only be called after executing a query.

Returns the table name of the column specified by col.

Objective-C Example:

OpenBase *connection;
int colNum;
...
printf (" %s\n",[ connection resultTableName:colNum]);

ANSI C Example:

OpenBase *connection;
int colNum;
...
printf("%s\n", ob_resultTableName(connection, colNum));

rollbackTransaction

Defined in <OpenBaseAPI/OpenBase.h>

- (BOOL)rollbackTransaction;

Returns TRUE if the transaction is rolled back. If an error is detected FALSE is returned.

Objective-C Example:

OpenBase *connection;
...
if ([connection rollbackTransaction]) return SUCCEED;

ANSI C Example:

OpenBase *connection;
...
if (ob_rollbackTransaction(connection)) return SUCCEED;

rowsAffected

Defined in <OpenBaseAPI/OpenBase.h>

- (int)rowsAffected;

This method is called after executing an SQL command using executeCommand.

Returns the number of database rows affected by the most recent SQL command.

Objective-C Example:

OpenBase *connection; ...
prinf ("Found %d items\ n", [ connection rowsAffected] );

ANSI C Example:

OpenBase *connection; ...
printf("Found %d items\n", ob_rowsAffected(connection));

serverMessage

Defined in <OpenBaseAPI/OpenBase.h>

- (const char *)serverMessage;

Returns a message from the server pertaining to the last query executed.

Objective-C Example:

OpenBase *connection; ...
prinf (" %s\ n", [ connection serverMessage] );

ANSI C Example:

OpenBase *connection; ...
printf("%s\n", ob_serverMessage(connection));

startNotification For:

Defined in <OpenBaseAPI/OpenBase.h>

- startNotificationFor:notificationDelegate;

startNotificationFor: starts a notification session for notificationDelegate. notificationDelegate must implement notifyChange:database:intable:vid:field:value:.

- notifyChange:(const char *)action database:(const char *)databaseName intable:(const char *)tableName vid:(const char *)rowid
field:(const char *)fieldName
value:(const char *)aValue

This delegate method is called to notify your application when a change is made to the database. The field and value parameters will always be an empty string, but they will be used in a future version of OpenBase. All objects that set themselves up as the delegate of the notifier object will be notified of database changes.

Please see the chapter on notification for more information about this method.

Objective-C Example:

OpenBase *connection;
id notificationDelegate;
...
[connection startNotificationFor:notificationDelegate];

uniqueRowIdForTable:

Defined in <OpenBaseAPI/OpenBase.h>

- (const char *)uniqueRowIdForTable:(const char *)tablename

Returns a unique _rowid value for the specified table tablename. This value must be inserted with a new record.

Objective-C Example:

OpenBase *connection;
char table[ 50] ;
char newRowId[ 30] ;
...
strcpy(newRowId,[connection uniqueRowIdForTable:table]);

ANSI C Example:

OpenBase *connection;
char table[ 50] ;
char newRowId[ 30] ;
...
strcpy(newRowId,
ob_uniqueRowIdForTable(connection, table));

BLOB/Object Handling Methods:

Methods Illustrated:
< retrieveBinary:
< insertBinary:size:

retrieveBinary:

Defined in <OpenBaseAPI/OpenBase.h>

- (NSData *)retrieveBinary:(const char *)anId;

This method retrieves a BLOB by its identification key and returns an NSData object. The NSData object will release itself automatically.

The ANSI-C API returns newly allocated memory containing the BLOB data. The BLOB size is returned through the size parameter.

Objective-C Example:

OpenBase *connection;
char blobID[ 10] ;
NSData *blobData;
...
blobData = [connection retrieveBinary:blobID];

ANSI C Example:

OpenBase *connection;
char blobID[ 10] ;
int returnSize;
char *bytes;
...
bytes = ob_retrieveBinary(connection, blobID, &returnSize);

insertBinary:size:

- (const char *)insertBinary:(char *)data size:(int)size;

This method loads the BLOB of length size and location data into the database. This method returns a key string (10 characters maximum) that can be used to retrieve the data later. Information that is saved using this method may be retrieved as a file as long as the filename is specified.

BLOBs that are saved into the database are automatically removed when the record referencing the BLOBs are deleted. You should never reference the same BLOB key string in multiple records. Doing so could cause BLOBs to be removed prematurely.

Objective-C Example:

OpenBase *connection; char data[ BIGVALUE] ; int size = BIGVALUE; char key[ 10] ;
...
strcpy(key, [connection insertBinary:data size:size]);

ANSI C Example:

OpenBase *connection; char data[ BIGVALUE] ; int size = BIGVALUE; char key[ 10] ;
...
strcpy(key, ob_insertBinary(connection, data, size))
Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License