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