Database Client/Server High Level API

The client/server database API module has the file name dbcs.c. This module provides a programmer with a high level callable API that will access the Bbuuzzb database server. The QNX platform version of this API uses QNX message passing as the interprocess communication method. All other platforms use the TCP socket interface to communicate to the database server. Note that there is no DOS version of this API. Almost all functions require a tid as the first function parameter.

Starting in GPL package version 1.2-2000.05.03, this API uses the socloc interface. Automatic partial failover of a system log server has been built into this API providing that there is another Bbuuzzb server available. Upon a socket communication error, another Bbuuzzb server will be selected but the database command that caused the socket error will not be re-tried. The reason for this is that the newly connected Bbuuzzb server will not have the same tables open that the original server did. When a socket error has caused another Bbuuzzb server to be selected, this API will return the reply code DBENG_FAILOVER. It is up to the application to decide what to do next.

This API requires a minimum of one running socloc server. A valid socloc startup file must also be present in the current directory.

Here is a list of functions in this module:

Module Dependencies

This module is part of the database client/server API and needs to be linked with the following modules:

In the Unix platform, this module is compiled along with the other database modules as part of the script cdbeng. A good example of a Unix script for a client application that uses this API is mkdbm.

Module Header Files

This module depends on the following header files:

Functions Unique to the Client/Server Database API

The following functions are unique to this module and are not present in the stand-alone database API.

db_status

Prototype   : int db_status(void)

Returns     : dbeng code

This function will send a status request to the Bbuuzzb database server. As long as the database server is running, the return code should be DBENG_OK.

db_version

Prototype   : int db_version(char *ver)
Parameters  :
      Name  : ver
Description : returned version string

Returns     : dbeng code

This function will obtain and return the version string of the currently connected Bbuuzzb server. The parameter ver must already be allocated to sufficient size by the caller

db_get_active

Prototype   : int db_get_active(char *hname, int *port)
Parameters  :
      Name  : hname
Description : returned host name

      Name  : port
Description : returned TCP/IP port number

Returns     : dbeng code

This function will obtain and return the host name and TCP/IP port number of the currently connected Bbuuzzb server. The parameter hname must already be allocated to sufficient size by the caller

db_cs_int

Prototype   : int db_cs_int(struct dbeng_send_message *slm, int *val)
Parameters  :
      Name  : slm
Description : dbeng_send_message structure pointer

      Name  : val
Description : returned value

Returns     : dbeng code

This function is used by many client/server API functions to send a message to the Bbuuzzb database server which returns an integer as well as a dbeng code. If a socket communication error is detected during the send or receive, the function db_failover will be called to attempt to connect to another Bbuuzzb server. If a connection to another server was successful, this function will return the reply code from db_failover.

db_cs_long

Prototype   : int db_cs_long(struct dbeng_send_message *slm, long *val)
Parameters  :
      Name  : slm
Description : dbeng_send_message structure pointer

      Name  : val
Description : returned value

Returns     : dbeng code

This function is used by many client/server API functions to send a message to the Bbuuzzb database server which returns a long integer as well as a dbeng code. If a socket communication error is detected during the send or receive, the function db_failover will be called to attempt to connect to another Bbuuzzb server. If a connection to another server was successful, this function will return the reply code from db_failover.

db_cs_code

Prototype   : int db_cs_code(struct dbeng_send_message *slm)
Parameters  :
      Name  : slm
Description : dbeng_send_message structure pointer

Returns     : dbeng code

This function is used by many client/server API functions to send a message to the Bbuuzzb database server which returns only a dbeng code. If a socket communication error is detected during the send or receive, the function db_failover will be called to attempt to connect to another Bbuuzzb server. If a connection to another server was successful, this function will return the reply code from db_failover.

db_cs_char

Prototype   : int db_cs_char(struct dbeng_send_message *slm, char *cval)
Parameters  :
      Name  : slm
Description : dbeng_send_message structure pointer

      Name  : cval
Description : returned string

Returns     : dbeng code

This function is used by many client/server API functions to send a message to the Bbuuzzb database server which returns a string as well as a dbeng code. The returned string must already be allocated to sufficient size by the caller. If a socket communication error is detected during the send or receive, the function db_failover will be called to attempt to connect to another Bbuuzzb server. If a connection to another server was successful, this function will return the reply code from db_failover.

db_cs_client_connect

Prototype   : static int db_cs_client_connect(void)

Returns     : TRUE upon success, FALSE otherwise

This function attempts to make a connection to the Bbuuzzb database server. This function is specific to implementations that use the TCP interprocess communication method (the Windows and Unix platforms). This function is also defined as static and is not visible outside this module.

db_failover

Prototype   : static int db_failover(void)

Returns     : TRUE upon success, FALSE otherwise

This private function will delete the current Bbuuzzb server entry registered with socloc using the function sloc_delete. Another responding Bbuuzzb server will attempted to be found by calling the function sloc_find. If the find is successful, the host name and TCP/IP port number of the new responding Bbuuzzb server will be loaded into the module global variables. If a connection to another Bbuuzzb server was successful, this function will return DBENG_FAILOVER as an indication to the application that a server failover has happened.

Goto Top | Future Lab Home | Contact Webmaster | Feedback

Copyright © 1999-2000 Future Lab Inc., Last Updated May 1, 2000