00001 /*-< CLI.H >---------------------------------------------------------*--------* 00002 * GigaBASE Version 1.0 (c) 1999 GARRET * ? * 00003 * (Post Relational 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 GigaBASE server 00009 *-------------------------------------------------------------------*--------*/ 00010 00011 #ifndef __CLI_H__ 00012 #define __CLI_H__ 00013 00014 #ifndef GIGABASE_DLL_ENTRY 00015 #ifdef GIGABASE_DLL 00016 #ifdef INSIDE_GIGABASE 00017 #define GIGABASE_DLL_ENTRY __declspec(dllexport) 00018 #else 00019 #define GIGABASE_DLL_ENTRY __declspec(dllimport) 00020 #endif 00021 #else 00022 #define GIGABASE_DLL_ENTRY 00023 #endif 00024 #endif 00025 00026 00027 #include "config.h" 00028 #include <stddef.h> 00029 #include <stdio.h> 00030 #ifdef _WINCE 00031 #include "wince.h" 00032 #else 00033 #include <time.h> 00034 #endif 00035 00036 #if !defined(_WIN32) && !defined(__cdecl) 00037 #define __cdecl 00038 #endif 00039 00040 #ifdef __cplusplus 00041 extern "C" { 00042 #endif 00043 00044 enum cli_result_code { 00045 cli_ok = 0, 00046 cli_bad_address = -1, 00047 cli_connection_refused = -2, 00048 cli_database_not_found = -3, 00049 cli_bad_statement = -4, 00050 cli_parameter_not_found = -5, 00051 cli_unbound_parameter = -6, 00052 cli_column_not_found = -7, 00053 cli_incompatible_type = -8, 00054 cli_network_error = -9, 00055 cli_runtime_error = -10, 00056 cli_bad_descriptor = -11, 00057 cli_unsupported_type = -12, 00058 cli_not_found = -13, 00059 cli_not_update_mode = -14, 00060 cli_table_not_found = -15, 00061 cli_not_all_columns_specified = -16, 00062 cli_not_fetched = -17, 00063 cli_already_updated = -18, 00064 cli_table_already_exists = -19, 00065 cli_not_implemented = -20, 00066 cli_login_failed = -21, 00067 cli_empty_parameter = -22, 00068 cli_closed_connection = -23, 00069 cli_not_unique = -24, 00070 cli_xml_parse_error = -25, 00071 cli_backup_failed = -26 00072 }; 00073 00074 enum cli_var_type { 00075 cli_oid, 00076 cli_bool, 00077 cli_int1, 00078 cli_int2, 00079 cli_int4, 00080 cli_int8, 00081 cli_real4, 00082 cli_real8, 00083 cli_decimal, 00084 cli_asciiz, /* zero terminated string */ 00085 cli_pasciiz, /* pointer to zero terminated string */ 00086 cli_cstring, /* string with counter */ 00087 cli_array_of_oid, 00088 cli_array_of_bool, 00089 cli_array_of_int1, 00090 cli_array_of_int2, 00091 cli_array_of_int4, 00092 cli_array_of_int8, 00093 cli_array_of_real4, 00094 cli_array_of_real8, 00095 cli_array_of_decimal, 00096 cli_array_of_string, /* array of pointers to zero terminated strings */ 00097 cli_any, /* use the same type for column as stored in the database */ 00098 cli_datetime, /* time in seconds since 00:00:00 UTC, January 1, 1970. */ 00099 cli_autoincrement, /* column of int4 type automatically assigned value during record insert */ 00100 cli_rectangle, 00101 cli_unknown 00102 }; 00103 00104 typedef char cli_bool_t; 00105 typedef signed char cli_int1_t; 00106 typedef signed short cli_int2_t; 00107 typedef float cli_real4_t; 00108 typedef double cli_real8_t; 00109 00110 #ifndef RECTANGLE_COORDINATE_TYPE 00111 #define RECTANGLE_COORDINATE_TYPE int 00112 //#define RECTANGLE_COORDINATE_TYPE double 00113 #endif 00114 typedef RECTANGLE_COORDINATE_TYPE cli_coord_t; 00115 #ifndef RECTANGLE_DIMENSION 00116 #define RECTANGLE_DIMENSION 2 00117 #endif 00118 00119 typedef struct cli_rectangle_t { 00120 cli_coord_t boundary[RECTANGLE_DIMENSION*2]; 00121 } cli_rectangle_t; 00122 00123 #ifndef CLI_TIME_T_DEFINED 00124 typedef time_t cli_time_t; 00125 #endif 00126 00127 #ifndef __STDTP_H__ 00128 #ifdef UNICODE 00129 typedef wchar_t char_t; 00130 #define STRLEN(x) wcslen(x) 00131 #define STRCMP(x, y) wcscmp(x, y) 00132 #define STRCPY(x, y) wcscpy(x, y) 00133 #define STRNCPY(x,y,z) wcsncpy(x, y, z) 00134 #define STRCOLL(x, y) wcscoll(x, y) 00135 #define STRNCMP(x,y,z) wcsncmp(x, y, z) 00136 #define STRLITERAL(x) (wchar_t*)L##x 00137 #define PRINTF wprintf 00138 #define FPRINTF fwprintf 00139 #ifdef _WIN32 00140 #ifdef _SWPRINTFS_DEPRECATED 00141 #define SPRINTF _swprintf 00142 #else 00143 #define SPRINTF swprintf 00144 #endif 00145 #define SPRINTF_BUFFER(buf) buf 00146 #else 00147 #define SPRINTF swprintf 00148 #define SPRINTF_BUFFER(buf) buf, 0x1000000 00149 #endif 00150 #define VFPRINTF vfwprintf 00151 #define FSCANF fwscanf 00152 #define SSCANF swscanf 00153 #define GETC(x) getwc(x) 00154 #define UNGETC(x, y) ungetwc(x, y) 00155 #define TOLOWER(x) towlower((x) & 0xFFFF) 00156 #define TOUPPER(x) towlower((x) & 0xFFFF) 00157 #define ISALNUM(x) iswalnum((x) & 0xFFFF) 00158 #define STRSTR(x, y) wcsstr(x, y) 00159 #define STRXFRM(x,y,z) wcsxfrm(x, y, z) 00160 #define STRFTIME(a,b,c,d) wcsftime(a,b,c,d) 00161 #ifndef _T 00162 #define _T(x) L##x 00163 #endif 00164 #else 00165 typedef char char_t; 00166 #define STRLEN(x) strlen(x) 00167 #define STRCMP(x, y) strcmp(x, y) 00168 #define STRCPY(x, y) strcpy(x, y) 00169 #define STRNCPY(x,y,z) strncpy(x, y, z) 00170 #define STRCOLL(x, y) strcoll(x, y) 00171 #define STRNCMP(x,y,z) strncmp(x, y, z) 00172 #define PRINTF printf 00173 #define FPRINTF fprintf 00174 #define SPRINTF sprintf 00175 #define SPRINTF_BUFFER(buf) buf 00176 #define VFPRINTF vfprintf 00177 #define FSCANF fscanf 00178 #define SSCANF sscanf 00179 #define GETC(x) getc(x) 00180 #define UNGETC(x, y) ungetc(x, y) 00181 #define TOLOWER(x) tolower((x) & 0xFF) 00182 #define TOUPPER(x) toupper((x) & 0xFF) 00183 #define ISALNUM(x) isalnum((x) & 0xFF) 00184 #define STRSTR(x, y) strstr(x, y) 00185 #define STRXFRM(x,y,z) strxfrm(x, y, z) 00186 #define STRFTIME(a,b,c,d) strftime(a,b,c,d) 00187 #ifndef _T 00188 #define _T(x) x 00189 #endif 00190 #endif 00191 #else 00192 USE_GIGABASE_NAMESPACE 00193 #endif 00194 00195 typedef struct cli_cstring_t { 00196 int len; 00197 char_t* ptr; 00198 } cli_cstring_t; 00199 00200 00201 #if !defined(SIZEOF_LONG) && (defined(_L64) || defined(_LP64) || defined(__osf__)) 00202 #define SIZEOF_LONG 8 00203 #endif 00204 00205 00206 #if (defined(_WIN32) || defined(__BORLANDC__)) && !defined(__MINGW32__) 00207 typedef signed __int32 cli_int4_t; 00208 typedef __int64 cli_int8_t; 00209 typedef unsigned __int64 cli_nat8_t; 00210 #else 00211 typedef signed int cli_int4_t; 00212 #if SIZEOF_LONG == 8 00213 typedef signed long cli_int8_t; 00214 typedef unsigned long cli_nat8_t; 00215 #else 00216 typedef signed long long cli_int8_t; 00217 typedef unsigned long long cli_nat8_t; 00218 #endif 00219 #endif 00220 00221 #ifndef CLI_OID_DEFINED 00222 #if dbDatabaseOidBits > 32 00223 typedef cli_nat8_t cli_oid_t; 00224 #else 00225 typedef unsigned cli_oid_t; 00226 #endif 00227 #endif 00228 00229 // structure used to represent array field in structure extracted by cli_execute_query 00230 typedef struct cli_array_t { 00231 size_t size; // number of elements in the array 00232 void* data; // pointer to the array elements 00233 size_t allocated; // internal field: size of allocated buffer 00234 } cli_array_t; 00235 00236 00237 /********************************************************************* 00238 * cli_open 00239 * Establish connection with the server 00240 * Parameters: 00241 * server_url - zero terminated string with server address and port, 00242 * for example "localhost:5101", "195.239.208.240:6100",... 00243 * max_connect_attempts - number of attempts to establish connection 00244 * reconnect_timeout_sec - timeput in seconds between connection attempts 00245 * user_name - user name for login 00246 * password - password for login 00247 * pooled_connection - if not 0, then connection will be allocated from the connection pool 00248 * Returns: 00249 * >= 0 - connectiondescriptor to be used in all other cli calls 00250 * < 0 - error code as described in cli_result_code enum 00251 */ 00252 int GIGABASE_DLL_ENTRY cli_open(char const* server_url, 00253 int max_connect_attempts, 00254 int reconnect_timeout_sec, 00255 char_t const* user_name, 00256 char_t const* password, 00257 int pooled_connection); 00258 00259 enum cli_open_attributes { 00260 cli_open_default = 0x00, 00261 cli_open_readonly = 0x01, // open database in readonly mode 00262 cli_open_truncate = 0x02, // truncate database file on open 00263 cli_open_no_buffering = 0x04, // do not use file system cache 00264 cli_open_multiclient = 0x08, // use OS file locks to provide multiclient access to the database 00265 cli_open_do_not_reuse_oids_on_close = 0x10 // do not reuse OIDs of deallocated objects when session is closed 00266 00267 }; 00268 /********************************************************************* 00269 * cli_create 00270 * Create connection to the local database 00271 * Parameters: 00272 * databasePath - path to the database file 00273 * transactionCommitDelay - trasnaction commit delay (specify 0 to disable) 00274 * openAttr - mask of cli_open_attributes 00275 * poolSize - size of page pool (in pages), specify 0 to let GigaBASE automaticaly detect pool size 00276 * Returns: 00277 * >= 0 - connection descriptor to be used in all other cli calls 00278 * < 0 - error code as described in cli_result_code enum 00279 */ 00280 00281 int GIGABASE_DLL_ENTRY cli_create(char_t const* databasePath, 00282 unsigned transactionCommitDelay, 00283 int openAttr, 00284 size_t poolSize); 00285 00286 00287 #ifdef SUPPORT_DATA_ENCRYPTION 00288 /********************************************************************* 00289 * cli_create_encrypted 00290 * Create connection to the local encrypted database 00291 * Parameters: 00292 * databasePath - path to the database file 00293 * transactionCommitDelay - trasnaction commit delay (specify 0 to disable) 00294 * openAttr - mask of cli_open_attributes 00295 * poolSize - size of page pool (in pages), specify 0 to let GigaBASE automaticaly detect pool size 00296 * password - password for accessing database 00297 * Returns: 00298 * >= 0 - connection descriptor to be used in all other cli calls 00299 * < 0 - error code as described in cli_result_code enum 00300 */ 00301 int GIGABASE_DLL_ENTRY cli_create_encrypted(char_t const* databasePath, 00302 unsigned transactionCommitDelay, 00303 int openAttr, 00304 size_t poolSize, 00305 char const* password); 00306 #endif 00307 00308 /********************************************************************* 00309 * cli_close 00310 * Close session 00311 * Parameters: 00312 * session - session descriptor returned by cli_open 00313 * Returns: 00314 * result code as described in cli_result_code enum 00315 */ 00316 int GIGABASE_DLL_ENTRY cli_close(int session); 00317 00318 /********************************************************************* 00319 * cli_clear_connection_pool 00320 * Close all released connection in connection pool 00321 */ 00322 void GIGABASE_DLL_ENTRY cli_clear_connection_pool(); 00323 00324 /********************************************************************* 00325 * cli_statement 00326 * Specify SubSQL statement to be executed at server 00327 * Binding to the parameters and columns can be established 00328 * Parameters: 00329 * session - session descriptor returned by cli_open 00330 * stmt - zero terminated string with SubSQL statement 00331 * Returns: 00332 * >= 0 - statement descriptor 00333 * < 0 - error code as described in cli_result_code enum 00334 */ 00335 int GIGABASE_DLL_ENTRY cli_statement(int session, char_t const* stmt); 00336 00337 /********************************************************************* 00338 * cli_parameter 00339 * Bind parameter to the statement 00340 * Parameters: 00341 * statement - statememt descriptor returned by cli_statement 00342 * param_name - zero terminated string with parameter name 00343 * Paramter name should start with '%' 00344 * var_type - type of variable as described in cli_var_type enum. 00345 * Only scalar and zero terminated string types are supported. 00346 * var_ptr - pointer to the variable 00347 * Returns: 00348 * result code as described in cli_result_code enum 00349 */ 00350 int GIGABASE_DLL_ENTRY cli_parameter(int statement, 00351 char_t const* param_name, 00352 int var_type, 00353 void* var_ptr); 00354 00355 /********************************************************************* 00356 * cli_column 00357 * Bind extracted column of select or insert statement 00358 * Parameters: 00359 * statement - statememt descriptor returned by cli_statement 00360 * column_name - zero terminated string with column name 00361 * var_type - type of variable as described in cli_var_type enum 00362 * var_len - pointer to the variable to hold length of array variable. 00363 * This variable should be assigned the maximal length 00364 * of the array/string buffer, pointed by var_ptr. 00365 * After the execution of the statement it is assigned the 00366 * real length of the fetched array/string. If it is large 00367 * than length of the buffer, then only part of the array 00368 * will be placed in the buffer, but var_len still will 00369 * contain the actual array length. 00370 * var_ptr - pointer to the variable 00371 * Returns: 00372 * result code as described in cli_result_code enum 00373 */ 00374 int GIGABASE_DLL_ENTRY cli_column(int statement, 00375 char_t const* column_name, 00376 int var_type, 00377 int* var_len, 00378 void* var_ptr); 00379 00380 00381 typedef void* (*cli_column_set)(int var_type, void* var_ptr, int len); 00382 typedef void* (*cli_column_get)(int var_type, void* var_ptr, int* len); 00383 00384 typedef void* (*cli_column_set_ex)(int var_type, void* var_ptr, int len, 00385 char_t const* column_name, int statement, void const* data_ptr, void* user_data); 00386 typedef void* (*cli_column_get_ex)(int var_type, void* var_ptr, int* len, 00387 char_t const* column_name, int statemen, void* user_data); 00388 00389 /********************************************************************* 00390 * cli_array_column 00391 * Specify get/set functions for the array column 00392 * Parameters: 00393 * statement - statememt descriptor returned by cli_statement 00394 * column_name - zero terminated string with column name 00395 * var_type - type of variable as described in cli_var_type enum 00396 * var_ptr - pointer to the variable 00397 * set - function which will be called to construct fetched 00398 * field. It receives pointer to the variable, 00399 * length of the fetched array and returns pointer to th 00400 * array's elements 00401 * get - function which will be called to update the field in the 00402 * database. Given pointer to the variable, it should return 00403 * pointer to the array elements and store length of the 00404 * array to the variable pointer by len parameter 00405 * user_data - pointer to user specific data passed to get and set functions 00406 * Returns: 00407 * result code as described in cli_result_code enum 00408 */ 00409 int GIGABASE_DLL_ENTRY cli_array_column(int statement, 00410 char_t const* column_name, 00411 int var_type, 00412 void* var_ptr, 00413 cli_column_set set, 00414 cli_column_get get); 00415 00416 int GIGABASE_DLL_ENTRY cli_array_column_ex(int statement, 00417 char_t const* column_name, 00418 int var_type, 00419 void* var_ptr, 00420 cli_column_set_ex set, 00421 cli_column_get_ex get, 00422 void* user_data); 00423 00424 00425 enum cli_cursor_type_t { 00426 cli_cursor_view_only, 00427 cli_cursor_for_update, 00431 cli_cursor_incremental, 00440 cli_cursor_detached 00441 }; 00442 00443 /********************************************************************* 00444 * cli_fetch 00445 * Execute select statement. 00446 * Parameters: 00447 * statement - statememt descriptor returned by cli_statement 00448 * cursor_type - cursor type described by cli_cursor_type_t enum 00449 * Returns: 00450 * >= 0 - success, for select statements number of fetched rows is returned 00451 * < 0 - error code as described in cli_result_code enum 00452 */ 00453 int GIGABASE_DLL_ENTRY cli_fetch(int statement, int cursor_type); 00454 00455 /********************************************************************* 00456 * cli_insert 00457 * Execute insert statement. 00458 * Parameters: 00459 * statement - statememt descriptor returned by cli_statement 00460 * oid - object identifier of created record. 00461 * Returns: 00462 * status code as described in cli_result_code enum 00463 */ 00464 int GIGABASE_DLL_ENTRY cli_insert(int statement, cli_oid_t* oid); 00465 00466 /********************************************************************* 00467 * cli_batch_insert 00468 * Execute batch insert statement. In batch insert mode records will be included in indices 00469 * at the trasnaction commit time or after explicit execution of cli_exec_batch 00470 * Parameters: 00471 * statement - statememt descriptor returned by cli_statement 00472 * oid - object identifier of created record. 00473 * Returns: 00474 * status code as described in cli_result_code enum 00475 */ 00476 int GIGABASE_DLL_ENTRY cli_batch_insert(int statement, cli_oid_t* oid); 00477 00478 /********************************************************************* 00479 * cli_get_first 00480 * Get first row of the selection. 00481 * Parameters: 00482 * statement - statememt descriptor returned by cli_statement 00483 * Returns: 00484 * result code as described in cli_result_code enum 00485 */ 00486 int GIGABASE_DLL_ENTRY cli_get_first(int statement); 00487 00488 /********************************************************************* 00489 * cli_get_last 00490 * Get last row of the selection. 00491 * Parameters: 00492 * statement - statememt descriptor returned by cli_statement 00493 * Returns: 00494 * result code as described in cli_result_code enum 00495 */ 00496 int GIGABASE_DLL_ENTRY cli_get_last(int statement); 00497 00498 /********************************************************************* 00499 * cli_get_next 00500 * Get next row of the selection. If get_next records is called 00501 * exactly after cli_fetch function call, is will fetch the first record 00502 * in selection. 00503 * Parameters: 00504 * statement - statememt descriptor returned by cli_statement 00505 * Returns: 00506 * result code as described in cli_result_code enum 00507 */ 00508 int GIGABASE_DLL_ENTRY cli_get_next(int statement); 00509 00510 /********************************************************************* 00511 * cli_get_prev 00512 * Get previous row of the selection. If get_next records is called 00513 * exactly after cli_fetch function call, is will fetch the last record 00514 * in selection. 00515 * Parameters: 00516 * statement - statememt descriptor returned by cli_statement 00517 * Returns: 00518 * result code as described in cli_result_code enum 00519 */ 00520 int GIGABASE_DLL_ENTRY cli_get_prev(int statement); 00521 00522 /********************************************************************* 00523 * cli_skip 00524 * Skip specified number of rows. 00525 * Parameters: 00526 * statement - statememt descriptor returned by cli_statement 00527 * n - number of objects to be skipped 00528 * - if "n" is positive, then this function has the same effect as 00529 * executing cli_get_next() function "n" times. 00530 * - if "n" is negative, then this function has the same effect as 00531 * executing cli_get_prev() function "-n" times. 00532 * - if "n" is zero, this method just reloads current record 00533 * Returns: 00534 * result code as described in cli_result_code enum 00535 */ 00536 int GIGABASE_DLL_ENTRY cli_skip(int statement, int n); 00537 00538 /********************************************************************* 00539 * cli_seek 00540 * Position cursor to the record with specified OID 00541 * Parameters: 00542 * statement - statememt descriptor returned by cli_statement 00543 * oid - object identifier of the record to which cursor should be positioned 00544 * Returns: 00545 * >= 0 - success, position of the record in the selection 00546 * < 0 - error code as described in cli_result_code enum 00547 */ 00548 int GIGABASE_DLL_ENTRY cli_seek(int statement, cli_oid_t oid); 00549 00550 /********************************************************************* 00551 * cli_get_oid 00552 * Get object identifier of the current record 00553 * Parameters: 00554 * statement - statememt descriptor returned by cli_statement 00555 * Returns: 00556 * object identifier or 0 if no object is seleected 00557 */ 00558 cli_oid_t GIGABASE_DLL_ENTRY cli_get_oid(int statement); 00559 00560 /********************************************************************* 00561 * cli_update 00562 * Update the current row in the selection. You have to set 00563 * for_update parameter of cli_fetch to 1 in order to be able 00564 * to perform updates. Updated value of row fields will be taken 00565 * from bound column variables. 00566 * Parameters: 00567 * statement - statememt descriptor returned by cli_statement 00568 * Returns: 00569 * result code as described in cli_result_code enum 00570 */ 00571 int GIGABASE_DLL_ENTRY cli_update(int statement); 00572 00573 /********************************************************************* 00574 * cli_remove 00575 * Remove all selected records. You have to set 00576 * for_update parameter of cli_fetch to 1 in order to be able 00577 * to remove records. 00578 * Parameters: 00579 * statement - statememt descriptor returned by cli_statement 00580 * Returns: 00581 * result code as described in cli_result_code enum 00582 */ 00583 int GIGABASE_DLL_ENTRY cli_remove(int statement); 00584 00585 /********************************************************************* 00586 * cli_remove_current 00587 * Remove currently selected record. You have to set 00588 * for_update parameter of cli_fetch to 1 in order to be able 00589 * to remove records. 00590 * Parameters: 00591 * statement - statememt descriptor returned by cli_statement 00592 * Returns: 00593 * result code as described in cli_result_code enum 00594 */ 00595 int GIGABASE_DLL_ENTRY cli_remove_current(int statement); 00596 00597 /********************************************************************* 00598 * cli_free 00599 * Deallocate statement and all associated data 00600 * Parameters: 00601 * statement - statememt descriptor returned by cli_statement 00602 * Returns: 00603 * result code as described in cli_result_code enum 00604 */ 00605 int GIGABASE_DLL_ENTRY cli_free(int statement); 00606 00607 /********************************************************************* 00608 * cli_close_cursor 00609 * Close current cursor 00610 * Parameters: 00611 * statement - statememt descriptor returned by cli_statement 00612 * Returns: 00613 * result code as described in cli_result_code enum 00614 */ 00615 int GIGABASE_DLL_ENTRY cli_close_cursor(int statement); 00616 00617 /********************************************************************* 00618 * cli_exec_batch 00619 * Complete all batch inserts 00620 * Parameters: 00621 * session - session descriptor as returned by cli_open 00622 * Returns: 00623 * status code as described in cli_result_code enum 00624 */ 00625 int GIGABASE_DLL_ENTRY cli_exec_batch(int session); 00626 00627 /********************************************************************* 00628 * cli_commit 00629 * Commit current database transaction 00630 * Parameters: 00631 * session - session descriptor as returned by cli_open 00632 * Returns: 00633 * result code as described in cli_result_code enum 00634 */ 00635 int GIGABASE_DLL_ENTRY cli_commit(int session); 00636 00637 /********************************************************************* 00638 * cli_precommit 00639 * Release all locks set by transaction. This methods allows other clients 00640 * to proceed, but it doesn't flush transaction to the disk. 00641 * Parameters: 00642 * session - session descriptor as returned by cli_open 00643 * Returns: 00644 * result code as described in cli_result_code enum 00645 */ 00646 int GIGABASE_DLL_ENTRY cli_precommit(int session); 00647 00648 /********************************************************************* 00649 * cli_abort 00650 * Abort current database transaction 00651 * Parameters: 00652 * session - session descriptor as returned by cli_open 00653 * Returns: 00654 * result code as described in cli_result_code enum 00655 */ 00656 int GIGABASE_DLL_ENTRY cli_abort(int session); 00657 00658 enum cli_field_flags { 00659 cli_hashed = 1, /* field should be indexed usnig hash table */ 00660 cli_indexed = 2, /* field should be indexed using B-Tree */ 00661 cli_case_insensitive = 4, /* index is case insensitive */ 00662 cli_cascade_delete = 8, /* perfrom cascade delete for for reference or array of reference fields */ 00663 cli_unique = 16, /* index containing unique keys */ 00664 cli_autoincremented = 32, /* field is assigned automaticall incremented value */ 00665 cli_optimize_duplicates = 64 /* index with lot of duplicate key values */ 00666 }; 00667 00668 typedef struct cli_field_descriptor { 00669 enum cli_var_type type; 00670 int flags; 00671 char_t const* name; 00672 char_t const* refTableName; 00673 char_t const* inverseRefFieldName; 00674 } cli_field_descriptor; 00675 00676 /********************************************************************* 00677 * cli_describe 00678 * Describe fileds of specified table 00679 * Parameters: 00680 * session - session descriptor as returned by cli_open 00681 * table - name of the table 00682 * fields - adress of the pointer to the array of fields descriptors, 00683 * this array should be later deallocated by application by cli_free_memory() 00684 * Returns: 00685 * >= 0 - number of fields in the table 00686 * < 0 - result code as described in cli_result_code enum 00687 */ 00688 int GIGABASE_DLL_ENTRY cli_describe(int session, char_t const* table, cli_field_descriptor** fields); 00689 00690 typedef struct cli_field_layout { 00691 cli_field_descriptor desc; 00692 int offs; 00693 int size; 00694 } cli_field_layout; 00695 00696 /********************************************************************* 00697 * cli_describe_layout 00698 * Describe fields layout of specified table 00699 * Parameters: 00700 * session - session descriptor as returned by cli_open 00701 * table - name of the table 00702 * fields - address of the pointer to the array of fields layout descriptors, 00703 * this array should be later deallocated by application by cli_free_memory() 00704 * 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 00705 * Returns: 00706 * >= 0 - number of fields in the table 00707 * < 0 - result code as described in cli_result_code enum 00708 */ 00709 int GIGABASE_DLL_ENTRY cli_describe_layout(int session, char_t const* table, cli_field_layout** fields, int* rec_size); 00710 00711 /********************************************************************* 00712 * cli_get_field_size 00713 * Calculate field size 00714 * Parameters: 00715 * fields - array with fields descriptors obtained using cli_describe function 00716 * field_no - number of the field 00717 */ 00718 int GIGABASE_DLL_ENTRY cli_get_field_size(cli_field_descriptor* fields, int field_no); 00719 00720 /********************************************************************* 00721 * cli_get_field_offset 00722 * Calculate offset of the field 00723 * Parameters: 00724 * fields - array with fields descriptors obtained using cli_describe function 00725 * field_no - number of the field 00726 */ 00727 int GIGABASE_DLL_ENTRY cli_get_field_offset(cli_field_descriptor* fields, int field_no); 00728 00729 typedef struct cli_table_descriptor { 00730 char_t const* name; 00731 } cli_table_descriptor; 00732 00733 /********************************************************************* 00734 * cli_show_tables 00735 * Show all tables of specified database 00736 * Parameters: 00737 * session - session descriptor as returned by cli_open 00738 * tables - address of the pointer to the array of tables descriptors, 00739 * this array should be later deallocated by application by cli_free_memory() 00740 * Returns: 00741 * >= 0 - number of tables in the database (Metatable is not returned/counted) 00742 * < 0 - result code as described in cli_result_code enum 00743 */ 00744 int GIGABASE_DLL_ENTRY cli_show_tables(int session, cli_table_descriptor** tables); 00745 00746 00747 00748 /********************************************************************* 00749 * cli_create_table 00750 * Create new table 00751 * Parameters: 00752 * session - session descriptor as returned by cli_open 00753 * tableName - name of new table 00754 * nFields - number of columns in the table 00755 * fields - array with table columns descriptors 00756 * Returns: 00757 * result code as described in cli_result_code enum 00758 */ 00759 int GIGABASE_DLL_ENTRY cli_create_table(int session, char_t const* tableName, int nFields, 00760 cli_field_descriptor* fields); 00761 00762 /********************************************************************* 00763 * cli_alter_table 00764 * Change table format 00765 * Parameters: 00766 * session - session descriptor as returned by cli_open 00767 * tableName - name of existing table 00768 * nFields - number of columns in the table 00769 * fields - array with new table columns descriptors 00770 * Returns: 00771 * result code as described in cli_result_code enum 00772 */ 00773 int GIGABASE_DLL_ENTRY cli_alter_table(int session, char_t const* tableName, int nFields, 00774 cli_field_descriptor* fields); 00775 00776 /********************************************************************* 00777 * cli_drop_table 00778 * drop the table 00779 * Parameters: 00780 * session - session descriptor as returned by cli_open 00781 * tableName - name of deleted table 00782 * Returns: 00783 * result code as described in cli_result_code enum 00784 */ 00785 int GIGABASE_DLL_ENTRY cli_drop_table(int session, char_t const* tableName); 00786 00787 00788 /********************************************************************* 00789 * cli_alter_index 00790 * add or remove column index 00791 * Parameters: 00792 * session - session descriptor as returned by cli_open 00793 * tableName - name of the table 00794 * fieldName - name of field 00795 * newFlags - new flags of the field, if index exists for this field, but is not specified in 00796 * <code>newFlags</code> mask, then it will be removed; if index not exists, but is 00797 * specified in <code>newFlags</code> mask, then it will be created. * 00798 * Returns: 00799 * result code as described in cli_result_code enum 00800 */ 00801 int GIGABASE_DLL_ENTRY cli_alter_index(int session, char_t const* tableName, char_t const* fieldName, 00802 int newFlags); 00803 00804 00805 /********************************************************************* 00806 * cli_set_error_handler 00807 * Set GigaBASE error handler. Handler should be no-return function which perform stack unwind. 00808 * Parameters: 00809 * session - session descriptor as returned by cli_open 00810 * handler - error handler 00811 * Returns: 00812 * previous handler 00813 */ 00814 enum cli_error_class { 00815 cli_no_error, 00816 cli_query_error, 00817 cli_arithmetic_error, 00818 cli_index_out_of_range_error, 00819 cli_database_open_error, 00820 cli_file_error, 00821 cli_out_of_memory_error, 00822 cli_deadlock, 00823 cli_null_reference_error, 00824 cli_lock_revoked, 00825 cli_file_limit_exeeded, 00826 cli_database_read_only, 00827 cli_unique_constraint_violation, 00828 cli_inconsistent_inverse_reference, 00829 cli_operation_not_supported, 00830 cli_socket_error, 00831 cli_cursor_error, 00832 cli_access_to_deleted_object, 00833 cli_incompatible_schema_change 00834 00835 }; 00836 typedef void (*cli_error_handler)(int error, char const* msg, int msgarg, void* context); 00837 cli_error_handler GIGABASE_DLL_ENTRY cli_set_error_handler(int session, cli_error_handler new_handler, void* context); 00838 00839 /********************************************************************* 00840 * cli_freeze 00841 * Freeze cursor. Make it possible to reused cursor after commit of the current transaction. 00842 * Parameters: 00843 * statement - statememt descriptor returned by cli_statement 00844 * Returns: 00845 * result code as described in cli_result_code enum 00846 */ 00847 int GIGABASE_DLL_ENTRY cli_freeze(int statement); 00848 00849 /********************************************************************* 00850 * cli_unfreeze 00851 * Unfreeze cursor. Reuse previously frozen cursor. 00852 * Parameters: 00853 * statement - statememt descriptor returned by cli_statement 00854 * Returns: 00855 * result code as described in cli_result_code enum 00856 */ 00857 int GIGABASE_DLL_ENTRY cli_unfreeze(int statement); 00858 00859 00860 /********************************************************************* 00861 * cli_attach 00862 * Attach thread to the database. Each thread except one opened the database should first 00863 * attach to the database before any access to the database, and detach after end of the work with database 00864 * Parameters: 00865 * session - session descriptor returned by cli_open 00866 * Returns: 00867 * result code as described in cli_result_code enum 00868 */ 00869 int GIGABASE_DLL_ENTRY cli_attach(int session); 00870 00871 /********************************************************************* 00872 * cli_detach 00873 * Detach thread from the database. Each thread except one opened the database should perform 00874 * attach to the database before any access to the database, and detach after end of the work with database 00875 * Parameters: 00876 * session - session descriptor returned by cli_open 00877 * detach_mode - bit mask representing detach mode 00878 * Returns: 00879 * result code as described in cli_result_code enum 00880 */ 00881 enum cli_detach_mode { 00882 cli_commit_on_detach = 1, 00883 cli_destroy_context_on_detach = 2 00884 }; 00885 00886 int GIGABASE_DLL_ENTRY cli_detach(int session, int detach_mode); 00887 00888 /********************************************************************* 00889 * cli_free_memory 00890 * Free memory allocated by cli_show_tables and cli_describe 00891 * Parameters: 00892 * session - session descriptor returned by cli_open 00893 * ptr - pointer to the allocated buffer 00894 */ 00895 void GIGABASE_DLL_ENTRY cli_free_memory(int session, void* ptr); 00896 00897 00898 typedef void* cli_transaction_context_t; 00899 /********************************************************************* 00900 * cli_create_transaction_context 00901 * Create new transaction xontext which can be used in cli_join_transaction function 00902 * Parameters: 00903 * Returns: 00904 * created transaction context 00905 */ 00906 cli_transaction_context_t GIGABASE_DLL_ENTRY cli_create_transaction_context(); 00907 00908 /********************************************************************* 00909 * cli_join_transaction 00910 * Associate current threads with specified transaction context, 00911 * It allows to share single transaction between multiple threads. 00912 * Parameters: 00913 * session - session descriptor returned by cli_open 00914 * ctx - transaction context created by cli_create_transaction_context 00915 * Returns: 00916 * result code as described in cli_result_code enum 00917 */ 00918 int GIGABASE_DLL_ENTRY cli_join_transaction(int session, cli_transaction_context_t ctx); 00919 00920 /********************************************************************* 00921 * cli_remove_transaction_context 00922 * Remove transaction context 00923 * Parameters: 00924 * ctx transaction context created by cli_create_transaction_context 00925 */ 00926 void GIGABASE_DLL_ENTRY cli_remove_transaction_context(cli_transaction_context_t ctx); 00927 00928 00929 /********************************************************************* 00930 * cli_set_trace_function 00931 * Set trace function which will be used to output GigaBASE trace messages 00932 * Parameters: 00933 * func - pointer to trace function which receives trace message terminated with new line character 00934 */ 00935 typedef void (*cli_trace_function_t)(char_t* msg); 00936 void GIGABASE_DLL_ENTRY cli_set_trace_function(cli_trace_function_t func); 00937 00938 /********************************************************************* 00939 * cli_prepare_query 00940 * Prepare SubSQL query statement. 00941 * Parameters: 00942 * session - session descriptor returned by cli_open 00943 * query - query string with optional parameters. Parameters are specified 00944 * as '%T' where T is one or two character code of parameter type using the same notation 00945 * as in printf: %d or %i - int, %f - float or double, %ld - int8, %s - string, %p - oid... 00946 * Parameter of cli_rectangle_t* type has format %R, cli_time_t type - %t 00947 * Returns: 00948 * >= 0 - statement descriptor 00949 * < 0 - error code as described in cli_result_code enum 00950 */ 00951 int GIGABASE_DLL_ENTRY cli_prepare_query(int session, char_t const* query); 00952 00965 int GIGABASE_DLL_ENTRY cli_execute_query(int statement, int cursor_type, void* record_struct, ...); 00966 00981 int GIGABASE_DLL_ENTRY cli_execute_query_ex(int statement, int cursor_type, void* record_struct, int n_params, int* param_types, void** param_values); 00982 00994 int GIGABASE_DLL_ENTRY cli_insert_struct(int session, char_t const* table_name, void* record_struct, cli_oid_t* oid); 00995 01004 int GIGABASE_DLL_ENTRY cli_lock(int session); 01005 01006 typedef enum cli_export_method { 01007 cli_export_all, /* just export all tables */ 01008 cli_export_all_expect, /* '-' Export all tables except the named tables */ 01009 cli_export_named_only /* '+' Only export explicitly named tables */ 01010 } cli_export_method; 01011 01024 int GIGABASE_DLL_ENTRY cli_xml_export(int session, FILE* out, char_t const* const* tables, int n_tables, cli_export_method method); 01025 01035 int GIGABASE_DLL_ENTRY cli_xml_import(int session, FILE* in); 01036 01049 int GIGABASE_DLL_ENTRY cli_backup(int session, char_t const* file_name, int compactify); 01050 01062 int GIGABASE_DLL_ENTRY cli_schedule_backup(int session, char_t const* file_name, int period); 01063 01073 int GIGABASE_DLL_ENTRY cli_get_database_size(int session, cli_nat8_t* size); 01074 01075 01076 #ifdef __cplusplus 01077 } 01078 #endif 01079 01080 #endif 01081 01082