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

Generated on Thu Nov 24 23:14:29 2005 for GigaBASE by doxygen 1.3.5