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 float        cli_real4_t;
00100 typedef double       cli_real8_t;
00101     
00102 #ifndef RECTANGLE_COORDINATE_TYPE
00103 #define RECTANGLE_COORDINATE_TYPE int
00104 //#define RECTANGLE_COORDINATE_TYPE double
00105 #endif
00106 typedef RECTANGLE_COORDINATE_TYPE cli_coord_t;
00107 #define CLI_RECTANGLE_DIMENSION 2
00108 
00109 typedef struct { 
00110     cli_coord_t  boundary[CLI_RECTANGLE_DIMENSION*2];
00111 } cli_rectangle_t;
00112 
00113 #if !defined(SIZEOF_LONG) && defined(L64) && ! defined(WIN64)
00114 #define SIZEOF_LONG 8
00115 #endif
00116 
00117 #if (defined(_WIN32) || defined(__BORLANDC__)) && !defined(__MINGW32__)
00118 typedef signed __int32   cli_int4_t;
00119 typedef signed __int64   cli_int8_t;
00120 #else
00121 typedef signed int       cli_int4_t;
00122 #if SIZEOF_LONG == 8
00123 typedef signed long      cli_int8_t;
00124 #else
00125 typedef signed long long cli_int8_t;
00126 #endif
00127 #endif
00128 
00129 #ifndef CLI_TIME_T_DEFINED
00130     typedef time_t cli_time_t;
00131 #endif
00132 
00133 #ifndef CLI_OID_DEFINED
00134 #if dbDatabaseOidBits > 32
00135 typedef size_t cli_oid_t;
00136 #else
00137 typedef unsigned cli_oid_t;
00138 #endif
00139 #endif
00140 
00141 // structure used to represent array field in structure extracted by cli_execute_query
00142 typedef struct cli_array_t { 
00143     size_t size;      // number of elements in the array
00144     void*  data;      // pointer to the array elements
00145     size_t allocated; // internal field: size of allocated buffer 
00146 } cli_array_t;
00147     
00148 /*********************************************************************
00149  * cli_open
00150  *     Establish connection with the server 
00151  * Parameters:
00152  *     server_url - zero terminated string with server address and port, 
00153  *                  for example "localhost:5101", "195.239.208.240:6100",...
00154  *     max_connect_attempts  - number of attempts to establish connection
00155  *     reconnect_timeout_sec - timeput in seconds between connection attempts
00156  * Returns:
00157  *     >= 0 - connectiondescriptor to be used in all other cli calls
00158  *     <  0 - error code as described in cli_result_code enum
00159  */
00160 int FASTDB_DLL_ENTRY cli_open(char const* server_url, 
00161                               int         max_connect_attempts,
00162                               int         reconnect_timeout_sec);
00163 
00164 enum cli_open_attributes { 
00165     cli_open_default    = 0x0, 
00166     cli_open_readonly   = 0x1, 
00167     cli_open_truncate   = 0x2,
00168     cli_open_concurrent = 0x4
00169 };
00170 /*********************************************************************
00171  * cli_create
00172  *     Create connection to the local database
00173  * Parameters:
00174  *     databaseName - name of the database 
00175  *     fileName - path to the database file 
00176  *     transactionCommitDelay - trasnaction commit delay (specify 0 to disable)
00177  *     openAttr - mask of cli_open_attributes
00178  *     initDatabaseSize - initial size of the database
00179  *     extensionQuantum - database extension quantum
00180  *     initIndexSize - initial size of object index
00181  *     fileSizeLimit - limit for file size (0 - unlimited)
00182  * Returns:
00183  *     >= 0 - connection descriptor to be used in all other cli calls
00184  *     <  0 - error code as described in cli_result_code enum
00185  */
00186 
00187 int FASTDB_DLL_ENTRY cli_create(char const* databaseName, 
00188                                 char const* filePath, 
00189                                 unsigned    transactionCommitDelay, 
00190                                 int         openAttr, 
00191                                 size_t      initDatabaseSize,
00192                                 size_t      extensionQuantum,
00193                                 size_t      initIndexSize,
00194                                 size_t      fileSizeLimit);
00195     
00196 /*********************************************************************
00197  * cli_create_replication_node
00198  *     Create connection to the local database with support of replication
00199  * Parameters:
00200  *     nodeId - node identifier: 0 <= nodeId < nServers
00201  *     nServers - number of replication nodes (primary + standby)
00202  *     nodeNames - array with URLs of the nodes (address:port)
00203  *     databaseName - name of the database 
00204  *     fileName - path to the database file 
00205  *     transactionCommitDelay - trasnaction commit delay (specify 0 to disable)
00206  *     openAttr - mask of cli_open_attributes (to allow concurrent read access to replication node, 
00207  *                cli_open_concurrent attribute should be set) 
00208  *     initDatabaseSize - initial size of the database
00209  *     extensionQuantum - database extension quantum
00210  *     initIndexSize - initial size of object index
00211  *     fileSizeLimit - limit for file size (0 - unlimited)
00212  * Returns:
00213  *     >= 0 - connection descriptor to be used in all other cli calls
00214  *     <  0 - error code as described in cli_result_code enum
00215  */
00216 
00217 int FASTDB_DLL_ENTRY cli_create_replication_node(int         nodeId,
00218                                                  int         nServers,
00219                                                  char*       nodeNames[],
00220                                                  char const* databaseName, 
00221                                                  char const* filePath, 
00222                                                  int         openAttr, 
00223                                                  size_t      initDatabaseSize,
00224                                                  size_t      extensionQuantum,
00225                                                  size_t      initIndexSize,
00226                                                  size_t      fileSizeLimit);
00227 
00228 /*********************************************************************
00229  * cli_close
00230  *     Close session
00231  * Parameters:
00232  *     session - session descriptor returned by cli_open
00233  * Returns:
00234  *     result code as described in cli_result_code enum
00235  */
00236 int FASTDB_DLL_ENTRY cli_close(int session);
00237 
00238 /*********************************************************************
00239  * cli_statement
00240  *     Specify SubSQL statement to be executed at server
00241  *     Binding to the parameters and columns can be established       
00242  * Parameters:
00243  *     session - session descriptor returned by cli_open
00244  *     stmt    - zero terminated string with SubSQL statement  
00245  * Returns:
00246  *     >= 0 - statement descriptor
00247  *     <  0 - error code as described in cli_result_code enum
00248  */
00249 int FASTDB_DLL_ENTRY cli_statement(int session, char const* stmt);
00250 
00251 /*********************************************************************
00252  * cli_parameter
00253  *     Bind parameter to the statement
00254  * Parameters:
00255  *     statement  - statememt descriptor returned by cli_statement
00256  *     param_name - zero terminated string with parameter name  
00257  *                  Paramter name should start with '%'
00258  *     var_type   - type of variable as described in cli_var_type enum.
00259  *                  Only scalar and zero terminated string types are supported.
00260  *     var_ptr    - pointer to the variable
00261  * Returns:
00262  *     result code as described in cli_result_code enum
00263  */
00264 int FASTDB_DLL_ENTRY cli_parameter(int         statement,
00265                                    char const* param_name, 
00266                                    int         var_type,
00267                                    void*       var_ptr);
00268 
00269 /*********************************************************************
00270  * cli_column
00271  *     Bind extracted column of select or insert statement
00272  * Parameters:
00273  *     statement   - statememt descriptor returned by cli_statement
00274  *     column_name - zero terminated string with column name  
00275  *     var_type    - type of variable as described in cli_var_type enum
00276  *     var_len     - pointer to the variable to hold length of array variable.
00277  *                   This variable should be assigned the maximal length
00278  *                   of the array/string buffer, pointed by var_ptr.
00279  *                   After the execution of the statement it is assigned the 
00280  *                   real length of the fetched array/string. If it is large 
00281  *                   than length of the buffer, then only part of the array
00282  *                   will be placed in the buffer, but var_len still will 
00283  *                   contain the actual array length. 
00284  *     var_ptr     - pointer to the variable
00285  * Returns:
00286  *     result code as described in cli_result_code enum
00287  */
00288 int FASTDB_DLL_ENTRY cli_column(int         statement,
00289                                 char const* column_name, 
00290                                 int         var_type, 
00291                                 int*        var_len, 
00292                                 void*       var_ptr);
00293 
00294 
00295 typedef void* (CLI_CALLBACK_CC *cli_column_set)(int var_type, void* var_ptr, int len);
00296 typedef void* (CLI_CALLBACK_CC *cli_column_get)(int var_type, void* var_ptr, int* len);
00297 
00298 typedef void* (CLI_CALLBACK_CC *cli_column_set_ex)(int var_type, void* var_ptr, int len, 
00299                                    char const* column_name, int statement, void const* data_ptr, void* user_data);
00300 typedef void* (CLI_CALLBACK_CC *cli_column_get_ex)(int var_type, void* var_ptr, int* len, 
00301                                    char const* column_name, int statemen, void* user_data);
00302 
00303 /*********************************************************************
00304  * cli_array_column
00305  *     Specify get/set functions for the array column
00306  * Parameters:
00307  *     statement   - statememt descriptor returned by cli_statement
00308  *     column_name - zero terminated string with column name  
00309  *     var_type    - type of variable as described in cli_var_type enum
00310  *     var_ptr     - pointer to the variable
00311  *     set         - function which will be called to construct fetched 
00312  *                   field. It receives pointer to the variable, 
00313  *                   length of the fetched array and returns pointer to th 
00314  *                   array's elements
00315  *     get         - function which will be called to update the field in the 
00316  *                   database. Given pointer to the variable, it should return 
00317  *                   pointer to the array elements and store length of the
00318  *                   array to the variable pointer by len parameter
00319  *     user_data   - pointer to user specific data passed to get and set functions
00320  * Returns:
00321  *     result code as described in cli_result_code enum
00322  */
00323 int FASTDB_DLL_ENTRY cli_array_column(int            statement,
00324                                       char const*    column_name, 
00325                                       int            var_type,
00326                                       void*          var_ptr,
00327                                       cli_column_set set,
00328                                       cli_column_get get);
00329     
00330 int FASTDB_DLL_ENTRY cli_array_column_ex(int               statement,
00331                                          char const*       column_name, 
00332                                          int               var_type,
00333                                          void*             var_ptr,
00334                                          cli_column_set_ex set,
00335                                          cli_column_get_ex get, 
00336                                          void*             user_data);
00337     
00338 enum { 
00339     cli_view_only, 
00340     cli_for_update
00341 };
00342 
00343 /*********************************************************************
00344  * cli_fetch
00345  *     Execute select statement.
00346  * Parameters:
00347  *     statement  - statememt descriptor returned by cli_statement
00348  *     for_update - not zero if fetched rows will be updated 
00349  * Returns:
00350  *     >= 0 - success, for select statements number of fetched rows is returned
00351  *     <  0 - error code as described in cli_result_code enum
00352  */
00353 int FASTDB_DLL_ENTRY cli_fetch(int statement, int for_update);
00354 
00355 /*********************************************************************
00356  * cli_insert
00357  *     Execute insert statement.
00358  * Parameters:
00359  *     statement  - statememt descriptor returned by cli_statement
00360  *     oid        - object identifier of created record. 
00361  * Returns:
00362  *     status code as described in cli_result_code enum
00363  */
00364 int FASTDB_DLL_ENTRY cli_insert(int statement, cli_oid_t* oid);
00365 
00366 /*********************************************************************
00367  * cli_get_first
00368  *     Get first row of the selection.
00369  * Parameters:
00370  *     statement  - statememt descriptor returned by cli_statement
00371  * Returns:
00372  *     result code as described in cli_result_code enum
00373  */
00374 int FASTDB_DLL_ENTRY cli_get_first(int statement);
00375 
00376 /*********************************************************************
00377  * cli_get_last
00378  *     Get last row of the selection.
00379  * Parameters:
00380  *     statement  - statememt descriptor returned by cli_statement
00381  * Returns:
00382  *     result code as described in cli_result_code enum
00383  */
00384 int FASTDB_DLL_ENTRY cli_get_last(int statement);
00385 
00386 /*********************************************************************
00387  * cli_get_next
00388  *     Get next row of the selection. If get_next records is called
00389  *     exactly after cli_fetch function call, is will fetch the first record
00390  *     in selection.
00391  * Parameters:
00392  *     statement  - statememt descriptor returned by cli_statement
00393  * Returns:
00394  *     result code as described in cli_result_code enum
00395  */
00396 int FASTDB_DLL_ENTRY cli_get_next(int statement);
00397 
00398 /*********************************************************************
00399  * cli_get_prev
00400  *     Get previous row of the selection. If get_next records is called
00401  *     exactly after cli_fetch function call, is will fetch the last record
00402  *     in selection.
00403  * Parameters:
00404  *     statement  - statememt descriptor returned by cli_statement
00405  * Returns:
00406  *     result code as described in cli_result_code enum
00407  */
00408 int FASTDB_DLL_ENTRY cli_get_prev(int statement);
00409 
00410 /*********************************************************************
00411  * cli_skip
00412  *     Skip specified number of rows. 
00413  * Parameters:
00414  *     statement  - statememt descriptor returned by cli_statement
00415  *     n          - number of objects to be skipped
00416  *                - if "n" is positive, then this function has the same effect as
00417  *                     executing cli_get_next() function "n" times.
00418  *                - if "n" is negative, then this function has the same effect as
00419  *                     executing cli_get_prev() function "-n" times.
00420  *                - if "n"  is zero, this method just reloads current record
00421  * Returns:
00422  *     result code as described in cli_result_code enum
00423  */
00424 int FASTDB_DLL_ENTRY cli_skip(int statement, int n);
00425 
00426 /*********************************************************************
00427  * cli_seek
00428  *    Position cursor to the record with specified OID
00429  * Parameters:
00430  *     statement   - statememt descriptor returned by cli_statement
00431  *     oid         - object identifier of the record to which cursor should be positioned
00432  * Returns:
00433  *     >= 0 - success, position of the record in the selection
00434  *     <  0 - error code as described in cli_result_code enum
00435  */
00436 int FASTDB_DLL_ENTRY cli_seek(int statement, cli_oid_t oid);
00437 
00438 
00439 /*********************************************************************
00440  * cli_get_oid
00441  *     Get object identifier of the current record
00442  * Parameters:
00443  *     statement  - statememt descriptor returned by cli_statement
00444  * Returns:
00445  *     object identifier or 0 if no object is seleected
00446  */
00447 cli_oid_t FASTDB_DLL_ENTRY cli_get_oid(int statement);
00448 
00449 /*********************************************************************
00450  * cli_update
00451  *     Update the current row in the selection. You have to set
00452  *     for_update parameter of cli_fetch to 1 in order to be able 
00453  *     to perform updates. Updated value of row fields will be taken
00454  *     from bound column variables. 
00455  * Parameters:
00456  *     statement   - statememt descriptor returned by cli_statement
00457  * Returns:
00458  *     result code as described in cli_result_code enum
00459  */
00460 int FASTDB_DLL_ENTRY cli_update(int statement);
00461 
00462 /*********************************************************************
00463  * cli_remove
00464  *     Remove all selected records. You have to set
00465  *     for_update parameter of cli_fetch to 1 in order to be able 
00466  *     to remove records. 
00467  * Parameters:
00468  *     statement   - statememt descriptor returned by cli_statement
00469  * Returns:
00470  *     result code as described in cli_result_code enum
00471  */
00472 int FASTDB_DLL_ENTRY cli_remove(int statement);
00473 
00474 /*********************************************************************
00475  * cli_remove_current
00476  *     Remove currently selected record. You have to set
00477  *     for_update parameter of cli_fetch to 1 in order to be able
00478  *     to remove records.
00479  * Parameters:
00480  *     statement   - statememt descriptor returned by cli_statement
00481  * Returns:
00482  *     result code as described in cli_result_code enum
00483  */
00484 int FASTDB_DLL_ENTRY cli_remove_current(int statement);
00485 
00486 /*********************************************************************
00487  * cli_free
00488  *     Deallocate statement and all associated data
00489  * Parameters:
00490  *     statement   - statememt descriptor returned by cli_statement
00491  * Returns:
00492  *     result code as described in cli_result_code enum
00493  */
00494 int FASTDB_DLL_ENTRY cli_free(int statement);
00495 
00496 /*********************************************************************
00497  * cli_close_cursor
00498  *     Close current cursor
00499  * Parameters:
00500  *     statement   - statememt descriptor returned by cli_statement
00501  * Returns:
00502  *     result code as described in cli_result_code enum
00503  */
00504 int FASTDB_DLL_ENTRY cli_close_cursor(int statement);
00505 
00506 /*********************************************************************
00507  * cli_commit
00508  *     Commit current database transaction
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_commit(int session);
00515 
00516 /*********************************************************************
00517  * cli_precommit
00518  *     Release all locks set by transaction. This methods allows other clients
00519  *     to proceed, but it doesn't flush transaction to the disk.
00520  * Parameters:
00521  *     session - session descriptor as returned by cli_open
00522  * Returns:
00523  *     result code as described in cli_result_code enum
00524  */
00525 int FASTDB_DLL_ENTRY cli_precommit(int session);
00526 
00527 /*********************************************************************
00528  * cli_abort
00529  *     Abort current database transaction
00530  * Parameters:
00531  *     session - session descriptor as returned by cli_open
00532  * Returns:
00533  *     result code as described in cli_result_code enum
00534  */
00535 int FASTDB_DLL_ENTRY cli_abort(int session);
00536 
00537 
00538 enum cli_field_flags { 
00539     cli_hashed           = 1, /* field should be indexed usnig hash table */
00540     cli_indexed          = 2, /* field should be indexed using B-Tree */
00541     cli_autoincremented  = 16 /* field is assigned automaticall incremented value */
00542 };
00543 
00544 typedef struct cli_field_descriptor { 
00545     enum cli_var_type type;
00546     int               flags;
00547     char const*       name;
00548     char const*       refTableName;
00549     char const*       inverseRefFieldName;
00550 } cli_field_descriptor;
00551 
00552 /*********************************************************************
00553  * cli_describe
00554  *     Describe fields of specified table
00555  * Parameters:
00556  *     session - session descriptor as returned by cli_open
00557  *     table   - name of the table
00558  *     fields  - address of the pointer to the array of fields descriptors, 
00559  *               this array should be later deallocated by application by cli_free_memory()
00560  * Returns:
00561  *     >= 0 - number of fields in the table
00562  *     < 0  - result code as described in cli_result_code enum
00563  */
00564 int FASTDB_DLL_ENTRY cli_describe(int session, char const* table, cli_field_descriptor** fields);
00565 
00566 typedef struct cli_field_layout {
00567     cli_field_descriptor desc;
00568     int                  offs;
00569     int                  size;
00570 } cli_field_layout;
00571 
00572 /*********************************************************************
00573  * cli_describe_layout
00574  *     Describe fields layout of specified table
00575  * Parameters:
00576  *     session - session descriptor as returned by cli_open
00577  *     table   - name of the table
00578  *     fields  - address of the pointer to the array of fields layout descriptors, 
00579  *               this array should be later deallocated by application by cli_free_memory()
00580  *     rec_size - pointer to the location to receive size of the record. This size can be used by application to allocate buffer for cli_execute_query function
00581  * Returns:
00582  *     >= 0 - number of fields in the table
00583  *     < 0  - result code as described in cli_result_code enum
00584  */
00585 int FASTDB_DLL_ENTRY cli_describe_layout(int session, char const* table, cli_field_layout** fields, int* rec_size);
00586 
00587 /*********************************************************************
00588  * cli_get_field_size
00589  *     Calculate field size
00590  * Parameters:
00591  *     fields  - array with fields descriptors obtained using cli_describe function
00592  *     field_no - number of the field
00593  */
00594 int FASTDB_DLL_ENTRY cli_get_field_size(cli_field_descriptor* fields, int field_no);
00595 
00596 /*********************************************************************
00597  * cli_get_field_offset
00598  *     Calculate offset of the field 
00599  * Parameters:
00600  *     fields  - array with fields descriptors obtained using cli_describe function
00601  *     field_no - number of the field
00602  */
00603 int FASTDB_DLL_ENTRY cli_get_field_offset(cli_field_descriptor* fields, int field_no);
00604 
00605 
00606 typedef struct cli_table_descriptor {
00607     char const*       name;
00608 } cli_table_descriptor;
00609 
00610 /*********************************************************************
00611  * cli_show_tables
00612  *     Show all tables of specified database
00613  * Parameters:
00614  *     session - session descriptor as returned by cli_open
00615  *     tables  - address of the pointer to the array of tables descriptors,
00616  *               this array should be later deallocated by application by cli_free_memory()
00617  * Returns:
00618  *     >= 0 - number of tables in the database (Metatable is not returned/counted)
00619  *     < 0  - result code as described in cli_result_code enum
00620  */
00621 int FASTDB_DLL_ENTRY cli_show_tables(int session, cli_table_descriptor** tables);
00622 
00623 
00624 /*********************************************************************
00625  * cli_create_table
00626  *     Create new table
00627  * Parameters:
00628  *     session   - session descriptor as returned by cli_open
00629  *     tableName - name of new table
00630  *     nFields   - number of columns in the table
00631  *     fields    - array with table columns descriptors
00632  * Returns:
00633  *     result code as described in cli_result_code enum
00634  */
00635 int FASTDB_DLL_ENTRY cli_create_table(int session, char const* tableName, int nFields, 
00636                                         cli_field_descriptor* fields);
00637 
00638 /*********************************************************************
00639  * cli_alter_table
00640  *     Change table format
00641  * Parameters:
00642  *     session   - session descriptor as returned by cli_open
00643  *     tableName - name of existing table
00644  *     nFields   - number of columns in the table
00645  *     fields    - array with new table columns descriptors
00646  * Returns:
00647  *     result code as described in cli_result_code enum
00648  */
00649 int FASTDB_DLL_ENTRY cli_alter_table(int session, char const* tableName, int nFields, 
00650                                      cli_field_descriptor* fields);
00651 
00652 /*********************************************************************
00653  * cli_drop_table
00654  *     drop the table
00655  * Parameters:
00656  *     session   - session descriptor as returned by cli_open
00657  *     tableName - name of deleted table
00658  * Returns:
00659  *     result code as described in cli_result_code enum
00660  */
00661 int FASTDB_DLL_ENTRY cli_drop_table(int session, char const* tableName);
00662 
00663 
00664 /*********************************************************************
00665  * cli_alter_index
00666  *     add or remove column index
00667  * Parameters:
00668  *     session   - session descriptor as returned by cli_open
00669  *     tableName - name of the table
00670  *     fieldName - name of field
00671  *     newFlags  - new flags of the field, if index exists for this field, but is not specified in 
00672  *                 <code>newFlags</code> mask, then it will be removed; if index not exists, but is 
00673  *                 specified in <code>newFlags</code> mask, then it will be created. *                   
00674  * Returns:
00675  *     result code as described in cli_result_code enum
00676  */
00677 int FASTDB_DLL_ENTRY cli_alter_index(int session, char const* tableName, char const* fieldName, 
00678                                      int newFlags);
00679 
00680 
00681 /*********************************************************************
00682  * cli_set_error_handler
00683  *     Set FastDB erro handler. Handler should be no-return function which perform stack unwind.
00684  * Parameters:
00685  *     session   - session descriptor as returned by cli_open
00686  *     handler   - error handler
00687  *     context   - error handler context: pointer to the user specific data
00688  *                  which will be passed to thr handler
00689  * Returns:
00690  *     previous handler
00691  */
00692 enum cli_error_class { 
00693     cli_no_error, 
00694     cli_query_error,
00695     cli_arithmetic_error,
00696     cli_index_out_of_range_error,
00697     cli_database_open_error,
00698     cli_file_error,
00699     cli_out_of_memory_error,
00700     cli_deadlock,
00701     cli_null_reference_error,
00702     cli_lock_revoked,
00703     cli_file_limit_exeeded        
00704 };
00705 typedef void (CLI_CALLBACK_CC *cli_error_handler)(int error, char const* msg, int msgarg, void* context); 
00706 cli_error_handler FASTDB_DLL_ENTRY cli_set_error_handler(int session, cli_error_handler new_handler, void* context);
00707 
00708 /*********************************************************************
00709  * cli_freeze
00710  *    Freeze cursor. Make it possible to reused cursor after commit of the current transaction.
00711  * Parameters:
00712  *     statement   - statememt descriptor returned by cli_statement
00713  * Returns:
00714  *     result code as described in cli_result_code enum
00715  */
00716 int FASTDB_DLL_ENTRY cli_freeze(int statement);
00717 
00718 /*********************************************************************
00719  * cli_unfreeze
00720  *    Unfreeze cursor. Reuse previously frozen cursor.
00721  * Parameters:
00722  *     statement   - statememt descriptor returned by cli_statement
00723  * Returns:
00724  *     result code as described in cli_result_code enum
00725  */
00726 int FASTDB_DLL_ENTRY cli_unfreeze(int statement);
00727 
00728 
00729 /*********************************************************************
00730  * cli_attach
00731  *    Attach thread to the database. Each thread except one opened the database should first
00732  *    attach to the database before any access to the database, and detach after end of the work with database
00733  * Parameters:
00734  *     session - session descriptor returned by cli_open
00735  * Returns:
00736  *     result code as described in cli_result_code enum
00737  */
00738 int FASTDB_DLL_ENTRY cli_attach(int session);
00739 
00740 /*********************************************************************
00741  * cli_detach
00742  *    Detach thread from the database. Each thread except one opened the database should perform 
00743  *    attach to the database before any access to the database, and detach after end of the work with database
00744  * Parameters:
00745  *     session - session descriptor returned by cli_open
00746  *     detach_mode - bit mask representing detach mode
00747  * Returns:
00748  *     result code as described in cli_result_code enum
00749  */
00750 enum cli_detach_mode {
00751     cli_commit_on_detach          = 1,
00752     cli_destroy_context_on_detach = 2
00753 };
00754 
00755 int FASTDB_DLL_ENTRY cli_detach(int session, int detach_mode);
00756 
00757 
00758 /*********************************************************************
00759  * cli_free_memory
00760  *    Free memory allocated by cli_show_tables and cli_describe
00761  * Parameters:
00762  *     session - session descriptor returned by cli_open
00763  *     ptr - pointer to the allocated buffer
00764  */
00765 void FASTDB_DLL_ENTRY cli_free_memory(int session, void* ptr);
00766 
00767 
00768 typedef struct cli_database_monitor {
00769     int n_readers;
00770     int n_writers;
00771     int n_blocked_readers;
00772     int n_blocked_writers;
00773     int n_users;
00774 } cli_database_monitor;
00775 
00776 /*********************************************************************
00777  * cli_get_database_state
00778  *    Obtain information about current state of the database
00779  * Parameters:
00780  *     session - session descriptor returned by cli_open
00781  *     monitor - pointer to the monitor structure. The folloing fields are set:
00782  *       n_readers: number of granted shared locks
00783  *       n_writers: number of granted exclusive locks
00784  *       n_blocked_reader: number of threads which shared lock request was blocked
00785  *       n_blocked_writers: number of threads which exclusive lock request was blocked
00786  *       n_users: number of processes openned the database
00787  * Returns:
00788  *     result code as described in cli_result_code enum
00789  */
00790 int FASTDB_DLL_ENTRY cli_get_database_state(int session, cli_database_monitor* monitor);
00791 
00792 
00793 
00794 /*********************************************************************
00795  * cli_set_trace_function
00796  *    Set trace function which will be used to output FastDB trace messages
00797  * Parameters:
00798  *     func - pointer to trace function which receives trace message terminated with new line character
00799  */
00800 typedef void (CLI_CALLBACK_CC *cli_trace_function_t)(char* msg);
00801 void FASTDB_DLL_ENTRY cli_set_trace_function(cli_trace_function_t func);
00802 
00803 
00804 /*********************************************************************
00805  * cli_prepare_query
00806  *     Prepare SubSQL query statement. 
00807  * Parameters:
00808  *     session - session descriptor returned by cli_open
00809  *     query   - query string with optional parameters. Parameters are specified
00810  *               as '%T' where T is one or two character code of parameter type using the same notation
00811  *               as in printf: %d or %i - int, %f - float or double, %ld - int8, %s - string, %p - oid...
00812  *               Parameter of cli_rectangle_t* type has format %R, cli_time_t type - %t
00813  * Returns:
00814  *     >= 0 - statement descriptor
00815  *     <  0 - error code as described in cli_result_code enum
00816  */
00817 int FASTDB_DLL_ENTRY cli_prepare_query(int session, char const* query);
00818 
00831 int FASTDB_DLL_ENTRY cli_execute_query(int statement, int for_update, void* record_struct, ...);
00832 
00847 int FASTDB_DLL_ENTRY cli_execute_query_ex(int statement, int for_update, void* record_struct, int n_params, int* param_types, void** param_values);
00848 
00860 int FASTDB_DLL_ENTRY cli_insert_struct(int session, char const* table_name, void* record_struct, cli_oid_t* oid);
00861 
00862 typedef void* cli_transaction_context_t;
00863 /*********************************************************************
00864  * cli_create_transaction_context
00865  *    Create new transaction xontext which can be used in cli_join_transaction function
00866  * Parameters:
00867  * Returns:
00868  *     created transaction context
00869  */
00870  cli_transaction_context_t FASTDB_DLL_ENTRY cli_create_transaction_context();
00871 
00872 /*********************************************************************
00873  * cli_join_transaction
00874  *    Associate current threads with specified transaction context,
00875  *    It allows to share single transaction between multiple threads.
00876  * Parameters:
00877  *     session - session descriptor returned by cli_open
00878  *     ctx     - transaction context created by cli_create_transaction_context
00879  * Returns:
00880  *     result code as described in cli_result_code enum
00881  */
00882 int FASTDB_DLL_ENTRY cli_join_transaction(int session, cli_transaction_context_t ctx);
00883 
00884 /*********************************************************************
00885  * cli_remove_transaction_context
00886  *    Remove transaction context
00887  * Parameters:
00888  *     ctx  transaction context created by cli_create_transaction_context
00889  */
00890 void FASTDB_DLL_ENTRY cli_remove_transaction_context(cli_transaction_context_t ctx);
00891 
00892 #ifdef __cplusplus
00893 }
00894 #endif
00895 
00896 #endif
00897 
00898 

Generated on Thu Feb 14 12:42:30 2008 for FastDB by doxygen1.2.18