• Main Page
  • Classes
  • Files
  • File List

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

Generated on Mon Aug 23 2010 00:04:01 for GigaBASE by  doxygen 1.7.1