class BDB::Common - RDoc Documentation

# class BDB::Common

Implement common methods for access to data

### Public Class Methods

create(name = nil, subname = nil, flags = 0, mode = 0, options = {}) click to toggle source

same than open

    # File common.rb, line 118
    def  create(name = nil, subname = nil, flags = 0, mode = 0, options = {})
    end

db_remove(name, subname = nil) click to toggle source

same than remove

    # File common.rb, line 135
    def  db_remove(name, subname = nil)
    end

db_upgrade(name) click to toggle source

same than upgrade

    # File common.rb, line 148
    def  db_upgrade(name)
    end

new(name = nil, subname = nil, flags = 0, mode = 0, options = {}) click to toggle source

same than open

    # File common.rb, line 122
    def  new(name = nil, subname = nil, flags = 0, mode = 0, options = {})
    end

open(name = nil, subname = nil, flags = 0, mode = 0, options = {}) click to toggle source

open the database

- name The argument name is used as the name of a single physical file on disk that will be used to back the database.

- subname The subname argument allows applications to have subdatabases, i.e., multiple databases inside of a single physical file. This is useful when the logical databases are both numerous and reasonably small, in order to avoid creating a large number of underlying files. It is an error to attempt to open a subdatabase in a database file that was not initially created using a subdatabase name.

- flags The flags must be the string “r”, “r+”, “w”, “w+”, “a”, “a+” or and integer value.

  The flags value must be set to 0 or by bitwise inclusively OR'ing together one or more of the following values

  - BDB::CREATE Create any underlying files, as necessary. If the files do not already exist and the DB_CREATE flag is not specified, the call will fail.

  - BD::EXCL Return an error if the database already exists. Underlying filesystem primitives are used to implement this flag. For this reason it is only applicable to the physical database file and cannot be used to test if a subdatabase already exists.

  - BDB::NOMMAP Do not map this database into process memory.

  - BDB::RDONLY Open the database for reading only. Any attempt to modify items in the database will fail regardless of the actual permissions of any underlying files.

  - BDB::TRUNCATE Physically truncate the underlying database file, discarding all previous subdatabases or databases. Underlying filesystem primitives are used to implement this flag. For this reason it is only applicable to the physical database file and cannot be used to discard subdatabases.

    The DB_TRUNCATE flag cannot be transaction protected, and it is an error to specify it in a transaction protected environment.

- options Hash, Possible options are (see the documentation of Berkeley DB for more informations)

  - store_nil_as_null: if `true' will store `nil' as `000', otherwise as an empty string (default `false')

  - set_array_base: base index for BDB::Recno, BDB::Queue or BDB::Btree (with BDB::RECNUM). Must be 0 or 1

  - set_bt_compare : specify a Btree comparison function

  - set_bt_minkey : set the minimum number of keys per Btree page

  - set_bt_prefix : specify a Btree prefix comparison function

  - set_cachesize : set the database cache size

  - set_dup_compare : specify a duplicate comparison function

  - set_store_key : specify a Proc called before a key is stored

  - set_fetch_key : specify a Proc called after a key is read

  - set_store_value : specify a Proc called before a value is stored

  - set_fetch_value : specify a Proc called after a value is read

  - set_flags : general database configuration

  - set_h_ffactor : set the Hash table density

  - set_h_hash : specify a hashing function

  - set_h_nelem : set the Hash table size

  - set_lorder : set the database byte order

  - set_pagesize : set the underlying database page size

  - set_re_delim : set the variable-length record delimiter

  - set_re_len : set the fixed-length record length

  - set_re_pad : set the fixed-length record pad byte

  - set_re_source : set the backing Recno text file

  - set_append_recno : modify the stored data for BDB::APPEND

  - set_encrypt : set the password used

  - set_feedback : set the function to monitor some operations

  - env : open the database in the environnement given as the value

  - txn : open the database in the transaction given as the value

  set_append_recno will be called with (key, value) and it must return nil or the modified value

  set_encrypt take an Array as arguments with the values [password, flags], where flags can be 0 or BDB::ENCRYPT_AES

  Proc given to set_bt_compare, set_bt_prefix, set_dup_compare, set_h_hash, set_store_key set_fetch_key, set_store_value, set_fetch_value set_feedback and set_append_recno can be also specified as a method (replace the prefix set_ with bdb_)

      For example

        module BDB
           class Btreesort < Btree
              def bdb_bt_compare(a, b)
                 b.downcase <=> a.downcase
              end
           end
        end

    # File common.rb, line 114
    def  open(name = nil, subname = nil, flags = 0, mode = 0, options = {})
    end

remove(name, subname = nil) click to toggle source

Removes the database (or subdatabase) represented by the name and subname combination.

If no subdatabase is specified, the physical file represented by name is removed, incidentally removing all subdatabases that it contained.

    # File common.rb, line 131
    def  remove(name, subname = nil)
    end

unlink(name, subname = nil) click to toggle source

same than remove

    # File common.rb, line 139
    def  unlink(name, subname = nil)
    end

upgrade(name) click to toggle source

Upgrade the database

    # File common.rb, line 144
    def  upgrade(name)
    end

### Public Instance Methods

[](key) click to toggle source

Returns the value corresponding the key

    # File common.rb, line 154
    def  [](key)
    end

[]=(key, value) click to toggle source

Stores the value associating with key

If nil is given as the value, the association from the key will be removed.

    # File common.rb, line 245
    def  []=(key, value)
    end

append(key, value) click to toggle source

Append the value associating with key

    # File common.rb, line 270
    def  append(key, value)
    end

associate(db, flag = 0) { |db, key, value| ... } click to toggle source

associate a secondary index db

flag can have the value BDB::RDONLY

The block must return the new key, or Qfalse in this case the secondary index will not contain any reference to key/value

    # File common.rb, line 164
    def  associate(db, flag = 0)
       yield db, key, value
    end

both?(key, value) click to toggle source

same than has_both?

    # File common.rb, line 487
    def  both?(key, value)
    end

byteswapped?() click to toggle source

Return if the underlying database is in host order

    # File common.rb, line 279
    def  byteswapped?
    end

cache_priority() click to toggle source

return the current priority value

    # File common.rb, line 170
    def  cache_priority
    end

cache_priority=(value) click to toggle source

set the priority value : can be BDB::PRIORITY_VERY_LOW, BDB::PRIORITY_LOW, BDB::PRIORITY_DEFAULT, BDB::PRIORITY_HIGH or BDB::PRIORITY_VERY_HIGH

    # File common.rb, line 177
    def  cache_priority=value
    end

clear() click to toggle source

same than truncate

    # File common.rb, line 615
    def  clear
    end

clear_partial() click to toggle source

Clear partial set.

    # File common.rb, line 288
    def  clear_partial
    end

close(flags = 0) click to toggle source

Closes the file.

    # File common.rb, line 297
    def  close(flags = 0)
    end

compact(start = nil, stop = nil, options = nil) click to toggle source

Only for Btree and Recno (DB VERSION >= 4.4)

- start starting point for compaction in a Btree or Recno database. Compaction will start at the smallest key greater than or equal to the specified key.

- stop the stopping point for compaction in a Btree or Recno database. Compaction will stop at the page with the smallest key greater than the specified key

- options hash with the possible keys

  - flags with the value 0, BDB::FREELIST_ONLY, or BDB::FREE_SPACE

  - compact_fillpercentthe goal for filling pages, specified as a percentage between 1 and 100.

  - compact_timeout the lock timeout set for implicit transactions, in microseconds.

    # File common.rb, line 325
    def compact(start = nil, stop = nil, options = nil)
    end

count(key) click to toggle source

Return the count of duplicate for key

    # File common.rb, line 330
    def  count(key)
    end

create_sequence(key, init = nil, options = {}) { |sequence| ... } click to toggle source

create a new sequence (see also open_sequence)

equivalent to open_sequence(key, BDB::CREATE|BDB::EXCL, init, options)

return (or yield) an object BDB::Sequence

    # File common.rb, line 186
    def create_sequence(key, init = nil, options = {})
       yield sequence
    end

cursor(flags = 0) click to toggle source

Open a new cursor.

    # File common.rb, line 339
    def  cursor(flags = 0)
    end

cursor_write() click to toggle source

Open a new cursor with the flag BDB::WRITECURSOR

    # File common.rb, line 348
    def  cursor_write()
    end

database() click to toggle source

Return the subname

    # File common.rb, line 357
    def  database()
    end

db_append(key, value) click to toggle source

same than append

    # File common.rb, line 274
    def  db_append(key, value)
    end

db_close(flags = 0) click to toggle source

same than close

    # File common.rb, line 301
    def  db_close(flags = 0)
    end

db_cursor(flags = 0) click to toggle source

same than cursor

    # File common.rb, line 343
    def  db_cursor(flags = 0)
    end

db_cursor_write(flags = 0) click to toggle source

same than #cursor_write

    # File common.rb, line 352
    def  db_cursor_write(flags = 0)
    end

db_del(key) click to toggle source

same than delete

    # File common.rb, line 373
    def  db_del(key)
    end

db_get(key, flags = 0) click to toggle source

same than get

    # File common.rb, line 225
    def  db_get(key, flags = 0)
    end

db_put(key, value, flags = 0) click to toggle source

same than put

    # File common.rb, line 261
    def  db_put(key, value, flags = 0)
    end

delete(key) click to toggle source

Removes the association from the key.

It return the object deleted or nil if the specified key don't exist.

    # File common.rb, line 369
    def  delete(key)
    end

delete_if(set = nil) { |key, value| ... } click to toggle source

Deletes associations if the evaluation of the block returns true.

set

    # File common.rb, line 380
    def  delete_if(set = nil)
       yield key, value
    end

dup_count(key) click to toggle source

same than count

    # File common.rb, line 334
    def  dup_count(key)
    end

duplicates(key , assoc = true) click to toggle source

Return an array of all duplicate associations for key

if assoc is false return only the values.

    # File common.rb, line 393
    def  duplicates(key , assoc = true)
    end

each(set = nil, bulk = 0, "flags" => 0) { |key, value| ... } click to toggle source

Iterates over associations.

set bulk

    # File common.rb, line 400
    def  each(set = nil, bulk = 0, "flags" => 0)
       yield key, value
    end

each_by_prefix(prefix = nil) { |key, value| ... } click to toggle source

iterate over associations, where the key begin with prefix

    # File common.rb, line 411
    def each_by_prefix(prefix = nil)
       yield key, value
    end

each_dup(key, bulk = 0) { |key, value| ... } click to toggle source

Iterates over each duplicate associations for key

bulk

    # File common.rb, line 419
    def  each_dup(key, bulk = 0)
       yield key, value
    end

each_dup_value(key, bulk = 0) { |value| ... } click to toggle source

Iterates over each duplicate values for key

bulk

    # File common.rb, line 427
    def  each_dup_value(key, bulk = 0)
       yield value
    end

each_key(set = nil, bulk = 0) { |key| ... } click to toggle source

Iterates over keys.

set bulk

    # File common.rb, line 435
    def  each_key(set = nil, bulk = 0)
       yield key
    end

each_pair(set = nil, bulk = 0) { |key, value| ... } click to toggle source

same than each

    # File common.rb, line 405
    def  each_pair(set = nil, bulk = 0)
       yield key, value
    end

each_primary(set = nil) { |skey, pkey, pvalue| ... } click to toggle source

Iterates over secondary indexes and give secondary key, primary key and value

    # File common.rb, line 442
    def  each_primary(set = nil)
       yield skey, pkey, pvalue
    end

each_value(set = nil, bulk = 0) { |value| ... } click to toggle source

Iterates over values.

set bulk

    # File common.rb, line 450
    def  each_value(set = nil, bulk = 0)
       yield value
    end

empty?() click to toggle source

Returns true if the database is empty.

    # File common.rb, line 456
    def  empty?()
    end

feedback=(proc) click to toggle source

monitor the progress of some operations

    # File common.rb, line 210
    def  feedback=(proc)
    end

fetch(key, flags = 0) click to toggle source

same than get

    # File common.rb, line 229
    def  fetch(key, flags = 0)
    end

filename() click to toggle source

Return the name of the file

    # File common.rb, line 461
    def  filename()
    end

get(key, flags = 0) click to toggle source

Returns the value correspondind the key

flags can have the values BDB::GET_BOTH, BDB::SET_RECNO or BDB::RMW

In presence of duplicates it will return the first data item, use

    duplicates if you want all duplicates (see also #each_dup)

    # File common.rb, line 221
    def  get(key, flags = 0)
    end

get_byteswapped() click to toggle source

same than byteswapped?

    # File common.rb, line 283
    def  get_byteswapped
    end

has_both?(key, value) click to toggle source

Returns true if the association from key is value

    # File common.rb, line 483
    def  has_both?(key, value)
    end

has_key?(key) click to toggle source

Returns true if the association from the key exists.

    # File common.rb, line 466
    def  has_key?(key)
    end

has_value?(value) click to toggle source

Returns true if the association to the value exists.

    # File common.rb, line 492
    def  has_value?(value)
    end

include?(key) click to toggle source

same than has_key?

    # File common.rb, line 474
    def  include?(key)
    end

index(value) click to toggle source

Returns the first key associated with value

    # File common.rb, line 501
    def  index(value)
    end

indexes(value1, value2, ) click to toggle source

Returns the keys associated with value1, value2, …

    # File common.rb, line 506
    def  indexes(value1, value2, )
    end

join(cursor , flag = 0) { |key, value| ... } click to toggle source

Perform a join. cursor is an array of BDB::Cursor

    # File common.rb, line 511
    def  join(cursor , flag = 0)
       yield key, value
    end

key?(key) click to toggle source

same than has_key?

    # File common.rb, line 470
    def  key?(key)
    end

keys() click to toggle source

Returns the array of the keys in the database

    # File common.rb, line 517
    def  keys
    end

length() click to toggle source

Returns the number of association in the database.

    # File common.rb, line 522
    def  length
    end

log_register(name) click to toggle source

The log_register function registers a file name.

    # File common.rb, line 532
    def  log_register(name)
    end

log_unregister() click to toggle source

The log_unregister function unregisters a file name.

    # File common.rb, line 538
    def  log_unregister()
    end

member?(key) click to toggle source

same than has_key?

    # File common.rb, line 478
    def  member?(key)
    end

open_sequence(key, flags = 0, init = nil, options = {}) { |sequence| ... } click to toggle source

create or open a sequence (see BDB::Sequence)

key : key for the sequence

flags : flags can have BDB::CREATE, BDB::EXCL, BDB::AUTO_COMMIT, BDB::THREAD

init : initial value for the sequence

options : hash with the possible keys “set_cachesize”, “set_flags” and “set_range”

return (or yield) an object BDB::Sequence

    # File common.rb, line 203
    def open_sequence(key, flags = 0, init = nil, options = {})
       yield sequence
    end

partial_clear() click to toggle source

same than #clear_partial

    # File common.rb, line 292
    def  partial_clear
    end

pget(key, flags = 0) click to toggle source

Returns the primary key and the value corresponding to key in the secondary index

only with >= 3.3.11

    # File common.rb, line 237
    def  pget(key, flags = 0)
    end

put(key, value, flags = 0) click to toggle source

Stores the value associating with key

If nil is given as the value, the association from the key will be removed. It return the object deleted or nil if the specified key don't exist.

flags can have the value DBD::NOOVERWRITE, in this case it will return nil if the specified key exist, otherwise true

    # File common.rb, line 257
    def  put(key, value, flags = 0)
    end

reject() { |key, value| ... } click to toggle source

Create an hash without the associations if the evaluation of the block returns true.

    # File common.rb, line 544
    def  reject
       yield key, value
    end

reject!(set = nil) { |key, value| ... } click to toggle source

same than #delete_if

    # File common.rb, line 385
    def  reject!(set = nil)
       yield key, value
    end

reverse_each(set = nil) { |key, value| ... } click to toggle source

Iterates over associations in reverse order

set

    # File common.rb, line 552
    def  reverse_each(set = nil)
       yield key, value
    end

reverse_each_by_prefix(prefix = nil) { |key, value| ... } click to toggle source

iterate over associations in reverse order, where the key begin with prefix

    # File common.rb, line 563
    def reverse_each_by_prefix(prefix = nil)
       yield key, value
    end

reverse_each_key(set = nil) { |key| ... } click to toggle source

Iterates over keys in reverse order

set

    # File common.rb, line 571
    def  reverse_each_key(set = nil)
       yield key
    end

reverse_each_pair(set = nil) { |key, value| ... } click to toggle source

same than #reverse_each

    # File common.rb, line 557
    def  reverse_each_pair(set = nil)
       yield key, value
    end

reverse_each_primary(set = nil) { |skey, pkey, pvalue| ... } click to toggle source

Iterates over secondary indexes in reverse order and give secondary key, primary key and value

    # File common.rb, line 578
    def  reverse_each_primary(set = nil)
       yield skey, pkey, pvalue
    end

reverse_each_value(set = nil) { |value| ... } click to toggle source

Iterates over values in reverse order.

set

    # File common.rb, line 586
    def  reverse_each_value(set = nil)
       yield value
    end

set_partial(len, offset) click to toggle source

Set the partial value len and offset

    # File common.rb, line 592
    def  set_partial(len, offset)
    end

size() click to toggle source

same than length

    # File common.rb, line 526
    def  size
    end

stat() click to toggle source

Return database statistics.

    # File common.rb, line 597
    def  stat
    end

store(key, value, flags = 0) click to toggle source

same than put

    # File common.rb, line 265
    def  store(key, value, flags = 0)
    end

subname() click to toggle source

same than database

    # File common.rb, line 361
    def  subname()
    end

to_a() click to toggle source

Return an array of all associations [key, value]

    # File common.rb, line 602
    def  to_a
    end

to_hash() click to toggle source

Return an hash of all associations {key => value}

    # File common.rb, line 607
    def  to_hash
    end

truncate() click to toggle source

Empty a database

    # File common.rb, line 612
    def  truncate
    end

value?(value) click to toggle source

same than has_value?

    # File common.rb, line 496
    def  value?(value)
    end

values() click to toggle source

Returns the array of the values in the database.

    # File common.rb, line 620
    def  values
    end

verify(file = nil, flags = 0) click to toggle source

Verify the integrity of the DB file, and optionnally output the key/data to file (file must respond to to_io)

    # File common.rb, line 626
    def  verify(file = nil, flags = 0)
    end