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