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

Generated on Thu Aug 23 19:35:51 2007 for GigaBASE by doxygen1.2.18