Main Page   Class Hierarchy   Compound List   File List   Compound Members  

cli.h

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

Generated on Mon Oct 23 13:23:57 2006 for FastDB by doxygen1.2.18