Main Page   Class Hierarchy   Compound List   File List   Compound Members  

cli.h

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

Generated on Thu Feb 14 21:46:03 2008 for GigaBASE by doxygen1.2.18