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.