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