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.

Note that any mention of QNX in this documentation refers to the QNX 4.x OS.

This API uses the socloc interface. Automatic partial failover of a Bbuuzzb 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.

The socloc requirement and the ability to failover to another Bbuuzzb server is built into the TCP version of the API only. The QNX message passing version has no socloc interface and no failover ability.

Here is a list of functions in this module:

- db_initialize
- db_open
- db_close
- db_next
- db_top
- db_get_rec
- db_get_rec_size
- db_get_field_size
- db_get_field
- db_goto
- db_count
- db_put_field
- db_write
- db_delete
- db_get_delete_flag
- db_set_delete_flag
- db_pack
- db_find
- db_find_field
- db_find_part
- db_find_field_part
- db_get_nfields
- db_get_rec_num
- db_get_pos
- db_set_pos
- db_get_change_rec_flag
- db_set_change_rec_flag
- db_get_enf_change_rec_flag
- db_set_enf_change_rec_flag
- db_get_autopack
- db_set_autopack
- db_get_rec_count
- db_new
- db_get_is_table_locked
- db_set_is_table_locked
- db_status
- db_new_table
- db_version
- db_get_open_table_list
- db_get_nsubfields
- db_get_subfield_size
- db_get_subfield
- db_put_subfield
- db_get_nsubsubfields
- db_get_subsubfield_size
- db_get_subsubfield
- db_put_subsubfield
- db_delete_table
- db_exist
- db_clear_table
- db_copy_table
- db_sort
- db_get_sort_max_mem
- db_get_sort_max_open_bin
- db_set_sort_max_mem
- db_set_sort_max_open_bin
- db_delete_field
- db_delete_subfield
- db_delete_subsubfield
- db_end
- db_get_active
- db_replicate_update
- db_cs_int
- db_cs_long
- db_cs_code
- db_cs_char
- db_cs_client_connect
- db_failover
- db_trans_num
- db_connect_num

# Module Dependencies

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

- fio.c
- parse.c
- logger.c
- ipcomm.c (except QNX)
- sys_log.c
- slogcode.c
- dbiocode.c
- dbcscfg.c
- sloc.c (except QNX)
- slconfig.c (except QNX)
- sliocode.c (except QNX)
- sconnect.c (except QNX)

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

# Module Header Files

This module depends on the following header files:

- stdhead.h
- flsocket.h
- ipcomm.h (except QNX)
- dbmess.h
- dbcs.h
- socloc.h (except QNX)
- sloc.h (except QNX)
- sliocode.h (except QNX)

# Functions Unique to the Client/Server Database API

The following functions are unique to this module and are not present in the single user 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 port number

    Returns     : dbeng code

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

## db_replicate_update

    Prototype   : int db_replicate_update(void)

    Returns     : dbeng code

This function will cause the Bbuuzzb server to update all replication information. This function applies to TCP IPC method only.

## 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 database 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. The failover ability is available in the TCP version only.

## 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 of the database 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. The failover ability is available in the TCP version only.

## 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 of the client/server database 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. The failover ability is available in the TCP version only.

## 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 of the database 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. The failover ability is available in the TCP version only.

## db_cs_client_connect

    Prototype   : static int db_cs_client_connect(void)

    Returns     : TRUE upon success, FALSE otherwise

This private 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, Linux and Unix platforms). This function applies to TCP IPC method only.

## 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. An attempt will be made to locate another responding Bbuuzzb server by calling the function sloc_find. If the find is successful, the host name and TCP 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. This function applies to TCP IPC only.

## db_trans_num

    Prototype  : int db_trans_num(long *trans_num)
    Parameters :
          Name : trans_num
    Description: output transaction count

    Returns    : dbeng code

This function will get the Bbuuzzb server current transaction count. Function returns the transaction count in the output transaction count upon success.

## db_connect_num

    Prototype  : int db_connect_num(int *connect_num)
    Parameters :
          Name : connect_num
    Description: output connection count

    Returns    : dbeng code

This function will get the Bbuuzzb server current connection count. Function returns the connection count in the output connection count upon success.

Goto Top | Future Lab Home | Contact Webmaster | Feedback

Copyright © 1999-2006 Future Lab, Last Updated Jun 30, 2006