NOTE: This document is preliminary.

Writing REALbasic Database Plug-Ins

Database plugins are a bit more complex than most other types of REALbasic plug-ins. The database plugin API is described here. All the general plugin comments in the Plugin SDK Documentation apply here as well.

A database plugin may register the following entities:

Required Data Structures

The plugin header files make use of three data structures which are not defined. You must define these as appropriate for your own particular database; RB doesn't care what you put in them. The three structures you must define are:

Registering a Database Engine

The REALRegisterDBEngine function passes a reference to a REALdbEngineDefinition structure. This is the set of functions which operate primarily on a dbDatabase object, and make up the core of the database functionality.

The fields of the REALdbEngineDefinition structure are as follows:

  1. version the version of the plugin architecture that the control was built under; just pass the constant kCurrentREALControlVersion

  2. forSystemUse: just pass 0 (zero)

  3. flags1:

  4. flags2:

  5. flags3:

  6. closeFunc: pointer to a function with prototype:

  7. getTableSchemaCursorFunc: pointer to a function with prototype:

  8. getFieldSchemaCursorFunc: pointer to a function with prototype:

  9. directSQLSelectFunc: nil, or a pointer to a function with prototype:

  10. directSQLExecuteFunc: nil, or a pointer to a function with prototype:

  11. createTableFunc: pointer to a function with prototype:

  12. addTableRecordFunc: pointer to a function with prototype:

  13. getTableCursorFunc: pointer to a function with prototype:

  14. updateFieldsFunc: nil, or a pointer to a function with prototype:

  15. addTableColumnFunc: nil, or a pointer to a function with prototype:

  16. getDatabaseIndexesFunc: pointer to a function with prototype:

  17. getLastErrorCodeFunc: nil, or a pointer to a function with prototype:

  18. getLastErrorStringFunc: nil, or a pointer to a function with prototype:

  19. commitFunc: pointer to a function with prototype:

  20. rollbackFunc: pointer to a function with prototype:

  21. getPropertyFunc: nil, or a pointer to a function with prototype:

Registering a Database Cursor

The REALRegisterDBCursor function passes a reference to a REALdbCursorDefinition structure. This is the set of functions which operate on a database cursor, which is essentially a set of records from a database query. You may register more than one type of cursor, e.g., one for normal queries and one for table schema.

The fields of the REALdbCursorDefinition structure are as follows:

  1. version the version of the plugin architecture that the control was built under; just pass the constant kCurrentREALControlVersion

  2. forSystemUse: just pass 0 (zero)

  3. closeCursorFunc: pointer to a function with prototype:

  4. cursorColumnCountFunc: pointer to a function with prototype:

  5. cursorColumnNameFunc: pointer to a function with prototype:

  6. cursorRowCountFunc: nil, or a pointer to a function with prototype:

  7. cursorColumnValueFunc: pointer to a function with prototype:

  8. cursorReleaseValueFunc: nil, or a pointer to a function with prototype:

  9. cursorNextRow: pointer to a function with prototype:

  10. cursorDeleteFunc: nil, or a pointer to a function delete the current record; prototype:

  11. cursorDeleteAllFunc: nil, or a pointer to a function to delete all records in the set; prototype:

  12. cursorFieldKeyFunc: nil, or a pointer to a mysterious function with prototype:

  13. cursorUpdateFunc: nil, or a pointer to a function with prototype:

  14. cursorEditFunc: nil, or a pointer to a function with prototype:
    This is called when the RB code does "cursor.Edit".

REALcursorUpdate structure

When the user modifies field values in a cursor, the changes are stored in a REALcursorUpdate struct. This is then passed to your cursorUpdate function. The update data is actually a linked list, defined as:
struct REALcursorUpdate
{
	REALcursorUpdate *next;
	int fieldIndex;
	REALstring columnValue;
};

Your code is responsible for converting the given string data to the appropriate datatype for the backend database.


plugin-doc.html
06 Jun 2000