beezwax 0.5.2 → 0.6.0

data/VERSION

@@ -1 +1 @@
-0.5.2
+0.6.0

data/beezwax.gemspec

@@ -1,57 +1,46 @@
 # Generated by jeweler
 # DO NOT EDIT THIS FILE DIRECTLY
-# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
 # -*- encoding: utf-8 -*-
 
 Gem::Specification.new do |s|
   s.name = %q{beezwax}
-  s.version = "0.5.2"
+  s.version = "0.6.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Patrick Lardin"]
-  s.date = %q{2010-10-07}
+  s.date = %q{2010-12-19}
   s.description = %q{Access Btrieve database files through a ruby API.}
   s.email = %q{plardin@gmail.com}
   s.extra_rdoc_files = [
     "LICENSE",
-     "README",
-     "README.rdoc"
+    "README",
+    "README.rdoc"
   ]
   s.files = [
     "LICENSE",
-     "README",
-     "README.rdoc",
-     "Rakefile",
-     "VERSION",
-     "beezwax.gemspec",
-     "lib/beezwax.rb",
-     "lib/btrieve/btrieve_const.rb",
-     "lib/btrieve/btrieve_core.rb",
-     "lib/btrieve/btrieve_model.rb",
-     "lib/btrieve/btrieve_record.rb",
-     "lib/btrieve/btrieve_schema.rb",
-     "lib/btrieve/btrieve_session.rb",
-     "lib/btrieve/btrieve_table.rb",
-     "pkg/beezwax-0.0.0.gem",
-     "pkg/beezwax-0.1.0.gem",
-     "pkg/beezwax-0.1.1.gem",
-     "pkg/beezwax-0.1.2.gem",
-     "pkg/beezwax-0.1.3.gem",
-     "pkg/beezwax-0.1.4.gem",
-     "pkg/beezwax-0.2.0.gem",
-     "pkg/beezwax-0.3.0.gem",
-     "pkg/beezwax-0.4.0.gem",
-     "test/helper.rb",
-     "test/test_beezwax.rb"
+    "README",
+    "README.rdoc",
+    "Rakefile",
+    "VERSION",
+    "beezwax.gemspec",
+    "lib/beezwax.rb",
+    "lib/btrieve/btrieve_const.rb",
+    "lib/btrieve/btrieve_core.rb",
+    "lib/btrieve/btrieve_record.rb",
+    "lib/btrieve/btrieve_schema.rb",
+    "lib/btrieve/btrieve_session.rb",
+    "lib/btrieve/btrieve_table.rb",
+    "test/btrieve/test_beezwax.rb",
+    "test/helper.rb"
   ]
   s.homepage = %q{http://github.com/plardin/beezwax}
-  s.rdoc_options = ["--charset=UTF-8"]
   s.require_paths = ["lib"]
   s.rubygems_version = %q{1.3.7}
   s.summary = %q{Btrieve API wrapper.}
   s.test_files = [
-    "test/test_beezwax.rb",
-     "test/helper.rb"
+    "test/btrieve/test_beezwax.rb",
+    "test/helper.rb"
   ]
 
   if s.respond_to? :specification_version then

data/lib/beezwax.rb

@@ -1 +1,3 @@
-require_relative 'btrieve/btrieve_core.rb'
+require_relative 'btrieve/btrieve_core.rb'
+
+# Loads the btrieve API

data/lib/btrieve/btrieve_const.rb

@@ -1,5 +1,9 @@
+# Btrieve codes used to talk with the BTR engine.
 module BtrCodes
   OK = 0
+  KEY_NOT_FOUND = 4
+  EOF = 9
+  
   OPEN = 0
   CLOSE = 1
   INSERT = 2
@@ -7,14 +11,18 @@ module BtrCodes
   DELETE = 4
   GET_EQUAL = 5
   GET_NEXT = 6
+  GET_PREVIOUS = 7
   GET_GREATER_THAN_OR_EQUAL = 9
   GET_LESS_THAN_OR_EQUAL = 11
-  SET_DIRECTORY = 17
+  GET_FIRST=12
   BEGIN_TRANSACTION = 19
   END_TRANSACTION = 20
   ABORT_TRANSACTION = 21
   STEP_NEXT = 24
-  EOF = 9
+  STOP = 25
+  RESET = 28
+  GET_EQUAL_KEY = 55
+  GET_NEXT_KEY = 56
   POS_BLOCK_SIZE = 128
   NULL_KEY = 0x00
   NULL_BUFFER = ''
@@ -34,6 +42,7 @@ module BtrCodes
   NO_CURRENCY_CHANGE = 0xFF
   MAX_DATATYPE = 200
 
+  # Exception messages potentially returned by the BTR engine
   EXCEPTION_MESSAGES = {
     1=>"The operation parameter is invalid.",
     2=>"The application encountered an I/O error.",

data/lib/btrieve/btrieve_core.rb

@@ -1,10 +1,12 @@
 require 'ffi'
 require_relative 'btrieve_const'
 
+# Main interface with the BTR engine. 
 module Btrieve
   extend FFI::Library
   include BtrCodes
 
+  # Detects the ruby platform to point ot the proper shared lib. 
   if(RUBY_PLATFORM.match('mswin|mingw|cygwin'))
     ffi_lib 'w3btrv7.dll'
   elsif(RUBY_PLATFORM.match('linux'))
@@ -13,42 +15,29 @@ module Btrieve
     raise Exception.new("Unknown RUBY_PLATFORM #{RUBY_PLATFORM} to perform FFI calls into PSQL.")
   end
 
+  # FFI declaration for the BTRCALLID method of the BTR engine.
   attach_function :BTRCALLID, [:int, :pointer, :pointer, :pointer, :pointer, :uchar, :uchar, :pointer], :int
   
-  def btr_op(session, ops, pos_buffer, data_buffer, key_buffer, key_number, valid_return_codes=[0])
-      data_length = [data_buffer.size].pack('L')
-      key_length = key_buffer.size
-      result_code = BTRCALLID(ops, pos_buffer, data_buffer, data_length, key_buffer, key_length, key_number, session.client_id)
-      unless valid_return_codes.include?(result_code)
-        p "ops=#{ops} data_buffer.length=#{data_buffer.length} key_buffer=#{key_buffer}, key_buffer.length=#{key_buffer.length}, key_number=#{key_number}, session.client_id=#{session.client_id}"
-        raise Exception.new("PSQL Exception Code #{result_code} - #{EXCEPTION_MESSAGES[result_code]}")
-      end
+  # Single entry point into the BTR engine. 
+  def btr_op(ops, pos_buffer, data_buffer, key_buffer, key_number, valid_return_codes=[BtrCodes::OK])
+    session=BtrieveSession.get_session
+    data_length = [data_buffer.size].pack('L')
+    key_length = key_buffer.size
+    result_code = BTRCALLID(ops, pos_buffer, data_buffer, data_length, key_buffer, key_length, key_number, session.client_id)
+    unless valid_return_codes.include?(result_code)
+      raise "PSQL Exception Code #{result_code} - #{EXCEPTION_MESSAGES[result_code]}"
+    end
     result_code
   end
 
+  # Utility method to create a buffer of a given size.
   def self.create_string_buffer(size)
     0.chr*(size)
-  end  
-  
-end
-
-module Timer
-  def timer(&block)
-    start_time = Time.now
-    yield
-    end_time = Time.now
-    end_time - start_time
-  end
-
-  def timer2(out=nil, &block)
-    start_time = Time.now
-    out = yield out
-    [Time.now - start_time, out]
-  end
+  end    
 end
 
+# Loads the rest of the BTR implementation.
 require_relative 'btrieve_session'
 require_relative 'btrieve_table'
 require_relative 'btrieve_schema'
 require_relative 'btrieve_record'
-require_relative 'btrieve_model'

data/lib/btrieve/btrieve_record.rb

@@ -1,174 +1,85 @@
 require 'digest/md5'
 
+# Represents a single btrieve record for a particular BTR table.
 class BtrieveRecord
   include Btrieve
   attr_reader :data_buffer, :btrieve_table
 
-  def initialize(btrieve_table, data_buffer = nil )
+  # Initializes a btrieve record.  
+  def initialize(btrieve_table, data_buffer=nil)
     @btrieve_table = btrieve_table
     @data_buffer = data_buffer.nil? ? Btrieve.create_string_buffer(@btrieve_table.schema[:record_size]) : data_buffer
-    @session = @btrieve_table.session
   end
 
+  # Inserts a new btrieve record through the transactional BTR engine.
   def insert
-    btr_op(@session, INSERT, @btrieve_table.pos_buffer, @data_buffer, NULL_BUFFER, NO_CURRENCY_CHANGE)
+    btr_op(@btrieve_table.session, INSERT, @btrieve_table.pos_buffer, @data_buffer, NULL_BUFFER, NO_CURRENCY_CHANGE)
   end
 
+  # Updates an existing btrieve record through the transactional BTR engine.
   def update
-    btr_op(@session, UPDATE, @btrieve_table.pos_buffer, @data_buffer, NULL_BUFFER, NO_CURRENCY_CHANGE)
-  end
-
-  def delete
-    btr_op(@session, DELETE, @btrieve_table.pos_buffer, NULL_BUFFER, NULL_BUFFER, NULL_KEY)
-  end
-  
-  def get_relation_bindings(key)
-    table_map=@session.relations[@btrieve_table.tablename]
-    raise Exception.new("No relations defined for table #{@btrieve_table.tablename}") if table_map.nil?
-    relation=table_map[key]
-    raise Exception.new("No relation found named #{key.to_s} in table #{@btrieve_table.tablename}") if relation.nil?
-    bindings=relation[:join].inject({}) do |map,join|
-      value=join[1][:match]
-      map[join[0]]=join[1][:source]==:table ? self[value] : value
-      map
-    end
-    {:table=>relation[:target],:index=>relation[:index],:bindings=>bindings}
-  end
-  
-  def get_relations_bindings(keys)
-    keys.inject({}){|map,key|map[key]=self.get_relation_bindings(key);map}
-  end
-  
-  def get_all_relations_bindings()
-    relations=@session.relations[@btrieve_table.tablename]||={}
-    get_relations_bindings(relations.keys)
-  end
-  
-  def get_relation(key)
-    match=get_relation_bindings(key)
-    target_table=BtrieveTable.new(relation[:target], @session)
-    index_number=relation[:index]
-    target_table.find(match,index_number)
-  end
-  
-  def get_relations(keys)
-    keys.inject({}){|map,key|map[key]=self.get_relation(key);map}
-  end
-  
-  def get_all_relations()
-    relations=@session.relations[@btrieve_table.tablename]||={}
-    get_relations(relations.keys)
+    btr_op(@btrieve_table.session, UPDATE, @btrieve_table.pos_buffer, @data_buffer, NULL_BUFFER, NO_CURRENCY_CHANGE)
   end
   
-  def get_mapping(key)
-    table_map=@session.mappings[@btrieve_table.tablename]
-    raise Exception.new("No mappings defined for table #{@btrieve_table.tablename}") if table_map.nil?
-    mapping=table_map[key]
-    raise Exception.new("No mapping found named #{key.to_s} in table #{@btrieve_table.tablename}") if mapping.nil?
-    @session.mapping_functions[mapping[:transform]].call(self[mapping[:column]])
-  end
-  
-  def get_mappings(keys)
-    keys.inject({}){|map,key|map[key]=self.get_mapping(key);map}
-  end
-  
-  def get_all_mappings()
-    mappings=@session.mappings[@btrieve_table.tablename]||={}
-    get_mappings(mappings.keys)
-  end
-
-  def get_attributes(keys)
-    keys.inject({}){|vals, key| vals[key]=self[key]; vals}
+  # Deletes an existing btrieve record through the transactional BTR engine.
+  def delete
+    btr_op(@btrieve_table.session, DELETE, @btrieve_table.pos_buffer, NULL_BUFFER, NULL_BUFFER, NULL_KEY)
   end
 
-  def get_all_attributes()
-    cols=@btrieve_table.schema[:columns].keys.sort
-    get_attributes(cols)
+  # Returns hash of column-value pairs for this btrieve record, given an array of named columns. 
+  # If the array is nil, the hash will contain ALL the column-value pairs defined by the schema. 
+  def values(column_names=nil)
+    if(column_names.nil?)
+      column_names=@btrieve_table.schema[:columns].keys.sort.inject([]){|array,column|array<< column;array}
+    end 
+    column_names.inject({}){|vals, key| vals[key]=self[key]; vals}
   end
 
+  # Returns this record's primary key value. Supports composite keys.
   def primary_key()
-    get_composite_key(@btrieve_table.primary_key)
-  end
-
-  def foreign_key(prefix)
-    keys=@btrieve_table.primary_key.map{|key|:"#{prefix} #{key.to_s}"}
-    get_composite_key(keys)
-  end
-
-  def get_unique_reference(association_name)
-    dereference(:one_to_one, association_name) do |map, target, index|
-      fk_columns = map.keys.inject([]){|vals, column| vals << column; vals}
-      fk_values = get_attributes(fk_columns)
-      pk_values = map.keys.inject({}){|vals, column| vals[map[column]] = fk_values[column]; vals}
-      target.find_in_unique_index(pk_values, index)
-    end
-  end
-
-  def get_multiple_references(association_name)
-    dereference(:one_to_many, association_name) do |map, target, index|
-      pk_columns = map.keys.inject([]){|vals, column| vals << map[column] unless map[column] == nil; vals}
-      pk_values = get_attributes(pk_columns)
-      fk_values = map.keys.inject({}){|vals, column| vals[column] = pk_values[map[column]]; vals}
-      target.find_in_index(fk_values, index)
-    end
+    values(@btrieve_table.primary_key)
   end
-
+  
+  # Returns this record's value of the column passed in. 
   def [](key_name)
-    schema_key=get_schema_key(key_name)
-    return nil if(schema_key.nil?)
-    @data_buffer.unpack(schema_key[:unpacker])[0]
+    column_info = get_column_info(key_name)
+    return nil if(column_info.nil?)
+    @data_buffer.unpack(column_info[:unpacker])[0]
   end
   
+  # Sets this record's value for a particular column.
   def []=(key_name, value)
     schema_key = get_schema_key(key_name)
     packer_string = schema_key[:unpacker]
     match = packer_string.match(/@(\d+)([a-zA-Z]+)(\d*)/)
     offset = match[1].to_i
     datatype = match[2]
-    sizeof = BtrieveSchema.sizeof(datatype)
-    sizeof *= match[3].empty? ? 1 : match[3].to_i
-    packer = "#{datatype}#{sizeof}"
+    thesizeof = BtrieveSchema.sizeof(datatype)
+    thesizeof *= match[3].empty? ? 1 : match[3].to_i
+    packer = "#{datatype}#{thesizeof}"
     array = [value]
     packed_value = array.pack(packer)
     range = (offset..offset+packed_value.size-1)
     @data_buffer[range] = packed_value
   end
-
+  
+  def nil?()
+    data_buffer.gsub("\x00", "").size==0
+  end
+  
+  # Returns a string representation of this record.
   def to_s()
-    @btrieve_table.schema[:columns].keys.inject('') { |pretty_print, key| pretty_print = "#{pretty_print} #{key}=>#{self[key]}"; pretty_print }
+    @btrieve_table.schema[:columns].keys.inject(''){|pretty_print, key| pretty_print = "#{pretty_print} #{key}=>#{self[key]}"; pretty_print}
   end
 
+  # Returns this record's version as a MD5 Digest value. 
   def version()
     Digest::MD5.hexdigest(@data_buffer)
   end
 
-  def method_missing(symbol)
-    return get_unique_reference(symbol) if(@btrieve_table.schema[:one_to_one][symbol])
-    return get_multiple_references(symbol) if(@btrieve_table.schema[:one_to_many][symbol])
-    super(symbol)
-  end
-
   private
 
-  def dereference(association_group, association_name, &block)
-    association = @btrieve_table.schema[association_group][association_name]
-    raise Exception.new("Unknown association '#{association_name}' for table '#{@btrieve_table.tablename}'.") unless association != nil
-    map = association[:map]
-    target = eval(association[:class].to_s)
-    index = association[:index]
-    yield(map, target, index)
-  end
-
-  def get_schema_key(key_name)
-    schema_key = @btrieve_table.schema[:columns][key_name]
-    # raising this exception is hurting the dbr process since I use keys that dont exist
-    # raise Exception.new("Unknown column '#{key_name}' for table '#{@btrieve_table.tablename}'.") unless schema_key != nil
-    schema_key
-  end
-
-  def get_composite_key(keys)
-    pk=keys.inject([]){|arr,col|arr<<self[col];arr}
-    pk[2]=pk[2].strip
-    pk.join('.')
+  def get_column_info(column_name)
+    @btrieve_table.schema[:columns][column_name]
   end
 end

data/lib/btrieve/btrieve_schema.rb

@@ -1,28 +1,52 @@
+# Represents the btrieve schema (DDF files) of a particular BTR database.
 class BtrieveSchema
   include Btrieve
-  attr_reader :session, :xfile_records, :xfield_records
-
-  def initialize(session)
-    @session = session
-    if(!@session.cache[:schemas_loaded])
+  attr_reader :xfile_records, :xfield_records
+  
+  # Datatypes used to transact with the BTR engine.
+  CHAR = { :name=>'CHAR', :unpacker=>'a', :size=>1 }
+  TINYINT = { :name=>'TINYINT', :unpacker=>'c', :size=>1 }
+  SMALLINT = { :name=>'SMALLINT', :unpacker=>'s', :size=>1 }
+  INTEGER = { :name=>'INTEGER', :unpacker=>'i', :size=>1 }
+  REAL = { :name=>'REAL', :unpacker=>'f', :size=>1 }
+  DOUBLE = { :name=>'DOUBLE', :unpacker=>'d', :size=>1 }
+  DATE = { :name=>'DATE', :unpacker=>'ccs', :size=>4 } #day month year
+  TIME = { :name=>'TIME', :unpacker=>'cccc', :size=>4 } #100th sec min hour
+  BIT = { :name=>'BIT', :unpacker=>'c', :size=>1 }
+  VARCHAR = { :name=>'VARCHAR', :unpacker=>'A', :size=>1 }
+  LONGVARCHAR = { :name=>'LONGVARCHAR', :unpacker=>'A', :size=>1 }
+  UTINYINT = { :name=>'UTINYINT', :unpacker=>'C', :size=>1, :size=>1 }
+  USMALLINT = { :name=>'USMALLINT', :unpacker=>'S', :size=>1 }
+  UINTEGER = { :name=>'UINTEGER', :unpacker=>'I', :size=>1 }
+  UBIGINT = { :name=>'UBIGINT', :unpacker=>'Q', :size=>1 }
+  
+  # Array of all datatypes supported by the BTR engine.
+  SIZEOF = {'a'=>1, 'c'=>1, 's'=>1, 'i'=>1, 'f'=>1, 'd'=>1, 'ccs'=>4, 'cccc'=>4, 'A'=>1, 'C'=>1, 'S'=>1, 'I'=>1, 'Q'=>1}
+  
+  # Creates a new instance of btrieve schema for a given session.
+  def initialize()
+    session=BtrieveSession.get_session
+    if(!session.cache[:schemas_loaded])
       cache_system_table(:'x$file')
       cache_system_table(:'x$field')
       cache_system_table(:'x$index')
-      @session.cache[:schemas_loaded] = true
+      session.cache[:schemas_loaded] = true
     end
   end
 
-  def load_schema(tablename)
+  # Loads the schema of a particular btrieve table.
+  def get_table_schema(tablename)
+    session=BtrieveSession.get_session
     schema = nil
     xfile_index = nil
-    @session.cache[:'x$file'].each do |xfile|
+    session.cache[:'x$file'].each do |xfile|
       next unless xfile[:'xf$name'].downcase.strip.to_sym == tablename
       schema = {:filename=>xfile[:'xf$loc'].downcase.strip, :record_size=>0, :columns=>{}}
       xfile_index = xfile[:'xf$id']
       break
     end
     xfield_index = []
-    @session.cache[:'x$field'].each do |xfield|
+    session.cache[:'x$field'].each do |xfield|
       next unless xfile_index == xfield[:'xe$file']
       next unless xfield[:'xe$datatype'] < MAX_DATATYPE
       id = xfield[:'xe$id']
@@ -33,10 +57,9 @@ class BtrieveSchema
       datatype = (name == 'kid - mult') ? 14 : datatype # Absolute BS line of code...  Needed for CTA-FOS
       unpacker = BtrieveSchema.unpacker(offset, datatype, size)
       schema[:columns][name.to_sym] = {:unpacker=>unpacker, :id=>id, :offset=>offset, :datatype=>datatype, :size=>size}
-      schema[:record_size] += size
       xfield_index[id] = name.to_sym
     end
-    @session.cache[:'x$index'].each do |xindex|
+    session.cache[:'x$index'].each do |xindex|
       next unless xfile_index == xindex[:'xi$file']
       indices = schema[:indices] ||= []
       index = indices[xindex[:'xi$number']] ||= []
@@ -44,16 +67,12 @@ class BtrieveSchema
       flags = schema[:index_flags] ||= []
       flags[xindex[:'xi$number']] = flags[xindex[:'xi$number']].to_i | xindex[:'xi$flags'].to_i
     end
+    last_field=schema[:columns].values.sort{|a,b| a[:offset] <=> b[:offset]}.last
+    schema[:record_size] = last_field[:offset]+last_field[:size]
     raise Exception.new("Unknown table '#{tablename}'.") if schema.nil?
-    schema[:one_to_one] = {}
-    schema[:one_to_many] = {}
     schema
   end
 
-  def self.sizeof(code)
-    SIZEOF[code]
-  end
-
   private
 
   SYS_DDF = {
@@ -61,25 +80,7 @@ class BtrieveSchema
     :'x$field'=>{:filename=>'field.ddf', :record_size=>32, :columns=>{:'xe$id'=>{:unpacker=>'@0S'}, :'xe$file'=>{:unpacker=>'@2S'}, :'xe$name'=>{:unpacker=>'@4a20'}, :'xe$datatype'=>{:unpacker=>'@24C'}, :'xe$offset'=>{:unpacker=>'@25S'}, :'xe$size'=>{:unpacker=>'@27S'}, :'xe$dec'=>{:unpacker=>'@29C'}, :'xe$flags'=>{:unpacker=>'@30S'}}},
     :'x$index'=>{:filename=>'index.ddf', :record_size=>32, :columns=>{:'xi$file'=>{:unpacker=>'@0S'},:'xi$field'=>{:unpacker=>'@2S'},:'xi$number'=>{:unpacker=>'@4S'},:'xi$part'=>{:unpacker=>'@6S'},:'xi$flags'=>{:unpacker=>'@8S'}}}
   }
-
-  CHAR = { :name=>'CHAR', :unpacker=>'a' }
-  TINYINT = { :name=>'TINYINT', :unpacker=>'c' }
-  SMALLINT = { :name=>'SMALLINT', :unpacker=>'s' }
-  INTEGER = { :name=>'INTEGER', :unpacker=>'i' }
-  REAL = { :name=>'REAL', :unpacker=>'f' }
-  DOUBLE = { :name=>'DOUBLE', :unpacker=>'d' }
-  DATE = { :name=>'DATE', :unpacker=>'ccs' } #day month year
-  TIME = { :name=>'TIME', :unpacker=>'cccc' } #100th sec min hour
-  BIT = { :name=>'BIT', :unpacker=>'c' }
-  VARCHAR = { :name=>'VARCHAR', :unpacker=>'A' }
-  LONGVARCHAR = { :name=>'LONGVARCHAR', :unpacker=>'A' }
-  UTINYINT = { :name=>'UTINYINT', :unpacker=>'C' }
-  USMALLINT = { :name=>'USMALLINT', :unpacker=>'S' }
-  UINTEGER = { :name=>'UINTEGER', :unpacker=>'I' }
-  UBIGINT = { :name=>'UBIGINT', :unpacker=>'Q' }
-
-  SIZEOF = {'a'=>1, 'c'=>1, 's'=>1, 'i'=>1, 'f'=>1, 'd'=>1, 'ccs'=>4, 'cccc'=>4, 'A'=>1, 'C'=>1, 'S'=>1, 'I'=>1, 'Q'=>1}
-
+  
   def self.unpacker(offset, datatype, size)
     offsetter = "@#{offset}"
     btrtype = lookup(datatype, size)
@@ -115,9 +116,10 @@ class BtrieveSchema
   end
 
   def cache_system_table(tablename)
-    @session.cache[tablename] = []
-    schema_table = BtrieveTable.new(SYS_DDF[tablename][:filename], @session, SYS_DDF[tablename])
-    schema_table.each_record(ACCELERATED_MODE) {|value| @session.cache[tablename] << value}
+    session=BtrieveSession.get_session
+    session.cache[tablename] = []
+    schema_table = BtrieveTable.new(SYS_DDF[tablename][:filename], SYS_DDF[tablename])
+    schema_table.each_record(ACCELERATED_MODE) {|value| session.cache[tablename] << value}
   end
 end
 

data/lib/btrieve/btrieve_session.rb

@@ -1,48 +1,57 @@
+# Concept of a BTR session.  Beware, this implementation is NOT thread safe!
 class BtrieveSession
-  SESSIONS = {}
   include Btrieve
-  attr_reader :pathname, :client_id, :cache, :model_classes, :btrieve_schema
-  attr_accessor :mappings, :mapping_functions, :relations
-
-  def self.set_context(pathname)
-    session = get_session
-    if session
-      raise Exception.new("The existing context in the current is set to a different pathname.")  if(session.pathname != pathname)
-    else
-      SESSIONS[Thread.current] = new(pathname)
-    end
+  attr_reader :client_id, :cache, :btrieve_schema
+  attr_accessor :host, :data_share
+  private_class_method :new
+  @@instance=nil
+  
+  # Factory of BTR sessions. A block can be passed into it, or alternatively the factory returns 
+  # the session instance to the caller, who then must call 'dispose' on it when done with it.
+  # The 'host' argument can be a named server or its IP address.
+  # The 'data_share' argument is typically the share name of the data folder. 
+  # The 'data_share' argument can also be the database name when "IDS" is used on the client. 
+  def BtrieveSession.create_session(host, data_share)
+    raise "Cannot create more than one instance of session." if(@@instance != nil)
+    @@instance = new(host, data_share)
+    @@instance.set_schema(BtrieveSchema.new())
   end
 
-  def self.get_session
-    SESSIONS[Thread.current]
+  # Returns the session instance created.  
+  def BtrieveSession.get_session()
+    @@instance
+  end
+  
+  # Disposes of the session object, releasing any and all resources consumed/locked on the server. 
+  def BtrieveSession.destroy_session()
+    @@instance.btr_op(RESET, NULL_BUFFER, NULL_BUFFER, NULL_BUFFER, NULL_KEY)
+    @@instance=nil
   end
 
-  def transaction(&block)
-    btr_op(self, BEGIN_TRANSACTION, NULL_BUFFER, NULL_BUFFER, NULL_BUFFER, NULL_KEY)
+  # Executes a block of BTR directive in a transaction. 
+  def BtrieveSession.transaction(&block)
     begin
+      @@instance.btr_op(BEGIN_TRANSACTION, NULL_BUFFER, NULL_BUFFER, NULL_BUFFER, NULL_KEY)
       yield
     rescue Exception => exception
-      btr_op(self, ABORT_TRANSACTION, NULL_BUFFER, NULL_BUFFER, NULL_BUFFER, NULL_KEY)
-      raise Exception.new("PSQL TX ABORTED!!! - #{exception.message}\n#{exception.backtrace.join("\n\t")}")
+      # Oops! We must roll back the whole shebang!
+      @@instance.btr_op(ABORT_TRANSACTION, NULL_BUFFER, NULL_BUFFER, NULL_BUFFER, NULL_KEY)
+      raise "PSQL TX ABORTED!!! - #{exception.message}\n#{exception.backtrace.join("\n\t")}"
+    ensure
+      @@instance.btr_op(END_TRANSACTION, NULL_BUFFER, NULL_BUFFER, NULL_BUFFER, NULL_KEY)
     end
-    btr_op(self, END_TRANSACTION, NULL_BUFFER, NULL_BUFFER, NULL_BUFFER, NULL_KEY)
   end
-
-  def get_table(tablename)
-    table=@table_cache[tablename]||=BtrieveTable.new(tablename.to_sym, self)
-    [table,table.version]
+  
+  def set_schema(schema)
+    @btrieve_schema=schema
   end
-
-  private
-
-  def initialize(pathname)
-    @cache = {}
-    @model_classes = {}
-    @table_cache = {}
-    @pathname = pathname
+  
+  private 
+  
+  def initialize(host, data_share)
+    @host = host
+    @data_share = data_share
     @client_id = "#{0.chr*12}#{[0x5257].pack('S')}#{rand(65535)}"
-    btr_op(self, SET_DIRECTORY, NULL_BUFFER, NULL_BUFFER, @pathname, NULL_KEY)
-    @btrieve_schema = BtrieveSchema.new(self)
+    @cache = {}
   end
 end
-

data/lib/btrieve/btrieve_table.rb

@@ -1,78 +1,52 @@
 require 'digest/md5'
 
+# Represents a single btrieve table for a particular BTR database.
 class BtrieveTable
   include Btrieve
-  attr_reader :tablename, :session, :pos_buffer, :schema 
+  attr_reader :tablename, :pos_buffer, :schema
   attr_accessor :primary_key
 
-  def initialize(tablename, session, schema=nil)
+  # Initializes a btrieve table.
+  def initialize(tablename, schema=nil)
     @tablename = tablename
-    @session = session
     @pos_buffer = Btrieve.create_string_buffer(POS_BLOCK_SIZE)
-    @schema = schema ? schema : @session.btrieve_schema.load_schema(@tablename)
-  end
-
-  def open(mode = NORMAL_MODE)
-    btr_op(@session, OPEN, @pos_buffer, NULL_BUFFER, @schema[:filename], mode)
-  end
-  
-  def mappings()
-    @session.mappings[@tablename] ||= {} 
-  end
-  
-  def add_mapping(attr_name, mapping_name, transform)
-    mappings[mapping_name.to_sym]={:column=>attr_name.to_sym,:transform=>transform.to_sym}
-  end
-  
-  def relations()
-    @session.relations[@tablename] ||= {}
-  end
-  
-  def add_relation(name, target_table, index, join)
-    relations[name.to_sym]={:target=>target_table.to_sym,:index=>index,:join=>join}
+    @schema = schema ? schema : session.btrieve_schema.get_table_schema(@tablename)
+  end
+
+  # Opens this btrieve table in preparation for some BTR operation(s).
+  # If a block is passed to the call, the table is closed automatically.
+  # If a block is NOT passed to the call, the client code has to make sure to close the file.
+  def open(mode=NORMAL_MODE, &block)
+    file_unc="//#{session.host}/#{session.data_share}/#{@schema[:filename]}"
+    btr_op(OPEN, @pos_buffer, NULL_BUFFER, file_unc, mode)
+    if block_given?
+      yield
+      close()
+    end
   end
   
-  def find(match, index_number)
-    unique=schema[:index_flags].map{|f|f&1==1}[index_number]
-    result=nil 
-    if(unique)
-      result=find_in_unique_index(match, index_numer) 
+  # Finds an array of records in this table, using the specified index number and match hash.
+  # If a block is passed in, the entries of this set are passed into this block one by one. Otherwise,
+  # the set is returned to the caller. 
+  def find(match, index_number, &block)
+    allows_duplicates=schema[:index_flags].map{|f|f&1==1;}[index_number]
+    set=nil 
+    if(allows_duplicates)
+      set=find_in_index(match, index_number)
     else
-      result=find_in_index(match, index_numer)
-    end
-    result
-  end
-
-  def find_in_unique_index(match, index_number=nil)
-    finder(match, index_number) do |key_buffer, index|
-      btr_record = BtrieveRecord.new(self)
-      batch(){ btr_op(@session, GET_EQUAL, @pos_buffer, btr_record.data_buffer, key_buffer, index) }
-      btr_record
+      rec=find_in_unique_index(match, index_number)
+      set=rec.nil? ? [] : [rec]
     end
-  end
-
-  def find_in_index(match, index_number=nil)
-    finder(match, index_number) do |key_buffer, index|
-      absolute_match = match.keys.inject({}){|vals, key| vals[key] = match[key] if(match[key] != nil); vals}
-      absolute_match_keys = absolute_match.keys
-      result = []
-      batch() do
-        btr_record = BtrieveRecord.new(self)
-        ops_result = btr_op(@session, GET_GREATER_THAN_OR_EQUAL, @pos_buffer, btr_record.data_buffer, key_buffer, index, [OK, EOF])
-        if OK==ops_result
-          result << btr_record
-          while(true)
-            btr_record = BtrieveRecord.new(self)
-            op_result = btr_op(@session, GET_NEXT, @pos_buffer, btr_record.data_buffer, key_buffer, index_number, [OK, EOF, 21])
-            break unless btr_record.get_attributes(absolute_match_keys)==absolute_match and op_result!=EOF and op_result!=21
-            result << btr_record
-          end
-        end
-      end
-      result
+    if(block_given?)
+      set.each{|record| yield record}
+    else
+      set
     end
   end
 
+  # Finds an array of records in this table, using the specified index number, a key and a range of values.
+  # If a block is passed in, the entries of this set are passed into this block one by one. Otherwise,
+  # the set is returned to the caller. 
   def find_in_range(index_num, key, range, &block)
     index = @schema[:indices][index_num]
     columns = @schema[:columns]
@@ -84,23 +58,32 @@ class BtrieveTable
       packer
     end
     key_buffer = index_values.pack(key_packer)
-
     btr_record = BtrieveRecord.new(self)
+    records = []
     batch do
-      btr_op(@session, GET_GREATER_THAN_OR_EQUAL, @pos_buffer, btr_record.data_buffer, key_buffer, index_num, [OK, EOF])
-      while(range.include?(btr_record[key])) 
-	yield btr_record
+      btr_op(GET_GREATER_THAN_OR_EQUAL, @pos_buffer, btr_record.data_buffer, key_buffer, index_num, [OK, EOF])
+      while(range.include?(btr_record[key]))
+        if(!block.nil?) 
+	        yield btr_record
+	      else
+	        records << btr_record
+	      end
         btr_record = BtrieveRecord.new(self)
-        btr_op(@session, GET_NEXT, @pos_buffer, btr_record.data_buffer, key_buffer, index_num, [OK, EOF])
+        btr_op(GET_NEXT, @pos_buffer, btr_record.data_buffer, key_buffer, index_num, [OK, EOF])
       end
     end
+    if(block.nil?) 
+	    records
+	  end
   end
 
+  # Closes this btrieve table to conclude a sequence of BTR operation(s). 
   def close
-    btr_op(@session, CLOSE, @pos_buffer, NULL_BUFFER, NULL_BUFFER, NULL_KEY)
+    btr_op(CLOSE, @pos_buffer, NULL_BUFFER, NULL_BUFFER, NULL_KEY)
   end
 
-  def each_record(mode = READ_ONLY_MODE, &block)
+  # Loops over the records of this BTR table and passes each record to the block passed in.
+  def each_record(mode=NORMAL_MODE, &block)
     batch(mode) do
       while(record = step_next) do
         yield record
@@ -108,34 +91,24 @@ class BtrieveTable
     end
   end
 
-  def batch(mode = READ_ONLY_MODE, &block)
+  # Wraps a sequence of BTR operations between a pair of open and close statements for this table.
+  # DEPRECATED - Use the "open" method instead and pass a block to it.
+  def batch(mode=NORMAL_MODE, &block)
     open(mode)
     yield
     close
   end
 
+  # Returns this table's version as a MD5 Digest value. 
   def version()
     Digest::MD5.hexdigest(BtrieveSchema.sort(schema[:columns]).inject([]){|array,column|array << BtrieveSchema.readable_type(column);array}.to_s)
   end
-
-  #def self.primary_key_match(pk)
-  #  vals=pk.split('.')
-  #  {PK_KEYS[0]=>vals[0].to_i,PK_KEYS[1]=>vals[1].to_i,PK_KEYS[2]=>vals[2],PK_KEYS[3]=>vals[3].to_i,PK_KEYS[4]=>vals[4].to_i}
-  #end
-
-  #def self.tablename_to_url(tablename)
-  #  tablename.gsub(' & ','.and.').gsub('a/c ', 'ac.').gsub('es - o','es.o').gsub(' ','.')
-  #end
-
-  #def self.url_to_tablename(url_tablename)
-  #  url_tablename.gsub('.and.', ' & ').gsub('ac.', 'a/c ').gsub('es.o','es - o').gsub('.',' ')
-  #end
   
   private
 
   def step_next
     btr_record = BtrieveRecord.new(self)
-    result = btr_op(@session, STEP_NEXT, @pos_buffer, btr_record.data_buffer, NULL_BUFFER, NULL_KEY, [OK, EOF])
+    result = btr_op(STEP_NEXT, @pos_buffer, btr_record.data_buffer, NULL_BUFFER, NULL_KEY, [OK, EOF])
     return false if(result == EOF)
     btr_record
   end
@@ -158,6 +131,7 @@ class BtrieveTable
       value = match[key]
       value = value.to_f if FLOAT_TYPES.include?(datatype)
       value = value.to_i if INTEGER_TYPES.include?(datatype)
+      value = value.ljust(columns[key][:size], ' ') if datatype=='CHAR' 
       vals << value
       vals
     end
@@ -173,5 +147,41 @@ class BtrieveTable
     key_buffer = key_components.pack(key_packer)
     yield(key_buffer, index_number)
   end
+
+  def find_in_unique_index(match, index_number=nil)
+    finder(match, index_number) do |key_buffer, index|
+      btr_record = BtrieveRecord.new(self)
+      batch(){ btr_op(GET_EQUAL, @pos_buffer, btr_record.data_buffer, key_buffer, index, [KEY_NOT_FOUND, OK, EOF]) }
+      btr_record.nil? ? nil : btr_record
+    end
+  end
+
+  def find_in_index(match, index_number=nil)
+    finder(match, index_number) do |org_key_buffer, index|
+      absolute_match = match.keys.inject({}){|vals, key| vals[key] = match[key] if(match[key] != nil); vals}
+      absolute_match_keys = absolute_match.keys
+      result = []    
+      batch do
+        key_buffer="#{org_key_buffer}"
+        ops_result = btr_op(GET_EQUAL_KEY, @pos_buffer, NULL_BUFFER, key_buffer, index, [OK, EOF, KEY_NOT_FOUND])
+        ops=GET_EQUAL
+        while(ops_result == OK) 
+          btr_record = BtrieveRecord.new(self)
+          ops_result = btr_op(ops, @pos_buffer, btr_record.data_buffer, key_buffer, index, [OK, EOF])
+          break if(key_buffer!=org_key_buffer)
+          ops=GET_NEXT
+          result << btr_record if(ops_result == OK)
+        end
+      end
+      result
+    end
+  end  
+  
+  def session
+    s=BtrieveSession.get_session
+    raise "Cannot manipulate a BtrieveTable when no BtrieveSession exists." if s.nil?
+    s
+  end
+    
 end
 

data/test/btrieve/test_beezwax.rb

@@ -0,0 +1,133 @@
+require 'helper'
+
+class TestBeezwax < Test::Unit::TestCase
+  context "when a BtrieveSession is initialized" do
+    setup do
+      BtrieveSession.create_session(DB_SERVER,"Demodata")
+    end
+    
+    teardown do
+      BtrieveSession.destroy_session
+    end
+    
+    should "not allow the creation of another session" do
+      assert_raise(RuntimeError){BtrieveSession.create_session(DB_SERVER,"Demodata")}
+    end
+ 
+    should "return a handle to the session singleton" do
+      session=BtrieveSession.get_session
+      assert_not_nil session 
+    end
+    
+    should "permit the instanciation of a DB table" do
+      table=BtrieveTable.new(:course)
+      assert_not_nil table
+    end
+    
+    should "allow an empty transaction to go through" do
+      BtrieveSession.transaction{}
+    end
+    
+    context "and an instance of BtrieveTable is created, it" do
+      setup do
+        @table=BtrieveTable.new(:course)
+      end
+      
+      teardown do
+        @table=nil
+      end
+    
+      should "be possible to open it for operations, then close it" do
+        assert_nothing_raised(RuntimeError){@table.open}
+        assert_nothing_raised(RuntimeError){@table.close}
+      end
+      
+      should "be possible to have the file automatically closed when a block is passed when opening a table" do
+        @table.open{}
+        assert_raise(RuntimeError){@table.close}
+      end
+      
+      should "return a version number for that table" do
+        table_version=@table.version
+        assert_not_nil table_version
+        assert_equal 32, table_version.size
+      end  
+      
+      should "allow looping over each of its records to count them" do
+        counter = 0
+        assert_nothing_raised{@table.each_record{|record|counter+=1}}
+        assert_equal 145, counter
+      end
+      
+      should "be possible to search the table for a given index" do
+        assert_nothing_raised {@table.find({:name=>'blah'}, 0)}
+      end
+      
+      should "be possible to find a particular record in a unique index" do
+        name = 'PHI 101'
+        record=@table.find({:name=>name}, 0).first
+        assert_not_nil record
+        assert_equal record[:name], name
+      end
+      
+      should "be possible to fetch a particular record and all its columns should be properly set" do
+        name = 'PHI 101'
+        record=@table.find({:name=>name}, 0).first
+        expected_values={:name=>name, :description=>'Introduction to Ethics', :credit_hours=>3, :dept_name=>'Philosophy'}
+        assert_equal expected_values, record.values
+      end
+      
+      should "be possible to search for a unique key that doesn't exist and not cause an exception" do
+        name = 'FRA 333'
+        records=@table.find({:name=>name}, 0)
+        assert_not_nil records
+        assert records.empty?, "records is NOT empty"
+      end
+
+      should "be possible to find several records in an index that supports duplicates" do
+        dept_name = 'Mathematics'
+        records=@table.find({:dept_name=>dept_name}, 1)
+        assert_not_nil records
+        assert !records.empty?, "records is empty"
+        assert_equal 9, records.size
+        assert records.inject(true){|test, record| test |= record[:dept_name]==dept_name; test}
+      end
+      
+      should "support finding records and looping over them if a block is passed in" do
+        dept_name = 'Mathematics'
+        counter = 0 
+        @table.find({:dept_name=>dept_name}, 1) do
+          counter += 1
+        end
+        assert_equal 9, counter
+      end
+      
+      should "be possible to search for a key that doesn't exit and not cause an exception" do
+        dept_name = 'Francais'
+        records=@table.find({:dept_name=>dept_name}, 1)
+        assert_not_nil records
+        assert records.empty?, "records is NOT empty"
+      end
+     
+     
+    end
+  end
+  
+  context "A destroyed BtrieveSession" do
+    setup do
+      BtrieveSession.create_session(DB_SERVER,"Demodata")
+      @table = BtrieveTable.new(:course)
+      BtrieveSession.destroy_session
+    end
+        
+    should "not allow the instanciation of a DB table" do
+      assert_raise(RuntimeError){BtrieveTable.new(:course)}
+    end
+    
+    should "not allow exsting tables to search against the DB" do
+      records=nil
+      assert_raise(RuntimeError){records=@table.find({:dept_name=>'Mathematics'}, 1)}
+      assert_nil records
+    end
+  end
+end

data/test/helper.rb

@@ -6,5 +6,13 @@ $LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
 $LOAD_PATH.unshift(File.dirname(__FILE__))
 require 'beezwax'
 
+
 class Test::Unit::TestCase
+  #DB_SERVER=nil
+  DB_SERVER="10.211.55.4"
+  context "The database server name DB_SERVER" do
+    should "be defined to match your environment" do
+      assert_not_nil DB_SERVER
+    end
+  end
 end

metadata

@@ -1,13 +1,12 @@
 --- !ruby/object:Gem::Specification 
 name: beezwax
 version: !ruby/object:Gem::Version 
-  hash: 15
   prerelease: false
   segments: 
   - 0
-  - 5
-  - 2
-  version: 0.5.2
+  - 6
+  - 0
+  version: 0.6.0
 platform: ruby
 authors: 
 - Patrick Lardin
@@ -15,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-10-07 00:00:00 -07:00
+date: 2010-12-19 00:00:00 -08:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -26,7 +25,6 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 1
         segments: 
         - 0
         - 6
@@ -54,29 +52,19 @@ files:
 - lib/beezwax.rb
 - lib/btrieve/btrieve_const.rb
 - lib/btrieve/btrieve_core.rb
-- lib/btrieve/btrieve_model.rb
 - lib/btrieve/btrieve_record.rb
 - lib/btrieve/btrieve_schema.rb
 - lib/btrieve/btrieve_session.rb
 - lib/btrieve/btrieve_table.rb
-- pkg/beezwax-0.0.0.gem
-- pkg/beezwax-0.1.0.gem
-- pkg/beezwax-0.1.1.gem
-- pkg/beezwax-0.1.2.gem
-- pkg/beezwax-0.1.3.gem
-- pkg/beezwax-0.1.4.gem
-- pkg/beezwax-0.2.0.gem
-- pkg/beezwax-0.3.0.gem
-- pkg/beezwax-0.4.0.gem
+- test/btrieve/test_beezwax.rb
 - test/helper.rb
-- test/test_beezwax.rb
 has_rdoc: true
 homepage: http://github.com/plardin/beezwax
 licenses: []
 
 post_install_message: 
-rdoc_options: 
-- --charset=UTF-8
+rdoc_options: []
+
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement 
@@ -84,7 +72,6 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 3
       segments: 
       - 0
       version: "0"
@@ -93,7 +80,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 3
       segments: 
       - 0
       version: "0"
@@ -105,5 +91,5 @@ signing_key:
 specification_version: 3
 summary: Btrieve API wrapper.
 test_files: 
-- test/test_beezwax.rb
+- test/btrieve/test_beezwax.rb
 - test/helper.rb

data/lib/btrieve/btrieve_model.rb

@@ -1,49 +0,0 @@
-class BtrieveModel
-  include Btrieve
-  def initialize(classname, tablename)
-    session = BtrieveSession.get_session()
-    table = BtrieveTable.new(tablename, session)
-    session.model_classes[classname] = table
-  end
-
-  def self.new_record()
-    BtrieveRecord.new(get_table())
-  end
-
-  def self.find_in_unique_index(match, index_number)
-    get_table().find_in_unique_index(match, index_number)
-  end
-
-  def self.find_in_index(match, index_number)
-    get_table().find_in_index(match, index_number)
-  end
-
-  def self.each_record(mode=ACCELERATED_MODE, &block)
-    get_table().each_record(mode, &block)
-  end
-
-  def self.batch(mode=ACCELERATED_MODE, &block)
-    get_table().batch(mode, &block)
-  end
-
-  def self.one_to_one(association)
-    get_table().schema[:one_to_one][association[:name]]=association
-  end
-
-  def self.one_to_many(association)
-    get_table().schema[:one_to_many][association[:name]]=association
-  end
-
-  private
-
-  def self.get_table()
-    session = BtrieveSession.get_session()
-    session.model_classes[self.name.to_sym]
-  end
-end
-
-def BtrieveModel(classname, tablename)
-  raise Exception.new("The context is not set. Call 'Btrieve::Session.set_context( <pathname> )' before declaring model classes.") unless BtrieveSession.get_session() != nil
-  BtrieveModel.new(classname, tablename)
-  BtrieveModel
-end

data/test/test_beezwax.rb

@@ -1,7 +0,0 @@
-require 'helper'
-
-class TestBeezwax < Test::Unit::TestCase
-  should "probably rename this file and start testing for real" do
-    flunk "hey buddy, you should probably rename this file and start testing for real"
-  end
-end