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 #include "config.h" 00015 #include <stdlib.h> 00016 #include <time.h> 00017 00018 #ifndef FASTDB_DLL_ENTRY 00019 #ifdef FASTDB_DLL 00020 #ifdef INSIDE_FASTDB 00021 #define FASTDB_DLL_ENTRY __declspec(dllexport) 00022 #else 00023 #define FASTDB_DLL_ENTRY __declspec(dllimport) 00024 #endif 00025 #else 00026 #define FASTDB_DLL_ENTRY 00027 #endif 00028 #endif 00029 00030 #ifndef CLI_CALLBACK_CC /* CLI callbacks calling convention */ 00031 #define CLI_CALLBACK_CC 00032 #endif 00033 00034 #ifdef __cplusplus 00035 extern "C" { 00036 #endif 00037 00038 enum cli_result_code { 00039 cli_ok = 0, 00040 cli_bad_address = -1, 00041 cli_connection_refused = -2, 00042 cli_database_not_found = -3, 00043 cli_bad_statement = -4, 00044 cli_parameter_not_found = -5, 00045 cli_unbound_parameter = -6, 00046 cli_column_not_found = -7, 00047 cli_incompatible_type = -8, 00048 cli_network_error = -9, 00049 cli_runtime_error = -10, 00050 cli_bad_descriptor = -11, 00051 cli_unsupported_type = -12, 00052 cli_not_found = -13, 00053 cli_not_update_mode = -14, 00054 cli_table_not_found = -15, 00055 cli_not_all_columns_specified = -16, 00056 cli_not_fetched = -17, 00057 cli_already_updated = -18, 00058 cli_table_already_exists = -19, 00059 cli_not_implemented = -20 00060 }; 00061 00062 enum cli_var_type { 00063 cli_oid, 00064 cli_bool, 00065 cli_int1, 00066 cli_int2, 00067 cli_int4, 00068 cli_int8, 00069 cli_real4, 00070 cli_real8, 00071 cli_decimal, /* not supported */ 00072 cli_asciiz, /* zero terminated string */ 00073 cli_pasciiz, /* pointer to zero terminated string */ 00074 cli_cstring, /* not supported */ 00075 cli_array_of_oid, 00076 cli_array_of_bool, 00077 cli_array_of_int1, 00078 cli_array_of_int2, 00079 cli_array_of_int4, 00080 cli_array_of_int8, 00081 cli_array_of_real4, 00082 cli_array_of_real8, 00083 cli_array_of_decimal, 00084 cli_array_of_string, 00085 cli_any, /* use the same type for column as stored in the database */ 00086 cli_datetime, /* time in seconds since 00:00:00 UTC, January 1, 1970. */ 00087 cli_autoincrement, /* column of int4 type automatically assigned value during record insert */ 00088 cli_rectangle, 00089 cli_unknown 00090 }; 00091 00092 #ifdef __STDTP_H__ 00093 USE_FASTDB_NAMESPACE 00094 #endif 00095 00096 typedef char cli_bool_t; 00097 typedef signed char cli_int1_t; 00098 typedef signed short cli_int2_t; 00099 typedef float cli_real4_t; 00100 typedef double cli_real8_t; 00101 00102 #ifndef RECTANGLE_COORDINATE_TYPE 00103 #define RECTANGLE_COORDINATE_TYPE int 00104 //#define RECTANGLE_COORDINATE_TYPE double 00105 #endif 00106 typedef RECTANGLE_COORDINATE_TYPE cli_coord_t; 00107 #define CLI_RECTANGLE_DIMENSION 2 00108 00109 typedef struct { 00110 cli_coord_t boundary[CLI_RECTANGLE_DIMENSION*2]; 00111 } cli_rectangle_t; 00112 00113 #if !defined(SIZEOF_LONG) && defined(L64) && ! defined(WIN64) 00114 #define SIZEOF_LONG 8 00115 #endif 00116 00117 #if (defined(_WIN32) || defined(__BORLANDC__)) && !defined(__MINGW32__) 00118 typedef signed __int32 cli_int4_t; 00119 typedef signed __int64 cli_int8_t; 00120 #else 00121 typedef signed int cli_int4_t; 00122 #if SIZEOF_LONG == 8 00123 typedef signed long cli_int8_t; 00124 #else 00125 typedef signed long long cli_int8_t; 00126 #endif 00127 #endif 00128 00129 #ifndef CLI_TIME_T_DEFINED 00130 typedef time_t cli_time_t; 00131 #endif 00132 00133 #ifndef CLI_OID_DEFINED 00134 #if dbDatabaseOidBits > 32 00135 typedef size_t cli_oid_t; 00136 #else 00137 typedef unsigned cli_oid_t; 00138 #endif 00139 #endif 00140 00141 // structure used to represent array field in structure extracted by cli_execute_query 00142 typedef struct cli_array_t { 00143 size_t size; // number of elements in the array 00144 void* data; // pointer to the array elements 00145 size_t allocated; // internal field: size of allocated buffer 00146 } cli_array_t; 00147 00148 /********************************************************************* 00149 * cli_open 00150 * Establish connection with the server 00151 * Parameters: 00152 * server_url - zero terminated string with server address and port, 00153 * for example "localhost:5101", "195.239.208.240:6100",... 00154 * max_connect_attempts - number of attempts to establish connection 00155 * reconnect_timeout_sec - timeput in seconds between connection attempts 00156 * Returns: 00157 * >= 0 - connectiondescriptor to be used in all other cli calls 00158 * < 0 - error code as described in cli_result_code enum 00159 */ 00160 int FASTDB_DLL_ENTRY cli_open(char const* server_url, 00161 int max_connect_attempts, 00162 int reconnect_timeout_sec); 00163 00164 enum cli_open_attributes { 00165 cli_open_default = 0x0, 00166 cli_open_readonly = 0x1, 00167 cli_open_truncate = 0x2, 00168 cli_open_concurrent = 0x4 00169 }; 00170 /********************************************************************* 00171 * cli_create 00172 * Create connection to the local database 00173 * Parameters: 00174 * databaseName - name of the database 00175 * fileName - path to the database file 00176 * transactionCommitDelay - trasnaction commit delay (specify 0 to disable) 00177 * openAttr - mask of cli_open_attributes 00178 * initDatabaseSize - initial size of the database 00179 * extensionQuantum - database extension quantum 00180 * initIndexSize - initial size of object index 00181 * fileSizeLimit - limit for file size (0 - unlimited) 00182 * Returns: 00183 * >= 0 - connection descriptor to be used in all other cli calls 00184 * < 0 - error code as described in cli_result_code enum 00185 */ 00186 00187 int FASTDB_DLL_ENTRY cli_create(char const* databaseName, 00188 char const* filePath, 00189 unsigned transactionCommitDelay, 00190 int openAttr, 00191 size_t initDatabaseSize, 00192 size_t extensionQuantum, 00193 size_t initIndexSize, 00194 size_t fileSizeLimit); 00195 00196 /********************************************************************* 00197 * cli_create_replication_node 00198 * Create connection to the local database with support of replication 00199 * Parameters: 00200 * nodeId - node identifier: 0 <= nodeId < nServers 00201 * nServers - number of replication nodes (primary + standby) 00202 * nodeNames - array with URLs of the nodes (address:port) 00203 * databaseName - name of the database 00204 * fileName - path to the database file 00205 * transactionCommitDelay - trasnaction commit delay (specify 0 to disable) 00206 * openAttr - mask of cli_open_attributes (to allow concurrent read access to replication node, 00207 * cli_open_concurrent attribute should be set) 00208 * initDatabaseSize - initial size of the database 00209 * extensionQuantum - database extension quantum 00210 * initIndexSize - initial size of object index 00211 * fileSizeLimit - limit for file size (0 - unlimited) 00212 * Returns: 00213 * >= 0 - connection descriptor to be used in all other cli calls 00214 * < 0 - error code as described in cli_result_code enum 00215 */ 00216 00217 int FASTDB_DLL_ENTRY cli_create_replication_node(int nodeId, 00218 int nServers, 00219 char* nodeNames[], 00220 char const* databaseName, 00221 char const* filePath, 00222 int openAttr, 00223 size_t initDatabaseSize, 00224 size_t extensionQuantum, 00225 size_t initIndexSize, 00226 size_t fileSizeLimit); 00227 00228 /********************************************************************* 00229 * cli_close 00230 * Close session 00231 * Parameters: 00232 * session - session descriptor returned by cli_open 00233 * Returns: 00234 * result code as described in cli_result_code enum 00235 */ 00236 int FASTDB_DLL_ENTRY cli_close(int session); 00237 00238 /********************************************************************* 00239 * cli_statement 00240 * Specify SubSQL statement to be executed at server 00241 * Binding to the parameters and columns can be established 00242 * Parameters: 00243 * session - session descriptor returned by cli_open 00244 * stmt - zero terminated string with SubSQL statement 00245 * Returns: 00246 * >= 0 - statement descriptor 00247 * < 0 - error code as described in cli_result_code enum 00248 */ 00249 int FASTDB_DLL_ENTRY cli_statement(int session, char const* stmt); 00250 00251 /********************************************************************* 00252 * cli_parameter 00253 * Bind parameter to the statement 00254 * Parameters: 00255 * statement - statememt descriptor returned by cli_statement 00256 * param_name - zero terminated string with parameter name 00257 * Paramter name should start with '%' 00258 * var_type - type of variable as described in cli_var_type enum. 00259 * Only scalar and zero terminated string types are supported. 00260 * var_ptr - pointer to the variable 00261 * Returns: 00262 * result code as described in cli_result_code enum 00263 */ 00264 int FASTDB_DLL_ENTRY cli_parameter(int statement, 00265 char const* param_name, 00266 int var_type, 00267 void* var_ptr); 00268 00269 /********************************************************************* 00270 * cli_column 00271 * Bind extracted column of select or insert statement 00272 * Parameters: 00273 * statement - statememt descriptor returned by cli_statement 00274 * column_name - zero terminated string with column name 00275 * var_type - type of variable as described in cli_var_type enum 00276 * var_len - pointer to the variable to hold length of array variable. 00277 * This variable should be assigned the maximal length 00278 * of the array/string buffer, pointed by var_ptr. 00279 * After the execution of the statement it is assigned the 00280 * real length of the fetched array/string. If it is large 00281 * than length of the buffer, then only part of the array 00282 * will be placed in the buffer, but var_len still will 00283 * contain the actual array length. 00284 * var_ptr - pointer to the variable 00285 * Returns: 00286 * result code as described in cli_result_code enum 00287 */ 00288 int FASTDB_DLL_ENTRY cli_column(int statement, 00289 char const* column_name, 00290 int var_type, 00291 int* var_len, 00292 void* var_ptr); 00293 00294 00295 typedef void* (CLI_CALLBACK_CC *cli_column_set)(int var_type, void* var_ptr, int len); 00296 typedef void* (CLI_CALLBACK_CC *cli_column_get)(int var_type, void* var_ptr, int* len); 00297 00298 typedef void* (CLI_CALLBACK_CC *cli_column_set_ex)(int var_type, void* var_ptr, int len, 00299 char const* column_name, int statement, void const* data_ptr, void* user_data); 00300 typedef void* (CLI_CALLBACK_CC *cli_column_get_ex)(int var_type, void* var_ptr, int* len, 00301 char const* column_name, int statemen, void* user_data); 00302 00303 /********************************************************************* 00304 * cli_array_column 00305 * Specify get/set functions for the array column 00306 * Parameters: 00307 * statement - statememt descriptor returned by cli_statement 00308 * column_name - zero terminated string with column name 00309 * var_type - type of variable as described in cli_var_type enum 00310 * var_ptr - pointer to the variable 00311 * set - function which will be called to construct fetched 00312 * field. It receives pointer to the variable, 00313 * length of the fetched array and returns pointer to th 00314 * array's elements 00315 * get - function which will be called to update the field in the 00316 * database. Given pointer to the variable, it should return 00317 * pointer to the array elements and store length of the 00318 * array to the variable pointer by len parameter 00319 * user_data - pointer to user specific data passed to get and set functions 00320 * Returns: 00321 * result code as described in cli_result_code enum 00322 */ 00323 int FASTDB_DLL_ENTRY cli_array_column(int statement, 00324 char const* column_name, 00325 int var_type, 00326 void* var_ptr, 00327 cli_column_set set, 00328 cli_column_get get); 00329 00330 int FASTDB_DLL_ENTRY cli_array_column_ex(int statement, 00331 char const* column_name, 00332 int var_type, 00333 void* var_ptr, 00334 cli_column_set_ex set, 00335 cli_column_get_ex get, 00336 void* user_data); 00337 00338 enum { 00339 cli_view_only, 00340 cli_for_update 00341 }; 00342 00343 /********************************************************************* 00344 * cli_fetch 00345 * Execute select statement. 00346 * Parameters: 00347 * statement - statememt descriptor returned by cli_statement 00348 * for_update - not zero if fetched rows will be updated 00349 * Returns: 00350 * >= 0 - success, for select statements number of fetched rows is returned 00351 * < 0 - error code as described in cli_result_code enum 00352 */ 00353 int FASTDB_DLL_ENTRY cli_fetch(int statement, int for_update); 00354 00355 /********************************************************************* 00356 * cli_insert 00357 * Execute insert statement. 00358 * Parameters: 00359 * statement - statememt descriptor returned by cli_statement 00360 * oid - object identifier of created record. 00361 * Returns: 00362 * status code as described in cli_result_code enum 00363 */ 00364 int FASTDB_DLL_ENTRY cli_insert(int statement, cli_oid_t* oid); 00365 00366 /********************************************************************* 00367 * cli_get_first 00368 * Get first row of the selection. 00369 * Parameters: 00370 * statement - statememt descriptor returned by cli_statement 00371 * Returns: 00372 * result code as described in cli_result_code enum 00373 */ 00374 int FASTDB_DLL_ENTRY cli_get_first(int statement); 00375 00376 /********************************************************************* 00377 * cli_get_last 00378 * Get last row of the selection. 00379 * Parameters: 00380 * statement - statememt descriptor returned by cli_statement 00381 * Returns: 00382 * result code as described in cli_result_code enum 00383 */ 00384 int FASTDB_DLL_ENTRY cli_get_last(int statement); 00385 00386 /********************************************************************* 00387 * cli_get_next 00388 * Get next row of the selection. If get_next records is called 00389 * exactly after cli_fetch function call, is will fetch the first record 00390 * in selection. 00391 * Parameters: 00392 * statement - statememt descriptor returned by cli_statement 00393 * Returns: 00394 * result code as described in cli_result_code enum 00395 */ 00396 int FASTDB_DLL_ENTRY cli_get_next(int statement); 00397 00398 /********************************************************************* 00399 * cli_get_prev 00400 * Get previous row of the selection. If get_next records is called 00401 * exactly after cli_fetch function call, is will fetch the last record 00402 * in selection. 00403 * Parameters: 00404 * statement - statememt descriptor returned by cli_statement 00405 * Returns: 00406 * result code as described in cli_result_code enum 00407 */ 00408 int FASTDB_DLL_ENTRY cli_get_prev(int statement); 00409 00410 /********************************************************************* 00411 * cli_skip 00412 * Skip specified number of rows. 00413 * Parameters: 00414 * statement - statememt descriptor returned by cli_statement 00415 * n - number of objects to be skipped 00416 * - if "n" is positive, then this function has the same effect as 00417 * executing cli_get_next() function "n" times. 00418 * - if "n" is negative, then this function has the same effect as 00419 * executing cli_get_prev() function "-n" times. 00420 * - if "n" is zero, this method just reloads current record 00421 * Returns: 00422 * result code as described in cli_result_code enum 00423 */ 00424 int FASTDB_DLL_ENTRY cli_skip(int statement, int n); 00425 00426 /********************************************************************* 00427 * cli_seek 00428 * Position cursor to the record with specified OID 00429 * Parameters: 00430 * statement - statememt descriptor returned by cli_statement 00431 * oid - object identifier of the record to which cursor should be positioned 00432 * Returns: 00433 * >= 0 - success, position of the record in the selection 00434 * < 0 - error code as described in cli_result_code enum 00435 */ 00436 int FASTDB_DLL_ENTRY cli_seek(int statement, cli_oid_t oid); 00437 00438 00439 /********************************************************************* 00440 * cli_get_oid 00441 * Get object identifier of the current record 00442 * Parameters: 00443 * statement - statememt descriptor returned by cli_statement 00444 * Returns: 00445 * object identifier or 0 if no object is seleected 00446 */ 00447 cli_oid_t FASTDB_DLL_ENTRY cli_get_oid(int statement); 00448 00449 /********************************************************************* 00450 * cli_update 00451 * Update the current row in the selection. You have to set 00452 * for_update parameter of cli_fetch to 1 in order to be able 00453 * to perform updates. Updated value of row fields will be taken 00454 * from bound column variables. 00455 * Parameters: 00456 * statement - statememt descriptor returned by cli_statement 00457 * Returns: 00458 * result code as described in cli_result_code enum 00459 */ 00460 int FASTDB_DLL_ENTRY cli_update(int statement); 00461 00462 /********************************************************************* 00463 * cli_remove 00464 * Remove all selected records. You have to set 00465 * for_update parameter of cli_fetch to 1 in order to be able 00466 * to remove records. 00467 * Parameters: 00468 * statement - statememt descriptor returned by cli_statement 00469 * Returns: 00470 * result code as described in cli_result_code enum 00471 */ 00472 int FASTDB_DLL_ENTRY cli_remove(int statement); 00473 00474 /********************************************************************* 00475 * cli_remove_current 00476 * Remove currently selected record. You have to set 00477 * for_update parameter of cli_fetch to 1 in order to be able 00478 * to remove records. 00479 * Parameters: 00480 * statement - statememt descriptor returned by cli_statement 00481 * Returns: 00482 * result code as described in cli_result_code enum 00483 */ 00484 int FASTDB_DLL_ENTRY cli_remove_current(int statement); 00485 00486 /********************************************************************* 00487 * cli_free 00488 * Deallocate statement and all associated data 00489 * Parameters: 00490 * statement - statememt descriptor returned by cli_statement 00491 * Returns: 00492 * result code as described in cli_result_code enum 00493 */ 00494 int FASTDB_DLL_ENTRY cli_free(int statement); 00495 00496 /********************************************************************* 00497 * cli_close_cursor 00498 * Close current cursor 00499 * Parameters: 00500 * statement - statememt descriptor returned by cli_statement 00501 * Returns: 00502 * result code as described in cli_result_code enum 00503 */ 00504 int FASTDB_DLL_ENTRY cli_close_cursor(int statement); 00505 00506 /********************************************************************* 00507 * cli_commit 00508 * Commit current database transaction 00509 * Parameters: 00510 * session - session descriptor as returned by cli_open 00511 * Returns: 00512 * result code as described in cli_result_code enum 00513 */ 00514 int FASTDB_DLL_ENTRY cli_commit(int session); 00515 00516 /********************************************************************* 00517 * cli_precommit 00518 * Release all locks set by transaction. This methods allows other clients 00519 * to proceed, but it doesn't flush transaction to the disk. 00520 * Parameters: 00521 * session - session descriptor as returned by cli_open 00522 * Returns: 00523 * result code as described in cli_result_code enum 00524 */ 00525 int FASTDB_DLL_ENTRY cli_precommit(int session); 00526 00527 /********************************************************************* 00528 * cli_abort 00529 * Abort current database transaction 00530 * Parameters: 00531 * session - session descriptor as returned by cli_open 00532 * Returns: 00533 * result code as described in cli_result_code enum 00534 */ 00535 int FASTDB_DLL_ENTRY cli_abort(int session); 00536 00537 00538 enum cli_field_flags { 00539 cli_hashed = 1, /* field should be indexed usnig hash table */ 00540 cli_indexed = 2, /* field should be indexed using B-Tree */ 00541 cli_autoincremented = 16 /* field is assigned automaticall incremented value */ 00542 }; 00543 00544 typedef struct cli_field_descriptor { 00545 enum cli_var_type type; 00546 int flags; 00547 char const* name; 00548 char const* refTableName; 00549 char const* inverseRefFieldName; 00550 } cli_field_descriptor; 00551 00552 /********************************************************************* 00553 * cli_describe 00554 * Describe fields of specified table 00555 * Parameters: 00556 * session - session descriptor as returned by cli_open 00557 * table - name of the table 00558 * fields - address of the pointer to the array of fields descriptors, 00559 * this array should be later deallocated by application by cli_free_memory() 00560 * Returns: 00561 * >= 0 - number of fields in the table 00562 * < 0 - result code as described in cli_result_code enum 00563 */ 00564 int FASTDB_DLL_ENTRY cli_describe(int session, char const* table, cli_field_descriptor** fields); 00565 00566 typedef struct cli_field_layout { 00567 cli_field_descriptor desc; 00568 int offs; 00569 int size; 00570 } cli_field_layout; 00571 00572 /********************************************************************* 00573 * cli_describe_layout 00574 * Describe fields layout of specified table 00575 * Parameters: 00576 * session - session descriptor as returned by cli_open 00577 * table - name of the table 00578 * fields - address of the pointer to the array of fields layout descriptors, 00579 * this array should be later deallocated by application by cli_free_memory() 00580 * rec_size - pointer to the location to receive size of the record. This size can be used by application to allocate buffer for cli_execute_query function 00581 * Returns: 00582 * >= 0 - number of fields in the table 00583 * < 0 - result code as described in cli_result_code enum 00584 */ 00585 int FASTDB_DLL_ENTRY cli_describe_layout(int session, char const* table, cli_field_layout** fields, int* rec_size); 00586 00587 /********************************************************************* 00588 * cli_get_field_size 00589 * Calculate field size 00590 * Parameters: 00591 * fields - array with fields descriptors obtained using cli_describe function 00592 * field_no - number of the field 00593 */ 00594 int FASTDB_DLL_ENTRY cli_get_field_size(cli_field_descriptor* fields, int field_no); 00595 00596 /********************************************************************* 00597 * cli_get_field_offset 00598 * Calculate offset of the field 00599 * Parameters: 00600 * fields - array with fields descriptors obtained using cli_describe function 00601 * field_no - number of the field 00602 */ 00603 int FASTDB_DLL_ENTRY cli_get_field_offset(cli_field_descriptor* fields, int field_no); 00604 00605 00606 typedef struct cli_table_descriptor { 00607 char const* name; 00608 } cli_table_descriptor; 00609 00610 /********************************************************************* 00611 * cli_show_tables 00612 * Show all tables of specified database 00613 * Parameters: 00614 * session - session descriptor as returned by cli_open 00615 * tables - address of the pointer to the array of tables descriptors, 00616 * this array should be later deallocated by application by cli_free_memory() 00617 * Returns: 00618 * >= 0 - number of tables in the database (Metatable is not returned/counted) 00619 * < 0 - result code as described in cli_result_code enum 00620 */ 00621 int FASTDB_DLL_ENTRY cli_show_tables(int session, cli_table_descriptor** tables); 00622 00623 00624 /********************************************************************* 00625 * cli_create_table 00626 * Create new table 00627 * Parameters: 00628 * session - session descriptor as returned by cli_open 00629 * tableName - name of new table 00630 * nFields - number of columns in the table 00631 * fields - array with table columns descriptors 00632 * Returns: 00633 * result code as described in cli_result_code enum 00634 */ 00635 int FASTDB_DLL_ENTRY cli_create_table(int session, char const* tableName, int nFields, 00636 cli_field_descriptor* fields); 00637 00638 /********************************************************************* 00639 * cli_alter_table 00640 * Change table format 00641 * Parameters: 00642 * session - session descriptor as returned by cli_open 00643 * tableName - name of existing table 00644 * nFields - number of columns in the table 00645 * fields - array with new table columns descriptors 00646 * Returns: 00647 * result code as described in cli_result_code enum 00648 */ 00649 int FASTDB_DLL_ENTRY cli_alter_table(int session, char const* tableName, int nFields, 00650 cli_field_descriptor* fields); 00651 00652 /********************************************************************* 00653 * cli_drop_table 00654 * drop the table 00655 * Parameters: 00656 * session - session descriptor as returned by cli_open 00657 * tableName - name of deleted table 00658 * Returns: 00659 * result code as described in cli_result_code enum 00660 */ 00661 int FASTDB_DLL_ENTRY cli_drop_table(int session, char const* tableName); 00662 00663 00664 /********************************************************************* 00665 * cli_alter_index 00666 * add or remove column index 00667 * Parameters: 00668 * session - session descriptor as returned by cli_open 00669 * tableName - name of the table 00670 * fieldName - name of field 00671 * newFlags - new flags of the field, if index exists for this field, but is not specified in 00672 * <code>newFlags</code> mask, then it will be removed; if index not exists, but is 00673 * specified in <code>newFlags</code> mask, then it will be created. * 00674 * Returns: 00675 * result code as described in cli_result_code enum 00676 */ 00677 int FASTDB_DLL_ENTRY cli_alter_index(int session, char const* tableName, char const* fieldName, 00678 int newFlags); 00679 00680 00681 /********************************************************************* 00682 * cli_set_error_handler 00683 * Set FastDB erro handler. Handler should be no-return function which perform stack unwind. 00684 * Parameters: 00685 * session - session descriptor as returned by cli_open 00686 * handler - error handler 00687 * context - error handler context: pointer to the user specific data 00688 * which will be passed to thr handler 00689 * Returns: 00690 * previous handler 00691 */ 00692 enum cli_error_class { 00693 cli_no_error, 00694 cli_query_error, 00695 cli_arithmetic_error, 00696 cli_index_out_of_range_error, 00697 cli_database_open_error, 00698 cli_file_error, 00699 cli_out_of_memory_error, 00700 cli_deadlock, 00701 cli_null_reference_error, 00702 cli_lock_revoked, 00703 cli_file_limit_exeeded 00704 }; 00705 typedef void (CLI_CALLBACK_CC *cli_error_handler)(int error, char const* msg, int msgarg, void* context); 00706 cli_error_handler FASTDB_DLL_ENTRY cli_set_error_handler(int session, cli_error_handler new_handler, void* context); 00707 00708 /********************************************************************* 00709 * cli_freeze 00710 * Freeze cursor. Make it possible to reused cursor after commit of the current transaction. 00711 * Parameters: 00712 * statement - statememt descriptor returned by cli_statement 00713 * Returns: 00714 * result code as described in cli_result_code enum 00715 */ 00716 int FASTDB_DLL_ENTRY cli_freeze(int statement); 00717 00718 /********************************************************************* 00719 * cli_unfreeze 00720 * Unfreeze cursor. Reuse previously frozen cursor. 00721 * Parameters: 00722 * statement - statememt descriptor returned by cli_statement 00723 * Returns: 00724 * result code as described in cli_result_code enum 00725 */ 00726 int FASTDB_DLL_ENTRY cli_unfreeze(int statement); 00727 00728 00729 /********************************************************************* 00730 * cli_attach 00731 * Attach thread to the database. Each thread except one opened the database should first 00732 * attach to the database before any access to the database, and detach after end of the work with database 00733 * Parameters: 00734 * session - session descriptor returned by cli_open 00735 * Returns: 00736 * result code as described in cli_result_code enum 00737 */ 00738 int FASTDB_DLL_ENTRY cli_attach(int session); 00739 00740 /********************************************************************* 00741 * cli_detach 00742 * Detach thread from the database. Each thread except one opened the database should perform 00743 * attach to the database before any access to the database, and detach after end of the work with database 00744 * Parameters: 00745 * session - session descriptor returned by cli_open 00746 * detach_mode - bit mask representing detach mode 00747 * Returns: 00748 * result code as described in cli_result_code enum 00749 */ 00750 enum cli_detach_mode { 00751 cli_commit_on_detach = 1, 00752 cli_destroy_context_on_detach = 2 00753 }; 00754 00755 int FASTDB_DLL_ENTRY cli_detach(int session, int detach_mode); 00756 00757 00758 /********************************************************************* 00759 * cli_free_memory 00760 * Free memory allocated by cli_show_tables and cli_describe 00761 * Parameters: 00762 * session - session descriptor returned by cli_open 00763 * ptr - pointer to the allocated buffer 00764 */ 00765 void FASTDB_DLL_ENTRY cli_free_memory(int session, void* ptr); 00766 00767 00768 typedef struct cli_database_monitor { 00769 int n_readers; 00770 int n_writers; 00771 int n_blocked_readers; 00772 int n_blocked_writers; 00773 int n_users; 00774 } cli_database_monitor; 00775 00776 /********************************************************************* 00777 * cli_get_database_state 00778 * Obtain information about current state of the database 00779 * Parameters: 00780 * session - session descriptor returned by cli_open 00781 * monitor - pointer to the monitor structure. The folloing fields are set: 00782 * n_readers: number of granted shared locks 00783 * n_writers: number of granted exclusive locks 00784 * n_blocked_reader: number of threads which shared lock request was blocked 00785 * n_blocked_writers: number of threads which exclusive lock request was blocked 00786 * n_users: number of processes openned the database 00787 * Returns: 00788 * result code as described in cli_result_code enum 00789 */ 00790 int FASTDB_DLL_ENTRY cli_get_database_state(int session, cli_database_monitor* monitor); 00791 00792 00793 00794 /********************************************************************* 00795 * cli_set_trace_function 00796 * Set trace function which will be used to output FastDB trace messages 00797 * Parameters: 00798 * func - pointer to trace function which receives trace message terminated with new line character 00799 */ 00800 typedef void (CLI_CALLBACK_CC *cli_trace_function_t)(char* msg); 00801 void FASTDB_DLL_ENTRY cli_set_trace_function(cli_trace_function_t func); 00802 00803 00804 /********************************************************************* 00805 * cli_prepare_query 00806 * Prepare SubSQL query statement. 00807 * Parameters: 00808 * session - session descriptor returned by cli_open 00809 * query - query string with optional parameters. Parameters are specified 00810 * as '%T' where T is one or two character code of parameter type using the same notation 00811 * as in printf: %d or %i - int, %f - float or double, %ld - int8, %s - string, %p - oid... 00812 * Parameter of cli_rectangle_t* type has format %R, cli_time_t type - %t 00813 * Returns: 00814 * >= 0 - statement descriptor 00815 * < 0 - error code as described in cli_result_code enum 00816 */ 00817 int FASTDB_DLL_ENTRY cli_prepare_query(int session, char const* query); 00818 00831 int FASTDB_DLL_ENTRY cli_execute_query(int statement, int for_update, void* record_struct, ...); 00832 00847 int FASTDB_DLL_ENTRY cli_execute_query_ex(int statement, int for_update, void* record_struct, int n_params, int* param_types, void** param_values); 00848 00860 int FASTDB_DLL_ENTRY cli_insert_struct(int session, char const* table_name, void* record_struct, cli_oid_t* oid); 00861 00862 typedef void* cli_transaction_context_t; 00863 /********************************************************************* 00864 * cli_create_transaction_context 00865 * Create new transaction xontext which can be used in cli_join_transaction function 00866 * Parameters: 00867 * Returns: 00868 * created transaction context 00869 */ 00870 cli_transaction_context_t FASTDB_DLL_ENTRY cli_create_transaction_context(); 00871 00872 /********************************************************************* 00873 * cli_join_transaction 00874 * Associate current threads with specified transaction context, 00875 * It allows to share single transaction between multiple threads. 00876 * Parameters: 00877 * session - session descriptor returned by cli_open 00878 * ctx - transaction context created by cli_create_transaction_context 00879 * Returns: 00880 * result code as described in cli_result_code enum 00881 */ 00882 int FASTDB_DLL_ENTRY cli_join_transaction(int session, cli_transaction_context_t ctx); 00883 00884 /********************************************************************* 00885 * cli_remove_transaction_context 00886 * Remove transaction context 00887 * Parameters: 00888 * ctx transaction context created by cli_create_transaction_context 00889 */ 00890 void FASTDB_DLL_ENTRY cli_remove_transaction_context(cli_transaction_context_t ctx); 00891 00892 #ifdef __cplusplus 00893 } 00894 #endif 00895 00896 #endif 00897 00898