The External Driver API

To build an external driver, you need to provide implementations for several functions, and then link your code with the provided 'nspdmain' program, found in the nspd.a library. The resulting "database proxy daemon" is contacted by the server's "external" driver (the client in the following descriptions) for all database activities. The 'nspdmain' program handles all communication with the server's 'external' driver, calling your routines database-specific functions. Note that there is a single database proxy daemon associated with each database connection, so all of the state for each connection is encapsulated here. Database connections are managed efficiently by the server's database pool mechanism.

The next section summarizes the External Driver Proxy Daemon functions. The reference section at the end of this appendix describes each function in detail and gives a pseudo-code implementation. Each implementation of a function may be a different for each dbms-specification. Consult your database client library documentation and the freely distributed AOLServer examples of the Sybase Proxy daemons for more information and dbms-specific examples.

Functions to be Implemented

The set of functions that need to be implemented are:

1. void *Ns_PdDbInit (void)

   This function is called once from the 'nspdmain' when the database driver is initialized at process startup. It normally allocates and returns a dbms-specific structure to be passed to all other routines. It also calls any dbms-specific initialization routines. This function does not open a connection to the database.

2. void Ns_PdDbCleanup(void *handle)

   This function is called once from the 'nspdmain' when the database driver is initialized at process startup. It performs cleanup associated with process shutdown and frees the database-specific handle.

3. void Ns_PdDbOpen(void *handle, char *openArgs)

   This function opens a connection to the database based on the openArgs passed in. The handle passed in is the handle that was returned by Ns_PdDbInit, and will usually be cast to some driver-specific data structure. If the open operation is successful, this function should call Ns_PdSendString with OK_STATUS. On failure, the function should use Ns_PdSendString to return an error string.

4. void Ns_PdDbClose(void *handle)

   This function closes the database. It should not free the database handle. If the close operation is successful, this function should call Ns_PdSendString with OK_STATUS. On failure, the function should use Ns_PdSendString to return an error string.

5. void Ns_PdDbExec(void *handle, char *sql)

   This function executes a SQL query. If the SQL is executed successfully, this function should call Ns_PdSendString with OK_STATUS followed by either Ns_PdSendString(EXEC_RET_ROWS) or Ns_PdSendString(EXEC_RET_DML), depending on whether the SQL returned rows or was a DML statement. On failure, the function should use Ns_PdSendException to return an error.

6. void Ns_PdDbFlush(void *handle)

   Flushes any pending data. Usually this function will call Ns_PdDbCancel or something similiar along with any other database specific clean-up routines. If the flush operation is successful, this function should call Ns_PdSendString with an OK_STATUS. On failure, the function should use Ns_PdSendString to return an error string.

7. void Ns_PdDbCancel(void *handle)

   This function cancels the current database operation. If the cancel operation was successful, this function should call Ns_PdSendString with OK_STATUS. On failure, the function should use Ns_PdSendString to return an error string.

8. void Ns_PdDbBindRow (void *handle)

   This function should retrieve from the DBMS a list of column names of rows and return this data to the client. If the bind-row operation is successful, this function should call Ns_PdSendString with an OK_STATUS. On failure this function should return an exception code with Ns_PdSendException.

9. void Ns_PdDbGetRow(void *handle, char *columnCount)

   This function should retrieve from the DBMS the row associated with the columnCount column and send this data to the client. If the get-row operation was successful, this function should call Ns_PdSendString with an OK_STATUS and then send the data with Ns_PdDbSendData. On failure, the function should use Ns_PdSendException to return an error.

10. void Ns_PdDbTableList (void *handle, char *includeSystem)

    This function should retrieve the list of table names from the database associated with the handle and send this data to the client. The includeSystem parameter indicates whether to include system tables with this list. The function should implement the following protocol:

    If the initial SQL query returns a successful status of DB_ROWS when generating the table names, then this function should:

    • Call Ns_PdSendString with an OK_STATUS.

    • Call Ns_PdSendString with a size of the item (table name).

    • Call Ns_PdSendData to send the actual data associated with the name and to signal the end of data.

    • If an exception occurs during the processing of the table data, then this function should send the partial data to the client and indicate an error with Ns_PdDbLog.

    If an exception is raised before successfully retrieving some of the table data, then this function should call Ns_PdSendException to return an error.

11. void Ns_PdDbGetTableInfo(void *handle, char *tableName)

    This function should retrieve the system catalog information (columns, types, etc.) about a table and send this to the client.

    If the initial SQL select query returns a successful status of DB_ROWS, then this function should:

    • Call Ns_PdSendString with an OK_STATUS.

    • Call Ns_PdSendRowInfo to send to the client the column info.

    • Call Ns_PdSendRowInfo to send to the client subsequent row info.

    • Call Ns_PdSendData to indicate to the client that END_DATA has been reached.

    • If an exception occurs during the processing of the row info, then this function should send the partial data to the client and indicate an error with Ns_PdDbLog.

    If an exception is raised before successfully retrieving some of the row info, then this function should call Ns_PdSendException to return an error.

12. void Ns_PdDbBestRowId(void *handle, char *tableName)

    This function retrieves the primary key of a table from the database and sends this to the client. If a table has a primary key, AOLserver can perform row updates and deletes. If the best-row-id operation is successful, this function should call Ns_PdSendString with an OK_STATUS. If a best-row-id is found then call Ns_PdSendString with the column name; otherwise, call Ns_PdSendString with NO_BESTROWID. On failure this function should return an exception code with Ns_PdSendException.

13. void Ns_PdDbIndentify(void *handle)

    This function sends a string identifying the proxy daemon name and version with Ns_PdSendString.

14. void Ns_PdDbGetTypes(void *handle)

    This function sends a string of the data types for the database with Ns_PdSendString.

15. void Ns_PdDbResultId(void *handle)

    This function sends to the client with Ns_PdSendString the id of the last object affected by an exec command or a null terminated string.

16. void Ns_PdDbResultRows(void *handle)

    This function sends to the client with Ns_PdSendString the number of rows affected by last exec command.

17. void Ns_PdDbSetMaxRows(void *handle, char *maxRows)

    This function sets the max rows for the database. If this function is successful or the SQL command is undefined for your specific DBMS, it should call Ns_PdSendString with an OK_STATUS. If set-max-rows is defined for your specific DBMS and there is an exception raised, then this function should send an exception code with Ns_PdSendException.

18. void Ns_PdDbSpExec(void *handle)

    This function executes a stored procedure that has been initialized with Ns_PdDbSpStart and Ns_PdDbSpSetParam.

19. void Ns_PdDbSpGetParams(void *handle)

    This function returns output parameters from a previously executed stored procedure.

20. void Ns_PdDbSpReturnCode (void *handle)

    This function gets the return code from a previously executed stored procedure.

21. void Ns_PdDbSpSetParam (void *handle, char *args)

    This function sets parameters in a stored procedure before executing it.

22. void Ns_PdDbSpStart(void *handle, char *procname)

    This function begins the definition of a stored procedure.

Utility Functions

In implementing the above functions, you will need to call some of the various utility functions described below. When using these functions, do not pass a parameter of NULL for string values. If you do, an error message is printed to the syslog and the function returns.

1. void Ns_PdLog(Ns_PdLogMsgType errtype, char *fmt, ...)

   The Ns_PdLog function sends a formatted messages to the client. Allowable values for the log type are the following with a default type of Error: Notice, Trace, Error.

2. void Ns_PdSendString(char *string)

   This function sends a string to the client.

3. void Ns_PdSendException(char *code, char *msg)

   This sends an exception code and an exception message to the client.

4. Ns_PdParseOpenArgs(char *openargs, char **datasource, char **user, char **password, char **param)

   This function parses the datasource, user, password, and param parameters leaving missing elements as NULL. This function is normally called from within Ns_PdDbOpen.

5. void Ns_PdSendRowInfo(Ns_PdRowInfo * rowInfo)

   This function sends a row encapsulated in an Ns_PdRowInfo structure to the client.

6. void Ns_PdSendData(char *data, int len)

   This function sends data of length len to the client. You indicate that you are finished sending data by calling this function with END_DATA.

7. void Ns_PdFreeRowInfo(Ns_PdRowInfo * rowInfo, int fFreeData)

   This function frees a Ns_PdRowInfo data structure. If fFreeData is a non-zero value, then this function frees the data associated with the Ns_PdRowData structure (encapsulated in Ns_PdRowInfo) as well.

Constants

The following constants are used in the example drivers:

    #define EXCEPTION_CODE_MAX 32
    #define EXCEPTION_MSG_MAX 4096

These constants are used for the buffer sizes for the database error/exception code and error/exception message, respectively. The given buffer size must include a terminating null byte. In other words, you can have an exception message of up to 4095 bytes, reserving the last byte for a null byte.