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