1 /*-< CLI.H >---------------------------------------------------------*--------* 2 * GigaBASE Version 1.0 (c) 1999 GARRET * ? * 3 * (Post Relational Database Management System) * /\| * 4 * * / \ * 5 * Created: 13-Jan-2000 K.A. Knizhnik * / [] \ * 6 * Last update: 13-Jan-2000 K.A. Knizhnik * GARRET * 7 *-------------------------------------------------------------------*--------* 8 * Call level interface to GigaBASE server 9 *-------------------------------------------------------------------*--------*/ 10 11 #ifndef __CLI_H__ 12 #define __CLI_H__ 13 14 #ifndef GIGABASE_DLL_ENTRY 15 #ifdef GIGABASE_DLL 16 #ifdef INSIDE_GIGABASE 17 #define GIGABASE_DLL_ENTRY __declspec(dllexport) 18 #else 19 #define GIGABASE_DLL_ENTRY __declspec(dllimport) 20 #endif 21 #else 22 #define GIGABASE_DLL_ENTRY 23 #endif 24 #endif 25 26 27 #include "config.h" 28 #include <stddef.h> 29 #include <stdio.h> 30 #ifdef _WINCE 31 #include "wince.h" 32 #else 33 #include <time.h> 34 #endif 35 36 #if !defined(_WIN32) && !defined(__cdecl) 37 #define __cdecl 38 #endif 39 40 #ifdef __cplusplus 41 extern "C" { 42 #endif 43 44 enum cli_result_code { 45 cli_ok = 0, 46 cli_bad_address = -1, 47 cli_connection_refused = -2, 48 cli_database_not_found = -3, 49 cli_bad_statement = -4, 50 cli_parameter_not_found = -5, 51 cli_unbound_parameter = -6, 52 cli_column_not_found = -7, 53 cli_incompatible_type = -8, 54 cli_network_error = -9, 55 cli_runtime_error = -10, 56 cli_bad_descriptor = -11, 57 cli_unsupported_type = -12, 58 cli_not_found = -13, 59 cli_not_update_mode = -14, 60 cli_table_not_found = -15, 61 cli_not_all_columns_specified = -16, 62 cli_not_fetched = -17, 63 cli_already_updated = -18, 64 cli_table_already_exists = -19, 65 cli_not_implemented = -20, 66 cli_login_failed = -21, 67 cli_empty_parameter = -22, 68 cli_closed_connection = -23, 69 cli_not_unique = -24, 70 cli_xml_parse_error = -25, 71 cli_backup_failed = -26 72 }; 73 74 enum cli_var_type { 75 cli_oid, 76 cli_bool, 77 cli_int1, 78 cli_int2, 79 cli_int4, 80 cli_int8, 81 cli_real4, 82 cli_real8, 83 cli_decimal, 84 cli_asciiz, /* zero terminated string */ 85 cli_pasciiz, /* pointer to zero terminated string */ 86 cli_cstring, /* string with counter */ 87 cli_array_of_oid, 88 cli_array_of_bool, 89 cli_array_of_int1, 90 cli_array_of_int2, 91 cli_array_of_int4, 92 cli_array_of_int8, 93 cli_array_of_real4, 94 cli_array_of_real8, 95 cli_array_of_decimal, 96 cli_array_of_string, /* array of pointers to zero terminated strings */ 97 cli_any, /* use the same type for column as stored in the database */ 98 cli_datetime, /* time in seconds since 00:00:00 UTC, January 1, 1970. */ 99 cli_autoincrement, /* column of int4 type automatically assigned value during record insert */ 100 cli_rectangle, 101 cli_unknown 102 }; 103 104 typedef char cli_bool_t; 105 typedef signed char cli_int1_t; 106 typedef signed short cli_int2_t; 107 typedef float cli_real4_t; 108 typedef double cli_real8_t; 109 110 #ifndef RECTANGLE_COORDINATE_TYPE 111 #define RECTANGLE_COORDINATE_TYPE int 112 //#define RECTANGLE_COORDINATE_TYPE double 113 #endif 114 typedef RECTANGLE_COORDINATE_TYPE cli_coord_t; 115 #ifndef RECTANGLE_DIMENSION 116 #define RECTANGLE_DIMENSION 2 117 #endif 118 119 typedef struct cli_rectangle_t { 120 cli_coord_t boundary[RECTANGLE_DIMENSION*2]; 121 } cli_rectangle_t; 122 123 #ifndef CLI_TIME_T_DEFINED 124 typedef time_t cli_time_t; 125 #endif 126 127 #ifndef __STDTP_H__ 128 #ifdef UNICODE 129 typedef wchar_t char_t; 130 #define STRLEN(x) wcslen(x) 131 #define STRCMP(x, y) wcscmp(x, y) 132 #define STRCPY(x, y) wcscpy(x, y) 133 #define STRNCPY(x,y,z) wcsncpy(x, y, z) 134 #define STRCOLL(x, y) wcscoll(x, y) 135 #define STRNCMP(x,y,z) wcsncmp(x, y, z) 136 #define STRLITERAL(x) (wchar_t*)L##x 137 #define PRINTF wprintf 138 #define FPRINTF fwprintf 139 #ifdef _WIN32 140 #ifdef _SWPRINTFS_DEPRECATED 141 #define SPRINTF _swprintf 142 #else 143 #define SPRINTF swprintf 144 #endif 145 #define SPRINTF_BUFFER(buf) buf 146 #else 147 #define SPRINTF swprintf 148 #define SPRINTF_BUFFER(buf) buf, 0x1000000 149 #endif 150 #define VFPRINTF vfwprintf 151 #define FSCANF fwscanf 152 #define SSCANF swscanf 153 #define GETC(x) getwc(x) 154 #define UNGETC(x, y) ungetwc(x, y) 155 #define TOLOWER(x) towlower((x) & 0xFFFF) 156 #define TOUPPER(x) towlower((x) & 0xFFFF) 157 #define ISALNUM(x) iswalnum((x) & 0xFFFF) 158 #define STRSTR(x, y) wcsstr(x, y) 159 #define STRXFRM(x,y,z) wcsxfrm(x, y, z) 160 #define STRFTIME(a,b,c,d) wcsftime(a,b,c,d) 161 #ifndef _T 162 #define _T(x) L##x 163 #endif 164 #else 165 typedef char char_t; 166 #define STRLEN(x) strlen(x) 167 #define STRCMP(x, y) strcmp(x, y) 168 #define STRCPY(x, y) strcpy(x, y) 169 #define STRNCPY(x,y,z) strncpy(x, y, z) 170 #define STRCOLL(x, y) strcoll(x, y) 171 #define STRNCMP(x,y,z) strncmp(x, y, z) 172 #define PRINTF printf 173 #define FPRINTF fprintf 174 #define SPRINTF sprintf 175 #define SPRINTF_BUFFER(buf) buf 176 #define VFPRINTF vfprintf 177 #define FSCANF fscanf 178 #define SSCANF sscanf 179 #define GETC(x) getc(x) 180 #define UNGETC(x, y) ungetc(x, y) 181 #define TOLOWER(x) tolower((x) & 0xFF) 182 #define TOUPPER(x) toupper((x) & 0xFF) 183 #define ISALNUM(x) isalnum((x) & 0xFF) 184 #define STRSTR(x, y) strstr(x, y) 185 #define STRXFRM(x,y,z) strxfrm(x, y, z) 186 #define STRFTIME(a,b,c,d) strftime(a,b,c,d) 187 #ifndef _T 188 #define _T(x) x 189 #endif 190 #endif 191 #else 192 USE_GIGABASE_NAMESPACE 193 #endif 194 195 typedef struct cli_cstring_t { 196 int len; 197 char_t* ptr; 198 } cli_cstring_t; 199 200 201 #if !defined(SIZEOF_LONG) && (defined(_L64) || defined(_LP64) || defined(__osf__)) 202 #define SIZEOF_LONG 8 203 #endif 204 205 206 #if (defined(_WIN32) || defined(__BORLANDC__)) && !defined(__MINGW32__) 207 typedef signed __int32 cli_int4_t; 208 typedef __int64 cli_int8_t; 209 typedef unsigned __int64 cli_nat8_t; 210 #else 211 typedef signed int cli_int4_t; 212 #if SIZEOF_LONG == 8 213 typedef signed long cli_int8_t; 214 typedef unsigned long cli_nat8_t; 215 #else 216 typedef signed long long cli_int8_t; 217 typedef unsigned long long cli_nat8_t; 218 #endif 219 #endif 220 221 #ifndef CLI_OID_DEFINED 222 #if dbDatabaseOidBits > 32 223 typedef cli_nat8_t cli_oid_t; 224 #else 225 typedef unsigned cli_oid_t; 226 #endif 227 #endif 228 229 typedef cli_oid_t cli_cardinality_t; 230 231 232 // structure used to represent array field in structure extracted by cli_execute_query 233 typedef struct cli_array_t { 234 size_t size; // number of elements in the array 235 void* data; // pointer to the array elements 236 size_t allocated; // internal field: size of allocated buffer 237 } cli_array_t; 238 239 240 /********************************************************************* 241 * cli_open 242 * Establish connection with the server 243 * Parameters: 244 * server_url - zero terminated string with server address and port, 245 * for example "localhost:5101", "195.239.208.240:6100",... 246 * max_connect_attempts - number of attempts to establish connection 247 * reconnect_timeout_sec - timeput in seconds between connection attempts 248 * user_name - user name for login 249 * password - password for login 250 * pooled_connection - if not 0, then connection will be allocated from the connection pool 251 * Returns: 252 * >= 0 - connectiondescriptor to be used in all other cli calls 253 * < 0 - error code as described in cli_result_code enum 254 */ 255 int GIGABASE_DLL_ENTRY cli_open(char const* server_url, 256 int max_connect_attempts, 257 int reconnect_timeout_sec, 258 char_t const* user_name, 259 char_t const* password, 260 int pooled_connection); 261 262 enum cli_open_attributes { 263 cli_open_default = 0x00, 264 cli_open_readonly = 0x01, // open database in readonly mode 265 cli_open_truncate = 0x02, // truncate database file on open 266 cli_open_no_buffering = 0x04, // do not use file system cache 267 cli_open_multiclient = 0x08, // use OS file locks to provide multiclient access to the database 268 cli_open_do_not_reuse_oids_on_close = 0x10 // do not reuse OIDs of deallocated objects when session is closed 269 270 }; 271 /********************************************************************* 272 * cli_create 273 * Create connection to the local database 274 * Parameters: 275 * databasePath - path to the database file 276 * transactionCommitDelay - trasnaction commit delay (specify 0 to disable) 277 * openAttr - mask of cli_open_attributes 278 * poolSize - size of page pool (in pages), specify 0 to let GigaBASE automaticaly detect pool size 279 * Returns: 280 * >= 0 - connection descriptor to be used in all other cli calls 281 * < 0 - error code as described in cli_result_code enum 282 */ 283 284 int GIGABASE_DLL_ENTRY cli_create(char_t const* databasePath, 285 unsigned transactionCommitDelay, 286 int openAttr, 287 size_t poolSize); 288 289 290 #ifdef SUPPORT_DATA_ENCRYPTION 291 /********************************************************************* 292 * cli_create_encrypted 293 * Create connection to the local encrypted database 294 * Parameters: 295 * databasePath - path to the database file 296 * transactionCommitDelay - trasnaction commit delay (specify 0 to disable) 297 * openAttr - mask of cli_open_attributes 298 * poolSize - size of page pool (in pages), specify 0 to let GigaBASE automaticaly detect pool size 299 * password - password for accessing database 300 * Returns: 301 * >= 0 - connection descriptor to be used in all other cli calls 302 * < 0 - error code as described in cli_result_code enum 303 */ 304 int GIGABASE_DLL_ENTRY cli_create_encrypted(char_t const* databasePath, 305 unsigned transactionCommitDelay, 306 int openAttr, 307 size_t poolSize, 308 char const* password); 309 #endif 310 311 /********************************************************************* 312 * cli_close 313 * Close session 314 * Parameters: 315 * session - session descriptor returned by cli_open 316 * Returns: 317 * result code as described in cli_result_code enum 318 */ 319 int GIGABASE_DLL_ENTRY cli_close(int session); 320 321 /********************************************************************* 322 * cli_clear_connection_pool 323 * Close all released connection in connection pool 324 */ 325 void GIGABASE_DLL_ENTRY cli_clear_connection_pool(); 326 327 /********************************************************************* 328 * cli_statement 329 * Specify SubSQL statement to be executed at server 330 * Binding to the parameters and columns can be established 331 * Parameters: 332 * session - session descriptor returned by cli_open 333 * stmt - zero terminated string with SubSQL statement 334 * Returns: 335 * >= 0 - statement descriptor 336 * < 0 - error code as described in cli_result_code enum 337 */ 338 int GIGABASE_DLL_ENTRY cli_statement(int session, char_t const* stmt); 339 340 /********************************************************************* 341 * cli_parameter 342 * Bind parameter to the statement 343 * Parameters: 344 * statement - statememt descriptor returned by cli_statement 345 * param_name - zero terminated string with parameter name 346 * Paramter name should start with '%' 347 * var_type - type of variable as described in cli_var_type enum. 348 * Only scalar and zero terminated string types are supported. 349 * var_ptr - pointer to the variable 350 * Returns: 351 * result code as described in cli_result_code enum 352 */ 353 int GIGABASE_DLL_ENTRY cli_parameter(int statement, 354 char_t const* param_name, 355 int var_type, 356 void* var_ptr); 357 358 /********************************************************************* 359 * cli_column 360 * Bind extracted column of select or insert statement 361 * Parameters: 362 * statement - statememt descriptor returned by cli_statement 363 * column_name - zero terminated string with column name 364 * var_type - type of variable as described in cli_var_type enum 365 * var_len - pointer to the variable to hold length of array variable. 366 * This variable should be assigned the maximal length 367 * of the array/string buffer, pointed by var_ptr. 368 * After the execution of the statement it is assigned the 369 * real length of the fetched array/string. If it is large 370 * than length of the buffer, then only part of the array 371 * will be placed in the buffer, but var_len still will 372 * contain the actual array length. 373 * var_ptr - pointer to the variable 374 * Returns: 375 * result code as described in cli_result_code enum 376 */ 377 int GIGABASE_DLL_ENTRY cli_column(int statement, 378 char_t const* column_name, 379 int var_type, 380 int* var_len, 381 void* var_ptr); 382 383 384 typedef void* (*cli_column_set)(int var_type, void* var_ptr, int len); 385 typedef void* (*cli_column_get)(int var_type, void* var_ptr, int* len); 386 387 typedef void* (*cli_column_set_ex)(int var_type, void* var_ptr, int len, 388 char_t const* column_name, int statement, void const* data_ptr, void* user_data); 389 typedef void* (*cli_column_get_ex)(int var_type, void* var_ptr, int* len, 390 char_t const* column_name, int statemen, void* user_data); 391 392 /********************************************************************* 393 * cli_array_column 394 * Specify get/set functions for the array column 395 * Parameters: 396 * statement - statememt descriptor returned by cli_statement 397 * column_name - zero terminated string with column name 398 * var_type - type of variable as described in cli_var_type enum 399 * var_ptr - pointer to the variable 400 * set - function which will be called to construct fetched 401 * field. It receives pointer to the variable, 402 * length of the fetched array and returns pointer to th 403 * array's elements 404 * get - function which will be called to update the field in the 405 * database. Given pointer to the variable, it should return 406 * pointer to the array elements and store length of the 407 * array to the variable pointer by len parameter 408 * user_data - pointer to user specific data passed to get and set functions 409 * Returns: 410 * result code as described in cli_result_code enum 411 */ 412 int GIGABASE_DLL_ENTRY cli_array_column(int statement, 413 char_t const* column_name, 414 int var_type, 415 void* var_ptr, 416 cli_column_set set, 417 cli_column_get get); 418 419 int GIGABASE_DLL_ENTRY cli_array_column_ex(int statement, 420 char_t const* column_name, 421 int var_type, 422 void* var_ptr, 423 cli_column_set_ex set, 424 cli_column_get_ex get, 425 void* user_data); 426 427 428 enum cli_cursor_type_t { 429 cli_cursor_view_only, 430 cli_cursor_for_update, 431 /** 432 * Execute query incrementally 433 */ 434 cli_cursor_incremental, 435 /** Detached cursor commits transaction immediately after execution of the query, 436 * and then temporarily start new transaction for fetching each element. 437 * Such cursor should be used in conjunction with DO_NOT_REUSE_OID_WITHIN_SESSION to detect 438 * removed objects. 439 * Please notice that this cursor is static - it only executed from the selection removed objects, 440 * but doesn't try to add the selection new records which match search criteria or remove 441 * record which do not match this criteria any more. 442 */ 443 cli_cursor_detached 444 }; 445 446 /********************************************************************* 447 * cli_fetch 448 * Execute select statement. 449 * Parameters: 450 * statement - statememt descriptor returned by cli_statement 451 * cursor_type - cursor type described by cli_cursor_type_t enum 452 * Returns: 453 * >= 0 - success, for select statements number of fetched rows is returned 454 * < 0 - error code as described in cli_result_code enum 455 */ 456 int GIGABASE_DLL_ENTRY cli_fetch(int statement, int cursor_type); 457 458 /********************************************************************* 459 * cli_fetch_ex 460 * Execute select statement. 461 * Parameters: 462 463 * statement - statememt descriptor returned by cli_statement 464 * for_update - not zero if fetched rows will be updated 465 * n_fetched_records - pointer to the location to receive number of fetched records 466 * Returns: 467 * result code as described in cli_result_code enum 468 */ 469 int GIGABASE_DLL_ENTRY cli_fetch_ex(int statement, int for_update, cli_cardinality_t* n_fetched_records); 470 471 /********************************************************************* 472 * cli_insert 473 * Execute insert statement. 474 * Parameters: 475 * statement - statememt descriptor returned by cli_statement 476 * oid - object identifier of created record. 477 * Returns: 478 * status code as described in cli_result_code enum 479 */ 480 int GIGABASE_DLL_ENTRY cli_insert(int statement, cli_oid_t* oid); 481 482 /********************************************************************* 483 * cli_batch_insert 484 * Execute batch insert statement. In batch insert mode records will be included in indices 485 * at the trasnaction commit time or after explicit execution of cli_exec_batch 486 * Parameters: 487 * statement - statememt descriptor returned by cli_statement 488 * oid - object identifier of created record. 489 * Returns: 490 * status code as described in cli_result_code enum 491 */ 492 int GIGABASE_DLL_ENTRY cli_batch_insert(int statement, cli_oid_t* oid); 493 494 /********************************************************************* 495 * cli_get_first 496 * Get first row of the selection. 497 * Parameters: 498 * statement - statememt descriptor returned by cli_statement 499 * Returns: 500 * result code as described in cli_result_code enum 501 */ 502 int GIGABASE_DLL_ENTRY cli_get_first(int statement); 503 504 /********************************************************************* 505 * cli_get_last 506 * Get last row of the selection. 507 * Parameters: 508 * statement - statememt descriptor returned by cli_statement 509 * Returns: 510 * result code as described in cli_result_code enum 511 */ 512 int GIGABASE_DLL_ENTRY cli_get_last(int statement); 513 514 /********************************************************************* 515 * cli_get_next 516 * Get next row of the selection. If get_next records is called 517 * exactly after cli_fetch function call, is will fetch the first record 518 * in selection. 519 * Parameters: 520 * statement - statememt descriptor returned by cli_statement 521 * Returns: 522 * result code as described in cli_result_code enum 523 */ 524 int GIGABASE_DLL_ENTRY cli_get_next(int statement); 525 526 /********************************************************************* 527 * cli_get_prev 528 * Get previous row of the selection. If get_next records is called 529 * exactly after cli_fetch function call, is will fetch the last record 530 * in selection. 531 * Parameters: 532 * statement - statememt descriptor returned by cli_statement 533 * Returns: 534 * result code as described in cli_result_code enum 535 */ 536 int GIGABASE_DLL_ENTRY cli_get_prev(int statement); 537 538 /********************************************************************* 539 * cli_skip 540 * Skip specified number of rows. 541 * Parameters: 542 * statement - statememt descriptor returned by cli_statement 543 * n - number of objects to be skipped 544 * - if "n" is positive, then this function has the same effect as 545 * executing cli_get_next() function "n" times. 546 * - if "n" is negative, then this function has the same effect as 547 * executing cli_get_prev() function "-n" times. 548 * - if "n" is zero, this method just reloads current record 549 * Returns: 550 * result code as described in cli_result_code enum 551 */ 552 int GIGABASE_DLL_ENTRY cli_skip(int statement, int n); 553 554 /********************************************************************* 555 * cli_seek 556 * Position cursor to the record with specified OID 557 * Parameters: 558 * statement - statememt descriptor returned by cli_statement 559 * oid - object identifier of the record to which cursor should be positioned 560 * Returns: 561 * >= 0 - success, position of the record in the selection 562 * < 0 - error code as described in cli_result_code enum 563 */ 564 int GIGABASE_DLL_ENTRY cli_seek(int statement, cli_oid_t oid); 565 566 /********************************************************************* 567 * cli_get_oid 568 * Get object identifier of the current record 569 * Parameters: 570 * statement - statememt descriptor returned by cli_statement 571 * Returns: 572 * object identifier or 0 if no object is seleected 573 */ 574 cli_oid_t GIGABASE_DLL_ENTRY cli_get_oid(int statement); 575 576 /********************************************************************* 577 * cli_update 578 * Update the current row in the selection. You have to set 579 * for_update parameter of cli_fetch to 1 in order to be able 580 * to perform updates. Updated value of row fields will be taken 581 * from bound column variables. 582 * Parameters: 583 * statement - statememt descriptor returned by cli_statement 584 * Returns: 585 * result code as described in cli_result_code enum 586 */ 587 int GIGABASE_DLL_ENTRY cli_update(int statement); 588 589 /********************************************************************* 590 * cli_remove 591 * Remove all selected records. You have to set 592 * for_update parameter of cli_fetch to 1 in order to be able 593 * to remove records. 594 * Parameters: 595 * statement - statememt descriptor returned by cli_statement 596 * Returns: 597 * result code as described in cli_result_code enum 598 */ 599 int GIGABASE_DLL_ENTRY cli_remove(int statement); 600 601 /********************************************************************* 602 * cli_remove_current 603 * Remove currently selected record. You have to set 604 * for_update parameter of cli_fetch to 1 in order to be able 605 * to remove records. 606 * Parameters: 607 * statement - statememt descriptor returned by cli_statement 608 * Returns: 609 * result code as described in cli_result_code enum 610 */ 611 int GIGABASE_DLL_ENTRY cli_remove_current(int statement); 612 613 /********************************************************************* 614 * cli_free 615 * Deallocate statement and all associated data 616 * Parameters: 617 * statement - statememt descriptor returned by cli_statement 618 * Returns: 619 * result code as described in cli_result_code enum 620 */ 621 int GIGABASE_DLL_ENTRY cli_free(int statement); 622 623 /********************************************************************* 624 * cli_close_cursor 625 * Close current cursor 626 * Parameters: 627 * statement - statememt descriptor returned by cli_statement 628 * Returns: 629 * result code as described in cli_result_code enum 630 */ 631 int GIGABASE_DLL_ENTRY cli_close_cursor(int statement); 632 633 /********************************************************************* 634 * cli_exec_batch 635 * Complete all batch inserts 636 * Parameters: 637 * session - session descriptor as returned by cli_open 638 * Returns: 639 * status code as described in cli_result_code enum 640 */ 641 int GIGABASE_DLL_ENTRY cli_exec_batch(int session); 642 643 /********************************************************************* 644 * cli_commit 645 * Commit current database transaction 646 * Parameters: 647 * session - session descriptor as returned by cli_open 648 * Returns: 649 * result code as described in cli_result_code enum 650 */ 651 int GIGABASE_DLL_ENTRY cli_commit(int session); 652 653 /********************************************************************* 654 * cli_precommit 655 * Release all locks set by transaction. This methods allows other clients 656 * to proceed, but it doesn't flush transaction to the disk. 657 * Parameters: 658 * session - session descriptor as returned by cli_open 659 * Returns: 660 * result code as described in cli_result_code enum 661 */ 662 int GIGABASE_DLL_ENTRY cli_precommit(int session); 663 664 /********************************************************************* 665 * cli_abort 666 * Abort current database transaction 667 * Parameters: 668 * session - session descriptor as returned by cli_open 669 * Returns: 670 * result code as described in cli_result_code enum 671 */ 672 int GIGABASE_DLL_ENTRY cli_abort(int session); 673 674 enum cli_field_flags { 675 cli_hashed = 1, /* field should be indexed usnig hash table */ 676 cli_indexed = 2, /* field should be indexed using B-Tree */ 677 cli_case_insensitive = 4, /* index is case insensitive */ 678 cli_cascade_delete = 8, /* perfrom cascade delete for for reference or array of reference fields */ 679 cli_unique = 16, /* index containing unique keys */ 680 cli_autoincremented = 32, /* field is assigned automaticall incremented value */ 681 cli_optimize_duplicates = 64 /* index with lot of duplicate key values */ 682 }; 683 684 typedef struct cli_field_descriptor { 685 enum cli_var_type type; 686 int flags; 687 char_t const* name; 688 char_t const* refTableName; 689 char_t const* inverseRefFieldName; 690 } cli_field_descriptor; 691 692 /********************************************************************* 693 * cli_describe 694 * Describe fileds of specified table 695 * Parameters: 696 * session - session descriptor as returned by cli_open 697 * table - name of the table 698 * fields - adress of the pointer to the array of fields descriptors, 699 * this array should be later deallocated by application by cli_free_memory() 700 * Returns: 701 * >= 0 - number of fields in the table 702 * < 0 - result code as described in cli_result_code enum 703 */ 704 int GIGABASE_DLL_ENTRY cli_describe(int session, char_t const* table, cli_field_descriptor** fields); 705 706 typedef struct cli_field_layout { 707 cli_field_descriptor desc; 708 int offs; 709 int size; 710 } cli_field_layout; 711 712 /********************************************************************* 713 * cli_describe_layout 714 * Describe fields layout of specified table 715 * Parameters: 716 * session - session descriptor as returned by cli_open 717 * table - name of the table 718 * fields - address of the pointer to the array of fields layout descriptors, 719 * this array should be later deallocated by application by cli_free_memory() 720 * 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 721 * Returns: 722 * >= 0 - number of fields in the table 723 * < 0 - result code as described in cli_result_code enum 724 */ 725 int GIGABASE_DLL_ENTRY cli_describe_layout(int session, char_t const* table, cli_field_layout** fields, int* rec_size); 726 727 /********************************************************************* 728 * cli_get_field_size 729 * Calculate field size 730 * Parameters: 731 * fields - array with fields descriptors obtained using cli_describe function 732 * field_no - number of the field 733 */ 734 int GIGABASE_DLL_ENTRY cli_get_field_size(cli_field_descriptor* fields, int field_no); 735 736 /********************************************************************* 737 * cli_get_field_offset 738 * Calculate offset of the field 739 * Parameters: 740 * fields - array with fields descriptors obtained using cli_describe function 741 * field_no - number of the field 742 */ 743 int GIGABASE_DLL_ENTRY cli_get_field_offset(cli_field_descriptor* fields, int field_no); 744 745 typedef struct cli_table_descriptor { 746 char_t const* name; 747 } cli_table_descriptor; 748 749 /********************************************************************* 750 * cli_show_tables 751 * Show all tables of specified database 752 * Parameters: 753 * session - session descriptor as returned by cli_open 754 * tables - address of the pointer to the array of tables descriptors, 755 * this array should be later deallocated by application by cli_free_memory() 756 * Returns: 757 * >= 0 - number of tables in the database (Metatable is not returned/counted) 758 * < 0 - result code as described in cli_result_code enum 759 */ 760 int GIGABASE_DLL_ENTRY cli_show_tables(int session, cli_table_descriptor** tables); 761 762 763 764 /********************************************************************* 765 * cli_create_table 766 * Create new table 767 * Parameters: 768 * session - session descriptor as returned by cli_open 769 * tableName - name of new table 770 * nFields - number of columns in the table 771 * fields - array with table columns descriptors 772 * Returns: 773 * result code as described in cli_result_code enum 774 */ 775 int GIGABASE_DLL_ENTRY cli_create_table(int session, char_t const* tableName, int nFields, 776 cli_field_descriptor* fields); 777 778 /********************************************************************* 779 * cli_alter_table 780 * Change table format 781 * Parameters: 782 * session - session descriptor as returned by cli_open 783 * tableName - name of existing table 784 * nFields - number of columns in the table 785 * fields - array with new table columns descriptors 786 * Returns: 787 * result code as described in cli_result_code enum 788 */ 789 int GIGABASE_DLL_ENTRY cli_alter_table(int session, char_t const* tableName, int nFields, 790 cli_field_descriptor* fields); 791 792 /********************************************************************* 793 * cli_drop_table 794 * drop the table 795 * Parameters: 796 * session - session descriptor as returned by cli_open 797 * tableName - name of deleted table 798 * Returns: 799 * result code as described in cli_result_code enum 800 */ 801 int GIGABASE_DLL_ENTRY cli_drop_table(int session, char_t const* tableName); 802 803 804 /********************************************************************* 805 * cli_alter_index 806 * add or remove column index 807 * Parameters: 808 * session - session descriptor as returned by cli_open 809 * tableName - name of the table 810 * fieldName - name of field 811 * newFlags - new flags of the field, if index exists for this field, but is not specified in 812 * <code>newFlags</code> mask, then it will be removed; if index not exists, but is 813 * specified in <code>newFlags</code> mask, then it will be created. * 814 * Returns: 815 * result code as described in cli_result_code enum 816 */ 817 int GIGABASE_DLL_ENTRY cli_alter_index(int session, char_t const* tableName, char_t const* fieldName, 818 int newFlags); 819 820 821 /********************************************************************* 822 * cli_set_error_handler 823 * Set GigaBASE error handler. Handler should be no-return function which perform stack unwind. 824 * Parameters: 825 * session - session descriptor as returned by cli_open 826 * handler - error handler 827 * Returns: 828 * previous handler 829 */ 830 enum cli_error_class { 831 cli_no_error, 832 cli_query_error, 833 cli_arithmetic_error, 834 cli_index_out_of_range_error, 835 cli_database_open_error, 836 cli_file_error, 837 cli_out_of_memory_error, 838 cli_deadlock, 839 cli_null_reference_error, 840 cli_lock_revoked, 841 cli_file_limit_exeeded, 842 cli_database_read_only, 843 cli_unique_constraint_violation, 844 cli_inconsistent_inverse_reference, 845 cli_operation_not_supported, 846 cli_socket_error, 847 cli_cursor_error, 848 cli_access_to_deleted_object, 849 cli_incompatible_schema_change 850 851 }; 852 typedef void (*cli_error_handler)(int error, char const* msg, int msgarg, void* context); 853 cli_error_handler GIGABASE_DLL_ENTRY cli_set_error_handler(int session, cli_error_handler new_handler, void* context); 854 855 /********************************************************************* 856 * cli_freeze 857 * Freeze cursor. Make it possible to reused cursor after commit of the current transaction. 858 * Parameters: 859 * statement - statememt descriptor returned by cli_statement 860 * Returns: 861 * result code as described in cli_result_code enum 862 */ 863 int GIGABASE_DLL_ENTRY cli_freeze(int statement); 864 865 /********************************************************************* 866 * cli_unfreeze 867 * Unfreeze cursor. Reuse previously frozen cursor. 868 * Parameters: 869 * statement - statememt descriptor returned by cli_statement 870 * Returns: 871 * result code as described in cli_result_code enum 872 */ 873 int GIGABASE_DLL_ENTRY cli_unfreeze(int statement); 874 875 876 /********************************************************************* 877 * cli_attach 878 * Attach thread to the database. Each thread except one opened the database should first 879 * attach to the database before any access to the database, and detach after end of the work with database 880 * Parameters: 881 * session - session descriptor returned by cli_open 882 * Returns: 883 * result code as described in cli_result_code enum 884 */ 885 int GIGABASE_DLL_ENTRY cli_attach(int session); 886 887 /********************************************************************* 888 * cli_detach 889 * Detach thread from the database. Each thread except one opened the database should perform 890 * attach to the database before any access to the database, and detach after end of the work with database 891 * Parameters: 892 * session - session descriptor returned by cli_open 893 * detach_mode - bit mask representing detach mode 894 * Returns: 895 * result code as described in cli_result_code enum 896 */ 897 enum cli_detach_mode { 898 cli_commit_on_detach = 1, 899 cli_destroy_context_on_detach = 2 900 }; 901 902 int GIGABASE_DLL_ENTRY cli_detach(int session, int detach_mode); 903 904 /********************************************************************* 905 * cli_free_memory 906 * Free memory allocated by cli_show_tables and cli_describe 907 * Parameters: 908 * session - session descriptor returned by cli_open 909 * ptr - pointer to the allocated buffer 910 */ 911 void GIGABASE_DLL_ENTRY cli_free_memory(int session, void* ptr); 912 913 914 typedef void* cli_transaction_context_t; 915 /********************************************************************* 916 * cli_create_transaction_context 917 * Create new transaction xontext which can be used in cli_join_transaction function 918 * Parameters: 919 * Returns: 920 * created transaction context 921 */ 922 cli_transaction_context_t GIGABASE_DLL_ENTRY cli_create_transaction_context(); 923 924 /********************************************************************* 925 * cli_join_transaction 926 * Associate current threads with specified transaction context, 927 * It allows to share single transaction between multiple threads. 928 * Parameters: 929 * session - session descriptor returned by cli_open 930 * ctx - transaction context created by cli_create_transaction_context 931 * Returns: 932 * result code as described in cli_result_code enum 933 */ 934 int GIGABASE_DLL_ENTRY cli_join_transaction(int session, cli_transaction_context_t ctx); 935 936 /********************************************************************* 937 * cli_remove_transaction_context 938 * Remove transaction context 939 * Parameters: 940 * ctx transaction context created by cli_create_transaction_context 941 */ 942 void GIGABASE_DLL_ENTRY cli_remove_transaction_context(cli_transaction_context_t ctx); 943 944 945 /********************************************************************* 946 * cli_set_trace_function 947 * Set trace function which will be used to output GigaBASE trace messages 948 * Parameters: 949 * func - pointer to trace function which receives trace message terminated with new line character 950 */ 951 typedef void (*cli_trace_function_t)(char_t* msg); 952 void GIGABASE_DLL_ENTRY cli_set_trace_function(cli_trace_function_t func); 953 954 /********************************************************************* 955 * cli_prepare_query 956 * Prepare SubSQL query statement. 957 * Parameters: 958 * session - session descriptor returned by cli_open 959 * query - query string with optional parameters. Parameters are specified 960 * as '%T' where T is one or two character code of parameter type using the same notation 961 * as in printf: %d or %i - int, %f - float or double, %ld - int8, %s - string, %p - oid... 962 * Parameter of cli_rectangle_t* type has format %R, cli_time_t type - %t 963 * Returns: 964 * >= 0 - statement descriptor 965 * < 0 - error code as described in cli_result_code enum 966 */ 967 int GIGABASE_DLL_ENTRY cli_prepare_query(int session, char_t const* query); 968 969 /** 970 * cli_execute_query 971 * Execute query previously prepared by cli_prepare_query 972 * Parameters: 973 * statement - statement descriptor returned by cli_prepare_query 974 * cursor_type - cursor type described by cli_cursor_type_t enum 975 * record_struct - structure to receive selected record fields 976 * ... - varying list of query parameters 977 * Returns: 978 * >= 0 - success, for select statements number of fetched rows is returned 979 * < 0 - error code as described in cli_result_code enum 980 */ 981 int GIGABASE_DLL_ENTRY cli_execute_query(int statement, int cursor_type, void* record_struct, ...); 982 983 /** 984 * cli_execute_query_ex 985 * Execute query previously prepared by cli_prepare_query with parameters passed as array 986 * Parameters: 987 * statement - statement descriptor returned by cli_prepare_query 988 * cursor_type - cursor type described by cli_cursor_type_t enum 989 * record_struct - structure to receive selected record fields 990 * n_params - number of parameters (cli_var_type) 991 * param_types - types of parameters 992 * param_values - array of pointers to parameter values 993 * Returns: 994 * >= 0 - success, for select statements number of fetched rows is returned 995 * < 0 - error code as described in cli_result_code enum 996 */ 997 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); 998 999 /** 1000 * cli_insert_struct 1001 * Insert new record represented as C structure 1002 * Parameters: 1003 * session - session descriptor returned by cli_open 1004 * table_name - name of the destination table 1005 * record_struct - structure specifying value of record fields 1006 * oid - pointer to the location to receive OID of created record (may be NULL) 1007 * Returns: 1008 * result code as described in cli_result_code enum 1009 */ 1010 int GIGABASE_DLL_ENTRY cli_insert_struct(int session, char_t const* table_name, void* record_struct, cli_oid_t* oid); 1011 1012 /** 1013 * cli_lock 1014 * Set exclusive database lock 1015 * Parameters: 1016 * session - session descriptor returned by cli_open 1017 * Returns: 1018 * result code as described in cli_result_code enum 1019 */ 1020 int GIGABASE_DLL_ENTRY cli_lock(int session); 1021 1022 typedef enum cli_export_method { 1023 cli_export_all, /* just export all tables */ 1024 cli_export_all_expect, /* '-' Export all tables except the named tables */ 1025 cli_export_named_only /* '+' Only export explicitly named tables */ 1026 } cli_export_method; 1027 1028 /** 1029 * cli_xml_export 1030 * Export all or some subset of database tables in XML format 1031 * Parameters: 1032 * session - session descriptor returned by cli_open 1033 * out - output stream 1034 * tables - list of table names 1035 * n_tables - number of tables 1036 * method - export method 1037 * Returns: 1038 * result code as described in cli_result_code enum 1039 */ 1040 int GIGABASE_DLL_ENTRY cli_xml_export(int session, FILE* out, char_t const* const* tables, int n_tables, cli_export_method method); 1041 1042 /** 1043 * cli_xml_import 1044 * Import data from XML stream 1045 * Parameters: 1046 * session - session descriptor returned by cli_open 1047 * in - input stream 1048 * Returns: 1049 * result code as described in cli_result_code enum 1050 */ 1051 int GIGABASE_DLL_ENTRY cli_xml_import(int session, FILE* in); 1052 1053 /** 1054 * cli_backup 1055 * Perform database backup 1056 * Parameters: 1057 * session - session descriptor returned by cli_open 1058 * file_name - backup file name 1059 * compatify - if true then databae will be compactified during backup - 1060 * i.e. all used objects will be placed together without holes; if false then 1061 * backup is performed by just writting memory mapped object to the backup file. 1062 * Returns: 1063 * result code as described in cli_result_code enum 1064 */ 1065 int GIGABASE_DLL_ENTRY cli_backup(int session, char_t const* file_name, int compactify); 1066 1067 /** 1068 * cli_backup 1069 * Schedule database backup 1070 * Parameters: 1071 * session - session descriptor returned by cli_open 1072 * file_name - path to backup file. If name ends with '?', then 1073 * each backup willbe placed in seprate file with '?' replaced with current timestamp 1074 * period - period of performing backups in seconds 1075 * Returns: 1076 * result code as described in cli_result_code enum 1077 */ 1078 int GIGABASE_DLL_ENTRY cli_schedule_backup(int session, char_t const* file_name, int period); 1079 1080 /** 1081 * cli_backup 1082 * Get database size 1083 * Parameters: 1084 * session - session descriptor returned by cli_open 1085 * size - pointer to the location where size should be stored 1086 * Returns: 1087 * result code as described in cli_result_code enum 1088 */ 1089 int GIGABASE_DLL_ENTRY cli_get_database_size(int session, cli_nat8_t* size); 1090 1091 /** 1092 * cli_get_wrapping_rectangle 1093 * Get wrapping rectangle for all objects in table 1094 * Parameters: 1095 * session - session descriptor returned by cli_open 1096 * table - table name 1097 * field - sptial index key field name 1098 * rect - pointer to wrapper rectangle 1099 * Returns: 1100 * result code as described in cli_result_code enum 1101 */ 1102 int GIGABASE_DLL_ENTRY cli_get_wrapping_rectangle(int session, char_t const* table, char_t const* field, cli_rectangle_t* rect); 1103 1104 #ifdef __cplusplus 1105 } 1106 #endif 1107 1108 #endif 1109 1110 1111