A B-tree file is a collection of data nodes stored to disk. Each node
stores a value called an element. Each value is referenced by a key.
Each file can only hold one kind of element (unless universal types are
used).
The programmer can traverse forward or
reverse through the file. File positions are designated by cursors.
This package is implemented using the Berkeley database. Creating a
file will also create several auxillary files in the same directory.
The files in one directory will share the same Berkeley environment.
This package includes three new types:
btree_io.file - a B-tree file
btree_io.cursor - a B-tree cursor
bdb.db_error constants are also defined (e.g. bdb.DB_OK ), though
not all errors for all versions of Berkeley DB are defined and
operating system error codes (e.g. EINVAL, ENOENT) may also be
returned.
It is possible to open the file with the wrong (or a different) file
data type but this is not recommended.
=> type clouds is (fog, cumulus, stratus, cirrus, cumulonimbus )
=> btree_io.new_file( f, clouds )
=> (Assuming f is a new btree_io.file variable)
=> btree_io.create( f, "clouds.btree", 80, 80 )
=> ? btree_io.is_open( f )
true
=> ? btree_io.name( f )
clouds.btree
=> ls
clouds.btree __db.001 __db.002 __db.003 __db.004
=> btree_io.set( f, "Toronto", fog )
=> btree_io.set( f, "New York", cirrus )
=> btree_io.set( f, "Moscow", cumulonimbus )
=> ? btree_io.has_element( f, "Tokyo" )
false
=> btree_io.get( f, "New York", c )
=> (Assuming c is a new clouds variable)
=> ? c
cirrus
=> btree_io.add( f, "New York", cumulus )
=> btree_io.get( f, "New York", c )
=> (Assuming c is a new clouds variable)
=> ? c
cirrus
=> btree_io.close( f )
Example: Using btree_io to create a file of cities and their clouds
type person_type isrecord
first_name : string;
age : natural;
endrecord;
person : person_type;
f : btree_io.file;
btree_io.new_file( f, person_type );
btree_io.create( f, "person.btree", 80, 80 );
person.first_name := "John";
person.age := 18;
btree_io.add( f, person.first_name, person );
person.first_name := "Sue";
person.age := 21;
btree_io.add( f, person.first_name, person );
person.first_name := "Al";
person.age := 42;
btree_io.add( f, person.first_name, person );
declare
c : btree_io.cursor;
key : string;
begin
btree_io.new_cursor( c, person_type );
btree_io.open_cursor( f, c );
btree_io.get_first( f, c, key, person );
put( person.first_name ) @ ( " /" ) @ (person.age);
new_line;
loop
btree_io.get_next( f, c, key, person );
put( person.first_name ) @ ( " /" ) @ (person.age);
new_line;
endloop;
exceptionwhenothers =>
btree_io.close_cursor( f, c );
put_line( "no more people" );
end;
btree_io.close( f );
Example: Using btree_io to sort records
btree_io.add( f, k, v )
Put value v under key k in the file. If the key already exists, do nothing.
Example
btree_io.add( fruit, "apples", 15 );
Parameters
Param
Mode
Type
Default
Description
f
in out
btree_io.file
required
the file
k
in
string
required
the key
v
in
file value type
required
the value
Exceptions
An exception is raised if the value is the wrong type
An exception is raised for a deadlock
An exception is raised if the files are read-only access
An exception is raised if the B-Tree is too large
An exception is raised if the value is the wrong type
An exception is raised for a deadlock
An exception is raised if the files are read-only access
An exception is raised if the value type is not a string
Create a new B-tree file f named p. Maximum key length is kl bytes and maximum value length is vl bytes. If the database exists, it is overwritten. If --verbose is used, BDB verbose error messages are enabled. If the file name is an empty string, the B-tree will be stored in memory and any supporting files will be stored in the current directory.
Example
btree_io.create( fruit, "fruit.btree", 80, 80 );
Parameters
Param
Mode
Type
Default
Description
f
in out
btree_io.file
required
the file
p
in
string
required
the pathname
kl
in
positive
required
the max key length
vl
in
positive
required
the max value length
Exceptions
An exception is raised for a database created in an incompatible version of BDB
An exception is raised for a deadlock
This maximum lengths are for allocating space to convert SparForte strings into the C strings used by Berkeley DB.
btree_io.decrement( f, k [,n] )
Reduce the numeric value under key k in the file by one (or n). If the key does not exist, do nothing.
Example
btree_io.decrement( fruit, "apples" );
Parameters
Param
Mode
Type
Default
Description
f
in out
btree_io.file
required
the file
k
in
string
required
the key
n
in
file value type
1
the amount to decrement
Exceptions
An exception is raised if the value is the wrong type
An exception is raised for a deadlock
An exception is raised if the files are read-only access
An exception is raised if the value type is not numeric
Iterate through the file. Return the first value in the file. The order is the alphabetical order of the keys. An exception is thrown if the file is empty.
Iterate through the file. Return the last value in the file. The order is the alphabetical order of the keys. An exception is thrown if the file is empty.
Iterate through the file. Return the next value in the file. The order is the alphabetical order of the keys. An exception is thrown if the file is empty. Iteration is started with get_first.
Iterate through the file. Return the previous value in the file. The order is the alphabetical order of the keys. An exception is thrown if the file is empty. Iteration is started with get_last.
Return the error code from the last Berkeley DB action.
Example
if btree_io.last_error /= bdb.DB_OK then ...
Parameters
Param
Mode
Type
Default
Description
e
return value
btree_io.db_error
required
the last error code
f
in
btree_io.file
required
the file
Exceptions
-
See Also
Ada: N/A (AdaScript extension)
Compare With
-
btree_io.new_cursor( c, t )
Initialize a new cursor, assigning the type for the values in the file. The type may be an array, record, scalar or a unversal type.
Example
btree_io.new_cursor( fruit, natural );
Parameters
Param
Mode
Type
Default
Description
c
in out
btree_io.cursor
required
the cursor
t
in
the value type
required
the type of values
Exceptions
An exception is raised if out of memory
Compare With
Ada: N/A (AdaScript extension)
Implementation Note
Allocates a resource for the list.
btree_io.new_file( f, t )
Initialize a new file, assigning the type for the values in the file. The type may be an array, record, scalar or a unversal type.
Example
btree_io.new_file( fruit, natural );
Parameters
Param
Mode
Type
Default
Description
f
in
btree_io.file
required
the file
t
in
the value type
required
the type of values
Exceptions
An exception is raised if out of memory
Compare With
Ada: N/A (AdaScript extension)
Implementation Note
Allocates a resource for the list.
btree_io.open( f, p, kl, vl )
Open a new B-tree file f named p. Maximum key length is kl bytes and maximum value length is vl bytes. If no database exists, an exception is raised. If --verbose is used, BDB verbose error messages are enabled.
Example
btree_io.open( fruit, "fruit.btree", 80, 80 );
Parameters
Param
Mode
Type
Default
Description
f
in out
btree_io.file
required
the file
p
in
string
required
the pathname
kl
in
positive
required
the max key length
vl
in
positive
required
the max value length
Exceptions
An exception is raised for a database created in an incompatible version of BDB
An exception is raised for a deadlock
Determine if Berkeley errors are raised as exceptions or if the programmer will check for errors with last_error as required. The default is to raise exceptions. If --trace is used, the location in the SparForte source code is included with the error message.
Example
btree_io.raise_exceptions( fruit, true );
Parameters
Param
Mode
Type
Default
Description
f
in
btree_io.file
required
the file
b
in
boolean
required
true if errors will be raised
Exceptions
An exception is raised if the value is the wrong type
An exception is raised if out of memory