This page documents the functions and macros that are implemented in the thread safe DP4 database API, contained in DP4DBAPI.H. The functions are mostly similar to the C functions that this documentation focuses on, but the interfaces do not rely on global variables and are implemented inside a DLL or shared library. The header file contains a few other functions, but these are reserved for internal use, are provided for compatibility with older DP4 releases only.
If you are familiar with the traditional C library, you should find it very easy to get used to the DP4DBAPI functions. You will find the information contained in Accessing multiple databases - A Better Way a useful background.
Programs that use DP4DBAPI should inculde dp4dbapi.h and be linked using CCOWN. However, assuming you have used only DP4DBAPI functions, your program will not bring in any of the C global variables, or the traditional OWN functions, but will link only the DP4 interface, which is exported from either SYSLIBx or USRLIBx depending on the platform. On Windows platforms you can check for this using link -dump -imports to see what libraries your program is actually using, and we will be happy to send you an import library for the API if you prefer.
BOOLEAN dp4_srv_load_srv(int argc,char **argv,dp4_name_string version_info);
CONN * dp4_srv_connect(dp4_name_string server_name,
int nr_system,
int rw_access,
dp4_error_callback error_handler,
int channel,
void *reserved);
BOOLEAN dp4_error_status(const CONN *conn,int *error_level,
int *error_nr,int *error_p0,int *error_p1);
BOOLEAN dp4_srv_enable(CONN *conn,int file_only);
/* function for use in ADC initialisation */
void dp4_adc_set_channel(CONN * conn,int channel);
BOOLEAN dp4_srv_disable(CONN *conn,int file_only); #define dp4_srv_disconnect(conn) dp4_srv_end_process(conn) void dp4_srv_end_process(CONN *conn);
#define dp4_dconn_conn(dconn) (* (CONN**) dconn) #define dp4_fconn_conn(fconn) (* (CONN**) fconn)
These two macros allow you to determine the server connection handle from a DCONN or FCONN handle. This might be useful if you are implementing a library in which you expect to be passed a handle to a database or file connection, and then want to open another file or database on the same server
DCONN * dp4_db_open(CONN * conn,dp4_name_string string_db_name,
int generation,int flags,int reserved,
dp4_swapper swapper,struct DP4_SWAP swap_table[]);
BOOLEAN dp4_db_close(DCONN * dconn);
If you require a (read-only) connection to the system database, then call the following function which is not otherwise documented in this manual.
DCONN * dp4_db_system_connection(CONN * conn,dp4_swapper swapper,struct DP4_SWAP swap_table[]);If you want to update the system database that it must be opened in the usual way using dp4_db_open()
BOOLEAN dp4_db_decommit(DCONN * dconn); int dp4_db_update(DCONN * dconn,int flags); int dp4_db_checkpoint(DCONN * dconn); int dp4_db_commit(DCONN * dconn);
These functions are primarily used by DP4 utilities, to access information relavent to the backup/maintenance cycle of a database. Mostly the same information is now available via the @DB_STATUS table, and you are recommended to use that instead of these APIS if you want to access this information for your own purposes.
int dp4_db_get_flag(DCONN * dconn,int flag_nr); int dp4_db_get_generation(DCONN * dconn); int dp4_db_get_status(DCONN * dconn);
These functions are suitable for reading records from the database one at time. Although you can also use them for accessing records sequentially you are recommended to use the buffered read functions for that purpose instead. If you are using the C++ DP4DBASE class wrapper, you will require only two additional lines of code to make your sequential database accesses use buffered instead of unbuffered reads.
BOOLEAN dp4_rec_fetch(DCONN * dconn,short * datarec,
int flags,int index,int index_role,
int match_keys);
BOOLEAN dp4_rec_fetch_main(DCONN * dconn,short * datarec,int flags,int match_keys);
These functions are intended for accessing a number of consecutive records in a table. Use these functions in preference to the unbuffered functions, as they improve performance and scalability of your application.
BF_HANDLE dp4_bf_open(short * datarec,int keysize,int count_wanted,int strategy);
void dp4_bf_close(BF_HANDLE buffer);
BOOLEAN dp4_bf_fetch(DCONN *dconn,BF_HANDLE buffer,
short * datarec,int flags,
int index,int role,int match_keys);
BOOLEAN dp4_bf_reset(DCONN *dconn,BF_HANDLE buffer,short * datarec,int flags);
Internally, the buffered fetch functions use the following "block fetch" function. However the block fetch function is much less convenient
int dp4_blk_fetch(DCONN * dconn,int number,short * datarec,
int flags,int index_rec,int index_role,
int match_keys);
BOOLEAN dp4_rec_autoinc(DCONN * dconn,short * datarec); BOOLEAN dp4_rec_kill(DCONN * dconn,short * datarec,int flags); BOOLEAN dp4_rec_post(DCONN * dconn,short * datarec,int flags); BOOLEAN dp4_rec_verify(DCONN * dconn,short * datarec,int flags);
Updates only become effective when you commit your transaction
These functions are provided for compatibility reasons. You are recommended to avoid them.
int dp4_rec_parent_copy(DCONN * dconn,short * parent,const short * child,int role);
int dp4_rec_child_copy(DCONN * dconn,short * child,
const short * parent,int role);
BOOLEAN dp4_rec_retrieve(DCONN * dconn,short *datarec);
These functions provide many of the facilities typically provided by an operating system. The purpose of implementing them in DP4DBAPI is that they allow DP4 utilities to perform this type of work across network connections.
BOOLEAN dp4_sf_get_date_time(CONN *conn,datetype * date,timetype * time);
BOOLEAN dp4_sf_set_date_time(CONN *conn,
const datetype * date,
const timetype * time);
DP4DBAPI has a range of APIS that can be used to create, modify and delete files on the computer where the DP4 database manager is running. These functions may be very convenient if you need to access files remotely as part of your DP4 application, but at the same time present a possible security hazard. In some cases these functions may be disabled on the server computer.
All the functions that take parameters or return values that are filek sizes or pointers, or disk space exist in two different variants: one using 32 bit values for such parameters, and one using 64 bit values. The 64 bit variants have the same name, but with the sf_ part of the name prefix replaced by sf64. The easiest way to use the 64 bit functions is to compile code with USE_DP5_FILEHANDLING defined to be 1. Local variables needed for file pointers and sizes can be declared using file_pointer, which maps either to dp4_file_pointer (unsigned long) or dp5_file_pointer (long long/__int64) as appropriate.
int dp4_sf_check(CONN *conn,dp4_name_string filenane);
BOOLEAN dp4_sf_close(FCONN * fconn);
dp4_name_string dp4_sf_default(CONN * conn,char * path_buffer,size_t buffer_size);
BOOLEAN dp4_sf_delete(CONN * conn,dp4_name_string filename);
BOOLEAN dp4_sf_flush(FCONN * fconn);
BOOLEAN dp4_sf_get_file_timestamp(FCONN * fconn,
datetype * date,
timetype * time);
dp4_file_size dp4_sf_get_size(FCONN * fconn);
dp4_file_pointer dp4_sf_get_position(FCONN * fconn);
FCONN * dp4_sf_open(CONN * conn,dp4_name_string filename,int mode);
dp4_file_size dp4_sf_read(FCONN * fconn,void * buffer,dp4_file_size nr_bytes);
BOOLEAN dp4_sf_read_record(FCONN * fconn,short * datarec);
BOOLEAN dp4_sf_rename(CONN * conn,dp4_name_string newname,
dp4_name_string oldname);
dp4_file_pointer dp4_sf_seek(FCONN * fconn,
dp4_file_pointer posn);
BOOLEAN dp4_sf_set_file_timestamp(FCONN * fconn,
const datetype * date,
const timetype * time);
dp4_file_size dp4_sf_space(CONN * conn,dp4_name_string filename);
BOOLEAN dp4_sf_write(FCONN * fconn,const void * buffer,
dp4_file_size nr_bytes);
BOOLEAN dp4_sf_write_record(FCONN * fconn,
const short * datarec);
BOOLEAN dp4_sf_read_sysdata(CONN * conn,
struct SYSDATA * sysdata,
size_t size_sysdata);
int dp4_conn_process_nr(CONN * conn); int dp4_conn_server_handle(CONN * conn); int dp4_db_nr(const DCONN * dconn);
The three functions above can be used to find values suitable for setting into the df_process, server_handle, and db_nr global variables of CCOWN. You might need to do this if you are writing new code using DP4DBAPI, but need to call previously written code that uses the CCOWN version of the DP4 interface. For example the 4.6xx MAPEDIT program uses this, because the DLL which is responsible for maintaining maps and controls on databases was written using the traditional DP4 C interface.