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