cli.h

一个不错的fastdb使用例子

   * Parameters:
   *     statement  - statememt descriptor returned by cli_statement
   * Returns:
   *     result code as described in cli_result_code enum
   */
  int FASTDB_DLL_ENTRY cli_get_prev(int statement);

  /*********************************************************************
   * cli_skip
   *     Skip specified number of rows. 
   * Parameters:
   *     statement  - statememt descriptor returned by cli_statement
   *     n          - number of objects to be skipped
   *                - if "n" is positive, then this function has the same effect as
   *                     executing cli_get_next() function "n" times.
   *                - if "n" is negative, then this function has the same effect as
   *                     executing cli_get_prev() function "-n" times.
   *                - if "n"  is zero, this method just reloads current record
   * Returns:
   *     result code as described in cli_result_code enum
   */
  int FASTDB_DLL_ENTRY cli_skip(int statement, int n);

  /*********************************************************************
   * cli_seek
   *    Position cursor to the record with specified OID
   * Parameters:
   *     statement   - statememt descriptor returned by cli_statement
   *     oid         - object identifier of the record to which cursor should be positioned
   * Returns:
   *     >= 0 - success, position of the record in the selection
   *     <  0 - error code as described in cli_result_code enum
   */
  int FASTDB_DLL_ENTRY cli_seek(int statement, cli_oid_t oid);


  /*********************************************************************
   * cli_get_oid
   *     Get object identifier of the current record
   * Parameters:
   *     statement  - statememt descriptor returned by cli_statement
   * Returns:
   *     object identifier or 0 if no object is seleected
   */
  cli_oid_t FASTDB_DLL_ENTRY cli_get_oid(int statement);

  /*********************************************************************
   * cli_update
   *     Update the current row in the selection. You have to set
   *     for_update parameter of cli_fetch to 1 in order to be able 
   *     to perform updates. Updated value of row fields will be taken
   *     from bound column variables. 
   * Parameters:
   *     statement   - statememt descriptor returned by cli_statement
   * Returns:
   *     result code as described in cli_result_code enum
   */
  int FASTDB_DLL_ENTRY cli_update(int statement);

  /*********************************************************************
   * cli_remove
   *     Remove all selected records. You have to set
   *     for_update parameter of cli_fetch to 1 in order to be able 
   *     to remove records. 
   * Parameters:
   *     statement   - statememt descriptor returned by cli_statement
   * Returns:
   *     result code as described in cli_result_code enum
   */
  int FASTDB_DLL_ENTRY cli_remove(int statement);

  /*********************************************************************
   * cli_free
   *     Deallocate statement and all associated data
   * Parameters:
   *     statement   - statememt descriptor returned by cli_statement
   * Returns:
   *     result code as described in cli_result_code enum
   */
  int FASTDB_DLL_ENTRY cli_free(int statement);

  /*********************************************************************
   * cli_commit
   *     Commit current database transaction
   * Parameters:
   *     session - session descriptor as returned by cli_open
   * Returns:
   *     result code as described in cli_result_code enum
   */
  int FASTDB_DLL_ENTRY cli_commit(int session);

  /*********************************************************************
   * cli_precommit
   *     Release all locks set by transaction. This methods allows other clients
   *     to proceed, but it doesn't flush transaction to the disk.
   * Parameters:
   *     session - session descriptor as returned by cli_open
   * Returns:
   *     result code as described in cli_result_code enum
   */
  int FASTDB_DLL_ENTRY cli_precommit(int session);

  /*********************************************************************
   * cli_abort
   *     Abort current database transaction
   * Parameters:
   *     session - session descriptor as returned by cli_open
   * Returns:
   *     result code as described in cli_result_code enum
   */
  int FASTDB_DLL_ENTRY cli_abort(int session);


  enum cli_field_flags
  {
    cli_hashed           = 1, /* field should be indexed usnig hash table */
    cli_indexed          = 2  /* field should be indexed using B-Tree */
  };

  typedef struct cli_field_descriptor
  {
    enum cli_var_type type;
    int               flags;
    char const*       name;
    char const*       refTableName;
    char const*       inverseRefFieldName;
    int               size;
    int               offs;
  }

  cli_field_descriptor;

  /*********************************************************************
   * cli_describe
   *     Describe fileds of specified table
   * Parameters:
   *     session - session descriptor as returned by cli_open
   *     table   - name of the table
   *     fields  - address of the pointer to the array of fields descriptors, 
   *               this array should be later deallocated by application by cli_free_memory()
   * Returns:
   *     >= 0 - number of fields in the table
   *     < 0  - result code as described in cli_result_code enum
   */
  int FASTDB_DLL_ENTRY cli_describe(int session, char const* table, cli_field_descriptor** fields);


  typedef struct cli_table_descriptor
  {
    char const*       name;
  }

  cli_table_descriptor;

  /*********************************************************************
   * cli_show_tables
   *     Show all tables of specified database
   * Parameters:
   *     session - session descriptor as returned by cli_open
   *     tables  - address of the pointer to the array of tables descriptors,
   *               this array should be later deallocated by application by cli_free_memory()
   * Returns:
   *     >= 0 - number of tables in the database (Metatable is not returned/counted)
   *     < 0  - result code as described in cli_result_code enum
   */
  int FASTDB_DLL_ENTRY cli_show_tables(int session, cli_table_descriptor** tables);


  /*********************************************************************
   * cli_create_table
   *     Create new table
   * Parameters:
   *     session   - session descriptor as returned by cli_open
   *     tableName - name of new table
   *     nFields   - number of columns in the table
   *     fields    - array with table columns descriptors
   * Returns:
   *     result code as described in cli_result_code enum
   */
  int FASTDB_DLL_ENTRY cli_create_table(int session, char const* tableName, int nFields,
                                        cli_field_descriptor* fields);

  /*********************************************************************
   * cli_drop_table
   *     drop the table
   * Parameters:
   *     session   - session descriptor as returned by cli_open
   *     tableName - name of deleted table
   * Returns:
   *     result code as described in cli_result_code enum
   */
  int FASTDB_DLL_ENTRY cli_drop_table(int session, char const* tableName);


  /*********************************************************************
   * cli_alter_index
   *     add or remove column index
   * Parameters:
   *     session   - session descriptor as returned by cli_open
   *     tableName - name of the table
   *     fieldName - name of field
   *     newFlags  - new flags of the field, if index exists for this field, but is not specified in 
   *                 <code>newFlags</code> mask, then it will be removed; if index not exists, but is 
   *                 specified in <code>newFlags</code> mask, then it will be created. *                   
   * Returns:
   *     result code as described in cli_result_code enum
   */
  int FASTDB_DLL_ENTRY cli_alter_index(int session, char const* tableName, char const* fieldName,
                                       int newFlags);


  /*********************************************************************
   * cli_set_error_handler
   *     Set FastDB erro handler. Handler should be no-return function which perform stack unwind.
   * Parameters:
   *     session   - session descriptor as returned by cli_open
   *     handler   - error handler
   * Returns:
   *     previous handler
   */
  enum cli_error_class {
    cli_no_error,
    cli_query_error,
    cli_arithmetic_error,
    cli_index_out_of_range_error,
    cli_database_open_error,
    cli_file_error,
    cli_out_of_memory_error,
    cli_deadlock,
    cli_null_reference_error,
    cli_lock_revoked,
    cli_file_limit_exeeded
  };
  typedef void (*cli_error_handler)(int error, char const* msg, int msgarg);
  cli_error_handler FASTDB_DLL_ENTRY cli_set_error_handler(int session, cli_error_handler new_handler);

  /*********************************************************************
   * cli_freeze
   *    Freeze cursor. Make it possible to reused cursor after commit of the current transaction.
   * Parameters:
   *     statement   - statememt descriptor returned by cli_statement
   * Returns:
   *     result code as described in cli_result_code enum
   */
  int FASTDB_DLL_ENTRY cli_freeze(int statement);

  /*********************************************************************
   * cli_unfreeze
   *    Unfreeze cursor. Reuse previously frozen cursor.
   * Parameters:
   *     statement   - statememt descriptor returned by cli_statement
   * Returns:
   *     result code as described in cli_result_code enum
   */
  int FASTDB_DLL_ENTRY cli_unfreeze(int statement);


  /*********************************************************************
   * cli_attach
   *    Attach thread to the database. Each thread except one opened the database should first
   *    attach to the database before any access to the database, and detach after end of the work with database
   * Parameters:
   *     session - session descriptor returned by cli_open
   * Returns:
   *     result code as described in cli_result_code enum
   */
  int FASTDB_DLL_ENTRY cli_attach(int session);

  /*********************************************************************
   * cli_detach
   *    Detach thread from the database. Each thread except one opened the database should perform 
   *    attach to the database before any access to the database, and detach after end of the work with database
   * Parameters:
   *     session - session descriptor returned by cli_open
   *     detach_mode - bit mask representing detach mode
   * Returns:
   *     result code as described in cli_result_code enum
   */
  enum cli_detach_mode {
    cli_commit_on_detach          = 1,
    cli_destroy_context_on_detach = 2
  };

  int FASTDB_DLL_ENTRY cli_detach(int session, int detach_mode);


  /*********************************************************************
   * cli_free_memory
   *    Free memory allocated by cli_show_tables and cli_describe
   * Parameters:
   *     session - session descriptor returned by cli_open
   *     ptr - pointer to the allocated buffer
   */
  void FASTDB_DLL_ENTRY cli_free_memory(int session, void* ptr);


  typedef struct cli_database_monitor
  {
    int n_readers;
    int n_writers;
    int n_blocked_readers;
    int n_blocked_writers;
    int n_users;
  }

  cli_database_monitor;

  /*********************************************************************
   * cli_get_database_state
   *    Obtain information about current state of the database
   * Parameters:
   *     session - session descriptor returned by cli_open
   *     monitor - pointer to the monitor structure. The folloing fields are set:
   *       n_readers: number of granted shared locks
   *       n_writers: number of granted exclusive locks
   *       n_blocked_reader: number of threads which shared lock request was blocked
   *       n_blocked_writers: number of threads which exclusive lock request was blocked
   *       n_users: number of processes openned the database
   * Returns:
   *     result code as described in cli_result_code enum
   */
  int FASTDB_DLL_ENTRY cli_get_database_state(int session, cli_database_monitor* monitor);



  /*********************************************************************
   * cli_set_trace_function
   *    Set trace function which will be used to output FastDB trace messages
   * Parameters:
   *     func - pointer to trace function which receives trace message terminated with new line character
   */
  typedef void (*cli_trace_function_t)(char* msg);
  void FASTDB_DLL_ENTRY cli_set_trace_function(cli_trace_function_t func);


  /*********************************************************************
   * cli_prepare_query
   *     Prepare SubSQL query statement. 
   * Parameters:
   *     session - session descriptor returned by cli_open
   *     query   - query string with optional parameters. Parameters are specified
   *               as '%T' where T is one or two character code of parameter type using the same notation
   *               as in printf: %d or %i - int, %f - float or double, %ld - int8, %s - string, %p - oid...
   * Returns:
   *     >= 0 - statement descriptor
   *     <  0 - error code as described in cli_result_code enum
   */
  int FASTDB_DLL_ENTRY cli_prepare_query(int session, char const* query);

  /**
   * cli_execute_query
   *     Execute query previously prepared by cli_prepare_query
   * Parameters:
   *     statement - statement descriptor returned by cli_prepare_query
   *     for_update - not zero if fetched rows will be updated 
   *     record_struct - structure to receive selected record fields
   *     ...     - varying list of query parameters
   * Returns:
   *     >= 0 - success, for select statements number of fetched rows is returned
   *     <  0 - error code as described in cli_result_code enum
   */
  int FASTDB_DLL_ENTRY cli_execute_query(int statement, int for_update, void* record_struct, ...);

  /**
   * cli_insert_struct
   *     Insert new record represented as C structure
   * Parameters:
   *     session - session descriptor returned by cli_open
   *     table_name - name of the destination table
   *     record_struct - structure specifying value of record fields
   *     oid - pointer to the location to receive OID of created record (may be NULL)
   * Returns:
   *     result code as described in cli_result_code enum
   */
  int FASTDB_DLL_ENTRY cli_insert_struct(int session, char const* table_name, void* record_struct, cli_oid_t* oid);

#ifdef __cplusplus
}

#endif

#endif