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

Generated on Mon Oct 23 13:22:58 2006 for GigaBASE by doxygen1.2.18