-- (c) Copyright - See License.txt

--

--****

-- == Euphoria Database (EDS)

--

-- <>

namespace eds

include std/error.e

include std/convert.e

include std/io.e

include std/filesys.e

include std/get.e

include std/pretty.e

include std/machine.e

include std/sequence.e

include std/datetime.e

include std/text.e

include std/math.e

--****

-- === Database File Format

--

-- ==== Header

-- * byte 0: magic number for this file-type: 77

-- * byte 1: version number (major)

-- * byte 2: version number (minor)

-- * byte 3: 4-byte pointer to block of table headers

-- * byte 7: number of free blocks

-- * byte 11: 4-byte pointer to block of free blocks

--

-- ==== Block of table headers

-- * -4: allocated size of this block (for possible reallocation)

-- * 0: number of table headers currently in use

-- * 4: table header1

-- * 16: table header2

-- * 28: etc.

--

-- ==== Table header

-- * 0: pointer to the name of this table

-- * 4: total number of records in this table

-- * 8: number of blocks of records

-- * 12: pointer to the index block for this table

--

-- There are two levels of pointers. The logical array of key pointers

-- is split up across many physical blocks. A single index block

-- is used to select the correct small block. This allows

-- inserts and deletes to be made without having to shift a

-- large number of key pointers. Only one small block needs to

-- be adjusted. This is particularly helpful when the table contains

-- many thousands of records.

--

-- ==== Index block

-- one per table

--

-- * -4: allocated size of index block

-- * 0: number of records in 1st block of key pointers

-- * 4: pointer to 1st block

-- * 8: number of records in 2nd " "

-- * 12: pointer to 2nd block

-- * 16: etc.

--

-- ==== Block of key pointers

-- many per table

--

-- * -4: allocated size of this block in bytes

-- * 0: key pointer 1

-- * 4: key pointer 2

-- * 8: etc.

--

-- ==== Free list

-- in ascending order of address

--

-- * -4: allocated size of block of free blocks

-- * 0: address of 1st free block

-- * 4: size of 1st free block

-- * 8: address of 2nd free block

-- * 12: size of 2nd free block

-- * 16: etc.

--

-- The key value and the data value for a record are allocated space

-- as needed. A pointer to the data value is stored just before the

-- key value. Euphoria objects, key and data, are stored in a compact form.

--

-- All allocated blocks have the size of the block in bytes, stored in the

-- four bytes just before the address.

--****

-- === Error Status Constants

public constant

--** Database is OK, not error has occurred.

--** The database could not be opened.

--** The database could not be created, it already exists.

--** A lock could not be gained on the database.

--** A fatal error has occurred.

--****

-- === Lock Type Constants

public enum

--** Do not lock the file.

--** Open the database with read-only access.

--** Open the database with read and write access.

--****

-- === Error Code Constants

public enum

--** Missing 0 terminator

--** current_db is not set

--** seek() failed.

--** no table was found.

--** this table already exists.

--** unknown key_location index was supplied.

--** couldn't insert a new record.

--** last error code

--** bad file

-- initial sizes for various things:

atom void

--****

-- === Variables

--

--**

-- **Exception handler**\\

-- Set this to a valid routine_id value for a procedure that

-- will be called whenever the library detects a serious error. You procedure

-- will be passed a single text string that describes the error. It may also

-- call [[:db_get_errors]] to get more detail about the cause of the error.

public integer db_fatal_id

-- the initial value doesn't show up in docs.

end if

-- read 1-byte value at current position in database file

end function

atom mem0, mem1, mem2, mem3

-- read 4-byte value at current position in database file

end function

-- read a 0-terminated string at current position in database file

sequence s

integer c

integer i

end if

end if

entry

end function

-- test if string at current position in database file equals given string

integer c

integer i

end if

end if

end if

entry

end function

-- Compressed format of Euphoria objects on disk

--

-- First byte:

-- 0..248 -- immediate small integer, -9 to 239

-- since small negative integers -9..-1 might be common

-- read a compressed Euphoria object from disk

-- if c is set, then c is not <= 248

sequence s

integer len

end if

end if

case I2B then

#100 * getc(current_db) +

MIN2B

case I3B then

#100 * getc(current_db) +

#10000 * getc(current_db) +

MIN3B

case I4B then

case F4B then

getc(current_db), getc(current_db)})

case F8B then

getc(current_db), getc(current_db),

getc(current_db), getc(current_db),

getc(current_db), getc(current_db)})

case else

-- sequence

else

end if

-- in-line small integer for greater speed on strings

else

end if

end switch

end function

-- return the compressed representation of a Euphoria object

-- as a sequence of bytes

sequence x4, s

else

end if

-- floating point

-- can represent as 4-byte float

else

end if

else

-- sequence

else

end if

end if

end function

-- write 1 byte to current database file

sequence memseq

-- write 4 bytes to current database file

-- x is 32-bits max

-- write a sequence of bytes to current database file

-- seek to a position in the current db file

end if

end if

--****

-- === Routines

--**

-- Fetches the most recent set of errors recorded by the library.

--

-- Parameters:

-- # ##clearing## : if zero the set of errors is not reset, otherwise

-- it will be cleared out. The default is to clear the set.

--

-- Returns:

-- A **sequence**, each element is a set of four fields.

-- # Error Code.

-- # Error Text.

-- # Name of library routine that recorded the error.

-- # Parameters passed to that routine.

--

-- Comments:

-- * A number of library routines can detect errors. If the routine is a

-- function, it usually returns an error code. However, procedures that

-- detect an error can't do that. Instead, they record the error details

-- and you can query that after calling the library routine.

-- * Both functions and procedures that detect errors record the details

-- in the ##Last Error Set##, which is fetched by this function.

--

--

-- Example 1:

--

-- db_replace_data(recno, new_data)

-- errs = db_get_errors()

-- if length(errs) != 0 then

-- display_errors(errs)

-- abort(1)

-- end if

--

sequence lErrors

end if

end function

--**

-- print the current database in readable form to file fn

--

-- Parameters:

-- # ##fn## : the destination file for printing the current Euphoria database;

-- # ##low_level_too## : a boolean. If true, a byte-by-byte binary dump

-- is presented as well; otherwise this step is skipped. If omitted,

-- //false// is assumed.

--

-- Errors:

-- If the current database is not defined, an error will occur.

--

-- Comments:

-- * All records in all tables are shown.

-- * If low_level_too is non-zero,

-- then a low-level byte-by-byte dump is also shown. The low-level

-- dump will only be meaningful to someone who is familiar

-- with the internal format of a Euphoria database.

--

-- Example 1:

--

-- if db_open("mydata", DB_LOCK_SHARED) != DB_OK then

-- puts(2, "Couldn't open the database!\n")

-- abort(1)

-- end if

-- fn = open("db.txt", "w")

-- db_dump(fn) -- Simple output

-- db_dump("lowlvl_db.txt", 1) -- Full low-level dump created.

--

-- print an open database in readable form to file fn

-- (Note: If you turn database.e into a .dll or .so, you will

-- have to use a file name, rather than an open file number.

-- All other database.e routines are ok as they are.)

integer magic, minor, major

integer fn

atom tables, ntables, tname, trecords, t_header, tnrecs,

key_ptr, data_ptr, size, addr, tindex, fbp

object key, data

integer c, n, tblocks

atom a

sequence ll_line

integer hi, ci

else

end if

end if

else

{db_names[eu:find(current_db, db_file_nums)], ntables})

else

end if

end if

-- low level dump: show all bytes in the file

end if

else

end if

end if

end if

end if

else

end if

entry

end if

-- high level dump

end if

end if

-- display the next table

-- display the next record

else

end if

end if

-- show the free list

else

end if

end if

--**

-- Detects corruption of the free list in a Euphoria database.

--

-- Comments:

-- This is a debug routine used by RDS to detect corruption of the free list.

-- Users do not normally call this.

--

atom free_count, free_list, addr, size, free_list_space

atom max

end if

end if

end if

end if

end if

end if

-- Allocate (at least) n bytes of space in the database file.

-- The usable size + 4 is stored in the 4 bytes before the returned address.

-- Upon return, the file pointer points at the allocated space, so data

-- can be stored into the space immediately without a seek.

-- When space is allocated at the end of the file, it will be exactly

-- n bytes in size, and the caller must fill up all the space immediately.

atom free_list, size, size_ptr, addr

integer free_count

sequence remaining

-- found a big enough block

-- loose fit: shrink first part, return 2nd part

else

-- close fit: remove whole block from list and return it

end if

end if

end if

-- no free block available - point to end of file

end function

-- Put a block of storage onto the free list in order of address.

-- Combine the new free block with any adjacent free blocks.

atom psize, i, size, addr, free_list, free_list_space

atom new_space, to_be_freed, prev_addr, prev_size

integer free_count

sequence remaining

-- need more space for free list

else

end if

end if

-- combine with previous block

-- combine space for all 3, delete the following block

else

end if

-- combine with following block - only size on free list is updated

else

-- insert a new block, shift the others down

end if

end if

integer k

else

end if

end if

end if

--****

-- === Managing databases

--**

-- Create a new database, given a file path and a lock method.

--

-- Parameters:

-- # ##path## : a sequence, the path to the file that will contain the database.

-- # ##lock_method## : an integer specifying which type of access can be

-- granted to the database. The value of ##lock_method##

-- can be either ##DB_LOCK_NO## (no lock) or

-- ##DB_LOCK_EXCLUSIVE## (exclusive lock).

-- # ##init_tables## : an integer giving the initial number of tables to

-- reserve space for. The default is 5 and the minimum is 1.

-- # ##init_free## : an integer giving the initial amount of free space pointers to

-- reserve space for. The default is 5 and the minimum is 0.

--

-- Returns:

-- An **integer**, status code, either DB_OK if creation successful or anything else on an error.

--

-- Comments:

--

-- On success, the newly created database

-- becomes the **current database** to which

-- all other database operations will apply.

--

-- If the path, s, does not end in .edb, it will be added automatically.

--

-- A version number is stored in the database file so future

-- versions of the database software can recognize the format, and

-- possibly read it and deal with it in some way.

--

-- If the database already exists, it will not be overwritten.

-- db_create() will return DB_EXISTS_ALREADY.

--

-- Example 1:

--

-- if db_create("mydata", DB_LOCK_NO) != DB_OK then

-- puts(2, "Couldn't create the database!\n")

-- abort(1)

-- end if

--

--

-- See Also:

-- [[:db_open]], [[:db_select]]

integer db

end if

end if

end if

-- see if it already exists

-- don't destroy an existing db - let user delete himself

end if

-- file must exist before "ub" can be used

end if

-- get read and write access, "ub"

end if

-- shared lock doesn't make sense for create

end if

end if

end if

-- initialize the header

-- 3:

-- 7:

-- 11:

-- 15: initial table block:

-- 19:

-- 23: initial space for tables

-- initial space for free list

end function

--**

-- Open an existing Euphoria database.

--

-- Parameters:

-- # ##path## : a sequence, the path to the file containing the database

-- # ##lock_method## : an integer specifying which sort of access can

-- be granted to the database. The types of lock that you can use are:

-- ## ##DB_LOCK_NO## : (no lock) - The default

-- ## ##DB_LOCK_SHARED## : (shared lock for read-only access)

-- ## ##DB_LOCK_EXCLUSIVE## : (for read/write access).

--

-- Returns:

-- An **integer**, status code, either ##DB_OK## if creation successful or anything else on an error.

--

-- The return codes are:

--

--

-- public constant

-- DB_OK = 0 -- success

-- DB_OPEN_FAIL = -1 -- could not open the file

-- DB_LOCK_FAIL = -3 -- could not lock the file in the

-- -- manner requested

--

--

-- Comments:

-- ##DB_LOCK_SHARED## is only supported on Unix platforms. It allows you to read the database,

-- but not write anything to it. If you request ##DB_LOCK_SHARED## on //WIN32// it will be

-- treated as if you had asked for DB_LOCK_EXCLUSIVE.

--

-- If the lock fails, your program should wait a few seconds and try again.

-- Another process might be currently accessing the database.

--

-- Example 1:

--

-- tries = 0

-- while 1 do

-- err = db_open("mydata", DB_LOCK_SHARED)

-- if err = DB_OK then

-- exit

-- elsif err = DB_LOCK_FAIL then

-- tries += 1

-- if tries > 10 then

-- puts(2, "too many tries, giving up\n")

-- abort(1)

-- else

-- sleep(5)

-- end if

-- else

-- puts(2, "Couldn't open the database!\n")

-- abort(1)

-- end if

-- end while

--

--

-- See Also:

-- [[:db_create]], [[:db_select]]

integer db, magic

end if

lock_method = DB_LOCK_EXCLUSIVE then

-- get read and write access, "ub"

else

-- DB_LOCK_SHARED

end if

elsedef

if lock_method = DB_LOCK_SHARED then

lock_method = DB_LOCK_EXCLUSIVE

end if

db = open(path, "ub")

end ifdef

end if

end if

end if

end if

end if

end function

--**

-- Choose a new, already open, database to be the current database.

--

-- Parameters:

-- # ##path## : a sequence, the path to the database to be the new current database.

-- # ##lock_method## : an integer. Optional locking method.

--

-- Returns:

-- An **integer**, ##DB_OK## on success or an error code.

--

-- Comments:

-- * Subsequent database operations will apply to this database. path is the

-- path of the database file as it was originally opened with ##db_open##()

-- or ##db_create##().\\

-- * When you create (db_create) or open (db_open) a database, it automatically

-- becomes the current database. Use ##db_select##() when you want to switch back

-- and forth between open databases, perhaps to copy records from one to the

-- other. After selecting a new database, you should select a table within

-- that database using ##db_select_table##().

-- * If the ##lock_method## is omitted and the database has not already been opened,

-- this function will fail. However, if ##lock_method## is a valid lock type for

-- [[:db_open]] and the database is not open yet, this function will attempt to

-- open it. It may still fail if the database cannot be opened.

--

-- Example 1:

--

-- if db_select("employees") != DB_OK then

-- puts(2, "Could not select employees database\n")

-- end if

--

--

-- Example 2:

--

-- if db_select("customer", DB_LOCK_SHARED) != DB_OK then

-- puts(2, "Could not open or select Customer database\n")

-- end if

--

--

-- See Also:

-- [[:db_open]], [[:db_select]]

integer index

end if

end if

end if

end if

end function

--**

-- Unlock and close the current database.

--

-- Comments:

-- Call this procedure when you are finished with the current database. Any lock will be removed, allowing other processes to access the database file. The current database becomes undefined.

-- close the current database

integer index

end if

-- unlock the database

end if

-- delete info for current_db

-- delete each cache entry for this database

end if

-- find a table, given its name

-- return table pointer

atom tables

atom nt

atom t_header, name_ptr

-- found it

end if

end function

--**

--==== Managing tables

-- Parameters:

-- # ##name## : a sequence which defines the name of the new current table.

--

-- Description:

-- On success, the table with name given by name becomes the current table.

--

-- Returns:

-- An **integer**, either DB_OK on success or DB_OPEN_FAIL otherwise.

--

-- Errors:

-- An error occurs if the current database is not defined.

--

-- Comments:

-- All record-level database operations apply automatically to the current table.

--

-- Example 1:

--

-- if db_select_table("salary") != DB_OK then

-- puts(2, "Couldn't find salary table!\n")

-- abort(1)

-- end if

--

--

-- See Also:

-- [[:db_table_list]]

-- let table with the given name be the current table

atom table, nkeys, index

atom block_ptr, block_size

integer blocks, k

end if

end if

end if

end if

-- read in all the key pointers for the current table

end if

end function

--**

-- Get name of currently selected table

--

-- Parameters:

-- # None.

--

-- Returns:

-- A **sequence**, the name of the current table. An empty string means

-- that no table is currently selected.

--

-- Example 1:

--

-- s = db_current_table()

--

--

-- See Also:

-- [[:db_select_table]], [[:db_table_list]]

end function

--**

-- Create a new table within the current database.

--

-- Parameters:

-- # ##name## : a sequence, the name of the new table.

-- # ##init_records## : The number of records to initially reserve space for.

-- (Default is 50)

--

-- Returns:

-- An **integer**, either DB_OK on success or DB_EXISTS_ALREADY on failure.

--

-- Errors:

-- An error occurs if the current database is not defined.

--

-- Comments:

-- * The supplied name must not exist already on the current database.

-- * The table that you create will initially have 0 records. However

-- it will reserve some space for a number of records, which will

-- improve the initial data load for the table.

-- * It becomes the current table.

--

-- Example 1:

--

-- if db_create_table("my_new_table") != DB_OK then

-- puts(2, "Could not create my_new_table!\n")

-- end if

--

--

-- See Also:

-- [[:db_select_table]], [[:db_table_list]]

atom name_ptr, nt, tables, newtables, table, records_ptr

atom size, newsize, index_ptr

sequence remaining

integer init_index

end if

end if

-- increment number of tables

-- enlarge the block of table headers

-- copy all table headers to the new block

-- fill the rest

else

end if

-- allocate initial space for 1st block of record pointers

-- allocate initial space for the index

-- store new table

end if

end function

--**

-- Delete a table in the current database.

--

-- Parameters:

-- # ##name## : a sequence, the name of the table to delete.

--

-- Errors:

-- An error occurs if the current database is not defined.

--

-- Comments:

-- If there is no table with the name given by name, then nothing happens.

-- On success, all records are deleted and all space used by the table

-- is freed up. If the table was the current table, the current table

-- becomes undefined.

--

-- See Also:

-- [[:db_table_list]], [[:db_select_table]], [[:db_clear_table]]

-- delete an existing table and all of its records

atom table, tables, nt, nrecs, records_ptr, blocks

atom p, data_ptr, index

sequence remaining

integer k

end if

-- free the table name

-- free all the records

-- free the block

-- free the index

-- get tables & number of tables

-- shift later tables up

tables+4+nt*SIZEOF_TABLE_HEADER-

(table+SIZEOF_TABLE_HEADER))

-- decrement number of tables

end if