Main Page   Class Hierarchy   Compound List   File List   Compound Members  

cli.h

00001 /*-< CLI.H >---------------------------------------------------------*--------*
00002  * FastDB                    Version 1.0         (c) 1999  GARRET    *     ?  *
00003  * (Main Memory Database Management System)                          *   /\|  *
00004  *                                                                   *  /  \  *
00005  *                          Created:     13-Jan-2000 K.A. Knizhnik   * / [] \ *
00006  *                          Last update: 13-Jan-2000 K.A. Knizhnik   * GARRET *
00007  *-------------------------------------------------------------------*--------*
00008  * Call level interface to FastDB server
00009  *-------------------------------------------------------------------*--------*/
00010 
00011 #ifndef __CLI_H__
00012 #define __CLI_H__
00013 
00014 #ifndef FASTDB_DLL_ENTRY
00015 #ifdef FASTDB_DLL
00016 #ifdef INSIDE_FASTDB
00017 #define FASTDB_DLL_ENTRY __declspec(dllexport)
00018 #else
00019 #define FASTDB_DLL_ENTRY __declspec(dllimport)
00020 #endif
00021 #else
00022 #define FASTDB_DLL_ENTRY
00023 #endif
00024 #endif
00025 
00026 #ifdef __cplusplus
00027 extern "C" { 
00028 #endif
00029 
00030 enum cli_result_code { 
00031     cli_ok = 0,
00032     cli_bad_address = -1,
00033     cli_connection_refused = -2,
00034     cli_database_not_found = -3, 
00035     cli_bad_statement = -4,
00036     cli_parameter_not_found = -5,
00037     cli_unbound_parameter = -6,
00038     cli_column_not_found = -7,
00039     cli_incompatible_type = -8,
00040     cli_network_error = -9,
00041     cli_runtime_error = -10,
00042     cli_bad_descriptor = -11,
00043     cli_unsupported_type = -12,
00044     cli_not_found        = -13,
00045     cli_not_update_mode  = -14,
00046     cli_table_not_found  = -15,
00047     cli_not_all_columns_specified = -16, 
00048     cli_not_fetched = -17,
00049     cli_already_updated = -18, 
00050     cli_table_already_exists = -19, 
00051     cli_not_implemented = -20
00052 };
00053     
00054 enum cli_var_type { 
00055     cli_oid,
00056     cli_bool, 
00057     cli_int1, 
00058     cli_int2,
00059     cli_int4,
00060     cli_int8,
00061     cli_real4,
00062     cli_real8,
00063     cli_asciiz,  /* zero terminated string */
00064     cli_pasciiz, /* pointer to zero terminated string */
00065     cli_array_of_oid,
00066     cli_array_of_bool, 
00067     cli_array_of_int1, 
00068     cli_array_of_int2,
00069     cli_array_of_int4,
00070     cli_array_of_int8,
00071     cli_array_of_real4,
00072     cli_array_of_real8,
00073     cli_array_of_string,
00074     cli_autoincrement, 
00075     cli_unknown
00076 };
00077 
00078 typedef char         cli_bool_t;
00079 typedef signed char  cli_int1_t;
00080 typedef signed short cli_int2_t;
00081 typedef signed int   cli_int4_t;
00082 typedef float        cli_real4_t;
00083 typedef double       cli_real8_t;
00084     
00085 #if defined(_WIN32) && !defined(__MINGW32__)
00086 typedef __int64      cli_int8_t;
00087 #else
00088 #if defined(__osf__ )
00089 typedef signed long  cli_int8_t;
00090 #else
00091 #if defined(__GNUC__) || defined(__SUNPRO_CC)
00092 typedef signed long long cli_int8_t;
00093 #else
00094 #error "integer 8 byte type is not defined" 
00095 #endif
00096 #endif
00097 #endif
00098 
00099 #ifndef CLI_OID_DEFINED
00100 typedef long cli_oid_t;
00101 #endif
00102 
00103 /*********************************************************************
00104  * cli_open
00105  *     Establish connection with the server 
00106  * Parameters:
00107  *     server_url - zero terminated string with server address and port, 
00108  *                  for example "localhost:5101", "195.239.208.240:6100",...
00109  *     max_connect_attempts  - number of attempts to establish connection
00110  *     reconnect_timeout_sec - timeput in seconds between connection attempts
00111  * Returns:
00112  *     >= 0 - connectiondescriptor to be used in all other cli calls
00113  *     <  0 - error code as described in cli_result_code enum
00114  */
00115 int FASTDB_DLL_ENTRY cli_open(char const* server_url, 
00116                               int         max_connect_attempts,
00117                               int         reconnect_timeout_sec);
00118 
00119 enum cli_open_attributes { 
00120     cli_open_default    = 0x0, 
00121     cli_open_readonly   = 0x1, 
00122     cli_open_truncate   = 0x2,
00123     cli_open_concurrent = 0x4
00124 };
00125 /*********************************************************************
00126  * cli_create
00127  *     Create conecntion to the local database
00128  * Parameters:
00129  *     databaseName - name of the database 
00130  *     fileName - path to the database file 
00131  *     transactionCommitDelay - trasnaction commit delay (specify 0 to disable)
00132  *     openAttr - mask of cli_open_attributes
00133  *     initDatabaseSize - initial size of the database
00134  * Returns:
00135  *     >= 0 - connection descriptor to be used in all other cli calls
00136  *     <  0 - error code as described in cli_result_code enum
00137  */
00138 
00139 int FASTDB_DLL_ENTRY cli_create(char const* databaseName, 
00140                                 char const* filePath, 
00141                                 unsigned    transactionCommitDelay, 
00142                                 int         openAttr, 
00143                                 size_t      initDatabaseSize);
00144     
00145 /*********************************************************************
00146  * cli_close
00147  *     Close session
00148  * Parameters:
00149  *     session - session descriptor returned by cli_open
00150  * Returns:
00151  *     result code as described in cli_result_code enum
00152  */
00153 int FASTDB_DLL_ENTRY cli_close(int session);
00154 
00155 /*********************************************************************
00156  * cli_statement
00157  *     Specify SunSQL statement to be executed at server
00158  *     Binding to the parameters and columns can be established       
00159  * Parameters:
00160  *     session - session descriptor returned by cli_open
00161  *     stmt    - zero terminated string with SubSQL statement  
00162  * Returns:
00163  *     >= 0 - statement descriptor
00164  *     <  0 - error code as described in cli_result_code enum
00165  */
00166 int FASTDB_DLL_ENTRY cli_statement(int session, char const* stmt);
00167 
00168 /*********************************************************************
00169  * cli_parameter
00170  *     Bind parameter to the statement
00171  * Parameters:
00172  *     statement  - statememt descriptor returned by cli_statement
00173  *     param_name - zero terminated string with parameter name  
00174  *                  Paramter name should start with '%'
00175  *     var_type   - type of variable as described in cli_var_type enum.
00176  *                  Only scalar and zero terminated string types are supported.
00177  *     var_ptr    - pointer to the variable
00178  * Returns:
00179  *     result code as described in cli_result_code enum
00180  */
00181 int FASTDB_DLL_ENTRY cli_parameter(int         statement,
00182                                    char const* param_name, 
00183                                    int         var_type,
00184                                    void*       var_ptr);
00185 
00186 /*********************************************************************
00187  * cli_column
00188  *     Bind extracted column of select or insert statement
00189  * Parameters:
00190  *     statement   - statememt descriptor returned by cli_statement
00191  *     column_name - zero terminated string with column name  
00192  *     var_type    - type of variable as described in cli_var_type enum
00193  *     var_len     - pointer to the variable to hold length of array variable.
00194  *                   This variable should be assigned the maximal length
00195  *                   of the array/string buffer, pointed by var_ptr.
00196  *                   After the execution of the statement it is assigned the 
00197  *                   real length of the fetched array/string. If it is large 
00198  *                   than length of the buffer, then only part of the array
00199  *                   will be placed in the buffer, but var_len still will 
00200  *                   contain the actual array length. 
00201  *     var_ptr     - pointer to the variable
00202  * Returns:
00203  *     result code as described in cli_result_code enum
00204  */
00205 int FASTDB_DLL_ENTRY cli_column(int         statement,
00206                                 char const* column_name, 
00207                                 int         var_type, 
00208                                 int*        var_len, 
00209                                 void*       var_ptr);
00210 
00211 
00212 typedef void* (*cli_column_set)(int var_type, void* var_ptr, int len);
00213 typedef void* (*cli_column_get)(int var_type, void* var_ptr, int* len);
00214 
00215 typedef void* (*cli_column_set_ex)(int var_type, void* var_ptr, int len, 
00216                                    char const* column_name, int statement, void const* data_ptr);
00217 typedef void* (*cli_column_get_ex)(int var_type, void* var_ptr, int* len, 
00218                                    char const* column_name, int statemen);
00219 
00220 /*********************************************************************
00221  * cli_array_column
00222  *     Specify get/set functions for the array column
00223  * Parameters:
00224  *     statement   - statememt descriptor returned by cli_statement
00225  *     column_name - zero terminated string with column name  
00226  *     var_type    - type of variable as described in cli_var_type enum
00227  *     var_ptr     - pointer to the variable
00228  *     set         - function which will be called to construct fetched 
00229  *                   field. It receives pointer to the variable, 
00230  *                   length of the fetched array and returns pointer to th 
00231  *                   array's elements
00232  *     get         - function which will be called to update the field in the 
00233  *                   database. Given pointer to the variable, it should return 
00234  *                   pointer to the array elements and store length of the
00235  *                   array to the variable pointer by len parameter
00236  * Returns:
00237  *     result code as described in cli_result_code enum
00238  */
00239 int FASTDB_DLL_ENTRY cli_array_column(int            statement,
00240                                       char const*    column_name, 
00241                                       int            var_type,
00242                                       void*          var_ptr,
00243                                       cli_column_set set,
00244                                       cli_column_get get);
00245     
00246 int FASTDB_DLL_ENTRY cli_array_column_ex(int               statement,
00247                                          char const*       column_name, 
00248                                          int               var_type,
00249                                          void*             var_ptr,
00250                                          cli_column_set_ex set,
00251                                          cli_column_get_ex get);
00252     
00253 enum { 
00254     cli_view_only, 
00255     cli_for_update
00256 };
00257 
00258 /*********************************************************************
00259  * cli_fetch
00260  *     Execute select statement.
00261  * Parameters:
00262  *     statement  - statememt descriptor returned by cli_statement
00263  *     for_update - not zero if fetched rows will be updated 
00264  * Returns:
00265  *     >= 0 - success, for select statements number of fetched rows is returned
00266  *     <  0 - error code as described in cli_result_code enum
00267  */
00268 int FASTDB_DLL_ENTRY cli_fetch(int statement, int for_update);
00269 
00270 /*********************************************************************
00271  * cli_insert
00272  *     Execute insert statement.
00273  * Parameters:
00274  *     statement  - statememt descriptor returned by cli_statement
00275  *     oid        - object identifier of created record. 
00276  * Returns:
00277  *     status code as described in cli_result_code enum
00278  */
00279 int FASTDB_DLL_ENTRY cli_insert(int statement, cli_oid_t* oid);
00280 
00281 /*********************************************************************
00282  * cli_get_first
00283  *     Get first row of the selection.
00284  * Parameters:
00285  *     statement  - statememt descriptor returned by cli_statement
00286  * Returns:
00287  *     result code as described in cli_result_code enum
00288  */
00289 int FASTDB_DLL_ENTRY cli_get_first(int statement);
00290 
00291 /*********************************************************************
00292  * cli_get_last
00293  *     Get last row of the selection.
00294  * Parameters:
00295  *     statement  - statememt descriptor returned by cli_statement
00296  * Returns:
00297  *     result code as described in cli_result_code enum
00298  */
00299 int FASTDB_DLL_ENTRY cli_get_last(int statement);
00300 
00301 /*********************************************************************
00302  * cli_get_next
00303  *     Get next row of the selection. If get_next records is called
00304  *     exactly after cli_fetch function call, is will fetch the first record
00305  *     in selection.
00306  * Parameters:
00307  *     statement  - statememt descriptor returned by cli_statement
00308  * Returns:
00309  *     result code as described in cli_result_code enum
00310  */
00311 int FASTDB_DLL_ENTRY cli_get_next(int statement);
00312 
00313 /*********************************************************************
00314  * cli_get_prev
00315  *     Get previous row of the selection. If get_next records is called
00316  *     exactly after cli_fetch function call, is will fetch the last record
00317  *     in selection.
00318  * Parameters:
00319  *     statement  - statememt descriptor returned by cli_statement
00320  * Returns:
00321  *     result code as described in cli_result_code enum
00322  */
00323 int FASTDB_DLL_ENTRY cli_get_prev(int statement);
00324 
00325 /*********************************************************************
00326  * cli_get_oid
00327  *     Get object identifier of the current record
00328  * Parameters:
00329  *     statement  - statememt descriptor returned by cli_statement
00330  * Returns:
00331  *     object identifier or 0 if no object is seleected
00332  */
00333 cli_oid_t FASTDB_DLL_ENTRY cli_get_oid(int statement);
00334 
00335 /*********************************************************************
00336  * cli_update
00337  *     Update the current row in the selection. You have to set
00338  *     for_update parameter of cli_fetch to 1 in order to be able 
00339  *     to perform updates. Updated value of row fields will be taken
00340  *     from bound column variables. 
00341  * Parameters:
00342  *     statement   - statememt descriptor returned by cli_statement
00343  * Returns:
00344  *     result code as described in cli_result_code enum
00345  */
00346 int FASTDB_DLL_ENTRY cli_update(int statement);
00347 
00348 /*********************************************************************
00349  * cli_remove
00350  *     Remove all selected records. You have to set
00351  *     for_update parameter of cli_fetch to 1 in order to be able 
00352  *     to remove records. 
00353  * Parameters:
00354  *     statement   - statememt descriptor returned by cli_statement
00355  * Returns:
00356  *     result code as described in cli_result_code enum
00357  */
00358 int FASTDB_DLL_ENTRY cli_remove(int statement);
00359 
00360 /*********************************************************************
00361  * cli_free
00362  *     Deallocate statement and all associated data
00363  * Parameters:
00364  *     statement   - statememt descriptor returned by cli_statement
00365  * Returns:
00366  *     result code as described in cli_result_code enum
00367  */
00368 int FASTDB_DLL_ENTRY cli_free(int statement);
00369 
00370 /*********************************************************************
00371  * cli_commit
00372  *     Commit current database transaction
00373  * Parameters:
00374  *     session - session descriptor as returned by cli_open
00375  * Returns:
00376  *     result code as described in cli_result_code enum
00377  */
00378 int FASTDB_DLL_ENTRY cli_commit(int session);
00379 
00380 /*********************************************************************
00381  * cli_precommit
00382  *     Release all locks set by transaction. This methods allows other clients
00383  *     to proceed, but it doesn't flush transaction to the disk.
00384  * Parameters:
00385  *     session - session descriptor as returned by cli_open
00386  * Returns:
00387  *     result code as described in cli_result_code enum
00388  */
00389 int FASTDB_DLL_ENTRY cli_precommit(int session);
00390 
00391 /*********************************************************************
00392  * cli_abort
00393  *     Abort current database transaction
00394  * Parameters:
00395  *     session - session descriptor as returned by cli_open
00396  * Returns:
00397  *     result code as described in cli_result_code enum
00398  */
00399 int FASTDB_DLL_ENTRY cli_abort(int session);
00400 
00401 
00402 enum cli_field_flags { 
00403     cli_hashed           = 1, /* field should be indexed usnig hash table */
00404     cli_indexed          = 2  /* field should be indexed using B-Tree */
00405 };
00406 
00407 typedef struct cli_field_descriptor { 
00408     enum cli_var_type type;
00409     int               flags;
00410     char const*       name;
00411     char const*       refTableName;
00412     char const*       inverseRefFieldName;
00413 } cli_field_descriptor;
00414 
00415 /*********************************************************************
00416  * cli_describe
00417  *     Describe fileds of specified table
00418  * Parameters:
00419  *     session - session descriptor as returned by cli_open
00420  *     table   - name of the table
00421  *     fields  - adress of the pointer to the array of fields descriptors, 
00422  *               this array should be later deallocated by application by free()
00423  * Returns:
00424  *     >= 0 - number of fields in the table
00425  *     < 0  - result code as described in cli_result_code enum
00426  */
00427 int FASTDB_DLL_ENTRY cli_describe(int session, char const* table, cli_field_descriptor** fields);
00428 
00429 
00430 typedef struct cli_table_descriptor {
00431     char const*       name;
00432 } cli_table_descriptor;
00433 
00434 /*********************************************************************
00435  * cli_show_tables
00436  *     Show all tables of specified database
00437  * Parameters:
00438  *     session - session descriptor as returned by cli_open
00439  *     tables  - address of the pointer to the array of tables descriptors,
00440  *               this array should be later deallocated by application by free()
00441  * Returns:
00442  *     >= 0 - number of tables in the database (Metatable is not returned/counted)
00443  *     < 0  - result code as described in cli_result_code enum
00444  */
00445 int FASTDB_DLL_ENTRY cli_show_tables(int session, cli_table_descriptor** tables);
00446 
00447 
00448 /*********************************************************************
00449  * cli_create_table
00450  *     Create new table
00451  * Parameters:
00452  *     session   - session descriptor as returned by cli_open
00453  *     tableName - name of new table
00454  *     nFields   - number of columns in the table
00455  *     fields    - array with table columns descriptors
00456  * Returns:
00457  *     result code as described in cli_result_code enum
00458  */
00459 int FASTDB_DLL_ENTRY cli_create_table(int session, char const* tableName, int nFields, 
00460                                         cli_field_descriptor* fields);
00461 
00462 /*********************************************************************
00463  * cli_drop_table
00464  *     drop the table
00465  * Parameters:
00466  *     session   - session descriptor as returned by cli_open
00467  *     tableName - name of deleted table
00468  * Returns:
00469  *     result code as described in cli_result_code enum
00470  */
00471 int FASTDB_DLL_ENTRY cli_drop_table(int session, char const* tableName);
00472 
00473 
00474 /*********************************************************************
00475  * cli_alter_index
00476  *     add or remove column index
00477  * Parameters:
00478  *     session   - session descriptor as returned by cli_open
00479  *     tableName - name of the table
00480  *     fieldName - name of field
00481  *     newFlags  - new flags of the field, if index exists for this field, but is not specified in 
00482  *                 <code>newFlags</code> mask, then it will be removed; if index not exists, but is 
00483  *                 specified in <code>newFlags</code> mask, then it will be created. *                   
00484  * Returns:
00485  *     result code as described in cli_result_code enum
00486  */
00487 int FASTDB_DLL_ENTRY cli_alter_index(int session, char const* tableName, char const* fieldName, 
00488                                      int newFlags);
00489 
00490 
00491 /*********************************************************************
00492  * cli_set_error_handler
00493  *     Set FastDB erro handler. Handler should be no-return function which perform stack unwind.
00494  * Parameters:
00495  *     session   - session descriptor as returned by cli_open
00496  *     handler   - error handler
00497  * Returns:
00498  *     previous handler
00499  */
00500 enum cli_error_class { 
00501     cli_no_error, 
00502     cli_query_error,
00503     cli_arithmetic_error,
00504     cli_index_out_of_range_error,
00505     cli_database_open_rror,
00506     cli_file_error,
00507     cli_out_of_memory_error,
00508     cli_deadlock,
00509     cli_null_reference_error,
00510     cli_lock_revoked,
00511     cli_file_limit_exeeded        
00512 };
00513 typedef void (*cli_error_handler)(enum cli_error_class error, char const* msg, int msgarg); 
00514 cli_error_handler FASTDB_DLL_ENTRY cli_set_error_handler(int session, cli_error_handler new_handler);
00515 
00516 #ifdef __cplusplus
00517 }
00518 #endif
00519 
00520 #endif
00521 
00522 

Generated on Fri Nov 15 21:06:28 2002 for FastDB by doxygen1.2.15